# Programming with the ALE and ALEPC APIs

# Reading and Writing Tags

The following sections provide an overview of the ALE API and describe how client applications use the ALE API to define requests for tag data:

- Overview of the ALE API and ALE Operation
- BEA Implementation of the ALE API
- Benefits of the BEA Implementation
- Programming Methods
- Reading Tag Data
- Writing Tag Data
- Comparison of Event Cycles and Programming Cycles

Note: | In the sections of this programming guide that deal with reading tags, it is assumed that you have read The Application Level Events (ALE) Specification Version 1.0, which in addition to defining the API provides necessary background information. If you do not have a copy of the specification, you can find one at the EPCglobal site: http://www.epcglobalinc.org.

## Overview of the ALE API and ALE Operation

Applications interact with an Edge Server through the ALE API. The application uses the ALE API to define tag reading requests and uses the BEA-provided ALEPC API to define tag writing requests. This section uses the term ALE API to refer to both APIs. The Javadoc for the ALE and ALEPC APIs is available online at the following URL:

    http://download.oracle.com/docs/cd/E13197_01/rfid/edge_server/docs20/javadocs/index.html

ALE provides a high-level, declarative way to read and write RFID data, without requiring application programmers to interact directly with RFID readers or to perform any low-level real-time processing or scheduling operations. ALE logically occupies a position between application business logic and low-level RFID tag reads and tag writes, thereby providing a strong degree of insulation between the two.

Note: | For information on configuring readers, see Installing WebLogic RFID Edge Server and RFID Reader Reference.

ALE processing takes place within the WebLogic RFID Edge Server, so that large volumes of RFID read data can be reduced to pertinent business events prior to traveling over local or wide-area enterprise networks to applications.

The basic concepts of ALE operation are straightforward:

- An application sends a request through the ALE interface in the form of an ECSpec to read tags, or in the form of a PCSpec to write tags.
- The ALE engine within the Edge Server processes the request, performs the requested actions (for example, filtering tag data during a read operation), and generates reports based on the conditions specified in the ECSpec or PCSpec.

A tag-reading request can be a one-time request that is satisfied synchronously (for example, "supply a list of the EPC codes that are currently stable in the field of readers at Dock Door 5"). Or the tag-reading request can be a standing request that generates asynchronous notifications when events of interest occur ("every ten minutes, how many new items have arrived").

A tag writing request can also be satisfied synchronously (for example,"write the following tag now"). Or the tag-writing request can be a standing request that writes a tag and generates a report when an external event occurs ("when the case crosses the electric eye beam, write the tag").

## BEA Implementation of the ALE API

The BEA implementation of the ALE API provides:

- Support of the standard EPCGlobal Application Level Events (ALE) Specification
- API support for advanced tag features, including all features of the EPCglobal Class-1 Generation-2 UHF RFID Air Interface Specification (commonly called Gen2). This specification includes changes to the ALE API and the ALE schema and WSDL.
- Extensions to the standard ALE API, such as extra boundaries and Gen2 read support.
- ALEPC extensions for tag writing and advanced Gen2 support
- Reliable messaging using JMS or Web Services (WS-Reliable Messaging)
- Out-of-the-box RFID workflow samples
- Support of the standard Java or J2EE programming model for workflows
- An RFID tag simulator for testing and development

For a full list of all the features in this release, see the Introduction and Roadmap section in the Product Overview manual.

## Benefits of the BEA Implementation

The BEA implementation of the ALE API provides a number of unique benefits:

- Rapid development and deployment: Different teams can independently get new projects up and running quickly with a minimum amount of programming.
- Flexibility: Individual applications can be easily modified while the Administration Console enables rapid reconfiguration of the overall deployment.
- Variety of deployment scenarios: Enterprise applications can be distributed across remote sites through a wide range of network transports and protocols.
- Built-in support for multiple applications to share readers: The Edge Server includes logic and security to handle multiple independent applications simultaneously.
- Manageability, security, and integrity: Centralized management of the control of the overall deployment supports use of RFID data in enterprise applications.
- Scalability: The ALE API supports a scalable number of readers per WebLogic RFID Edge Server, number of RFID Server instances per site, and number of sites in the overall application.
- Standards leadership and support: The BEA implementation of the ALE API supports and extends Version 1.0 of the ALE Specification.
- WebLogic RFID Edge Server-specific extensions: WebLogic RFID Edge Server extensions to the ALE API are explicitly noted throughout this document.

## Programming Methods

To use ALE from a program, use one of the following methods:

- You can use standard SOAP-based Web Services development tools to generate an ALE client stub for any programming language. The WebLogic RFID Edge Server installation provides WSDL files that you can use for this purpose. The WSDL files are in your WebLogic RFID Edge Server installation directory at:

    /share/schemas/EPCglobal-ale-1_0.wsdl

    /share/schemas/ALEPCService.wsdl

- WebLogic RFID Edge Server provides a Remote Client library for the Java programming language, which Java programs can use to access a WebLogic RFID Edge Server through the ALE API.

## Reading Tag Data

The following sections describe how tag data is read and reported:

- Read Cycles and Event Cycles
- How Applications Interact with the Edge Server ALE Engine
- ECSpec Reports

Applications define event cycle specifications (ECSpecs), which specify to the ALE engine what RFID data is of interest. An example of the content of an ECSpec is "send a report every 60 seconds of what objects have been added or removed to warehouse shelves #4 and #5, including Acme products only and excluding pallet-level data."

Once an application defines an ECSpec, the application receives RFID data through event cycle reports (ECReports). In the previous example, the ALE engine within the WebLogic RFID Edge Server generates a new ECReports instance every 60 seconds, containing a list of objects added or removed from the warehouse shelves as specified.

For a detailed overview of ECSpec and ECReports, see ECSpec Data Type and ECReports Data Type, respectively.

An application can define and subscribe to an ECSpec programmatically by using the ALE Remote Client to access the ALE API directly. Through the API, you can define an ECSpec and subscribe one or more destinations to an ECSpec for asynchronous delivery of ECReports. You can also use the API to request the delivery of an ECReports instance on demand, in a synchronous manner.

### Read Cycles and Event Cycles

RFID readers generally scan for tags much more frequently than real-world applications require data. In addition, the likelihood of an RFID reader actually reading a tag during any one attempt depends on many factors, including the position and motion of tags, presence of objects or people, and even the activity of other readers. Because of these factors, applications generally use the data accumulated from a number of RFID reads, and the ALE interface distinguishes between the rate at which readers scan for tags and the rate at which applications receive data.

A read cycle refers to a single complete scan of all tags in a single reader antenna's field. This scan generally happens a few times a second. An event cycle is one or more read cycles, from one or more readers, that are to be treated as a unit from an application perspective. The data of an event cycle consists of all tags seen in any read cycles by any of the readers.

At the completion of an event cycle, the ALE engine within the Edge Server processes the set of tags the readers saw during that cycle and generates one or more reports to the requesting application. Each report specification can include different criteria for reporting, such as whether to report all tags or only changes; whether to include actual tag IDs or just counts; whether to include or exclude certain tags based on their identities; and how filtered EPCs are grouped together for reporting. Because different applications can interact with a single Edge Server, many overlapping event cycles can be in progress at any one time, sharing the data from overlapping sets of readers in arbitrary ways.

The following picture shows the relationship of read cycles, event cycles, and reports.

There are a number of ways to specify the boundaries of event cycles relative to read cycles:

- Duration: Specify the event cycle to last a certain amount of time, independent of how many read cycles are involved.
- Number of read cycles: Specify the event cycle to last a fixed number of read cycles.
- Field stability: Specify the event cycle to complete when the set of tags read by a reader has been stable for a specified period of time (no new tags are seen during that period).
- External events: Specify the event cycle to begin or end when an external event occurs, such as a container passing an electric eye beam, or a human pressing a button.

Multiple end conditions can be specified, with the event cycle concluding when any of the conditions are met. For example, you can specify that an event cycle last 10 seconds OR the field is stable for at least 5 seconds.

### Smoothing Read Cycles with Transient Filtering

WebLogic RFID Edge Server provides a transient filtering mechanism that can help produce smoother results when tags are not read reliably by readers. You can use the transient filter when you want to filter out tags that appear only briefly, keeping those tags that are read several times within a specified interval of time. The transient filter can also be used to smooth over gaps when tags disappear briefly (though accumulation of multiple read cycles into an event cycle has a similar effect, even without transient filtering). See Installing WebLogic RFID Edge Server for information on transient filtering.

### How Applications Interact with the Edge Server ALE Engine

Applications interact with the RFID Edge Server ALE engine through event cycle specifications (ECSpecs) and event cycle reports (ECReports). An ECSpec identifies the specific information or events that an application is looking for in each event cycle. The ECSpec also defines which locations (logical readers) are to be included; which external events or time parameters define the start and stop of an event cycle; and a set of report specifications, each defining a subset of the data of interest. The WebLogic RFID Edge Server ALE engine can process large numbers of ECSpec instances from different applications simultaneously.

Three modes of interaction can occur between an application and an Edge Server:

- Immediate: The application uses the ALE interface to send an ECSpec, and the ALE engine within the Edge Server fulfills the specification by completing one event cycle, after which the application receives the corresponding reports.
- Immediate with predefined request ("poll"): Applications can request a single event cycle from a previously defined ECSpec and receive the reports in the response.
- Asynchronous ("subscribe"): An application subscribes to a previously defined ECSpec by using the subscribe operation, indicating an address to which reports should be delivered. The ALE engine within the Edge Server then sends reports to the application as each event cycle completes, continuing to do so until the application cancels the subscription.

An application or user can define a standing ECSpec at any time. The Edge Server remembers all such ECSpec instances until an application or the user explicitly undefines them; thus, numerous applications can poll or subscribe to the same ECSpec.

The Edge Server remembers all subscribers until they unsubscribe. Thus, if the application subscribes and then exits, the Edge Server continues to send reports.

The `immediate` and `poll` methods are synchronous, insofar as the application blocks after making its request until the ALE engine responds with the corresponding reports. The subscribe method is asynchronous, as control is returned to the application immediately after processing the subscribe call. Subsequent reports are delivered through an asynchronous channel.

### ECSpec Reports

An ECSpec specifies one or more reports that may be generated at the end of each event cycle. The report is based on the complete list of tags that were detected by the specified readers during the event cycle. Each tag that was read is listed once, even if it was detected in multiple read cycles on one reader or on multiple readers. Starting with this list of tags, each report is defined according to criteria applied in the following sequence:

1. What tags should be included for consideration: all tags read during this event cycle, only those tags that are new relative to the last event cycle for the same request (additions), or only those tags that were present during the last event cycle for the same request, but which are no longer present (deletions). Note that the latter two choices do not apply to a one-time, immediate request as there is no previous event cycle to compare against.
2. What filters should be applied to the list of tags from Step 1. A filter might specify that certain tags should be excluded from consideration ("do not include any Acme products"), or that only certain tags should be included ("only include pallet-level tags"). EPC Patterns includes a detailed description of filter options.
3. If there are no tags left after Step 2, should a report should be generated or not?
4. How filtered EPCs are grouped together for reporting.
5. When a report is generated, should the report enumerate the actual tag identities that result from Steps 1, 2, and 4, or merely include a count of the number of tags left in each group after Steps 1, 2, and 4?

The option in Step 3 is useful for specifying that applications receive reports only for event cycles where something of interest actually occurred. For example, in a warehouse application that is monitoring what goods are present on a shelf, the option in Step 3 might be used so that the ALE engine sends a report only when something is placed on or removed from the shelf.

For more information on reports, see Reading Tags by Using the ALE API.

## Writing Tag Data

The process of instructing a reader to encode an EPC value onto an RFID tag is called both "writing" and "programming." Tag writing can be performed both by RFID readers, and by RFID-enabled printers, which can print labels with embedded tags. For a complete list of the readers and printers for which WebLogic RFID Edge Server supports tag writing, as well as the specific tag formats which are supported for each device, see the supported RFID readers section of the RFID Reader Reference.

Applications define programming cycle specifications (PCSpecs), which specify an interval of time during which a single tag is written and verified. At the end of a programming cycle, applications receive a write report (PCWriteReport), which tells the applications whether the write was successful.

When several tags are to be written, one after another, each tag should be assigned a distinct EPC value. The Edge Server provides a mechanism for ensuring that each tag has a unique value. An EPC cache is a set of distinct EPC values, which can be used to provide EPC values to consecutive programming cycles without further application intervention. Applications receive cache reports (EPCCacheReport) to indicate when a cache is low or empty.

The following sections provide information about various aspects of writing tag data:

- Programming Cycles
- EPC Caches
- PCSpec Reports

### Programming Cycles

Tag writing services provided by the ALE API are organized around the notion of a programming cycle. A programming cycle is an interval of time during which a single tag is written and verified. Within a programming cycle, the reader attempts to ensure that there is a single tag in the field, write the tag, then read the tag to verify whether the write succeeded.

Like an event cycle, a programming cycle is an interval of time during which a specified operation takes place, at the conclusion of which a report is issued. And, like an event cycle, a programming cycle is specified through declarative specifications, in this case called programming cycle specifications (PCSpecs).

The overall pattern within a programming cycle consists of one or more "check" operations followed by one or more "verification cycles," each verification cycle consisting of a write attempt followed by one or more read attempts.

A check operation is a read carried out to verify that exactly one tag is in the field.

A verification cycle succeeds if the correct value is read from the tag, otherwise it fails. The programming cycle as a whole terminates successfully as soon as a successful verification cycle is completed.

In the diagram above, Programming Cycle 1 first checks that a single tag is in the field. It then performs a verification cycle, in which a write operation is performed, followed by a read operation. In the example, the read operation shows no tags, so it is repeated, and a tag value other than what was written is seen. Thus, this verification cycle is deemed a failure. A second verification cycle is performed, which succeeds.

Note: | A check operation is not needed before the second verification cycle, because the first verification cycle's read operations verify that a single tag is (still) in the field.

In Programming Cycle 2, the check operation sees two tags in the field, so the programming cycle immediately fails.

In Programming Cycle 3, each verification cycle's read shows the tag having a value other than the value written, so after `trials` attempts, the programming cycle fails.

The following parameters govern execution of a programming cycle:

- `trials`

The number of times an attempt is made to write the tag. If the PCSpec involves multiple logical readers, then each trial includes all logical readers.

- `duration`

The total amount of time allotted to attempting to program the tag.

A programming cycle as a whole terminates when the first successful verification cycle completes, or after trials is exhausted, or `duration` elapses, or a stop trigger is received, whichever comes first.

### Reader Implementation of Programming Cycles

Various reader manufacturers expose varying capabilities for tag writing. WebLogic RFID Edge Server maps between the definition of programming cycles, described in Programming Cycles, and the actual capabilities available on various types of readers.

For example, one vendor's reader provides a "verify" function which can be used to probe the field for tags, even unprogrammed or invalid tags, but does not return distinct codes for "no tag" versus "multiple tags in field." Therefore, this vendor's reader cannot directly implement WebLogic RFID Edge Server's "check" notion. However, the vendor's "program" function performs WebLogic RFID Edge Server's "check," "write," and "read" operations together, so WebLogic RFID Edge Server can map its programming cycle onto the vendor's reader capabilities.

In general, WebLogic RFID Edge Server presents a tag writing interface based on programming cycles as defined previously, and maps programming cycles onto each kind of supported reader. Sometimes the mapping is exact, and other times the mapping is approximate but yields correct results.

### EPC Caches

Programming cycles support a variety of use cases for tag writing. In the simplest case, an application makes an immediate request to write a single tag with a specified EPC value. In more complex cases, it is desirable for the ALE engine to write many tags (through consecutive programming cycles) without intervention by an application that specifies the EPC value for each programming cycle. These use cases are handled through the use of EPC caches.

A PCSpec can be associated with an EPC cache, which is a collection of EPC values. Multiple PCSpec instances can share the same EPC cache. WebLogic RFID Edge Server maintains the defined PCSpec instances and their EPC caches as part of its persistent state. Each time a PCSpec is activated, it takes the next EPC value from its EPC cache, and attempts to write that to a tag. When multiple PCSpec instances share a single cache, each will get a different EPC value each time it is activated. Hence, caches serve to ensure uniqueness of the EPC values written to tags.

When a PCSpec's EPC cache has at least one EPC value available for writing, the cache is said to be replenished. When it has no EPC values, it is said to be depleted. A PCSpec whose EPC cache is depleted cannot program tags. Applications can receive asynchronous notifications when cache instances are depleted or nearing depletion. Applications can also add more EPC values to an existing cache (whether or not the cache is currently depleted) through the `replenishEPCCache` API operation. There is also an API operation called `depleteEPCCache` that removes all remaining IDs from a the EPC cache; this is useful when an application knows that it will no longer use the cache, and wants to reclaim any unassigned EPC values for later use.

An application creates an EPC cache using the `defineEPCCache` operation, giving the name of the cache, and an `EPCCacheSpec` that specifies reporting parameters (these are described later). Optionally, initial contents of the EPC cache might be supplied to the `defineEPCCache` operation, in which case the EPC cache is initialized in the replenished state. Alternatively, an application might omit the initial contents in the define operation, in which case it must later call `replenishEPCCache` in order for the PCSpec to be able to write tags.

Abstractly, an EPC cache is an ordered list of EPC values. Concretely, the ALE API provides a simple way to specify EPC caches using the EPC Pattern URN notation. An EPC cache is specified by an ordered list of Pattern URNs. Each Pattern URN represents a range of EPC values ordered lexicographically; the contents of the EPC cache is the concatenation of the ranges corresponding to Pattern URNs in the list.

### Creating Tag Caches

Here are some examples of how to create tag caches.

This first example (GID-64-i tag format) is not in the EPC Tag Specification but will work with the Reader Simulator and help you to learn how to create tag patterns. For information about the simulator, see Using the Reader Simulator.

Pattern URNs | Cache Contents
urn:epc:pat:gid-64-i:1000.1000.1000 urn:epc:pat:gid-64-i:1000.1000.[2000-2002] urn:epc:pat:gid-64-i:1000.[100-101].[300-301] | urn:epc:tag:gid-64-i:1000.1000.1000 urn:epc:tag:gid-64-i:1000.1000.2000 urn:epc:tag:gid-64-i:1000.1000.2001 urn:epc:tag:gid-64-i:1000.1000.2002 urn:epc:tag:gid-64-i:1000.100.300 urn:epc:tag:gid-64-i:1000.100.301 urn:epc:tag:gid-64-i:1000.101.300 urn:epc:tag:gid-64-i:1000.101.301

Here is an example of creating a tag cache of SGTIN-64 tags.

Pattern URNs | Cache Contents
urn:epc:pat:sgtin-64:0.047400.126279.1 urn:epc:pat:sgtin-64:0.047400.126279.[10-13] | urn:epc:tag:sgtin-64:0.047400.126279.1 urn:epc:tag:sgtin-64:0.047400.126279.10 urn:epc:tag:sgtin-64:0.047400.126279.11 urn:epc:tag:sgtin-64:0.047400.126279.12 urn:epc:tag:sgtin-64:0.047400.126279.13

Here is an example of creating a tag cache of GID-96 tags.

Pattern URNs | Cache Contents
urn:epc:pat:gid-96:1000.1000.1000 urn:epc:pat:gid-96:1000.1000.[2000-2002] urn:epc:pat:gid-96:1000.[100-101].[300-301] | urn:epc:tag:gid-96:1000.1000.1000 urn:epc:tag:gid-96:1000.1000.2000 urn:epc:tag:gid-96:1000.1000.2001 urn:epc:tag:gid-96:1000.1000.2002 urn:epc:tag:gid-96:1000.100.300 urn:epc:tag:gid-96:1000.100.301 urn:epc:tag:gid-96:1000.101.300 urn:epc:tag:gid-96:1000.101.301

Typically, only one component of the pattern is a range.

Note that while the EPC values generated from any one EPC Pattern URN are distinct and in ascending order, different patterns used to replenish the same cache might overlap or appear in non-ascending sequence. If an application wants to ensure uniqueness of EPCs generated from the same cache (as is commonly the case), the application must always replenish the cache with unique patterns.

### PCSpec Reports

When a programming cycle completes, it sends a report to interested applications to say what happened. Unlike event cycle reports, however, the reports issued by a programming cycle are more limited in nature.

The Edge Server's tag programming facility can issue two kinds of report:

- Write report

Issued when a programming cycle completes, either successfully having written a tag value or because an error occurred. For a successful tag write, the report includes the EPC value that was written. For a failed tag write, the report contains information describing the error.

- Cache report

Issued when an EPC cache's number of remaining EPC values drops to (or below) a specified level.

PCSpec instances do not contain any parameters describing the write reports to be generated; this is in contrast to ECSpec instances which include one or more ECReportSpec instances describing the various reports generated by event cycles. EPCCacheSpec instances do contain parameters that describe the cache reports to be generated, including the threshold at which a cache report should be generated.

## Comparison of Event Cycles and Programming Cycles

WebLogic RFID Edge Server's approaches to tag reading (as embodied in event cycles) and tag writing (as embodied in programming cycles) are very similar, but differ in certain respects. Table 2-1summarizes the similarities and differences between event cycles and programming cycles.

Table 2-1

Metric | Event Cycle | Programming Cycle
Direction | The flow of tag data is in one direction: from tag, through the Edge Server, to application. | The flow of tag data is bidirectional: tag data flows from application to the Edge Server to say what tag ID should be written; tag data flows back from a tag through the Edge Server to the application when the write to the tag is verified.
Readers | One or more logical readers; each can be a single antenna, or multiple antennas, or a composite of other logical readers. | Same, but multiple antennas are used differently. In the reading case, the event cycle combines the set of tags seen by all of the antennas. In the writing case, the programming cycle tries writing with each antenna in turn until the tag is successfully written. The "check" and "read" operations are carried out using all antennas.
Cycle start condition | Start trigger, repeat interval, or `immediate`/`poll` by application. | Start trigger, or `immediate`/`poll` by application. There can be no repeat interval.
Cycle end condition | Stop trigger, duration, stable field interval, or all applications `unsubscribe`. | Successful tag write, unless stopped first by stop trigger, duration, trials, application `undefine`/`suspend`.
Reports | One or more tag read reports, each specifying report type, report set, report groups, and filters. | Reports of specific events, including: Successful tag write Failed tag write EPC cache level low
Report Subscriptions | Applications that subscribe to know what tags are in the field. | Two kinds of subscription: Applications that subscribe to write reports are notified whenever a tag programming operation completes. Applications that subscribe to low-cache reports are notified when the cache is low.
API operations | `define`, `undefine`, `subscribe`, `unsubscribe`, `poll`, `immediate`. | PCSpec operations: `define`, `undefine`, `subscribe`, `unsubscribe`, `poll`, `immediate`. EPCCacheSpec operations: `defineEPCCache,` `undefineEPCCache`, `replenishEPCCache`, `depleteEPCCache`, `subscribeEPCCache`, `unsubscribeEPCCache`.

Comparing Event Cycles and Programming Cycles