KonaKart (Enterprise Extensions Only) provides the functionality to post messages to and read messages from java Message Queues with the integration of the Apache ActiveMQ messaging framework.
The Business Edition of KonaKart has limited support for message queues. It supports only the sending of messages to a RabbitMQ message queue.
According to their web site ( ActiveMQ ) Apache ActiveMQ is the most popular and powerful open source messaging and Integration Patterns provider. ActiveMQ fully supports JMS 1.1 with support for transient, persistent, transactional and XA messaging.
Whilst ActiveMQ has a rich and extensive feature set the integration from KonaKart only accesses a small fraction of the available functionality.
The integration from KonaKart allows the programmer to post messages to a specified message queue ("postMessageToQueue") and read messages from a specified message queue ("readMessageFromQueue"). Engine API calls are provided to make these fundamental queue operations extremely easy to use. Note that these two calls provide very easy-to-use message manipulation functions but do not expose the full power of ActiveMQ. In most cases the only message queue functionality required by a KonaKart system will be to post a simple message to a queue so the simple abstraction provided is helpful in that it masks all the underlying complexity. See the javadoc on these API calls for more details.
A typical use for a message queue within a KonaKart implementation is to ensure guaranteed delivery of an order to an external system. A common approach would be to post a message containing the order information to a message queue when that order reaches a certain status in KonaKart (for example, that status could be PAYMENT_RECEIVED). In KonaKart, a convenient place to add the code to do this is in the OrderIntegrationMgr and the AdminOrderIntegrationMgr. Rather than delivering the message to the external system from these classes and risking the loss of that communication if the external system was unavailable, the order can be placed on a message queue to be picked up by the external system when it comes back on line. The delivery to the message queue is guaranteed and running in the same JVM as KonaKart (the ActiveMQ broker is "embedded" in the konakart webapp).
Examples of posting order messages to a message queue are provided in the installation kits (in the OrderIntegratonMgr, the AdminOrderIntegrationMgr and in the java API examples). An example of reading messages from the order message queue is also provided (in the java API examples).
Whilst it's conceivable that you may wish to make use of the "readMessageFromQueue" API calls to read messages sent from external systems in your IT infrastructure, there are no implementations of this API call in the standard KonaKart installation (other than example code to demonstrate how to make the calls).
The ActiveMQ Broker is embedded in the konakart webapp. You need to uncomment the ActiveMQ section in the konakart web.xml to enable the start-up of the broker and define a number of parameters:
<!-- Servlet for Apache Message Queue ApacheMQ Server parameters: uri = The broker URI mqEnabled = Enable (true) or Disable (false) the Apache Message Queue mqRandomConnNames = If true (the default) Connector Names are randomised mqJMXRMIPort = The management port for JMX RMI connections (default is 1099) mqName = A name for this Broker to make it unique (. + hostname will be added) mqAdminUserName = admin username mqAdminUserPassword = admin password mqUserUserName = username mqUserPassword = password mqKonaKartQStub = users are authorised to use Queue Names starting with this prefix mqStoreLimitMB = disk space (in MB) reserved for persistent messages (using KahaDB) mqTempLimitMB = disk space (in MB) reserved for non-persistent messages mqMemoryLimitMB = JVM Memory (in MB) available for the broker mqSchedulerSupport = Include (true) or exclude (false) Scheduler Support mqPropertiesFile = name of the properties file containing additional configurations --> <!-- Apache ActiveMQ --> <servlet> <servlet-name>KonakartMQServlet</servlet-name> <display-name>KonaKart MQ</display-name> <description>KonaKart MQ</description> <servlet-class>com.konakart.mq.KKMQServer</servlet-class> <init-param> <param-name>uri</param-name><param-value>tcp://localhost:8791</param-value> </init-param> <init-param> <param-name>mqEnabled</param-name><param-value>true</param-value> </init-param> <init-param> <param-name>mqJMXRMIPort</param-name><param-value>1099</param-value> </init-param> <init-param> <param-name>mqName</param-name><param-value>KonaKart.Broker.1</param-value> </init-param> <init-param> <param-name>mqAdminUserName</param-name><param-value>kkadmin</param-value> </init-param> <init-param> <param-name>mqAdminUserPassword</param-name><param-value>princess</param-value> </init-param> <init-param> <param-name>mqUserUserName</param-name><param-value>kkuser</param-value> </init-param> <init-param> <param-name>mqUserPassword</param-name><param-value>prince</param-value> </init-param> <init-param> <param-name>mqKonaKartQStub</param-name><param-value>KonaKart.</param-value> </init-param> <init-param> <param-name>mqStoreLimitMB</param-name><param-value>1024</param-value> </init-param> <init-param> <param-name>mqTempLimitMB</param-name><param-value>256</param-value> </init-param> <init-param> <param-name>mqMemoryLimitMB</param-name><param-value>64</param-value> </init-param> <init-param> <param-name>mqSchedulerSupport</param-name><param-value>true</param-value> </init-param> <init-param> <param-name>mqPropertiesFile</param-name><param-value>konakart.properties</param-value> </init-param> <load-on-startup>20</load-on-startup> </servlet>
In addition to the parameters in the konakart web.xml you must also define properties in the konakart.properties and konakartadmin.proprties files as follows:
# ----------------------------------------------------------------------------------- # Message Queue Configuration konakart.mq.broker.uri = tcp://localhost:8791 konakart.mq.username = kkuser konakart.mq.password = prince konakart.mq.orders.queue = KonaKart.Orders.Queue #konakart.mq.ERP.queue = KonaKart.ERP.Q # Extended Configuration for Network / Broker / Queue Configurations # If these are set, by uncommenting, NetworkConnections are set up with the specified # statically-defined Queue and credentials #konakart.mq.connector.store1.uri = static:(tcp://localhost:61616) #konakart.mq.connector.store1.queue = KonaKart.store1.Q #konakart.mq.connector.store1.user = user_store1 #konakart.mq.connector.store1.password = prince_store1 #konakart.mq.connector.store2.uri = static:(tcp://localhost:61617) #konakart.mq.connector.store2.queue = KonaKart.store2.Q #konakart.mq.connector.store2.user = user_store2 #konakart.mq.connector.store2.password = prince_store2
The "konakart.mq.broker.uri" property defines the URI of the broker.
The "konakart.mq.username" and "konakart.mq.password" properties define the credentials used to post and read messages.
The "konakart.mq.orders.queue" property defines the name of the queue to post messages to and read messages from. Note that the prefix "KonaKart." matches the "mqKonaKartQStub" parameter in the web.xml. The "mqUserUserName" defined in the web.xml (and also here in the konakart.properties file) is authorised to post messages to and read messages from queues whose name begins with this prefix.
By default the location for the broker's persistent data is defined to be "%CATALINA_HOME%/mq". This is defined in the startkonakart.bat and startkonakart.sh scripts in the KonaKart\bin directory. The location is defined as a System Property called "activemq.store.dir" and by default it is added to the CATALINA_OPTS environment variable in the above scripts.
The extended properties are for setting up network connections to remote brokers for defining a topology of queues.
Apache ActiveMQ provides a web-based monitoring tool which can be configured to monitor and administer the ActiveMQ message queue embedded within KonaKart. This tool is free and can be downloaded from the ActiveMQ website.
For basic monitoring tasks it's also very easy to use the jconsole tool that's provided in your java/bin directory.
By default the API calls on the KonaKart engine (KKEngIf) must be executed using the default Session.AUTO_ACKNOWLEDGE mode. This is fine for most purposes and has the advantage that the APIs can be used over the remote APIs (such as JSON) and in a load-balanced environment.
If, however, you require transactional control over message processing, functionality is exposed on the message queue manager (MqMgrIf) to allow a finer level of control (and higher-performance message processing as well).
For transactional control you need to set the mode (on the MqOptionsIf object) to Session.SESSION_TRANSACTED.
An example of transactional message processing is provided in the java_api_example that can be found in all Enterprise installations under the installation home at "/java_api_examples/src/com/konakart/apiexamples/MqMessageProcessing.java"
The example program shows how to use commit and delayMessage interfaces on MqMgrIf in order to have greater control over the processing of messages on Queues.
Refer to the javadoc on MqMgrIf and MqOptionsIf for more details.