|
|
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:
| 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. |
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:
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:
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").
The BEA implementation of the ALE API provides:
For a full list of all the features in this release, see the Introduction and Roadmap section in the Product Overview manual.
The BEA implementation of the ALE API provides a number of unique benefits:
To use ALE from a program, use one of the following methods:
/share/schemas/EPCglobal-ale-1_0.wsdl/share/schemas/ALEPCService.wsdl
The following sections describe how tag data is read and reported:
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.
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:
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.
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.
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:
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.
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:
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.
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:
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:
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.
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.
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.
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.
Here is an example of creating a tag cache of SGTIN-64 tags.
Here is an example of creating a tag cache of GID-96 tags.
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.
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:
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.
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.
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
|