Download Extending Java Message Service messaging to retail store devices

Extending Java Message Service messaging to retail
store devices
Andreas Dannhauer ([email protected])
IBM Software Group Lab Services, Boeblingen, Germany
Stefan Fassmann ([email protected])
IBM Lab Services, Boeblingen, Germany
Gerald Kallas ([email protected] )
IBM Sales & Distributions, Düsseldorf, Germany
January 2011
© Copyright International Business Machines Corporation 2011. All rights reserved.
Summary: This paper explains how to enable near-real-time business processing using a
JavaTM Message Service (JMS) example for Java applications running on IBM® 4690 POS
Controllers.
Table of Contents
1 Introduction..........................................................................................................................1
2 Typical retail store integration solutions...............................................................................2
2.1 Business context..........................................................................................................2
2.2 Solution approach........................................................................................................3
3 Extending secure and reliable messaging to the last mile...................................................4
3.1 JMS Client....................................................................................................................5
3.2 The “IBM 4690 JMS Persistence Adapter” asset.........................................................6
4 Integrating IBM messaging technology into in-store devices...............................................7
4.1 Integrating the JMS Buffered Client into a POS Java application................................8
4.2 Configuring the JMS Provider in Lotus Expeditor Integrator®....................................13
4.3 Testing the created example......................................................................................15
5 Conclusion.........................................................................................................................18
6 Resources.........................................................................................................................18
7 About the authors..............................................................................................................18
Disclaimer.............................................................................................................................19
1 Introduction
Retail companies face very difficult competition. The only way to further reduce costs is
seen in streamlining business processes, and business process flexibility and automation
requires state-of-the-art IT systems.
Furthermore, expanding businesses to new locations and---most of all---moving into remote
markets challenge existing IT systems. Reliable and secure data transmission between
remote stores and backend infrastructure is key to ensuring continuous business and
availability.
1
Business analytics and optimization must support ad hoc decisions and reactions to market
and environment changes. Analytical investigations need the most current data (for
example, store revenue / transaction data), and subsequent actions must be processed
instantly (for example, distribution of price updates to stores).
Existing, traditional, time-triggered batch processing and data transport technologies like
File Transfer Protocol (FTP) or even Microsoft® Windows® shares are not able to fulfill
these requirements reliably, securely, and economically, if network connections are slow
and unreliable. Messaging technology addresses these drawbacks and adds the potential
for data-triggered transmission and transactional processing.
Messaging is already recognized as the backbone data transport mechanism in serviceoriented IT infrastructures. In today's retail business, data transmission based on messaging
technology is extended not only to the store but into the store. To achieve seamless end-toend integration, it is recommended that all connected devices and appliances in the store
also use messaging technology.
This paper is intended for IT architects and developers, discussing the advantages of
extending messaging technologies to the last mile in retail stores.
First, we introduce a typical solution for integration of retail stores with existing enterprise
systems in secure and transactional manner. Then we explain in detail how messaging
technology can be easily extended to in-store devices (for example, integration in Point-ofSales POS systems).
Java implementation recommendations and code samples are provided so that developers
are able to include messaging in their Java programs quickly.
2 Typical retail store integration solutions
Let's begin by discussing typical retail-store integration solutions based on secure and
reliable messaging.
2.1 Business context
In the retail industry, there's a common scenario that data such as item and price
information needs to be transferred from enterprise systems down to stores and from stores
up to the enterprise (for example, sales transaction data).
Historically coming from the batch-oriented approach, these data transfer processes are
often realized with simple file transfer (FTP, local file system). However, today's retail
business is changing in several ways:
•
Opening hours of retail stores are dramatically extended (24 x 7 opening hours),
especially in emerging countries.
•
Retailers want to know sales transaction summaries in near real time, to be able to
react faster with their order processes.
•
The transfer of data must be faster and more efficient to support core retail business
processes like promotions.
All these factors lead to an approach that requires a reliable and appropriately monitored
near-real-time data transfer.
2
All these requirements can be fulfilled with the introduction of a messaging backbone that
provides the following features to retail business:
•
•
guaranteed data transfer (if required, “once and only once and in stringent order”)
strict decoupling of business logic and processing from underlying infrastructure
Different messaging and service stacks help to satisfy different Service Level Agreements
(SLAs) at the central side and the store side. The underlying infrastructure stack must
provide seamless messaging transport with the ability to monitor all transactions.
In terms of business, the last mile becomes increasingly important. For example, if data
transaction records are sent down to a store, it must be ensured that these records are
processed successfully (for example, that a price update was applied to the POS system).
This requires that business applications must be enhanced with additional capabilities to
send / receive (monitoring and status) data so that instant status feedback about data
processing can be given. At the same time, these extensions must be as non-intrusive as
possible.
2.2 Solution approach
Typically, retailers have started rolling out secure and reliable messaging to (1) provide data
to the store (price updates, scale and label printer data) and to (2) collect data from the
store (transaction data, invoice data) in a transactional context.
Figure 1 shows an architectural overview of such a solution.
Figure 1. Architectural overview
3
Monitoring systems such as the IBM WebSphere® Business Monitor and IBM Tivoli®
Enterprise Console can alert business process owners about process execution status (data
distribution and/or data pick up processes).
The messaging hub inside the store is the IBM Lotus® Expeditor integrator in this example.
It forwards and picks up the data in a transactional manner to/from in-store systems like
POS systems, scales, and label printers, using existing legacy transport protocols.
It therefore must support the required interfaces like FTP, Secure Shell (SSH), HTTP, Java
Database Connectivity (JDBC), Local File System, and Windows shares. The following list
describes the key components in our example:
•
Enterprise Service Bus. This component is the central messaging bus in the enterprise
infrastructure. All retail stores are connected to the Enterprise Service Bus.
•
IBM Lotus Expeditor integrator (micro broker). Lotus Expeditor integrator provides a
lightweight integration hub for remote locations such as retail stores. It enables
straightforward business and application integration of the enterprise central office with
its retail stores in a reliable, flexible, and managed way.
It can even be deployed at remote locations with limited hardware and software
resources and with no skilled IT management available. Expeditor integrator interacts
with the POS systems, label printers, and scales for forwarding price update data, label
data, and scale data to the retail stores and for picking up transaction log and other
data from the retail store.
•
POS controller. This component controls the POS systems and manages the price data
and POS transaction data. For example, if an IBM 4690 system is used, it can be
connected to the Lotus Expeditor integrator component via the FTP interface.
•
Scales. This component controls the scales and manages the data required on the
scales, which are connected to the in-store server via Windows shares, FTP, or HTTP.
•
Label printer. This component/device prints the labels required in the retail store. The
label data is transferred via Windows shares between the in-store server and the label
printer.
3 Extending secure and reliable messaging to the last mile
This scenario extends standard messaging to the last mile inside the retail store, to attain
the following goals:
•
Overcome drawbacks of legacy interfaces like FTP not offering transactional support
•
Allow near-real-time information, such as report invoice data, to reach the backend
systems for every single transaction as soon as data is created by the POS
controller.
Figure 2 provides an overview of the proposed architecture.
4
Figure 2. Architectural overview of integration of in-store devices through JMS
In-store devices like POS systems, scales, and label printers are enhanced with standard
JMS messaging functionality to replace legacy interfaces like FTP and Windows shares.
The JMS interface between the in-store device and Lotus Expeditor integrator is realized via
integration of the IBM JMS Buffered Client into a Java application running on the in-store
device.
For the 4690 POS controller case, JMS is used instead of the FTP interface for
communicating from the IBM 4690 POS controller to the JMS provider contained in Lotus
Expeditor integrator (IBM micro broker).
The IBM 4690 supports Java version 1.4.2, and the integrated file system supports highavailability features like mirroring between the POS controllers (controlled via file attributes).
3.1 JMS Client
This component, being part of an application on the in-store devices, manages the JMS
connection to the Lotus Expeditor integrator. The JMS client is provided as a library and
must be integrated via an API. It cannot simply be installed on an in-store device; rather, it
must be integrated into every application that requires JMS messaging functionality.
The JMS client must fulfill the following requirements:
•
REQ_JMS_Client_001. Acts as a black box for the Java application, providing an
interface to send data to and receive data from IBM micro broker as the JMS Provider in
IBM Lotus Expeditor integrator.
5
Based on this general requirement the following requirements are derived:
•
REQ_JMS_Client_002. Connectivity handling. Handles connectivity to Lotus Expeditor
integrator (IBM micro broker). This includes establishing the JMS connection on startup,
monitoring the connection, and applying a reconnect policy in case of connection
outages.
•
REQ_JMS_Client_003. Message buffering. Messages handed over to the JMS Buffered
client in a “fire-and-forget” manner must be buffered to assure message delivery in case
of connection problems. As soon as the connection is re-established, buffered messages
must be automatically sent to IBM Lotus Expeditor integrator.
The buffering mechanism is also applied for the message-receiving procedure; as soon
as messages are received by the JMS Buffered Client from Lotus Expeditor, they are
buffered. The application processes the incoming messages one by one, and the
buffering mechanism assures that no message is lost, if processing by the application
takes additional time.
•
REQ_JMS_Client_004. Message persistence. Messages handed over to the JMS
Buffered Client must be persisted, to avoid message loss in case of application shutdown
and abnormal application stops. On application and client restart, persisted messages
must be read (recovered) and sent to Lotus Expeditor integrator.
Currently, three persistence adapters are shipped with Lotus Expeditor:
•
Memory persistence: This adapter stores messages only in the RAM.
•
Shutdown persistence: This adapter stores messages in the RAM. On normal
shutdown, the messages are persisted on the file system.
•
Full persistence: This adapter stores messages instantly in the file system after
receiving a message for processing (sending or receiving) for reliability reasons (to
prevent message losses under any circumstances).
3.2 The “IBM 4690 JMS Persistence Adapter” asset
A persistence adapter that specifically supports the IBM 4690 file system is not currently
part of the IBM Lotus Expeditor integrator product. However, the “IBM 4690 JMS
Persistence Adapter” is provided to customers and partners as an IBM Services Asset.
This adapter addresses the missing 4690 file-system attribute support in standard Java and
does the following:
•
Supports the native file system of IBM 4690 POS controller
•
Respects the constraints of the IBM 4690 file system, like:
◦
◦
•
restricted file names to the PC-DOS-style 8.3 file format.
total path length of files, including the directory names (must not exceed 26
characters)
Provides support for the specific file flags so that the messaging buffer being used is
automatically synchronized between 4690 primary and back-up controllers (file
mirroring for high-availability reasons).
6
The use of the 4690 JMS Persistence Adapter is transparent to the POS Java application,
which uses the IBM JMS Buffered Client. Only 4690-specific operating/file system
configuration parameters are required as configuration data. Figure 3 illustrates the
interaction between the JMS client and the Lotus Expeditor integrator in detail.
Figure 3. Message flow from JMS Buffered Client via Lotus Expeditor integrator to MQ
The IBM JMS Buffer Client is configured to connect to the JMS Provider (IBM micro broker)
in Lotus Expeditor integrator and to send the message to the XPDinteg_PosJmsClientQ
queue. As soon as the messages arrive on this queue, they are processed accordingly.
The JMS Resource Adapter, PosJmsClient_Adapter, monitors this queue and triggers the
Lotus Expeditor integrator flow engine to run the corresponding flow, to process the data in
the incoming messages.
The flow simply takes the message and writes it to the XPDinteg_ResOutQ queue, which is
bridged to the IBM WebSphere MQ backend infrastructure to send the message
automatically to the backend.
4 Integrating IBM messaging technology into in-store
devices
This section describes in detail how to integrate the JMS Buffered Client into a Java
application that runs on the in-store devices such as POS controllers, scales, and label
printers. We explain in detail how to integrate the JMS Buffered Client into an application
running on the IBM 4690 POS controller.
The same code can be used to run it on other systems supporting the Standard Java
technology. The differences are on the configuration side only and are clearly described.
7
4.1 Integrating the JMS Buffered Client into a POS Java
application
The IBM JMS Buffered Client needs to be programmatically integrated into Java
applications (for example, a Java application running on the IBM 4690 controller). The Client
is not a stand-alone application that can be deployed directly. The Java application and the
JMS Buffered Client that is used by this application must be packaged and deployed
together onto the target system, such as 4690 POS.
In this subsection we recommend how to integrate the JMS Buffered Client into a Java
application. The first part describes how to integrate a JMS Publisher for sending messages
from Java applications to Lotus Expeditor integrator (using IBM micro broker as JMS
Provider). The second part explains how a JMS Receiver can be developed for receiving
messages from Lotus Expeditor integrator.
Sample code is available in the Eclipse project “BufferedJmsClient4690AssetSample” as a
download accompanying this white paper. The code is based on best practices for using
JMS Buffered Clients. Figure 4 shows the package explorer view of the sample project.
Figure 4. Package explorer view of the JMS Buffered Client sample project
In the provided sample project, the Java libraries required to run the JMS Buffered Client
can be found in the “jar” folder, and these .jar files are as follows:
•
Messaging libraries (the most current version from the Lotus Expeditor integrator
version must be taken)
8
◦
◦
◦
◦
◦
◦
◦
◦
•
IBM 4690 JMS Persistence Adapter library (required only if the application runs on
the 4690 POS controller):
◦
•
com.ibm.micro.utils_3.0.1.4-20100929.jar
com.ibm.micro.utils.extended_3.0.1.4-20100929.jar
com.ibm.mqttclient.jms_3.0.1.4-20100929.jar
com.ibm.msg.client.commonservices.jar
com.ibm.msg.client.jms.internal.jar
com.ibm.msg.client.jms.jar
com.ibm.msg.client.provider.jar
com.ibm.pvc.jms_1.1.0.20090925-1604.jar
4690pers.jar
IBM 4690 specific classes (required only if the application runs on the 4690 POS
controller):
◦
OS4690.ZIP
The OS4690.ZIP file contains IBM 4690-specific Java classes to address 4690-specific
characteristics like the file system attributes. The 4690pers.jar file contains the 4690-specific
persistence adapter, required to persist messages on the native 4690 file system.
4.1.1 Create the JMS Publisher
The publisher is used to send messages from the POS application to the JMS Provider in
Lotus Expeditor integrator (micro broker). Listing 1 describes the parameters that must be
set to configure the JMS Buffered Client:
•
Connection factory name
•
Client name for this JMS Buffered Client (must be unique among all messaging
clients connecting to the instance of Lotus Expeditor integrator).
•
Connection string, containing the connection schema (tcp), and the IP address and
port of the micro broker in Lotus Expeditor integrator.
•
Buffer size, describing the maximum size, in bytes, for the message buffer used on
the hard disk.
•
Persistence type, which must to be set to user defined, to allow the use of the IBM
4690 JMS Persistence Adapter
Listing 1. Configuration parameters for the JMS Buffered Client - Publisher
// ------- connection factory settings ------// name for the JMS connection factory
private static final String CONNECTION_FACTORY_NAME =
MQTTConstants.MQTT_PROVIDER_NAME;
// unique name for the JMS client
private static final String CLIENT_NAME = "BufferedSender";
// URL to the micro broker instance
private static final String MB_CONNECTION_STRING =
MQTTConstants.MQTT_TCP_SCHEMA + "yourXPDintegIPAddress:1883";
// size of the buffer for storing messages in case the connectivity is
lost (in byte (512kb is the default))
9
private static final int BUFFER_SIZE =
MQTTConstants.DEFAULT_OUTBOUND_BUFFER_SIZE;
// type of persistence
private static final int PERSISTENCE_TYPE =
MQTTConstants.MQTT_PERSISTENCE_TYPE_USER_DEFINED;
// ------- end properties connection factory -------
If you want to use the JMS Buffered Client with the Standard Java technology, the following
persistence types can be set as well:
•
MQTTConstants.MQTT_PERSISTENCE_TYPE_NONE:
Messages are held purely in memory.
•
MQTTConstants.MQTT_PERSISTENCE_TYPE_SHUTDOWN:
Messages are persisted in the file system when the JMS Buffered Client is stopped
cleanly (see shutdown procedure).
•
MQTTConstants.MQTT_PERSISTENCE_TYPE_FULL:
Messages are persisted in the file system instantly after receiving a message for
processing (sending or receiving) for reliability reasons (prevent message losses
under any circumstances).
Next, we apply the above configuration data to the instantiated connection factory (see
listing 2).
Listing 2. Apply settings to the connection factory
ifLogger.info("START instantiating factory and setting properties");
JmsFactoryFactory jmsFactory =
JmsFactoryFactory.getInstance(CONNECTION_FACTORY_NAME);
iConnFactory = jmsFactory.createConnectionFactory();
iConnFactory.setBooleanProperty(MQTTConstants.MQTT_BUFFERED, true);
iConnFactory.setIntProperty(MQTTConstants.MQTT_OUTBOUND_BUFFER_SIZE,
BUFFER_SIZE);
iConnFactory.setIntProperty(MQTTConstants.MQTT_PERSISTENCE_TYPE,
PERSISTENCE_TYPE);
iConnFactory.setStringProperty(MQTTConstants.USER_DEFINED_PERSISTENCE,"com
.ibm.labsvcbb.mqttclient.utils.persistence.MqttPos4690FilePersistence");
iConnFactory.setStringProperty(MQTTConstants.MQTT_CONNECTION_URL,
MB_CONNECTION_STRING);
ifLogger.fine("FINISH instantiating factory and setting properties");
Here, the most important part is setting the user-defined persistence adapter to
com.ibm.labsvcbb.mqttclient.utils.persistence.MqttPos4690FilePersistence
so that the JMS Buffered Client can be run on the 4690 POS controller.
NOTE: The property MQTTConstants.MQTT_DATA_DIRECTORY is invalid when the 4690
JMS Persistence Adapter is used. The data directory must be provided as described below.
10
Next, we need to provide the configuration data for the 4690 JMS Persistence Adapter.
These properties must be provided as JVM system properties:
•
DATA_DIR. Describes the location of the message store; for example:
DATA_DIR=Q
HomeDir of the POS app = JMS
Client-specific store directory is the first letter of the ClientName provided when
instantiating the JMS Buffered Client.
c:\JMS\Q\B\s\1.m → shortest possible message full path name, already contains 17
characters. (Only a maximum of 26 characters is allowed on the 4690 POS
Controller file system, per Oracle's Sun Developer Web page.)
•
POS4690_ATTRIBUTE_SETTINGS. Attributes for the 4690 file system. This is a
structured String with the following syntax (separator is a comma ","):
ACCESS_TYPE,FILETYPE,DISTRIBUTIONMETHOD
Allowed values for ACCESS_TYPE:
◦
◦
◦
EXCLUSIVE_ACCESS
SHARED_READ_ACCESS
SHARED_READ_WRITE_ACCESS
Allowed values for FILE_TYPE:
◦
◦
MIRRORED_FILE
COMPOUND_FILE
Allowed values for DISTRIBUTIONMETHOD:
◦
◦
DISTRIBUTE_ON_UPDATE
DISTRIBUTE_ON_CLOSE
Note that, if this property is not provided, the following default value is applied:
EXCLUSIVE_ACCESS,COMPOUND_FILE,DISTRIBUTE_ON_CLOSE
These properties must be set as Java system properties, using either the command line
when starting the POS Java application or programmatically in the POS application code.
Example of using a startup command:
java -DDATA_DIR=./S
-DPOS4690_ATTRIBUTE_SETTINGS=EXCLUSIVE_ACCESS,COMPOUND_FILE,DISTRI
BUTE_ON_CLOSE -jar yourjar.jar
Example of setting the system property programmatically:
System.setProperty("DATA_DIR", "./Q");
If you want to use the JMS Buffered Client with the Standard Java technology, do not set
the property, MQTTConstants.USER_DEFINED_PERSISTENCE . Set the data directory for
the message store (for On-shutdown- and Full-Persistence), using the property,
MQTTConstants.MQTT_DATA_DIRECTORY (see listing 3).
11
Listing 3. Setting the DATA directory when NOT using the 4690 POS Persistence adapter
private static final String DATA_DIRECTORY = "./msgstore";
// setting the data directory for the messages store (works only with
Persistence types NONE, SHUTDOWN and FULL)
iConnFactory.setStringProperty(MQTTConstants.MQTT_DATA_DIRECTORY,
DATA_DIRECTORY);
Messages can either be sent to JMS queues or be published on a topic; therefore, the target
queue and topic are defined. Here's an example for constant definition of JMS target Queue
and Topic:
// name
private
// name
private
of the
static
of the
static
topic
final
queue
final
for publishing messages
String TOPIC_NAME = "XPDinteg_PosJmsClientTopic";
to send messages
String QUEUE_NAME = "XPDinteg_PosJmsClientQ";
Refer to the complete “init” method of the sample code, which shows how to fully instantiate
the JMS Buffered Client and how to create the target topic and queue.
Listing 4 describes how to send a text message.
Listing 4. Example code for sending a message to the Queue
public void sendTextMessageToQueue(String pMsg) {
ifLogger.info("sendTextMessageToQueue("+pMsg+")");
try {
message = iQueueSession.createTextMessage();
message.setStringProperty("ResourceType", "POSMessage");
message.setText(pMsg);
iQueueSender.send(message);
} catch (Throwable t) {
ifLogger.log(Level.SEVERE, "error while sending Message to
Queue.", t);
}
}
The method, setStringProperty(), can be used for setting custom message headers
(properties) in the message. Lotus Expeditor integrator supports these custom headers and
considers them for further processing.
Refer to the sample code for sending a message to a Topic. The enclosing POS Java
application must also take care of the JMS Buffered Client being shut down appropriately.
For further information, refer to the shutdown() method in the sample code.
The JMS Buffered Client works asynchronously. Once a message is handed over to the
JMS Buffered Client, the POS Java application does not receive any feedback and, from
then on, it is the responsibility of the JMS Buffered Client to process and send the message
correctly.
Any errors are typically reported using ExceptionListener (see method onException(..)).
Therefore, the Publisher class implements the interface javax.jms.ExceptionListener.
12
4.1.2 Create the JMS Receiver/Consumer
The message receiver class in the provided example code demonstrates how to receive
messages from the JMS Provider in Lotus Expeditor integrator (IBM micro broker).
It must be configured similarly to the JMS Publisher (see listing 5). For this example,
message persistence is not used. If persistence is required, it can be configured as
described in the Publisher example in section 4.1.1 above.
Listing 5. Configuration parameter example for the JMS Buffered Client - Receiver
// ------- connection factory settings ------// name for the JMS connection factory
private static final String CONNECTION_FACTORY_NAME =
MQTTConstants.MQTT_PROVIDER_NAME;
// unique name of the JMS client
private static final String CLIENT_NAME = "Receiver";
// URL to the micro broker instance
private static final String MB_CONNECTION_STRING =
MQTTConstants.MQTT_TCP_SCHEMA + "yourXPDintegIPAddress:1883";
// ------- end properties connection factory -------
Listing 6 describes how configuration data is applied.
Listing 6. Apply settings to the connection factory
ifLogger.info("START instantiating factory and setting properties");
JmsFactoryFactory jmsFactory =
JmsFactoryFactory.getInstance(CONNECTION_FACTORY_NAME);
iConnFactory = jmsFactory.createConnectionFactory();
iConnFactory.setStringProperty(MQTTConstants.MQTT_CONNECTION_URL,
MB_CONNECTION_STRING);
iConnFactory.setBooleanProperty(MQTTConstants.MQTT_BUFFERED, true);
iConnFactory.setIntProperty(MQTTConstants.MQTT_PERSISTENCE_TYPE,
MQTTConstants.MQTT_PERSISTENCE_TYPE_NONE);
ifLogger.fine("FINISH instantiating factory and setting properties");
For this example the Receiver listens on the same queue and topic to which the Publisher is
sending messages.
The most common way for receiving messages is using the message listener interface. The
Receiver class implements the interface javax.jms.MessageListener, and the receiver is
informed about incoming messages through the method onMessage(..).
The POS Java application must also correctly shut down the JMS Receiver. See the
“shutdown()” method in the sample code for more details.
The above example demonstrates how to create the JMS Publisher and Receiver/Consumer
separately. If both sending and receiving messages is required within the same Java
application, it is best practice to create only one IBM JMS Buffered Client that handles both
sending and receiving messages.
4.2 Configuring the JMS Provider in Lotus Expeditor Integrator®
This subsection describes how the configuration of the JMS Provider (IBM micro broker) in
Lotus Expeditor Integrator must be updated to support the scenario in Section 3, “Extending
secure and reliable messaging to the last mile.”
13
First, we must add a:
•
•
•
•
Local target Queue definition to receive messages sent by the POS Java application
Local Topic definition to receive messages published by the POS Java application
JMS Adapter to listen for incoming messages on the defined target queue
Flow for processing the incoming messages (Message forward)
Local Queue definition
This is the target queue in which the Lotus Expeditor Integrator is expecting the messages
sent from the JMS Buffered Client of the Java application on the POS Controller. Here's the
Lotus Expeditor Integrator configuration section for the local target queue (in XPDinteg.xml):
<queue purpose="PosJmsClientQueue">
<queue-name>XPDinteg_PosJmsClientQ</queue-name>
<jndi-key>jms/XPDinteg_PosJmsClientQ</jndi-key>
</queue>
Here's the configuration section for the local topic:
<topic purpose="PosJmsClientTopic">
<topic-name>XPDinteg_PosJmsClientTopic</topic-name>
<jndi-key>jms/XPDinteg_PosJmsClientTopic</jndi-key>
</topic>
JMS Adapter definition
This JMS adapter in Lotus Expeditor Integrator listens on the above-defined queue. It
triggers an Application Control Service (ACS) Flow to process the incoming message as
soon as a message arrives (see listing 7).
Listing 7. Lotus Expeditor Integrator configuration section for JMS Adapter (XPDinteg.xml)
<adapter type="XPDINTEG_JMS_DESTINATION_ADAPTER"
name="PosJmsClient_Adapter">
<!-- async mode -->
<listener>
<topic>
com/ibm/integrator/flowtriggerevent/MessageForward/PosJmsClient/JmsAdapter
</topic>
</listener>
<configuration>
<param name="JndiConnectionFactoryKey"
value="jms/XPDinteg_ConnectionFactory"/>
<param name="JndiDestinationKey"
value="jms/XPDinteg_PosJmsClientQ"/>
<param name="JndiDeadLetterKey"
value="jms/XPDinteg_ServerDeadletterQ"/>
<param name="ValidateLocationId" value="OFF"/>
</configuration>
</adapter>
ACS Flow definition for “Extending secure and reliable messaging to the last mile”
scenario
This example flow processes incoming messages from the POS Java application. It
retrieves them from the local target queue and forwards them to another local queue
(bridged queue) that is bridged to the backend messaging infrastructure (see listing 8).
14
Listing 8. Example of ACS Flow definition file for the Message Forwarding example
(PosData_MsgForward.flow)
<Process Name="PosData_MsgForward_Process"
Trigger="com/ibm/integrator/flowtriggerevent/MessageForward/PosJmsClient/
JmsAdapter">
<XPDintegActivity
Name="PosData_MsgForward_ReadResource"
ActivityName="XPDINTEG_MESSAGE_READ"
PropertyKey="DATA_REFERENCE"
/>
<XPDintegActivity
Name="PosData_MsgForward_MessageWrite"
ActivityName="XPDINTEG_MESSAGE_WRITE"
JndiConnectionFactoryKey="jms/XPDinteg_ConnectionFactory"
DestinationName="jms/XPDinteg_ResOutQ"
/>
</Process>
The flow is an example of processing and forwarding messages to any backend messaging
system in a transactional context. The PosData_MsgForward.flow flow file is put into the
folder <XPDintegHome>/flowdefs.
An alternative would be sending messages from the POS Java application directly to the
bridged queue without having an ACS Flow processing it. In this case, the JMS Destination
Adapter and the ACS Flow are not required, but the messages will not be forwarded to the
backend in a transactional context.
NOTE: The provided sample code contains a sample Lotus Expeditor Integrator
configuration file (XPDinteg.xml) and the created flow file (in the config folder). The
configuration file already contains the above-described sections but no backend bridge
configuration, resulting in connection errors on the console when starting the Lotus
Expeditor Integrator.
The tests described in the next subsection are not affected by this. The configuration file will
work with Lotus Expeditor Integrator version 6.2.1 Fixpack 1.
4.3 Testing the created example
The sample code contains a build file named build-Tester.xml. Run this ANT file to create a
run-able .jar file containing the sample code and all required libraries.
To create a Java application not targeted for the 4690 POS controller, you must remove the
jar files 4690pers.jar and OS4690.zip from the class path and the ANT file. Every other step
can be done as described below.
The run-able BClientR.jar file is found in the “build” folder. Deploy this .jar to the IBM 4690
POS controller into a separate directory, for instance, c:/JMS. The sample does the
following:
•
Creates a message store directory named “Q”. If the JMS Buffered Client cannot
connect to the Lotus Expeditor Integrator, the messages are persisted in here locally.
The messages are stored in the directory Q/B/S, with a single file for every message.
The file “-1.M” in this directory is used for internal purposes and is not a message.
•
Writes a log file named Log.txt, which contains only INFO logging. The logging
behavior can be changed in the sample code.
15
•
Maintains a file containing the counter of sent messages, named SCTR.TXT. It must
be deleted to reset the counter. The counter is part of the message payload.
•
Maintains a file containing the counter for received messages, named RCTR.TXT.
4.3.1 Run the Sending Messages test
This test sends a message from the sample POS Java application to Lotus Expeditor
Integrator. When it is received at Expeditor integrator, the Message Forward flow is
triggered, and the message is forwarded to the configured backend queue.
To perform the test, follow these steps:
1. Start the Lotus Expeditor Integrator.
2. Execute the following command to start running the test, replacing “NoOfMsg” with
the number of messages you want to send:
java -Dmsg=NoOfMsg -jar BclientR.jar
3. Check the result: If the ACS Flow status logging is enabled, the result can be seen
on the Lotus Expeditor Integrator console:
Sending Messages test – Expeditor integrator console output example:
2010-10-07 07:44:40.845 : PosData_MsgForward_Process/STARTED
(TxnId:POSSampleStore_1286430280845_2)
2010-10-07 07:44:40.876 : PosData_MsgForward_Process/FINISHED
(TxnId:POSSampleStore_1286430280845_2)
If the Lotus Expeditor Integrator is connected to a backend messaging system, all
received messages are forwarded automatically to this backend.
4. Use the Expeditor integrator monitoring tool:
a) Browse to the URL http://IPAddressofyourXPDinteg:8777/ui
b) Log in, using the configured credentials; the default is
xpdintegadmin/xpdintegadmin
c) Select the monitoring tool > Live, or Historical view, where you can see the list of
processed flows. You should see the flow, PosData_MsgForward_Process
If the Lotus Expeditor Integrator is NOT connected to a backend messaging system,
the message stays on the XPDinteg_ResOutQ queue in the Lotus Expeditor
Integrator.
Using the UI monitoring tool, you can browse this queue and check the messages by
selecting the monitoring tool > Live view > Resources, and then searching for
XPDinteg_ResOutQ and selecting the browse command.
4.3.2 Run the Sending and Receiving Messages test (message round trip)
We used this test scenario:
(1) Receiver in POS Java application connects to Lotus Expeditor Integrator and
registers to receive messages from the queue XPDinteg_JmsClientQ.
16
(2) Publisher in POS Java application sends a message to the Lotus Expeditor
Integrator on the queue XPDinteg_JmsClientQ.
(3) Lotus Expeditor Integrator receives this message from POS Java application on the
queue XPDinteg_JmsClientQ.
(4) Receiver in POS Java application retrieves this messages from Lotus Expeditor
Integrator.
Follow these steps to run the test:
1.
2.
First, we need to reconfigure the Lotus Expeditor Integrator so that the JMS Adapter
does not retrieve the message from the incoming queue:
a)
To do this, remove the JMS Adapter configuration section (in XPDinteg.xml), apply
the changed configuration, and restart Lotus Expeditor Integrator (for example, by
moving XPDinteg.xml into <XPDINTEG_HOME>/config/new directory and waiting
until the Configuration Update flow has succeeded).
b)
Re-start Expeditor integrator so that the changes take effect.
Execute the following command to start the test, replacing NoOfMsg with the number of
messages you want to send:
java -Dmsg=NoOfMsg -DSTART_REC=true -jar BclientR.jar
3.
Examine the log file to see the logging for received messages. Here's an example Log
for the Sending and Receiving Messages test:
16.01.2009 01:59:23 com.ibm.labsvcbb.bufferedjmsclient.Publisher init
INFO: START instantiating factory and setting properties
16.01.2009 01:59:34
com.ibm.labsvcbb.mqttclient.utils.persistence.MqttPos4690FilePersistence <init>
INFO: constructor started. version: 1.0
16.01.2009 01:59:34
com.ibm.labsvcbb.mqttclient.utils.persistence.MqttPos4690FilePersistence <init>
INFO: Default value for POS file attributes applied.
16.01.2009 01:59:37 com.ibm.labsvcbb.bufferedjmsclient.Publisher init
INFO: start connection
16.01.2009 01:59:37 com.ibm.labsvcbb.bufferedjmsclient.Receiver init
INFO: START instantiating factory and setting properties
16.01.2009 01:59:39 com.ibm.labsvcbb.bufferedjmsclient.Receiver init
INFO: start connection
16.01.2009 01:59:39 com.ibm.labsvcbb.bufferedjmsclient.SampleApp sendMessages
INFO: start sending messages.
16.01.2009 01:59:39 com.ibm.labsvcbb.bufferedjmsclient.Publisher
sendTextMessageToQueue
INFO: sendTextMessageToQueue(2### SamplePayload)
16.01.2009 01:59:54 com.ibm.labsvcbb.bufferedjmsclient.SampleApp sendMessages
INFO: finished sending messages.
16.01.2009 01:59:54 com.ibm.labsvcbb.bufferedjmsclient.SampleApp$1$MsgListener
onMessage
INFO: content: 2### SamplePayload
17
5 Conclusion
We have demonstrated how Java applications can use the IBM JMS Buffered Client to send
and receive messages reliably to/from IBM Expeditor integrator (IBM micro broker) as JMS
Provider and bridge to messaging-based enterprise IT infrastructures (ESB).
Although our example focuses on a messaging-enabled Java application running on an IBM
4690 POS Controller, it should be clear that this sample Java application could also run on
any other Java-enabled device or appliance. The differences were clearly cited in Section 4.
In the retail industry, devices like scale systems, printers, or display systems can use the
provided example in the same way for exchanging data with messaging backend
infrastructures.
If legacy in-store devices are connected through messaging, an end-to-end messaging
infrastructure for secure and reliable data transmission between retail stores and backend
processes can be established.
Due to the event- and messaging-driven transactional nature of our approach, end-to-end
management and monitoring is possible, enabling ad hoc analyses of data for business
process optimization and near-real-time reaction to environment and business changes.
6 Resources
IBM Lotus Expeditor Integrator product information:
http://www-01.ibm.com/software/lotus/products/expeditor/integrator.html
Lotus Expeditor wiki:
http://www.lotus.com/ldd/lewiki.nsf/
Lotus Expeditor Product Documentation:
http://www-10.lotus.com/ldd/lewiki.nsf/xpViewCategories.xsp?lookupName=Product
%20Documentation
Lotus Expeditor Integrator wiki article, “Messaging from the Edge in an SOA environment
using IBM Lotus Expeditor 6.2”:
http://www.lotus.com/ldd/lewiki.nsf/dx/10092008022324PMJHEPKF.htm
developerWorks® Lotus Expeditor product page:
http://www.ibm.com/developerworks/lotus/products/expeditor/
Oracle Sun Developer Network, Java Messaging API documentation:
http://java.sun.com/products/jms/docs.html
OSGi Alliance:
http://www.osgi.org
Eclipse Consortium:
http://www.eclipse.org
7 About the authors
Gerald Kallas is a Software IT Architect in IBM's Software Group. He finished his degree in
Information Technology in 1990 and has been working for IBM since 2001, mostly in the
18
retail industry. He has executed numerous successful business integration projects for retail
customers. Gerald was certified as Software IT Architect at IBM in December 2004 (certified
Open Group Software IT Architect).
Stefan Fassmann is an IT Architect from IBM Software Group's Lab Services in
Boeblingen, Germany. With his degree in Electrical Engineering, he started working on
mobile-workforce and remote-access solutions in IBM Global Services in 1996. In 2000, he
moved to IBM Lab Services, where he has been engaged in various mobile- and embeddedsolution customer projects using WebSphere and Lotus software technology. He became an
Open Group certified IT Architect in 2009.
Andreas Dannhauer is an IT Architect from IBM Software Group’s Lab Services in
Boeblingen, Germany. He earned his degree in Business Informatics and specialized early
in mobile, wireless, and embedded computing after he joined IBM in 2001. He was a key
driver in various telematics and retail projects based on IBM WebSphere and Lotus
embedded software technology.
Disclaimer
The code accompanying this paper is sample code created by IBM. This sample code is
provided to you solely for the purpose of concept explanations. The code is provided "AS
IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your
use of the sample code, even if you have been advised of the possibility of such damages.
Trademarks
•
developerWorks, IBM, Lotus, Lotus Enterprise Integrator, Tivoli, and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States, other
countries, or both.
•
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
•
Microsoft and Windows are trademarks of Microsoft Corporation in the United States,
other countries, or both.
•
Other company, product, or service names may be trademarks or service marks of
others.
19