KonaKart offers you the ability to communicate with the application engine using JSON (JavaScript Object Notation). A servlet receives requests in JSON format over HTTP/HTTPS and passes these on to an application engine that processes the request. The response is returned in JSON format.
By default the JSON Server servlet sections in the web.xml file for the konakart webapp are not commented out so JSON services are enabled after a standard install.
There are two sections in the konakart webapp's web.xml file to modify to disable the JSON server. The first is the servlet definition and the second is the servlet mapping. To disable the JSON Server servlet section you must comment out the definition in the konakart webapp's web.xml file shon below:
<!-- JSON Server -->
<servlet>
<servlet-name>KonaKart_JSON_Servlet</servlet-name>
<display-name>KonaKart JSON Server</display-name>
<description>KonaKart JSON Server</description>
<servlet-class>
com.konakart.json.KKJSONServer
</servlet-class>
<init-param>
<param-name>jsonEnabled</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>30</load-on-startup>
</servlet>
Next, to disable the servlet mapping, you must comment out the definition shown below. The servlet mapping may be set as you wish (the URL used must be used by the clients who wish to call the JSON Server and is defined in konakart.properties for clients using the client side of the JSON engine). The default servlet mapping URL is "/konakartjson" but this can be changed if required:
<!-- JSON Server -->
<servlet-mapping>
<servlet-name>KonaKart_JSON_Servlet</servlet-name>
<url-pattern>/konakartjson</url-pattern>
</servlet-mapping>
You need to specify the mode that the JSON engines will use in the konakart.properties file in the konakart webapp's WEB-INF/classes directory. This section defines the engine class used to service the JSON requests with the default being defined as com.konakart.app.KKEng.
The configuration settings must match those of your KonaKart installation (the engine mode, customers shared and products shared settings). These are set by the installer automatically but if you have installed manually you need to adjust these to suit your installation:
# ----------------------------------------------------------------------------------- # Enterprise Feature # KonaKart engine class used by the JSON services # For the default engine use: com.konakart.app.KKEng # For the custom engine use: com.konakart.app.KKCustomEng konakart.app.json.engine.classname = com.konakart.app.KKEng # ----------------------------------------------------------------------------------- # Enterprise Feature # URL for the JSON engine servlet konakart.json.engine.url = http://localhost:8780/konakart/konakartjson # Generate match Id on generated JSON Requests konakart.json.generateMatchIds = false # ----------------------------------------------------------------------------------- # Enterprise Feature # Engine mode that the JSON engine will use # 0 = Single Store (default) # 1 = Multi-Store Multiple-Databases (add konakart.databases.used above as well) # 2 = Multi-Store Single Database konakart.json.mode = 2 # ----------------------------------------------------------------------------------- # Enterprise Feature # Customers Shared / Products Shared mode that the JSON engine will use # When in multi-store single database mode, the customers can be shared between stores konakart.json.customersShared = false # When in multi-store single database mode, the products can be shared between stores konakart.json.productsShared = false
Note that the property "konakart.json.engine.url" that defines the URL for the JSON service must match the web.xml servlet-mapping defintion (see above).
The property "konakart.json.generateMatchIds" defines whether matching Ids are generated in JSON requests that are sent to the engine. The default for this is false which minimizes message size and parsing time.
As with the POJO, RMI and SOAP versions of the engines, it's easy to select which one you would like to use in your code by simply specifying it by name at runtime.
A very simple example of this is provided in the GetProduct.java example provided in the download kit (under the java_api_examples directory). The example demonstrates how simple it is to select different engines and get the same result with each:
/*
* Get an instance of the KonaKart engine and retrieve. The method called can be found in
* BaseApiExample.java
*/
EngineConfig engConf = new EngineConfig();
engConf.setMode(getEngineMode());
engConf.setStoreId(getStoreId());
engConf.setCustomersShared(isCustomersShared());
engConf.setProductsShared(isProductsShared());
/*
* Instantiate a direct java Engine by name - to find a product
* KKEngIf eng = new KKEng(engConf);
*/
KKEngIf eng = getKKEngByName("com.konakart.app.KKEng", engConf);
System.out.println("Get a product using the KKEng engine");
getProductUsingEngine(eng);
/*
* Instantiate a java JSON Engine by name - to find a product
* KKEngIf jsonEng = new KKJSONEng(engConf);
*/
KKEngIf jsonEng = getKKEngByName("com.konakart.json.KKJSONEng", engConf);
System.out.println("Get a product using the KKJSONEng engine");
getProductUsingEngine(jsonEng);
Notice how both of the engines implement the KKEngIf. If you code your solution to the KKEngIf interface you can delay the decision about which engine to use until runtime or (probably more likely) until you have decided how you wish to distribute your KonaKart solution over multiple machines.
The implementation of the getKKEngByName() call used in the above example is provided in the GetProduct.java source file.
Since all four of the application engines implement the same KKEngIf interface the javadoc is applicable to every one of them.
You do not have to use the client side of the JSON engine if you don't want to. Instead you may wish to construct your own client requests yourself. You can derive the format of the requests by applying the standard conventions for translating our KKEngIf into JSON calls as follows.
Some examples of JSON requests to the KonaKart JSON Server:
A login request:
{
"emailAddr" : "fred@flintstone.com",
"password" : "abcde02",
"f" : "login",
"s" : "store1"
}
A customer registration request:
{
"custReg" : {
"emailAddr" : "robin@batcave.com",
"city" : "GothamCity",
"company" : "ACME Inc",
"countryId" : 223,
"faxNumber" : "123456",
"firstName" : "Robin",
"gender" : "m",
"lastName" : "Wayne",
"newsletter" : "0",
"postcode" : "st5 ort",
"productNotifications" : -1,
"streetAddress" : "12345 Alligator Alley",
"streetAddress1" : "Blue house",
"suburb" : "Harlem",
"telephoneNumber" : "654321",
"birthDate" : 1303223768362,
"addressCustom1" : "addressCustom1",
"addressCustom5" : "addressCustom5",
"customerCustom1" : "customerCustom1",
"customerCustom5" : "customerCustom5",
"groupId" : -1,
"zoneId" : -1,
"invisible" : false,
"state" : "Florida",
"password" : "abcde02"
},
"f" : "registerCustomer",
"s" : "store1"
}
Some examples of JSON responses from the KonaKart JSON Server:
A response to a login request showing the result which is a sessionId:
{
"r" : "f663832c049322d2fb6882ba0abf4db9"
}
A response from a getCustomer request:
{
"r" : {
"id" : 123,
"type" : 0,
"birthDate" : 1303223708000,
"emailAddr" : "robin@batcave.com",
"firstName" : "Robin",
"gender" : "m",
"lastName" : "Wayne",
"telephoneNumber" : "654321",
"invisible" : 0,
"numberOfLogons" : 0,
"defaultAddrId" : 147,
"globalProdNotifier" : 0,
"groupId" : -1
}
}
If an exception is thrown during the processing of a request, the server will respond with a message in JSON format as follows:
An exception thrown in any request where a sessionId is required but cannot
be found is transformed into this JSON response:
{
"e" : "com.konakart.app.KKException",
"m" : "The session bad-session-id cannot be found"
}
An exception thrown in a login request is transformed into this JSON response:
{
"e" : "com.konakart.app.KKException",
"m" : "[5] Cannot find customer with email address = bad-user@localhost"
}