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. These work fine most of the time but there are occasions, especially with heavily-customized solutions, where you need to modify the behavior of the KonaKart APIs.
A simple framework has been developed that allows you to modify what happens when you call the KonaKart APIs.
It may be instructive to start by explaining the architecture so that you get a clear view of where you should add your customizations.
The interface to the KonaKart application engine is defined in KKEngIf.java . This is implemented by KKEng.java . A new, custom, implementation of the interface is provided in KKCustomEng.java . For every API call, there is a method in KKCustomEng.java that in turn calls a method in KKEng.java . The call is made by instantiating an instance of a class that has the same name as the method and executing the relevant API call on that class. The source for all of these classes is provided in the download package (from version 2.2.6.0). If you wish to change the behavior of a certain API call, you simply move the relevant source file from custom/gensrc/com/konakart/app/METHOD.java to custom/src/com/konakart/app/METHOD.java , then modify the code in that java file, to implement the behavior you require for that particular API call.
KonaKart has two major API sets - one for the Application , and one for Administration . The paragraph above explained the classes involved in the Application API but there is an equivalent set for the Administration API as follows:
The interface to the KonaKart administration engine is defined in KKAdminIf.java . This is implemented by KKAdmin.java . A new, custom, implementation of the interface is provided in KKAdminCustomEng.java . For every API call, there is a method in KKAdminCustomEng.java that in turn calls a method in KKAdmin.java . The call is made by instantiating an instance of a class that has the same name as the method and executing the relevant API call on that class. The source for all of these classes is provided in the download package (from version 2.2.6.0). If you wish to change the behavior of a certain API call, you simply move the relevant source file from custom/gensrc/com/konakartadmin/app/METHOD.java to custom/src/com/konakartadmin/app/METHOD.java , then modify the code in that java file, to implement the behavior you require for that particular API call.
An ANT build file is provided in the standard download kits that help you build your custom code into jars and wars for subsequent deployment.
The next two sections step through the engine customization process in detail. The first illustrates how to add your own code in the custom() interface call, and the second shows you how to modify what happens in the getCustomerForId() API call.
As from KonaKart version 2.2.6.0 there are two custom API calls for both the application APIs and the Admin APIs for this purpose. The default implementations all return null. One of the two calls is called customSecure ("Secure" because a sessionId is validated before it is executed), and the other simply called custom . An equivalent pair of calls are available on the Admin API.
The calls are defined as follows (you could also find this information in the javadoc):
/** * A custom interface that you have to provide an implementation * for. The default implementation will simply return a null. * * There are two versions, one that requires a valid sessionId * (customSecure) and one that does not (custom). * * You are free to use the two input String parameters in any way * you choose, for example you may wish to use one to indicate which * of your custom functions to run, and the other might * contain XML to give you a great deal of flexibility - but it's up * to you! * * @param input1 * The first input String - can be anything you choose * @param input2 * The second input String - can be anything you choose * @return Returns a String * @throws KKException */ public String custom(String input1, String input2) throws KKException;
Also, the version that checks the session ID:
/**
* A custom interface that you have to provide an implementation
* for. The default implementation will throw an exception for an
* invalid sessionId or return a null.
*
* There are two versions, one that requires a valid sessionId
* (customSecure) and one that does not (custom).
*
* You are free to use the two input String parameters in any way
* you choose, for example you may wish to use one to indicate which
* of your custom functions to run, and the other might contain XML
* to give you a great deal of flexibility - but it's up to you!
*
* @param sessionId
* The session id of the logged in user
* @param input1
* The first input String - can be anything you choose
* @param input2
* The second input String - can be anything you choose
* @return Returns a String
* @throws KKException
*/
public String customSecure(String sessionId, String input1, String input2)
throws KKException;
So let's work through an example of using the custom API call.
Let's suppose you wanted to create an API call that returns the OrderId of the last order that was processed. (Yes, it's a simple case, but you can make it do whatever you like once you know how to use this mechanism!).
This functionality is best-suited to the Admin API so we'll use that in our example.
Move (yes, don't copy but move, because we only want one version of this file to ensure there are no duplicate classes produced) the Custom.java file from the gensrc directory tree to the src directory tree:
$ mv custom/adminengine/gensrc/com/konakartadmin/app/Custom.java \
custom/adminengine/src/com/konakartadmin/app/
It is possible to edit these files in the gensrc directory tree but this isn't advisable as it will make it harder for you to upgrade to a future version of KonaKart. It's better to separate your customized versions out from the gensrc tree so that you can easily see which interfaces you've customized.
Implement the code in Custom.java
Before you change it, Custom.java contains just this:
package com.konakartadmin.app;
import com.konakartadmin.bl.KKAdmin;
/**
* The KonaKart Custom Engine - Custom -
* Generated by CreateKKAdminCustomEng
*/
public class Custom
{
KKAdmin kkAdminEng = null;
/**
* Constructor
*/
public Custom(KKAdmin _kkAdminEng)
{
kkAdminEng = _kkAdminEng;
}
public String custom(
String input1, String input2) throws KKAdminException
{
return kkAdminEng.custom(input1, input2);
}
}
Since the default implementation for these custom() and customSecure() methods is simply to return null we will need to replace the lines above (marked in bold) with the following code: (full source code for this example is provided in the download kit in custom/adminengine/examples/com/konakartadmin/app/Custom.java )
public String custom(String input1, String input2)
throws KKAdminException
{
/*
* Run a query that selects the orders_id of the last order
* processed.
*/
List<Record> records =
KKBasePeer.executeQuery("SELECT max(orders_id) FROM orders");
if (records == null)
{
// No Orders Found
return null;
} else
{
return records.get(0).getValue(1).asString();
}
}
Compile the new Custom class and rebuild the jars
An ANT build file is provided for this purpose - under the custom directory in the download kit.
C:\KonaKart\custom>bin\kkant -p
Buildfile: build.xml
Main targets:
build Compiles all the custom code and creates all the jars
clean Clears away everything that's created during a build
clean_admin_portlet_war Clears away the admin portlet war
clean_custom_admin_service_classes Clears away the generated custom admin service
artifacts
clean_custom_admin_service_classes_json Clears away the generated custom admin service
artifacts
- JSON
clean_custom_store_service_classes Clears away the generated custom store service
artifacts
clean_custom_store_service_classes_json Clears away the generated custom store service
artifacts
- JSON
clean_liferay_sso_jar Clean the KonaKart Liferay SSO classes and jar
clean_manifest_file Clean the MANIFEST file for all jars
clean_portlet_war Clears away the portlet war
clean_torque_classes Clears away the generated torque artifacts
clean_wars Clears away all the WARs and EARs
compile Compile the customisable application code
compile_admin_portlet_liferay Compile the Admin portlet utilities for Liferay
compile_adminappn Compile the customisable admin appn code
compile_adminappnEE Compile the customisable admin appnEE code
compile_appEngEE Compile the customisable appEngEE code
compile_appn Compile the customisable appn code
compile_appnEE Compile the customisable appnEE code
compile_customAdminService Compile the Custom Admin Service code
compile_customAdminService_json Compile the Custom Admin Service code including JSON
compile_customStoreService Compile the Custom Store Service code
compile_customStoreService_json Compile the Custom Store Service code - including JSON
compile_custom_adminengine Compile the customisable admin engine code
compile_custom_engine Compile the customisable engine code
compile_konakartadmin_app Compile the konakartadmin_app code
compile_modules Compile the customisable module code
compile_utils Compile the customisable utils code
copy_jars Copy selected custom konakart jars to the lib
directories
create_konakartadmin2 Create the konakartadmin2 webapp
create_torque_classes Process the Custom Schema to produce torque classes
debugenv Debug the environment
deploy_customAdminService Deploys the Custom Admin Service
deploy_customDB Deploys the Custom Database Jar
deploy_customStoreService Deploys the Custom Store Service
enable_ERPIntegration Enable ERP Integration - EE Only
.. continued below
enable_JAXWS Enable JAX Web Services in konakart web.xml - BE or
EE Only
enable_JSON Enable JSON in konakart web.xml - BE or EE Only
enable_JSON_CAS Enable JSON Custom Admin Service in konakartadmin
web.xml - BE or EE Only
enable_JSON_CSS Enable JSON Custom Store Service in konakart web.xml
- BE or EE Only
enable_KKAdmin_JAXWS Enable JAX Web Services in konakartadmin web.xml -
BE or EE Only
enable_KKAdmin_JSON Enable KKAdmin JSON in konakartadmin web.xml - BE or
EE Only
enable_KKAdmin_RMI Enable KKAdmin RMI in konakartadmin web.xml - EE Only
enable_KonaKart_Messenger Enable KonaKart Messenger in konakart web.xml - EE Only
enable_MQ Enable MQ in konakart web.xml
enable_RMI Enable RMI in konakart web.xml - EE Only
execute_sql_file Execute the specified SQL file
generate_customAdminService Builds the Custom Admin Service code
generate_customAdminService_json Builds the Custom Admin Service code - JSON
generate_customStoreService Builds the Custom Store Service code
generate_customStoreService_json Builds the Custom Store Service code - JSON
generate_torque_java Process the Custom Schema to produce torque java files
load_custom_mago_sql Load the Custom Mago SQL commands
load_mago_sql Load the Mago SQL commands
mago_debugenv Debug the Mago Set-up environment
mago_setup Sets up the Integration with Mago
make_admin_liferay_portlet_war Create the konakartadmin portlet war for Liferay
make_ear Create the konakart EAR
make_eclipse_project Create an Eclipse Project for Developing the Struts-2
Storefront
make_eclipse_wizard_project Create an Eclipse Project for Developing the Product
Creation Wizard
make_jar_appEngEE Create the konakart_app jar
make_jar_custom Create konakart_custom jar
make_jar_customAdminService Create the konakartadmin_custom_admin_service jar
make_jar_customDB Create the konakart_custom_db jar
make_jar_customEE Create the konakart_customEE jar
make_jar_customStoreService Create the konakart_custom_store_service jar
make_jar_custom_admin Create the konakartadmin_custom jar
make_jar_custom_adminEE Create the konakartadmin_customEE jar
make_jar_custom_adminengine Create the konakartadmin_custom_engine jar
make_jar_custom_engine Create the konakart_custom_engine jar
make_jar_custom_utils Create the konakart_custom_utils jar
make_jar_konakartadmin_app Create the konakartadmin_app jar
make_jars Create the konakart custom jars
make_liferay_portlet_war Create the KonaKart portlet war for Liferay
make_liferay_portlet_wars Create the KonaKart and KonaKartAdmin portlet wars for
Liferay
make_liferay_sso_jar Create the KonaKart Liferay SSO jar
make_manifest_file Create the MANIFEST file for all jars
make_ordertotal_module_jar Create the ordertotal module jar
make_other_module_jar Create the other module jar
make_payment_module_jar Create the payment module jar
make_shipping_module_jar Create the shipping module jar
make_wars Create the konakart wars
print_classpaths Print the classpaths for diagnostic purposes
print_custom_classpath prints the specified classpath
reset_database Removes the default KonaKart database set-up
Default target: build
You can compile and copy the relevant jars in one statement, as follows:
C:\KonaKart\custom>.\bin\ant build,copy_jars
Buildfile: build.xml
clean_torque_classes:
clean_portlet_war:
[echo] Cleanup portlet WARs...
[echo] Cleanup portlet classes...
[echo] Cleanup portlet WAR staging area...
clean_admin_portlet_war:
[echo] Cleanup admin portlet WARs...
[echo] Cleanup admin portlet WAR staging area...
clean_wars:
[echo] Cleanup WARs...
[echo] Cleanup EARs...
clean:
[echo] Cleanup...
generate_torque_java:
create_torque_classes:
make_manifest_file:
[echo] Create the MANIFEST.MF file for all jars
compile:
[echo] Compile the customisable application code
compile_appn:
[echo] Copy the properties over to C:\KonaKart\custom/appn/classes
[copy] Copying 3 files to C:\KonaKart\custom\appn\classes
[echo] Compile the customisable application code
[javac] Compiling 133 source files to C:\KonaKart\custom\appn\classes
compile_appnEE:
[echo] Compile the customisable appnEE code
[mkdir] Created dir: C:\KonaKart\custom\appnEE\classes
[javac] Compiling 5 source files to C:\KonaKart\custom\appnEE\classes
compile_appEngEE:
[echo] Compile the customisable appnEE code
[mkdir] Created dir: C:\KonaKart\custom\appEngEE\classes
[javac] Compiling 38 source files to C:\KonaKart\custom\appEngEE\classes
compile_adminappn:
[mkdir] Created dir: C:\KonaKart\custom\adminappn\classes
[javac] Compiling 10 source files to C:\KonaKart\custom\adminappn\classes
compile_adminappnEE:
[echo] Compile the customisable adminappnEE code
[mkdir] Created dir: C:\KonaKart\custom\adminappnEE\classes
[javac] Compiling 2 source files to C:\KonaKart\custom\adminappnEE\classes
compile_utils:
[echo] Compile the customisable utils code
[mkdir] Created dir: C:\KonaKart\custom\utils\classes
[javac] Compiling 3 source files to C:\KonaKart\custom\utils\classes
compile_modules:
[echo] Compile the customisable module code
[mkdir] Created dir: C:\KonaKart\custom\modules\classes
[javac] Compiling 152 source files to C:\KonaKart\custom\modules\classes
(- the middle section has been cut out here -)
make_other_module_jar:
[echo] Create the other module jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_others_uspsaddrval.jar
compile_custom_engine:
[echo] Compile the customisable engine code
[mkdir] Created dir: C:\KonaKart\custom\engine\classes
[javac] Compiling 241 source files to C:\KonaKart\custom\engine\classes
compile_custom_adminengine:
[echo] Compile the customisable admin engine code
[mkdir] Created dir: C:\KonaKart\custom\adminengine\classes
[javac] Compiling 441 source files to C:\KonaKart\custom\adminengine\classes
make_jars:
[echo] Create the konakart custom jars
make_jar_custom:
[echo] Create the konakart_custom.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_custom.jar
make_jar_customEE:
[echo] Create the konakart_customEE.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_customEE.jar
make_jar_custom_engine:
[echo] Create the konakart_custom_engine.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_custom_engine.jar
make_jar_appEngEE:
[echo] Create the konakart_app.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_app.jar
make_jar_custom_utils:
[echo] Create the konakart_custom_utils.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakart_custom_utils.jar
make_jar_custom_admin:
[echo] Create the konakartadmin_custom.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakartadmin_custom.jar
make_jar_custom_adminEE:
[echo] Create the konakartadmin_customEE.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakartadmin_customEE.jar
make_jar_custom_adminengine:
[echo] Create the konakartadmin_custom_engine.jar
[jar] Building jar: C:\KonaKart\custom\jar\konakartadmin_custom_engine.jar
make_torque_jar:
build:
copy_jars:
[echo] Copy the custom jars to their respective lib directories
[copy] Copying 54 files to C:\KonaKart\webapps\konakartadmin\WEB-INF\lib
[echo] Copy the custom jars to their respective lib directories
[copy] Copying 55 files to C:\KonaKart\webapps\konakart\WEB-INF\lib
BUILD SUCCESSFUL
Define the Engine Implementation Class
Your custom code will never be executed if we don't define that KonaKart should instantiate the KKAdminCustomEng class as its engine class rather than the default, which is KKAdmin.
A small java program is provided in the download kit (called /java_api_examples/src/com/konakartadmin/apiexamples/CustomExamples.java ) which demonstrates how you would call one version of custom() or the other from a java program.
The code in CustomExamples.java actually calls custom() three times, once with the default com.konakartadmin.bl.KKAdmin engine, once with the com.konakartadmin.app.KKAdminCustomEng engine and finally using the web services client engine, called com.konakartadmin.ws.KKWSAdmin .
When calling using the default com.konakartadmin.bl.KKAdmin engine you should see the default response from custom() which is a null being returned.
When calling using the com.konakartadmin.app.KKAdminCustomEng engine you should see the response from the custom() implementation that we coded above (i.e. it should return the highest orderId in the database).
Finally when calling using the com.konakartadmin.app.KKAdminCustomEng engine, what you see depends on which engine the web services are configured to use (they could be using the default com.konakartadmin.bl.KKAdmin engine or the custom com.konakartadmin.app.KKAdminCustomEng engine). Which engine is used in this case is defined in the konakartadmin.properties file as follows:
# ------------------------------------------------------------------ # KonaKart engine class used by the admin web services # For the default engine use: com.konakartadmin.bl.KKAdmin # For the custom engine use: com.konakartadmin.app.KKAdminCustomEng konakart.admin.ws.engine.classname = com.konakartadmin.bl.KKAdmin
The above definition is for the Admin App engine class name definition. An equivalent engine class name definition is required for the application web services, and this is defined in konakart.properties (you can find this under webapps\konakart\WEB-INF\classes )
# ------------------------------------------------------------------ # KonaKart engine class used by the web services # For the default engine use: com.konakart.app.KKEng # For the custom engine use: com.konakart.app.KKCustomEng konakart.app.ws.engine.classname = com.konakart.app.KKEng
Finally, to actually run the CustomExamples , change directory to the java_api_examples directory where there is another ANT build file for building and running the examples. (You will have to start the KonaKart server before running the CustomExamples test if you want a response from the web service call!):
This shows the commands to execute:
C:\KonaKart\custom>.\bin\kkant > customBuild.log C:\KonaKart\custom>.\bin\kkant enable_JAXWS enable_KKAdmin_JAXWS C:\KonaKart\custom>..\bin\startkonakart.bat C:\KonaKart\custom>cd ..\java_api_examples C:\KonaKart\java_api_examples>..\custom\bin\kkant build
At the end of a build process some examples are executed. You should see these executing successfully with no exceptions.
We will illustrate how this is done with an example using the getCustomerForId() Admin API call.
The default implementation of getCustomerForId() returns an AdminCustomer object for the specified customer Id.
Suppose you want to change the data returned for whatever reason. It may be that you have customer data in another table somewhere that you would like to look up and add to the AdminCustomer object whenever getCustomerForId() is called (this other table may or may not be a KonaKart table).
Anyway, to keep this really simple so that we don't lose track of the point of this example we will set the String value "CUSTOM SETTING" in the custom5 attribute of the AdminCustomer object that is returned. This does mean we will overwrite the previous custom5 attribute value if such existed - so you in a proper implementation will have to be aware of which fields are freely available for your use (the custom fields are designed for customers to use in ways that they see fit).
Move the GetCustomerForId.java file to the src directory tree.
We need to modify the default implementation and to do this we move the file from the gensrc directory tree to the src directory tree, specifically, this means we need to move the GetCustomerForId.java from /custom/adminengine/gensrc/com/konakartadmin/app to /custom/adminengine/src/com/konakartadmin/app .
Add our customizations to GetCustomerForId.java
By default the implementation of GetCustomerForId.java is as follows:
/**
* The KonaKart Custom Engine - GetCustomerForId
* Generated by CreateKKAdminCustomEng
*/
public class GetCustomerForId
{
KKAdmin kkAdminEng = null;
/**
* Constructor
*/
public GetCustomerForId(KKAdmin _kkAdminEng)
{
kkAdminEng = _kkAdminEng;
}
public AdminCustomer getCustomerForId(
String sessionId, int customerId) throws KKAdminException
{
return kkAdminEng.getCustomerForId(sessionId, customerId);
}
}
We will add our simple changes so that it looks like this: (this file is included in the download kit under the custom/adminengine/examples directory structure)
public AdminCustomer getCustomerForId
(String sessionId, int customerId) throws KKAdminException
{
// Leave the original call to the KonaKart API unchanged
AdminCustomer myCustomer = kkAdminEng.getCustomerForId(sessionId, customerId);
// Now add our special value into custom5:
// (we may have got this value from a database query?)
myCustomer.setCustom5("CUSTOM SETTING");
return myCustomer;
}
Compile the new GetCustomerForId class and rebuild the jars:
An ANT build file is provided for this purpose - under the custom directory in the download kit.
C:\KonaKart\custom>bin\kkant -p
Buildfile: build.xml
Main targets:
build Compiles all the custom code and creates all the jars
clean Clears away everything that's created during a build
clean_admin_portlet_war Clears away the admin portlet war
clean_custom_admin_service_classes Clears away the generated custom admin service
artifacts
clean_custom_admin_service_classes_json Clears away the generated custom admin service
artifacts
- JSON
clean_custom_store_service_classes Clears away the generated custom store service
artifacts
clean_custom_store_service_classes_json Clears away the generated custom store service
artifacts
- JSON
clean_liferay_sso_jar Clean the KonaKart Liferay SSO classes and jar
clean_manifest_file Clean the MANIFEST file for all jars
clean_portlet_war Clears away the portlet war
clean_torque_classes Clears away the generated torque artifacts
clean_wars Clears away all the WARs and EARs
compile Compile the customisable application code
compile_admin_portlet_liferay Compile the Admin portlet utilities for Liferay
compile_adminappn Compile the customisable admin appn code
compile_adminappnEE Compile the customisable admin appnEE code
compile_appEngEE Compile the customisable appEngEE code
compile_appn Compile the customisable appn code
compile_appnEE Compile the customisable appnEE code
compile_customAdminService Compile the Custom Admin Service code
compile_customAdminService_json Compile the Custom Admin Service code including JSON
compile_customStoreService Compile the Custom Store Service code
compile_customStoreService_json Compile the Custom Store Service code - including JSON
compile_custom_adminengine Compile the customisable admin engine code
compile_custom_engine Compile the customisable engine code
compile_konakartadmin_app Compile the konakartadmin_app code
compile_modules Compile the customisable module code
compile_utils Compile the customisable utils code
copy_jars Copy selected custom konakart jars to the lib
directories
create_konakartadmin2 Create the konakartadmin2 webapp
create_torque_classes Process the Custom Schema to produce torque classes
debugenv Debug the environment
deploy_customAdminService Deploys the Custom Admin Service
deploy_customDB Deploys the Custom Database Jar
deploy_customStoreService Deploys the Custom Store Service
enable_ERPIntegration Enable ERP Integration - EE Only
.. continued below
enable_JAXWS Enable JAX Web Services in konakart web.xml - BE or
EE Only
enable_JSON Enable JSON in konakart web.xml - BE or EE Only
enable_JSON_CAS Enable JSON Custom Admin Service in konakartadmin
web.xml - BE or EE Only
enable_JSON_CSS Enable JSON Custom Store Service in konakart web.xml
- BE or EE Only
enable_KKAdmin_JAXWS Enable JAX Web Services in konakartadmin web.xml -
BE or EE Only
enable_KKAdmin_JSON Enable KKAdmin JSON in konakartadmin web.xml - BE or
EE Only
enable_KKAdmin_RMI Enable KKAdmin RMI in konakartadmin web.xml - EE Only
enable_KonaKart_Messenger Enable KonaKart Messenger in konakart web.xml - EE Only
enable_MQ Enable MQ in konakart web.xml
enable_RMI Enable RMI in konakart web.xml - EE Only
execute_sql_file Execute the specified SQL file
generate_customAdminService Builds the Custom Admin Service code
generate_customAdminService_json Builds the Custom Admin Service code - JSON
generate_customStoreService Builds the Custom Store Service code
generate_customStoreService_json Builds the Custom Store Service code - JSON
generate_torque_java Process the Custom Schema to produce torque java files
load_custom_mago_sql Load the Custom Mago SQL commands
load_mago_sql Load the Mago SQL commands
mago_debugenv Debug the Mago Set-up environment
mago_setup Sets up the Integration with Mago
make_admin_liferay_portlet_war Create the konakartadmin portlet war for Liferay
make_ear Create the konakart EAR
make_eclipse_project Create an Eclipse Project for Developing the Struts-2
Storefront
make_eclipse_wizard_project Create an Eclipse Project for Developing the Product
Creation Wizard
make_jar_appEngEE Create the konakart_app jar
make_jar_custom Create konakart_custom jar
make_jar_customAdminService Create the konakartadmin_custom_admin_service jar
make_jar_customDB Create the konakart_custom_db jar
make_jar_customEE Create the konakart_customEE jar
make_jar_customStoreService Create the konakart_custom_store_service jar
make_jar_custom_admin Create the konakartadmin_custom jar
make_jar_custom_adminEE Create the konakartadmin_customEE jar
make_jar_custom_adminengine Create the konakartadmin_custom_engine jar
make_jar_custom_engine Create the konakart_custom_engine jar
make_jar_custom_utils Create the konakart_custom_utils jar
make_jar_konakartadmin_app Create the konakartadmin_app jar
make_jars Create the konakart custom jars
make_liferay_portlet_war Create the KonaKart portlet war for Liferay
make_liferay_portlet_wars Create the KonaKart and KonaKartAdmin portlet wars for
Liferay
make_liferay_sso_jar Create the KonaKart Liferay SSO jar
make_manifest_file Create the MANIFEST file for all jars
make_ordertotal_module_jar Create the ordertotal module jar
make_other_module_jar Create the other module jar
make_payment_module_jar Create the payment module jar
make_shipping_module_jar Create the shipping module jar
make_wars Create the konakart wars
print_classpaths Print the classpaths for diagnostic purposes
print_custom_classpath prints the specified classpath
reset_database Removes the default KonaKart database set-up
Default target: build
You can compile and copy the relevant jars in one statement, as follows:
C:\KonaKart\custom>.\bin\kkant build,copy_jars
Define the Engine Implementation Class
Your custom code will never be executed if we don't define that KonaKart should instantiate the KKAdminCustomEng class as its engine class rather than the default, which is KKAdmin .
A small java program is provided in the download kit (called /java_api_examples/src/com/konakartadmin/apiexamples/GetCustomerExamples.java ) which demonstrates how you would call one version of getCustomerForId() or the other from a java program.
The code in GetCustomerExamples.java actually calls getCustomerForId() three times, once with the default com.konakartadmin.bl.KKAdmin engine, once with the com.konakartadmin.app.KKAdminCustomEng engine and finally using the web services client engine, called com.konakartadmin.ws.KKWSAdmin .
When calling using the default com.konakartadmin.bl.KKAdmin engine you should see the default response from getCustomerForId() which should show a null being returned for the custom5 attribute (unless you fill in these values with something else in your own implementation).
When calling using the com.konakartadmin.app.KKAdminCustomEng engine you should see the response from the getCustomerForId() implementation that we coded above (i.e. it should return "CUSTOM SETTING" in the custom5 attribute).
Finally when calling using the com.konakartadmin.app.KKAdminCustomEng engine, what you see depends on which engine the web services are configured to use (they could be using the default com.konakartadmin.bl.KKAdmin engine or the custom com.konakartadmin.app.KKAdminCustomEng engine). Which engine is used in this case is defined in the konakartadmin.properties file as follows:
# ------------------------------------------------------------------ # KonaKart engine class used by the admin web services # For the default engine use: com.konakartadmin.bl.KKAdmin # For the custom engine use: com.konakartadmin.app.KKAdminCustomEng konakart.admin.ws.engine.classname = com.konakartadmin.bl.KKAdmin
The above definition is for the Admin App engine class name definition. An equivalent engine class name definition is required for the application web services, and this is defined in konakart.properties (you can find this under webapps\konakart\WEB-INF\classes )
# ------------------------------------------------------------------ # KonaKart engine class used by the web services # For the default engine use: com.konakart.app.KKEng # For the custom engine use: com.konakart.app.KKCustomEng konakart.app.ws.engine.classname = com.konakart.app.KKEng
Finally, to actually run the GetCustomerExamples , change directory to the java_api_examples directory where there is another ANT build file for building and running the examples. (You will have to start the KonaKart server before running the CustomExamples test if you want a response from the web service call!). Enter the following commands:
C:\KonaKart\custom>cd ../java_api_examples
C:\KonaKart\java_api_examples>
..\custom\bin\ant clean, compile, runGetCustomerExamples
At the end of a build process you should see the example program was executed successfully with no exceptions.
So, you've made some engine customizations as described above and you want them to be executed when you run KonaKart.
Assuming you have placed all the newly-built jars in the appropriate lib directories (the ANT build copy_jars target will do this for you in a standard tomcat installation) you have to modify some properties files to make KonaKart instantiate the custom engines so that your customizations will actually be executed.
There is a lot of flexibility here as you can define different engines in different places. It's advisable to change only those engine definitions that you need to change however.
webapps/konakart/WEB-INF/classes/konakart_app.properties
Defines which engine the main Struts Application will use
# ------------------------------------------------------------------ # KonaKart engine class used by the KonaKart Application users # # For the default engine use: com.konakart.app.KKEng # For the JAXWS engine use: com.konakart.jws.KKJAXWSEng # For the web services engine use: com.konakart.app.KKWSEng # For the RMI services engine use: com.konakart.rmi.KKRMIEng # For the JSON services engine use: com.konakart.json.KKJSONEng konakart.app.engineclass = com.konakart.app.KKEng
webapps/konakart/WEB-INF/classes/konakart.properties
Defines which engine the Application web services will use
# ------------------------------------------------------------------ # KonaKart engine class used by the web services # For the default engine use: com.konakart.app.KKEng # For the custom engine use: com.konakart.app.KKCustomEng konakart.app.ws.engine.classname = com.konakart.app.KKEng
webapps/konakartadmin/WEB-INF/classes/konakartadmin.properties
Defines which engine the Administration web services will use
# ------------------------------------------------------------------ # KonaKart engine class used by the admin web services # For the default engine use: com.konakartadmin.bl.KKAdmin # For the custom engine use: com.konakartadmin.app.KKAdminCustomEng konakart.admin.ws.engine.classname = com.konakartadmin.bl.KKAdmin
webapps/konakartadmin/WEB-INF/classes/konakartadmin_gwt.properties
Defines which engine the GWT Admin Application will use
# ---------------------------------------------------------------------- # KonaKart engine class used by the KonaKart Admin Application users # # For the default engine use: com.konakartadmin.bl.KKAdmin # For the web services engine use: com.konakartadmin.ws.KKWSAdmin # For the RMI services engine use: com.konakartadmin.rmi.KKRMIAdminEng # For the JSON services engine use: com.konakartadmin.json.KKJSONAdminEng # For the JAXWS services engine use: com.konakartadmin.jws.KKJAXWSAdmin konakartadmin.gwt.engineclass=com.konakartadmin.bl.KKAdmin #konakartadmin.gwt.engineclass=com.konakartadmin.ws.KKWSAdmin #konakartadmin.gwt.engineclass=com.konakartadmin.rmi.KKRMIAdminEng #konakartadmin.gwt.engineclass=com.konakartadmin.json.KKJSONAdminEng #konakartadmin.gwt.engineclass=com.konakartadmin.jws.KKJAXWSAdmin