Can you show me an example of how to use the Java API ?
How do I use KonaKart's SOAP Web Service interface ?
How do I run my own SQL ?
Can you show me an example of how to use the Java API ?
One of the most important features of KonaKart is the availability of a set of open APIs that allow you to control KonaKart as you require as part of your IT solution. You may wish to add a different front-end for your KonaKart shopping cart application or you may wish to integrate KonaKart with other applications in your back office. When you use the java APIs for whatever purpose you can be confident that they will work with future releases of KonaKart as backwards compatibility will always be maintained (although some API calls may be deprecated, they will not be removed).
A number of simple java sources are provided in every KonaKart download kit (you can find them under the installation directory in a directory called java_api_examples) that demonstrate how you call the direct POJO form of the KonaKart APIs:
To give you a flavour of the examples in the downloadable sources, here is an extract from one of them that demonstrates how you can register a new customer using the KonaKart Admin APIs. (See the example sources for a complete set of java files).
| /* * Instantiate an AdminCustomerRegistration object and set its attributes */ AdminCustomerRegistration acr = new AdminCustomerRegistration(); /* Compulsory attributes */ // Gender should be set to "m" of "f" acr.setGender("m"); acr.setFirstName("Peter"); acr.setLastName("Smith"); // If you do not require the birthdate, just set it to the current date. It is // compulsory and so needs to be set. acr.setBirthDate(new Date()); acr.setEmailAddr("peter.smith@konakart.com"); acr.setStreetAddress("23 Halden Close"); acr.setCity("Newcastle"); acr.setPostcode("ST5 ORT"); acr.setTelephoneNumber("01782 639706"); acr.setPassword("secret"); /* Optional attributes */ acr.setCompany("DS Data Systems Ltd."); // Country Id needs to be set with the id of a valid country from the Countries table acr.setCountryId(222); acr.setFaxNumber("01782 639707"); // Newsletter should be set to "0" (don't receive) or "1" (receive) acr.setNewsletter("1"); acr.setSuburb("May Bank"); acr.setState("Staffs"); /* Optional Custom fields for customer object */ acr.setCustomerCustom1("Number Plate"); acr.setCustomerCustom2("Driver's license"); acr.setCustomerCustom3("Passport"); acr.setCustomerCustom4("custom 4"); acr.setCustomerCustom5("custom 5"); /* Optional Custom fields for address object */ acr.setAddressCustom1("custom 1"); acr.setAddressCustom2("custom 2"); acr.setAddressCustom3("custom 3"); acr.setAddressCustom4("custom 4"); acr.setAddressCustom5("custom 5"); // Register the customer and get the customer Id int custId = eng.registerCustomer(sessionId, acr);; System.out.println("Id of the new customer = " + custId); |
How do I use konakart's SOAP web service interface ?
KonaKart has two major interface types - the direct POJO interface, and the SOAP interface. Both support exactly the same interface calls. Which one you choose will depend on many factors but the best perfromance is likely to come from the direct interface, whereas the SOAP interface gives greater flexibility in distributed implementations and interoperability.
It's remarkably simple to use KonaKart's SOAP interfaces. If your IDE can create client stubs from WSDL then you can use that to create your SOAP clients or, if you prefer, you can use AXIS as in the downloadable example which follows.
There are two WSDL definitions; one for the KonaKart Application API, and the other for the KonaKart Admin API. They can be seen at these URLs:
http://www.konakart.com/konakart/services/KKWebServiceEng?wsdl
http://www.konakart.com/konakartadmin/services/KKWSAdmin?wsdl
1) The SOAP examples kit that is provided in every KonaKart download kit (you can find them under the installation directory in a directory called java_soap_examples) contains everything you need to build a simple SOAP client from the KonaKart Application WSDL. First verify that you have the kit in your version of KonaKart.
2) Next, ensure that KonaKart is running on your machine. After the default installation you should be able to start KonaKart by clicking on the "Start KonaKart Server" start-up icon (on Windows) or by executing the <Konakart Home>/bin/startkonakart.sh script (on *nix). You need KonaKart to be running in order to get responses so your SOAP calls that you will make with the examples.
3) Check that the KonaKart server has started OK - a quick way would be to see if the application appears at http://localhost:8780/konakart
4) Open up a console window and change directory to the location of the java_soap_examples, for example this would be:
C:\> cd C:\Program Files\KonaKart\java_soap_examples
on Windows.
5) Ensure that the environment variable JAVA_HOME is set correctly. On Windows, a suitable setting might be:
JAVA_HOME=C:\jdk1.5.0_07
6) Ensure that the JAVA_HOME/bin directory appears on your PATH. On Windows, this might look something like this:
Path=C:\jdk1.5.0_07\bin;C:\WINDOWS\system32;C:\WINDOWS
{You could also check that when you issue "java -version" you get the java version you expect}
7) If you already have ANT installed, ANT_HOME is defined and ANT's bin directory is on your PATH you can skip the next two sections.
If you don't have ANT installed you can use the cut-down version of ANT that we include in the KonaKart download kit, but you must set the following environment variables. Ensure that the environment variable ANT_HOME is set correctly in the command shell that you are executing (you probably don't want to change the environment variable globally). On Windows, if you installed KonaKart to the default location (C:\Program Files\KonaKart), it would be (note the slashes):
ANT_HOME=C:/Program Files/KonaKart/custom/bin
8) Ensure that the ANT_HOME/bin directory appears on your PATH. On Windows, this might look something like this:
Path=C:\jdk1.5.0_07\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\KonaKart\custom\bin
As a sanity check that you are set up ready to build the examples, check that you see the following when you issue a "ant -p" command:
| C:\Program Files\KonaKart\java_soap_examples>ant -p Buildfile: build.xml Main targets: axis_client_generation Generate client stubs from the WSDL build Creates the SOAP clients, compiles and runs a little example clean Clears away everything that's created during a build compile Compile the examples run Run the little example program Default target: build |
[The KonaKart download kit contains just enough of ANT for you to build the examples. For subsequent development using ANT you should consider installing a complete ANT installation - check the Apache ANT site for details]
9) Simply execute the "ant" command to compile, then run, the simple SOAP example.
If all is well you should see the following output:
C:\Program Files\KonaKart\java_soap_examples>ant clean: [echo] Cleanup... [delete] C:\Program Files\KonaKart\java_soap_examples\classes not found. [delete] C:\Program Files\KonaKart\java_soap_examples\src\com\konakart\ws not found. [delete] C:\Program Files\KonaKart\java_soap_examples\src\com\konakart\wsapp not found. axis_client_generation: [echo] Create the KonaKart client stubs from the WSDL compile: [echo] Compile the examples [mkdir] Created dir: C:\Program Files\KonaKart\java_soap_examples\classes [javac] Compiling 35 source files to C:\Program Files\KonaKart\java_soap_examples\classes [javac] Note: Some input files use unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details. run: [java] There are 239 countries [java] There are 9 manufacturers [java] The default currency is: USD build: BUILD SUCCESSFUL Total time: 14 seconds |
The code is very simple; here's an extract from AxisExample.java:
KKWSEngIf port = new KKWSEngIfServiceLocator().getKKWebServiceEng(); // make some example calls Country[] countries = port.getAllCountries(); System.out.println("There are " + countries.length + " countries"); Manufacturer[] manufacturers = port.getAllManufacturers(); System.out.println("There are " + manufacturers.length + " manufacturers"); Currency curr = port.getDefaultCurrency(); System.out.println("The default currency is: " + curr.getCode()); |
Notes:
- If you've installed to a port other than 8780, you will have to modify the konakart.wsdl file to match (change the port number right at the end of the file) .
- If you get "connection refused" - check that your firewall isn't blocking your client calls.
How do I run my own SQL ?
A convenient way to use the same database connection techniques as KonaKart is as follows:
First a SELECT query... note the processing of the result set after the results are returned.
/* * Run a query that selects the product id and product model from all products that have * an id less than 10. All Select queries need to be run using the BasePeer.executeQuery * command */ List<Record> records = BasePeer .executeQuery("select products_id, products_model, products_price from products where products_id < 10"); /* * Loop through the result set and print out the results. Note that the first attribute * in the Record object is at index = 1 and not index = 0 */ if (records != null) { for (Iterator<Record> iterator = records.iterator(); iterator.hasNext();) { Record rec = (Record) iterator.next(); System.out.println("id = " + rec.getValue(1).asInt() + "; model = " + rec.getValue(2).asString() + "; price = " + rec.getValue(3).asBigDecimal(/* scale */2)); } } |
Here's a simple UPDATE example:
| /* * Now let's run another query to change the model name of the product with id = 1. All * non select queries need to be run using the BasePeer.executeStatement command */ BasePeer .executeStatement("update products set products_model='Super Turbo' where products_id=1"); |
The /java_api_examples/src/com/konakart/apiexamples/RunCustomQuery.java example, provided in the download kit, illustrates this technique.
If you have questions on using the java API or the SOAP API please post these on our forum.