 | Level: Intermediate Yang Liu (elainel@cn.ibm.com), Software Engineer, IBM
19 Jul 2006 Learn how to integrate your enterprise application with the IBM® WebSphere® RFID Premises Server V1.1 using the step-by-step example in this article.
Introduction
The IBM WebSphere RFID Premises Server (hereafter called Premises Server) is an application platform that performs the functions of the Premises domain within the IBM RFID solution architecture. The Premises Server processes RFID information and events from the RFID readers, controllers and automation equipment of the Edge domain, and provides access to RFID information to the Business Processing Integration domain.
This article builds upon the check-in and check-out scenario used in the developerWorks article Develop an agent with IBM RFID Tracking Kit and WebSphere Studio Device Developer. That article focused on implementing the check-in/check-out scenario on the Edge domain. In this article, we'll focus on implementing it in the Premises domain, as follows:
- When an object bound with a RFID tag is checked in or out, its RFID information is sent to the Premises Server.
- Once the Premises Server receives messages containing RFID information, it triggers the related enterprise applications to update the checked-in/checked-out object status accordingly.
Requirements
This article assumes that you have Premises Server installed, and have developed and configured your application on the Edge domain. In other words, the Edge controller is ready for sending messages containing RFID information to the Premises Server. For information on how to use the IBM RFID Tracking Kit to customize your application on the Edge domain, see Develop an agent with IBM RFID Tracking Kit and WebSphere Studio Device Developer.
Message flow of the check-in and check-out use case
The RFID Event Server is the primary component of the IBM WebSphere RFID Premises Server. It processes RFID event information using a system of WebSphere MQ message queues, message queue handlers, and event processing logic. The Premises Server defines five message queues for event processing:
Table 1. Predefined message queues in the RFID Event Server
| Queue name | Description |
|---|
| EDGE.Q.IN | For messages from the Edge controller(s) | | EDGE.Q.OUT | For messages to the Edge controller(s) | | CONTROL.Q.IN | For messages from the business logic | | CONTROL.Q.OUT | For messages to the business logic | | TASK.Q | For message processing |
Each message queue is bound with one or more Message Driven Beans (MDBs). When event messages flow through a series of message queues, the MDBs listening on these queues are triggered to consume these messages. They process the events according to the event type, and publish new messages to the other queues. See WebSphere RFID Handbook: A Solution Guide for detailed information about event processing on Premises Server.
For simplicity, we'll just use a one-way message flow in the messages in our check-in and check-out use case: messages flow from the Edge controller to the enterprise application. Specifically, when messages containing RFID tag information for the object arrive at the Premises Server, we'll parse the messages and then invoke the related enterprise application to update the object's status accordingly. We won't cover the backward message flow, that is, the control message flowing from the enterprise application to the Edge controller, in this article.
The Premises Server includes a set of predefined event templates (for example, a Tag Read event). Customers can extend these predefined event types as needed. Since the check-in and check-out use case is similar to the sample predefined in Premises Server, we can use the predefined event templates for our use case.
Figure 1 illustrates the message flow in the message queues of the check-in and check-out use case.
Figure 1. Message flow of check-in and check-out use case
- An RFID tag is scanned by the reader. The message flows from the Edge controller, through the MicroBroker Bridge, and into the EDGE.IN.Q.
The MicroBroker Bridge transforms the message from the published topic format of the MQTT protocol to the XML template format of the corresponding message type.
- The Edge Input Handler MDB listening on EDGE.IN.Q processes the messages according to message type, constructs a new message of
tag_read tag, and puts it into TASK.Q.
- The Tag Read Event Handler MDB listening on TASK.Q consumes the message, constructs a message of type
new_tag or repeat_tag, and puts it into TASK.Q.
- The Dock Door Receiving Event Handler MDB listening on the TASK.Q converts the
new_tag or repeat_tag event to a dock_door_receiving event, and puts it into CONTROL.OUT.Q.
- The messages in CONTROL.OUT.Q are now ready for the enterprise business adapter to access.
Implement the enterprise application adapter
In Figure 1, you see that the exit of the event messages is the CONTROL.OUT.Q message queue, which shows you that our enterprise application adapter can also be an MDB that listens on this message queue. In another words, we can use this MDB to trigger our own enterprise application.
In our check-in and check-out scenario, the business logic of updating an object's status is designed as a Web service, which is deployed on another WebSphere Application Server. Therefore, our MDB listening on CONTROL.OUT.Q is responsible for parsing the receiving XML messages, extracting the RFID tag information and calling the Web service to update the status of the checked-in/checked-out object. The event message in the CONTROL.OUT.Q with an RFID tag of 3114f4da34b2d05e12345678 is like:
Listing 1. Sample XML message representing a dock-door-receiving event in CONTROL.OUT.Q
<?xml version="1.0" encoding="UTF-8"?>
<dock-door-receiving-event>
<read timestamp="1124163262406" date="2005-08-16T11:34:22" location="R1" status="1">
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error: The previous line is longer than the max of 90 characters ---------|
<epcs><epc>3114f4da34b2d05e12345678</epc></epcs>
</read>
</dock-door-receiving-event>
|
As described in the previous section, the Dock Door Receiving Event Handler MDB extracts the RFID tag information from the input message, constructs a new XML message of dock-door-receiving-event type, and encapsulates the RFID tag into the XML node epc. Therefore, our MDB should parse this XML message and extract the RFID tag id from the epc node value.
|
EPC (Electronic product code)
A serialized global identifier (GID) comprised of a 96-bit code that gives each product its own specific identifying number.
EPC is the standard for RFID tag labels.
|
|
Listing 2 shows the onMessage method of our MDB class MDBRFIDBean. See Downloads for the MDBRFIDBean.java and XMLParser.java source code.
Listing 2. The Onmessage method of the sample MDB - MDBRFIDBean
public void onMessage(javax.jms.Message msg)
String epcCode = null;
String strMessage = null;
try {
if (msg instanceof TextMessage) {
TextMessage txtMessage = (TextMessage) msg;
strMessage = txtMessage.getText();
}
} catch (JMSException e) {
e.printStackTrace();
}
if (null != strMessage) {
// parse the xml message and extract the epc code
epcCode = XMLParser.parseXMLToEPC(strMessage);
// if epcCode found, then call the RFIDFilter to call webservice
if (null != epcCode) {
System.out.println(“RFID Tag: ” + epcCode);
// call the web service to perform the business logic of
// check in and check out use case
…
}
}
}
|
Integrate the adapter with Premises Server
To integrate the adapter with the Premises Server, you need to create a listener port and then deploy the MDB.
Create a listener port
Before deploying our MDB on Premises Server, we need to create a listener port on WebSphere Application Server. The listener port is a component of the Premises Server that listens on the output channel of the event messages, CONTROL.OUT.Q. To create a listener port, do the following:
- Open the Application Server Administrative Console by pointing your Web browser to http://<premises_server_ip>:9090/admin.
- Expand Servers and click Application Servers. Click the appropriate server name of the server instance; in our case, the server name is server1.
Figure 2. Select server instance
- On the Configuration tab, click Message Listener Service in Additional Properties.
Figure 3. Select Message Listener Service
- Click Listener Ports to list all created listener ports. You see four predefined listener ports in the list, listening on the
message queues described earlier. The
kimonolistener is for the pre-built kimono example application.
Figure 4. View listener ports
- Create a new listener port named
checkinlistener to listen on the CONTROL.OUT.Q, as follows:
- Click New and enter the following information:
| Name | checkinlistener | | Connection factory JNDI name | jms/ibm.rfid.qm | | Destination JNDI name | jms/control.out.q |
- Leave the defaults for the other fields, and click OK. You can see that a new listener port is added in the list.
Figure 5. Create checkinlistener port
- Select checkinlistener in the port list, and click Start to start the listener.
- Click Save in the information message on top of the page to save your changes.
Deploy the MDB
To deploy the MDB on Premises Server, you need to build the MDB into an EAR package, install it as an enterprise application on the Application Sever that is on the Premises Server, and bind the MDB with the checkinlistener you just created.
- Expand Applications and click Install New Application on the Administrative Console page.
Upload the EAR file
- Click Browse and navigate to the path of your ear package, then click Next.
- Click Next on the next two pages until you get to the page titled Step 2: Provide Listener Ports for Message Beans.
- Enter the
checkinlistener as the Listener Port, and click Next.
Figure 7. Provide the listener port for message beans
- Leave all other settings as the default values, and click Save in the information message on top of the page.
- Make sure your back-end enterprise application is started (in our case, the Web service for updating object status).
- Return to the
Enterprise Applications page and select the application name you just installed, then click Start to start the application.
Figure 8. Start the application
Run the check-in and check-out use case
To run the use case, you need to define the RFID network topology, start the applicaton, and view the event messages.
Define your RFID network topology
To enable the connection from the Edge controller to the Premises server, you need to define the RFID network topology using the administrative console of the
Premises Server. See WebSphere RFID Handbook: A Solution Guide for detailed information on creating locations, readers, and controllers in the network topology.
In our case, we'll define a controller with the ID E1, a location with the R1 and a reader with the ID R1 to compose the network topology. The reader type is SamsysType because we use the SamasysMp9320 RFID reader. These definitions are shown in Figures 9, 10 and 11.
Figure 9. The location definition of the check-in and check-out use case
Figure 10. The reader definition of the check-in and check-out use case
Figure 11. The controller definition of the check-in and check-out use case
Start the application
Before starting the agent bundles on the Edge controller, start the SMF runtime on the Premises Server, which starts the MicroBroker Bridge and
other necessary bundles to communicate with the Edge controller.
- On the Premises Server, stop the SMF service.
- Open a command prompt window and change to the SMF directory: <IBM_RFID_HOME>\edgecontroller\premises\smf\.
- Run
smf.bat
Now start the SMF runtime on the Edge controller, which includes the agent bundles to implement the check-in and check-out use case.
See
Develop an agent with IBM RFID Tracking Kit and WebSphere Studio Device Developer for details.
In the sample use case, we use some example bundles to simulate the behavior of the Premises Server. As you have the real Premises Server now,
you should change the VM argument of the runtime to the configuration of the real Premises Server. In our example bundles, you just need change the
parameter –Dpremises.ip to the IP and port of the Premises Server and the -Dedge.id to the controller ID you defined in your network topology, as shown:
-Xalwaysclassgc -Xgc:stringconstantGC -noverify -Xint -Dpremises.ip=10.1.1.186:9080
-Dedge.id=E1 -Dkimono.console.log.threshold=DEBUG
|
Start the SMF runtime on the Edge controller, and install the necessary bundles. Now you can run the check-in and check-out use case in your RFID environments.
View event messages
To validate the results in your application, which in our case is the output of our Web service, you need to start the RFID reader and scan some RFID tags. Following are some tips for viewing the event messages in different message queues:
- Go to the listener ports list page in the Administrative Console of the Application Server. Stop the
edgelistener.
- Scan a tag in the Reader side, such as a tag with an ID of
3114f4da34b2d05e12345678 .
- Open the WebSphere MQ Resource Manager installed on your Premises Server, expand WebSphere MQ in the console root node, and select Queue Manager => IBM.RFID.QM => Queue.
- Double-click EDGE.IN.Q and view the message data. The message in EDGE.IN.Q is like that in Listing 3, which is the message format when MicroBroker Bridge transforms the message received from the Edge controller with a type of
tag_read.
Listing 3. Sample XML message representing tag_read event in EDGE.IN.Q
<?xml version='1.0' encoding='UTF-8'?>
<ibmprem:ibm-premises-unified-format os;2006-06-16T11:34:22'
xmlns:ibmprem='http://www.ibm.com'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.ibm.com IBMPremisesUnifiedMessageFormat.xsd'>
|--10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error: The previous line is longer than the max of 90 characters ---------|
<event location='R1' type='tag_read'>
<rfid-tag-data antenna='1' count='1'
discovered='1122904270578' reader='R1'
tagid='3114f4da34b2d05e12345678'/>
</event>
</ibmprem:ibm-premises-unified-format>
|
- Stop the
tasklistener and then start the edgelistener.
- The Edge Input Handler MDB consumes the message in Listing 3 and constructs a new message, then puts it in TASK.Q as shown in Listing 4:
Listing 4. Sample XML message representing tag_read event in TASK.Q
<?xml version='1.0' encoding='UTF-8'?>
<ibmprem:ibm-premises-unified-format dts='2006-06-16T11:34:22'>
<event location='R1' type='tag_read'>
<rfid-tag-data antenna='1' count='1'
discovered='1122904270578' reader='R1'
tagid='3114f4da34b2d05e12345678'/>
</event>
</ibmprem:ibm-premises-unified-format>
|
- Stop the
checkinlistener and then start the tasklistener.
- The MDBs listening on TASK.Q process the message according to the event type, and finally put a message in CONTROL.OUT.Q as shown in
Listing 1.
- Start the
checkinlistener. Since we output the RFID tag to the console of Application Server, open the SystemOut.log file in the
<Application_Server_Root>\log\server1\ directory. Verify whether the epc code has been extracted correctly.
 |
Conclusion
The IBM WebSphere RFID Premises Server provides a platform for integrating RFID processes into back-end enterprise applications. It processes RFID events according to use cases
and customer requirements. The Premises Server provides ready-to-use event templates. In this article, you learned how to integrate RFID processes into an enterprise application by:
- Creating a simple MDB to listen on the output channel of the Premises Server event server. This MDB acts as the adapter to the enterprise application.
- Configuring a listener port and deploying the MDB on the Application Server.
Combining the solution presented in this article with that described in the article
Develop an agent with IBM RFID Tracking Kit and WebSphere Studio Device Developer, you can create a typical custom IBM RFID solution.
Download | Description | Name | Size | Download method |
|---|
| Code samples | SampleCode.zip | 7KB | FTP|HTTP |
|---|
Resources Learn
Get products and technologies
-
IBM trial software: Build your next development project with trial software available from developerWorks.
Discuss
About the author | 
| | Yang Liu is a software engineer at IBM China Software Development Lab in Shanghai, China. She works in the Shanghai Globalization Lab, and focuses on RFID technology, Web services and globalization technologies. You can reach her at elainel@cn.ibm.com. |
Rate this page
| |
