C H A P T E R 5

ALE Web Services

This chapter describes the Sun Java System RFID Software 3.0 implementation of the EPCglobal Application Level Events (ALE) specification, also known as collection and filtering. ALE is a web service specification containing a WSDL to define, configure, and request reports. There is also an XML schema for requesting reports and for the reports themselves. You should be thoroughly familiar with Application Level Events (ALE) Specification, Version 1.0 before using the ALE components. The specification can be found at the EPCglobal web site http://www.epcglobalinc.com.

The following topics are included in this chapter:

Broad Architecture

ALE Service Architecture

Other Considerations

Using ALE Web Services Client (ALEClient) API

Broad Architecture

The Sun Java RFID Software implements the ALE web service using Java API for XML-based RPC (JAX-RPC). This is contained in the sun-ale-service.war file and is deployed to an application server, such as Sun Java System Application Server 7, 8.1. This service acts as an intermediary to a Jini RMI service contained within the RFID Event Manager.

The implementation of ALE in the RFID Event Manager is based on a new service named ALE. This service implements the WSDL methods described in the specification. The ALE service uses Java RMI (Java Remote Method Invocation). Report requests and report messages are implemented as POJO (Plain old Java objects) in the package com.sun.autoid.ale.spec.

Illustration showing the ALE service in the RFID Event Manager using RMI calls to communicate from readers to the RMI client and the ALE web service.

To conform to the ALE specification, the ALE WSDL is processed using JAX-RPC to generate Java web service classes. These classes include client-side classes that work with the POJO objects contained in com.sun.autoid.ale.spec. The ALE WSDL common server and client code is packaged into sun-alesvc-common.jar. An ALE client API is implemented to hide some of the complexity of the JAX-RPC code. The ALE client API is described in the section titled, "Using ALE Web Services Client API". A sample of using the ALE client API is listed in CODE EXAMPLE 4-2.

The ALE XML schema is processed using JAXB and the generated files are placed into package com.sun.autoid.ale.xml. There is generally a one-to-one mapping of the JAXB generated objects to the classes in com.sun.autoid.ale.spec. The class com.sun.autoid.ale.XMLUtil provides methods to translate back and forth between the JAXB representation and the POJO representation of the spec classes.

ALE functionality includes a requirement to register for reader events based on the ALE request. So, the ALE service discovers all readers and when a request becomes active, the ALE service registers with the event producer (com.sun.autoid.logger.REProducer in Connector) on the reader. The mechanics of how this is done is described later.

ALE Service Architecture

The ALE Service is deployed as a Jini RMI service in the RFID Event Manager. Each ALE report request is translated into an event processing network, including devices, filters, and connectors.

The ALE specification contains the concept of a physical reader and a logical reader. A logical reader can be comprised of one or more physical readers. To discover the physical or logical readers, the ALE implementation uses the reader name as defined in the Configuration Object for the reader and also uses the logicalReaders property for the reader. The logicalReaders property comprises a comma-separated list of logical names. A reader may belong to more than one logical group. For example, if a reader belongs to the logical groups named Dock Door 1 and Receiving, the logicalReaders property is set to the values Dock Door 1 and Receiving.

The ALE implementation constantly searches for all readers on the system and maintains the current list of physical and logical names. If the reader service goes offline and the reader specified in the ALE event cycle specification cannot be located, an ALE exception is thrown.

The ALEEventFilter implements the event cycle as described in the ALE specification. The event cycle is a state machine as described in the specification. Basically, an event cycle is started, tag events are gathered, and when the event cycle finishes, the tag list is pushed out to the ALEEventReportFilter. To fully understand the ALEEventFilter it is necessary to understand the ALE specification. An ECSpec describes an event cycle and one or more reports that are to be generated from it. It contains a list of logical Readers whose read cycles are to be included in the event cycle, a specification of how the boundaries of event cycles are to be determined, and a list of specifications each of which describes a report to be generated from this event cycle. A sample of an ECSpec is listed in CODE EXAMPLE 5-1.

The ALE specification identifies external triggers that can start or stop the event cycle. These triggers are specified as URIs, but the interpretation of the URI is up to the implementation. In Sun's implementation, the URIs behave as follows:

An EPC pattern-matching URI - the trigger is fired when an EPC is seen that matches.

JMS URI - designates a queue or topic to receive messages

HTTP URI - which is opened and read to receive a message.

FILE URI - which is opened and read to receive a message.

TCP URI - designates a socket, which is opened and read to receive a message.

Anything else, default is to always fire.

For the JMS, HTTP, FILE and TCP URIs the format of the payload is a simple XML document. For example:

<Trigger fired="true" />

<Trigger fired="false"/>

At the end of an event cycle, as defined by the ALE specification, the ALEEventFilter creates an ALEEvent that contains a list of tags and a list or readers that produced the tag events. This is passed to the ALEEventReportFilter which takes the input and creates a MiscEvent that contains a property that holds the ECReport object.

In the ALE specification, the definition of the report and the subscription to receive the report output are two distinct operations. Therefore, when a subscribe request comes in, a specialized logger is created to handle the request.

The types of loggers are:

JMS Logger - the Report XML is include as the payload message to a JMS queue or topic

File logger - where the Report XML is written to a local file

TCP logger - where the Report is written to a socket

Poll logger - where the Report is returned as a String to the poll request

All other loggers are treated as an URL, which is opened for writing

An event cycle cannot start until at least one subscriber is registered to receive the reports. When subscriptions are registered, the appropriate Logger is created and dynamically linked to the ALEEventReportFilter. Similarly, when a subscription is removed, the Logger is stopped and disconnected from the ALEEventReportFilter.

Lastly, when a Report specification is "undefined," all the processing components are stopped, and dynamically removed from the ALE service.

Other Considerations

Because ALE has been implemented as RFID Event Manager components, the components can be used in the same way other components are used. The ECSpec can be set up using the component properties. In this way, the ALE components can be permanently attached to a reader, if needed. A sample configuration file demonstrating this can be found in the Sun Java System RFID Software 3.0 Administration Guide, Appendix C.

CODE EXAMPLE 5-1 Sample ECSpec file
<?xml version="1.0" encoding="UTF-8"?> <ECSpec xmlns="urn:epcglobal:ale:xsd:1" includeSpecInReports="true" creationDate="2005-02-07T13:42:40.790-05:00" schemaVersion="1.0"> <logicalReaders xmlns=""> <logicalReader>Reader</logicalReader> </logicalReaders> <boundarySpec xmlns=""> <startTrigger>http://localhost/start</startTrigger> <duration>2000</duration> <stableSetInterval>0</stableSetInterval> </boundarySpec> <reportSpecs xmlns=""> <reportSpec reportIfEmpty="false" reportName="report" reportOnlyOnChange="false"> <reportSet set="CURRENT"/> <output includeCount="false" includeList="true"/> </reportSpec> </reportSpecs> </ECSpec>

Using ALE Web Services Client (ALEClient) API

The ALE web service client, MyAleClient.java, is a sample program for the purposes of illustrating how to create a Java client that communicates with the ALE web service. It is installed when the ALE custom option is selected during installation of the RFID Event Manager and is located in rfid-install-dir/rfidem/samples/ale/aleclient. Where rfid-install-dir is one of the following depending on your platform:

Solaris - /opt/SUNWrfid

Linux - /opt/sun/rfidem

Microsoft Windows - C:\Program Files\Sun\RFID Software\rfidem\

This sample includes all the necessary tools for compiling and running the sample program. It also includes a sample ECSpec that can be used to query the ALE web service for tag data.

Client Checklist

Before running MyAleClient, be sure to confirm the following items:

The ALE client software must be started on the same machine on which the RFID Event Manager is installed. This is necessary because the ALE service depends on specific JAX libraries, which are installed with the RFID Event Manager. Alternatively, you can copy the necessary files from a machine where the RFID Event Manager is already installed and then set the JAX_LIB_PATH environment variable to that directory. See Step 3 in the procedure To Set Up the ALE Client Environment.

Your application server is running

Confirm that the server.policy file in the application server has been updated by the Event Manager installer or you did it manually.

Note - Note, the application server must be restarted after the policy file has been changed.

The ALE web service was properly deployed to the application server. See Chapter 3 - "To Install the Event Manager Using Custom Installation" of the RFID Software Installation Guide for instructions on installing the ALE web service.

The RFID Event Manager is running.

Confirm that you are receiving tags from the Event Manager in the tag viewer

To Set Up the ALE Client Environment

1. Change to the directory containing the ALE sample directory.

Solaris - /opt/SUNWrfid/samples/ale/aleclient

Linux - /opt/sun/rfidem/samples/ale/aleclient

Windows - C:\Program Files\Sun\RFID Software\rfidem\samples\ale\aleclient

2. Create a lib directory in the aleclient directory.

Solaris - mkdir -p lib

3. Copy the following JAR files to the new lib directory.

Solaris - /opt/SUNWrfid/lib/sun-alesvc-common.jar and sun-rfid-common.jar

Linux - /opt/sun/rfidem/lib/sun-alesvc-common.jar and sun-rfid-common.jar

Windows - C:\Program Files\Sun\RFID Software\rfidem\lib\sun-alesvc-common.jar and sun-rfid-common.jar

4. Verify that the build_properties.xml file is correct for your installation.

To Run the ALE Web Services Client

1. Be sure that you have confirmed all items in the client checklist (see Client Checklist) and performed the procedure To Set Up the ALE Client Environment.

2. Set the environment variable, JAX_LIB_PATH as follows. For example, using the csh shell for Solaris and Linux:

Solaris

setenv JAX_LIB_PATH /usr/share/lib

Linux

setenv JAX_LIB_PATH /opt/sun/share/lib

Windows

set JAX_LIB_PATH=\C:\Program Files\Sun\RFID Software\rfidem\\lib\utils

3. Edit the build.xml file found in the sample aleclient directory and change the localhost and port number to match your target environment.

For example, change the runMyAleClient ant target value as follows - change the following:

<arg value=http://localhost/ALEService/ale

to the following:

<arg value=http://em-hostname/app-server-port/ALEService/ale

Troubleshooting for ALE Client

Symptom: You see an ImplementationException with the following message when you run the ALE client

[java] Message for the exception: Connection to ALE Services is not available at this time

Solution: Confirm that the RFID Event Manager is running and sufficient time has elapsed to enable all components to start.