C H A P T E R 4 - ALE Web Services

This chapter describes the Sun Java System RFID Software 2.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.

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, or BEA WebLogic 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 Rio service named ALE. This service implements the WSDL methods described in the specification not as WSDL, but rather as RMI. Report requests and report messages are implemented as POJO (Plain old Java objects) in the package com.sun.autoid.ale.spec.

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 Rio class, com.sun.rio.event.EventDescriptor, was extended to produce the RFID Event Manager common class, com.sun.autoid.event.ReaderEventDescriptor. This class adds two new properties: logical and physical. For a reader to participate in the ALE implementation, its configuration must include an REProducer that defines the physical reader and logical reader name. The name of the physical reader defined in the reader configuration file, RfidConfig.xml, must match the name for the service defined in the readers.xml file contained in /etc/opt/sun/rfidem.The most appropriate place for this component is connected directly to the reader adapter, however this is not a requirement.

The ALE service continually monitors the Jini lookup service to discover ReaderEventDescriptors and uses this to maintain a list of discovered readers. When an ALE Report request comes in, the logical and physical reader names from the Report Specification are used to locate the readers. From the ReaderEventDescriptor, the eventID number is located, and this is used to seed an REConsumer that connects to the correct REProducer for the reader.

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 4-1.

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

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.

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. Provision has been made to enable the ECSpec to be set up via 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 2.0 Administration Guide, Appendix C.

CODE EXAMPLE 4-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

An ALE client API is implemented to hide some of the complexity of the JAX-RPC code.

ALE Web Services Client Interface and Implementation

The interface of ALE client API is contained in the com.sun.autoid.ale.AleAPI.class file. The implementation of ALE client API is contained in the com.sun.autoid.ale.client.ALEClient.class. Both of these classes are packaged in sun-alesvc-common.jar.

Sample Program - MyAleClient.java

Two JAR files, sun-alesvr-common.jar and sun-rfid-common.jar, need to be copied into the lib directory of the development directory. They can be found on the machine that has RFID Event Manager and the optional component, ALE Web Services installed. The name of the directory is install_dir/lib. See Sun Java System RFID Software 2.0 Installation Guide for the default directories found in Appendix C.

A sample program, MyAleClient, which uses the ALE Web Service Client Interface, AleAPI.class and the implementation class, ALEClient.class is packaged with the ALE Web Service component. The samples directory of the MyAleClient.java sample program and the environment are installed in install_dir/samples/ale/aleclient. To install the ALE Web Service component, refer to Chapter 3 of the Sun Java System RFID Software 2.0 Installation Guide.

Sample Development Environments

The following sections describe the sample development environments. These are provided to help you set up the necessary environment and start developing ALE Web Services applications using Sun ALE Web Services Client APIs quickly.

Sample Development Directories

CODE EXAMPLE 4-2 Sample Development Directory Tree
aleclient - src (contains the source) * com/sun/epcglobal/aleclient/MyAleClient.java - classes (contains the compiled class files) - lib (contains Sun RFID and ALE JAR files) - sun-alesvc-common.jar - sun-rfid-common.jar - xml (contains the ECSpec XML file) - ECSpec.xml * build.xml * build_properties.xml

Java Web Services Developer Pack 1.5

Java Web Services Developer Pack (Java WSDP) 1.5 is required to compile and run the program. The directory structure of Java WSDP is listed in CODE EXAMPLE 4-3.

CODE EXAMPLE 4-3 Sample Java WSDP 1.4 Directory Tree
jwsdp - jaxb/lib/.jar - jaxp/lib/.jar - jaxp/lib/endorsed/.jar - jaxrpc/lib/.jar - jwsdp-shared/lib/.jar - saaj/lib/.jar

Sample ANT Build XML Files

The sample ANT build.xml and build_properties.xml can be used to build and run MyAleClient. They can be found in the install_dir/samples/ale/elegant directory.