|
|
The following sections describe the ALE API programming components that you use to read tags and include a formal, abstract specification of the ALE API. The external interface of the ALE API for reading tags is defined by the ALE class (See ALE: Main Tag Reading Interface with UML Diagrams). This interface uses complex data types that are documented in the sections starting at ECSpec Data Type. The ALE API is compliant with the EPCglobal ALE 1.0 specification.
One or more clients make method calls to the ALE interface. Each method call is a request, which causes the ALE engine to take an action and return results. Thus, methods of the ALE interface are synchronous.
The ALE interface also enables clients to subscribe to events that are delivered asynchronously, by using methods that take a URI as an argument. Such methods return results immediately, but subsequently the ALE engine within the Edge Server can asynchronously deliver information to the consumer denoted by the URI argument.
In the sections that follow, the API is described using Unified Modeling Language (UML) class diagram notation, as shown below:
The box as a whole refers to a conceptual class, having the specified data members and methods. Within the UML descriptions, data members and methods are marked as belonging to one of the following categories:
The ALE API is realized in several equivalent forms within the RFID Edge Server:
Each of these concrete forms of the ALE API has a slightly different structure and gives slightly different names to the different conceptual classes, data members, and methods defined in UML within this section. These differences are unavoidable, owing to syntactic constraints and stylistic norms within these different implementation technologies.
In most cases, the mapping from conceptual UML to the concrete details of any particular binding is very straightforward. Where it is not, the specific documentation for each binding makes clear the relationship to the UML. The UML-level descriptions in these sections are normative.
./share/schemas:EPCglobal-ale-1_0.wsdl ./share/schemas:EPCglobal-ale-1_0-RFTagAware-extensions.xsdDefines the schema extensions.
Also see XML Representations.
ALE is the main Application Level Events (ALE) application programming interface.
Java implementation package: com.connecterra.ale.api
An ECSpec is a complex type that defines how an event cycle is to be calculated.
An event cycle can be triggered in two ways:
ECSpec can be posted using the define method. Subsequently, one or more clients subscribe to that ECSpec using the subscribe method. The ECSpec generates event cycles as long as there is at least one subscriber.
A poll call is like subscribing then unsubscribing immediately after one event cycle is generated (except that the results are returned from poll instead of being sent to a URI).
ECSpec can be submitted for immediate execution using the immediate method. This is equivalent to defining an ECSpec, performing a single poll operation, and then undefining it.
The execution of ECSpec instances is defined formally as follows. Each ECSpec instance is in one of three states: unrequested, requested, and active. An ECSpec is in the requested state it meets one or more of the following conditions:
define, it has not yet been undefined, and there has been at least one subscribe call for which there has not yet been a corresponding unsubscribe call.define, it has not yet been undefined, a poll call has been made, and the first event cycle since the poll was received has not yet been completed.immediate method, and the first event cycle has not yet been completed.
Once requested, an ECSpec is in the active state if reads are currently being accumulated into an event cycle based on the ECSpec. Standing ECSpec instances that are requested using subscribe can transition between active and inactive multiple times. ECSpec instances that are requested using poll or created using immediate will transition between active and inactive just once (though in the case of poll, the ECSpec remains defined afterward so that it could be subsequently polled again or subscribed to).
Two other methods are provided to manipulate ECSpec instances while preserving existing subscriptions:
suspend and unsuspend methods let you temporarily "suspend" an ECSpec without removing its subscriptions. While an ECSpec is suspended, you can add and remove subscriptions using the subscribe and unsubscribe methods, but the ECSpec behaves as though it is in the unrequested state — it causes no read cycles to take place, and generates no ECReports.redefine method lets you replace the definition of an ECSpec. It is roughly equivalent to unsubscribing all subscribers, undefining the ECSpec, defining a new ECSpec with the same name, then replacing the subscribers. The redefine method is intended for development and not production use, because it might cause a gap in event cycle processing.Figure 4-1 shows how the methods described in "ALE: Main Tag Reading Interface with UML Diagrams" on page 4-3 affect an ECSpec.
In addition, the two methods getStandardVersion and getVendorVersion return information about compliance with EPCglobal specifications:
getStandardVersion returns a string that identifies which version of the EPCglobal ALE specification this implementation complies with. For this version of WebLogic RFID Edge Server, the method returns the string 1.0.getVendorVersion returns a string that identifies the vendor extensions this implementation provides. For this version of WebLogic RFID Edge Server, this method returns the string http://version.connecterra.com/ALE/1.
The primary data types associated with the ALE API are:
ECSpec, which specifies how an event cycle is to be calculated and reportedECReports, which contains one or more reports generated from one activation of an ECSpec.
ECReports instances are returned from the poll and immediate methods, and also sent to URIs when ECSpec instances are subscribed to using the subscribe method.
For detailed information on the ECSpec and ECReports data types, see ECSpec Data Type and ECReports Data Type.
Java implementation package: com.connecterra.ale.api.
An ECSpec is a complex type that describes an event cycle and one or more reports that are to be generated from it. The following sections provide information about ECSpecs:
ECSpec as part of every ECReports instance generated by this ECSpec.ECReports instance generated from this ECSpec.
Java Implementation Notes: In the Java API, ECSpec does not include a boundaries data member that references an ECBoundarySpec. Rather, in Java, ECSpec provides getter and setter methods for accessing ECBoundarySpec data members (startTrigger, repeatPeriod, and so on) directly. See the
Javadoc and ECBoundarySpec.
Both an ECSpec's associated ECBoundarySpec and ECReportSpec can contain an optional <stableCount> element. This element modifies the Stable Set Interval (SSI) stop condition on an Event Cycle by modifying the requirements that must be fulfilled before the SSI will cause an Event Cycle to terminate. Java access is provided by the following methods:
| Note: | It is an error to specify a stableCount element in a reportSpec that uses an ECReportSetSpec of DELETIONS. |
If no stableCount elements are present, the stable set condition's semantics are identical to those in prior releases: the number of tags in the event cycle must be constant for the specified duration before the SSI will end the Event Cycle.
If one or more reports specify a stableCount, but the ECSpec has no top-level stableCount, the stable set interval is calculated only with respect to those reports that include the count. A report is considered stable if its included tag count has been stable for the entire stable set interval, and the included tag count is greater than or equal to the specified stableCount. The stable set interval ends the Event Cycle once all reports that contain a stableCount are stable.
If stableCount is specified at the ECSpec level, and no reports contain a stableCount, the count of tags in the event cycle must reach the specified value before the SSI condition will trigger the end of the event cycle.
If stableCount is present in reports and at the top level, both of the preceding conditions must be met before the SSI will cause the event cycle to end. Each report with an associated stableCount must be stable, and the number of tags in the event cycle must be stable and greater than or equal to the top-level stableCount before the SSI triggers.
If stableCount is specified but Stable Set Interval is specified (with either stableSetInterval or stableSetIntervalReadCycles), the rules apply as if the stable set interval is specified as 0, and ends the event cycle immediately when the stable count conditions are met. It is an error to specify an ECSpec with an implicit or explicit stable set interval of 0 unless at least one stableCount is specified nonzero.
An ECBoundarySpec specifies how the beginning and end of event cycles are determined, as described in the following sections:
The time values duration and stableSetInterval can be expressed in either of two units: milliseconds or read cycles. One read cycle unit denotes the time required to complete one read cycle for every reader that is included in the event cycle. The time values must be non-negative. Zero means "unspecified" (in which case the value of the corresponding units argument is irrelevant).
startTrigger and repeatPeriod are mutually exclusive.
The conditions under which an event cycle is started depends on the settings for startTrigger and repeatPeriod:
An event cycle, once started, extends until one of the following is true:
| Note: | The first of these conditions to become true terminates the event cycle. For example, if both duration and stableSetInterval are specified, then the event cycle terminates when the duration expires, even if the reader field has not been stable for stableSetInterval. But if the field is stable for stableSetInterval, the event cycle terminates even if the total time is shorter than the specified duration. Likewise, if both duration and durationReadCycles are specified, the event cycle terminates when the first of these time periods elapses. |
In all the preceding descriptions, an ECSpec presented through the immediate method means that the ECSpec transitions from unrequested to requested immediately upon calling immediate, and transitions from requested to unrequested immediately after completion of the event cycle.
| Note: | URIs specify an event cycle's start or stop triggers. See Triggers for more information about trigger URIs. |
It is possible to specify both duration and stableSetInterval in units of milliseconds and/or units of read cycles. Be careful when you use units of read cycles. If any reader experiences a failure during the event cycle, it will not complete its read cycles, and thus time as measured in read cycles might never reach the limits set for duration or stableSetInterval. For this reason, it is highly recommended that you include a duration in units of milliseconds, to act as an overall timeout for the event cycle.
Java: ECBoundarySpec,ECTime, ECTimeUnit, and ECTrigger are not visible in the Java API. Instead, they are encapsulated by the ECSpec methods:
See the Javadoc for information on these methods.
XML: To express duration and stableSetInterval in read cycles (rather than milliseconds), use the ECBoundarySpec elements durationReadCycles and stableSetIntervalReadCycles.
ECTime denotes a span of time in an ECBoundarySpec, measured in physical time units. See ECBoundarySpec and ECBoundarySpec Implementation Notes.
ECTimeUnit is an enumerated type denoting different units of physical time that can be used in an ECBoundarySpec. See ECBoundarySpec and ECBoundarySpec Implementation Notes. ECTimeUnit currently supports only one time unit (milliseconds).
ECTrigger denotes a URI that specifies a start or stop trigger for an event cycle. See ECBoundarySpec and ECBoundarySpec Implementation Notes.
Java implementation package: com.connecterra.ale.api
An ECReportSpec specifies one report to be returned from executing an event cycle. An ECSpec contains one or more ECReportSpec instances.
The reportSet parameter specifies the set of EPCs to be considered for reporting: all currently read, additions from the previous event cycle, or deletions from the previous event cycle. The filter parameter specifies how the raw EPCs are filtered before inclusion in the report. The group parameter (of type ECGroupSpec) specifies how the filtered EPCs are grouped together for reporting. If no group parameter is specified, then all EPCs are placed in a single default group. The output parameter specifies whether to return the EPCs themselves, a count, or both.
The reportIfEmpty parameter specifies whether this report should be included in the final ECReports instance if the final, filtered list of EPCs is empty; that is, if the final EPC list would be empty, or if the final count would be zero. If the parameter is set to:
If reportOnlyOnChange set to true, in the case of a standing report request, then reports will not be sent to subscribers unless the filtered list of EPCs is different from the previous event cycle's filtered list of EPCs. This comparison takes place before the filtered list has been modified based on reportSet or output parameters. The comparison also disregards whether the previous report was actually sent due to the effect of this boolean, or the reportIfEmpty boolean.
The essential parameter specifies whether this report is considered "essential" for the containing event cycle. "Essential" means that this report must be present for an ECReports instance to be generated. In the event that more than one report is essential, all such reports must be present for an ECReports instance to be generated.
For example, in a shipment-receiving application there might be an event cycle with two ECReportSpec instances. The first, for which essential=true, has a filter set to include only those tags that match the tags expected in a particular shipment. The second, for which essential=false, has a count of all tags read. If a shipment is received that contains at least one item on the expected list, then an ECReports instance is delivered that contains a list of the tags expected, and a total count of all tags read. If, however, a shipment contains no tags from the expected list, the essential setting on the first report suppresses the generation of any other report, and no notification is delivered.
| Note: | If the report has been marked essential=true, consider whether to change the default "empty report" behavior (omit the report when it is empty), which is controlled by the reportIfEmpty parameter. |
The reportName parameter is an arbitrary string that is copied to the ECReport instance created when this event cycle completes. The reportName parameter enables a client to distinguish which ECReport instance that it receives corresponds to which ECReportSpec instance contained in the original ECSpec. This capability is especially useful in cases where fewer reports are delivered than there were ECReportSpec instances in the ECSpec, because false reportIfEmpty settings suppressed the generation of some reports.
Java Implementation Notes: ECFilterSpec, ECGroupSpec, and ECReportOutputSpec are not visible in the Java API. Instead, they are encapsulated in the ECReportSpec methods:
get/set/addIncludePattern and get/set/addExcludePatternSee ECFilterSpec.
get/setGroupSpecSee ECGroupSpec.
includeList, includeCountSee ECReportOutputSpec.
Java implementation package: com.connecterra.ale.api
ECReportSetSpec is an enumerated type that specifies the set of EPCs to be considered for filtering and output: all EPCs read in the current event cycle, additions from the previous event cycle, or deletions from the previous event cycle.
An ECFilterSpec specifies what EPCs are to be included in the final report.
The ECFilterSpec implements a flexible filtering scheme based on two pattern lists. Each list contains zero or more URI-formatted EPC patterns. Each EPC pattern denotes a single EPC, a range of EPCs, or some other set of EPCs. (Patterns are described in detail in EPC Patterns.)
An EPC is included in the final report if (a) the EPC does not match any pattern in the excludePatterns list, and (b) the EPC does match at least one pattern in the includePatterns list. The (b) test is omitted if the includePatterns list is empty.
This can be expressed in mathematical notation as follows:
F(R) = { epc | epc in R & epc in I1 & ... & epc in In & epc not in E1 & ... & epc not in En }
where Ii denotes the set of EPCs matched by the ith pattern in the includePatterns list, and Ei denotes the set of EPCs matched by the ith pattern in the excludePatterns list.
Java Implementation Notes: ECFilterSpec is not visible in the Java API. Instead, it is encapsulated by the ECReportSpec methods:
See the Javadoc for information on these methods.
EPC Patterns are used to specify filters within an ECFilterSpec. The complete syntax is defined by the EPCglobal EPC Tag Data Standard Version 1.1 rev 1.27. Consult that document, available at
http://www.epcglobalinc.org/standards_technology/specifications.html, for full details. Highlights are summarized here.
A single EPC pattern is a URI-formatted string that denotes a single EPC or set of EPCs. The general format is:
urn:epc:pat:TagEncodingName:Filter.DomainManager.ObjectClass.SerialNumber
where the four fields Filter, DomainManager, ObjectClass, and SerialNumber correspond to fields of an EPC. (Depending on the TagEncodingName, some of these fields might not be present. Consult the EPCglobal EPC Tag Data Standard for details.) In an EPC pattern, each of those fields can be (a) a decimal integer, meaning that a matching EPC must have that specific value in the corresponding field; (b) an asterisk (*), meaning that a matching EPC might have any value in that field; or (c) a range denoted like [lo-hi], meaning that a matching EPC must have a value between the decimal integers lo and hi, inclusive. (The tag data standards document includes restrictions and further details not documented here.)
Here are some examples. In these examples, assume that 20 is the Domain Manager for XYZ Corporation, and 300 is the Object Class for its UltraWidget product, and that GID-96 tag encodings are used.
ECGroupSpec defines how filtered EPCs are grouped together for reporting.
For detailed information, see About Group Reports
Java Implementation Notes: ECGroupSpec is not visible in the Java API. Instead, it is encapsulated by the ECReportSpec methods getGroupSpec and setGroupSpec.
See the Javadoc for information on these methods.
Sometimes it is useful to group EPCs read during an event cycle based on portions of the EPC or attributes of the objects identified by the EPCs. For example, in a shipment receipt verification application, it is useful to know the quantity of each type of case (for example, each distinct case GTIN), but not necessarily the serial number of each case. This requires slightly more complex processing, based on grouping patterns.
You specify groups by supplying one or more group patterns in the patternList field of ECGroupSpec. Each element of the pattern list is an EPC Pattern URI as defined by the EPCglobal EPC Tag Data Standard, extended by allowing the character X in each position where a * character is allowed. Pattern URIs used in an ECGroupSpec are interpreted as follows:
Here are examples of pattern URIs used as grouping patterns:
In the corresponding ECReport, each group is named by another EPC Pattern URI that is identical to the grouping pattern URI, except that the group name URI has an actual value in every position where the grouping pattern URI had an X character.
For example, if these are the filtered EPCs read for the current event cycle:
urn:epc:tag:sgtin-64:3.0036000.123456.400
urn:epc:tag:sgtin-64:3.0036000.123456.500
urn:epc:tag:sgtin-64:3.0029000.111111.100
urn:epc:tag:sscc-64:3.0012345.31415926
Then a pattern list consisting of just one element, like this:
urn:epc:pat:sgtin-64:*.X.*.*
would generate the following groups in the report:
Every filtered EPC that is part of the event cycle is part of exactly one group. If an EPC does not match any of the EPC Pattern URIs in the pattern list, it is included in a special "default group." The name of the default group is null. In the above example, the SSCC EPC did not match any pattern in the pattern list, and so was included in the default group.
As a special case of the above rule, if the pattern list is empty (or if the group parameter of the ECReportSpec is null or omitted), then all EPCs are part of the default group.
In order to ensure that each EPC is part of only one group, there is an additional restriction that all patterns in the pattern list must be pairwise disjoint. Disjointness of two patterns is defined as follows. Assume Pat_i and Pat_j are two pattern URIs, written as a series of fields:
Pat_i = urn:epc:pat:type_i:field_i_1.field_i_2.field_i_3...
Pat_j = urn:epc:pat:type_j:field_j_1.field_j_2.field_j_3...
Then Pat_i and Pat_j are disjoint if:
The formal definition of grouping is as follows. A group operator G is specified by a list of pattern URIs:
G = (Pat_1, Pat_2, ..., Pat_N)
If each pattern is written as a series of fields, where each field_i_j is either X, *, Number, or [Lo-Hi].
Pat_i = urn:epc:pat:type_i:field_i_1.field_i_2.field_i_3...
Then the definition of G(epc), the group name associated with a specific EPC, is as follows:
urn:epc:tag:type_epc:field_epc_1.field_epc_2.field_epc_3...
The epc is said to match Pat_i if
Because of the disjointedness constraint specified above, the epc is guaranteed to match at most one of the patterns in G.
The group name G(epc) is then defined as follows:
ECReportOutputSpec specifies how the final set of EPCs is to be reported.
If any one of the four Booleans includeEPC, includeTag, includeRawHex, or includeRawDecimal is true, the report includes a list of the EPCs in the final set for each group. Each element of this list, when included, includes the formats specified by these four Booleans. If includeCount is true, the report includes a count of the EPCs in the final set for each group. Both might be true, in which case each group includes both a list and a count. If all five Booleans includeEPC, includeTag, includeRawHex, includeRawDecimal, and includeCount are false, then the define and immediate methods raise an exception.
Java Implementation Notes: ECReportOutputSpec is not visible in the Java API. Instead, it is encapsulated by these ECReportSpec methods:
See the Javadoc for information on these methods.
Java implementation package: com.connecterra.ale.api
The following sections provide information related to ECReports:
ECReports is the output from an event cycle.
The most important part of an ECReports instance is the list of ECReport instances, each corresponding to an ECReportSpec instance in the event cycle's ECSpec. In addition to the reports themselves, ECReports contains a number of "header" fields that provide useful information about the event cycle.
Indicates what kind of event caused the event cycle to terminate: the receipt of an explicit stop trigger, the expiration of the event cycle duration, or the set of EPCs being stable for the prescribed amount of time. These correspond to the possible ways of specifying the end of an event cycle as defined in ECBoundarySpec.
|
|
Java implementation package: com.connecterra.ale.api
ECTerminationCondition is an enumerated type that describes how an event cycle was ended.
The first three values, TRIGGER, DURATION, and STABLE_SET, correspond to the receipt of an explicit stop trigger, the expiration of the event cycle duration, or the set of EPCs being stable for the event cycle stableSetInterval, respectively. These are the possible stop conditions described in ECBoundarySpec.
The last value, UNREQUEST, corresponds to an event cycle being terminated because there were no longer any clients requesting it. By definition, this value cannot actually appear in an ECReports instance sent to any client.
Java implementation package: com.connecterra.ale.api
ECReport represents a single report within an ECReports instance that is generated by an event cycle.
The reportName field is a copy of the reportName field from the corresponding ECReportSpec within the ECSpec that controlled this event cycle. The groups field is a list containing one element for each group in the report as controlled by the group field of the corresponding ECReportSpec. When no grouping is specified, the groups list contains the single default group. Each element of the list is an instance of ECReportGroup.
Java Implementation Notes: The Java API provides two methods (hasCount and hasList) that indicate whether each contained ECReportGroup instance includes an ECReportGroupCount instance and an ECReportGroupList instance, respectively.
Java implementation package: com.connecterra.ale.api
ECReportGroup represents one group within an ECReport.
The groupName is null for the default group (in XML, the group name is omitted to indicate the default group). Otherwise, the groupName is a string calculated as specified in About Group Reports.
The groupList field is null if the includeEPC, includeTag, includeRawHex, and includeRawDecimal fields of the corresponding ECReportOutputSpec are all false.
The groupCount field is null if the includeCount field of the corresponding ECReportOutputSpec is false.
Java Implementation Notes: The Java API provides two methods (hasCount and hasList) that indicate whether this ECReportGroup instance includes an ECReportGroupCount instance and an ECReportGroupList instance, respectively.
An ECReportGroupList is included in an ECReportGroup when any one of the four Boolean fields includeEPC, includeTag, includeRawHex, and includeRawDecimal of the corresponding ECReportOutputSpec is true.
The order in which EPCs are enumerated within the list is unspecified.
Java Implementation Notes: ECReportGroupList is not visible in the Java API. Instead, it is encapsulated by the ECReportGroup method getGroupList. See the
Javadoc for information on this method.
Java implementation package: com.connecterra.ale.api
Each member of the ECReportGroupList is an ECReportGroupListMember as defined below. ECReportGroupListMember allows multiple EPC formats to be included and provides an extension point for adding per-EPC information to the list report.
Each of the URI fields either contains a URI or is null, depending on the value of a boolean in the corresponding ECReportOutputSpec. For example, the epc field is non-null if and only if the includeEPC field of ECReportOutputSpec is true.
When non-null, the epc field contains an EPC represented as a pure identity URI according to the EPCglobal EPC Tag Data Standard (urn:epc:id:...). A pure identity URI contains just the EPC, with no additional information such as tag type, filter bits, and so on. If the information on the tag cannot be successfully decoded into a pure identity URI, the epc field contains a raw decimal URI instead.
When non-null, the tag field contains an EPC represented as a tag URI according to the EPCglobal EPC Tag Data Standard (urn:epc:tag:...). A tag URI contains all information on the tag, including the EPC, tag type, and filter bits (when applicable). The tag URI is also suitable for use in writing tags using the ALEPC API (see Reading and Writing Tags and Writing Tags by Using the ALEPC API). If the information on the tag cannot be successfully decoded into a tag URI, the tag field contains a raw decimal URI instead.
When non-null, the rawDecimal field contains a raw tag value represented as a raw decimal URI according to the EPCglobal EPC Tag Data Standard (urn:epc:raw:...).
When non-null, the rawHex field contains a raw tag value represented as a raw hexadecimal URI according to the following extension to the EPCglobal EPC Tag Data Standard. The URI is determined by concatenating the following: the string urn:epc:raw:, the length of the tag value in bits, a dot (.) character, a lowercase x character, and the tag value considered as a single hexadecimal integer. The length value preceding the dot character has no leading zeros. The hexadecimal tag value following the dot has a number of characters equal to the length of the tag value in bits divided by four and rounded up to the nearest whole number, and uses only uppercase letters for the hexadecimal digits A, B, C, D, E, and F.
Each distinct tag value included in the report has a distinct ECReportGroupListMember element in the ECReportGroupList, even if those ECReportGroupListMember elements would be identical due to the formats selected. In particular, it is possible for two different tags to have the same pure identity EPC representation; for example, two SGTIN-64 tags that differ only in the filter bits. If both tags are read in the same event cycle, and ECReportOutputSpec specified includeEPC true and all other formats false, then the resulting ECReportGroupList has two ECReportGroupListMember elements, each having the same pure identity URI in the epc field. In other words, the result should be equivalent to performing all duplicate removal, additions/deletions processing, grouping, and filtering before converting the raw tag values into the selected representation(s).
The situation in which this rule applies is expected to be extremely rare. In theory, no two tags should be programmed with the same pure identity, even if they differ in filter bits or other fields not part of the pure identity.
See the EPCglobal Tag Data Standard for more information on URI representations of Electronic Product Codes.
An ECReportGroupCount is included in an ECReportGroup when the includeCount field of the corresponding ECReportOutputSpec is true.
The count field is the total number of distinct EPCs that are part of this group.
Java Implementation Notes: ECReportGroupCount is not visible in the Java API. Instead, it is encapsulated by the ECReportGroup method getGroupCount. See the
Javadoc for information on this method.
An ECReportGroupListMemberMemory provides access to the individual memory values returned in the ECReport from the Edge Server.
There are two URI forms for specifying a memory location on a tag:
When performing absolute addressing, the URI needs to include a selection for the memory bank, an offset within the memory bank, and a length of the memory extent, in bits.
urn:connecterra:tagmem:@bankid.length[.offset]
Where bankid is, in Gen2, one of the four values: epc, tid, user, or reserved. Length and offset are integer values in bits, specified as decimal. The default offset value is 0.
When referring to a symbolic name, the URI simply includes the name.
urn:connecterra:tagmem:name
In the current implementation, the only valid value for name is epc.
Data is padded before being returned as a 64-, 96-, or 128-bit value. For example, 48 bits of data would be returned as a padded 64-bit value.
The following sections define other types that are used in the WebLogic RFID Edge Server ALE API. These types are all BEA extensions to the EPCglobal specification.
Java implementation package: com.connecterra.ale.api
ECSpecInfo gives information about the current state of a defined ECSpec.
XML Implementation Notes: ECSpecInfo values are expressed in the element EventCycleSpecInfo.
Java implementation package: com.connecterra.ale.api
ECSubscriptionInfo gives information about a specific subscriber to an ECSpec.
XML Implementation Notes: ECSubscriptionInfo values are expressed in the element EventCycleSubscriptionInfo.
Java implementation package: com.connecterra.ale.api
ECSubscriptionControls contains parameters that govern when subscriptions are automatically unsubscribed in case of delivery failures. Most subscriptions are governed by a default set of parameters that are configured when the Edge Server is deployed. When a client wants to override these settings for a specific subscription, the client uses the form of the ALE subscribe call that takes an explicit ECSubscriptionControls argument.
XML Implementation Notes: ECSubscriptionControl values are expressed in the element EventCycleSubscriptionControls.
The focal points of the ALE tag reading interface from an application perspective are the ECSpec and ECReports objects. The Edge Server provides a standard way of representing ECSpec and ECReports instances in XML. The XML form of ECReports is used by most asynchronous event cycle delivery mechanisms, as described in Asynchronous Notification Mechanisms. User applications can also use the XML forms as a means of interchange, and for persistent storage.
The XML forms of ECSpec and ECReports are defined by the XSD files:
EPCglobal-ale-1_0.xsd
Defines EPCglobal ALE schema; references BEA extensions. ECSpec and ECReports are both defined in this schema. The top-level element for ECSpec is ECSpec; for ECReports the top-level element is ECReports.
EPCglobal.xsd
Defines the EPCglobal common types, Document and EPC, referred to by EPCglobal-ale-1_0.xsd.
EPCglobal-ale-1_0-RFTagAware-extensions.xsd
These files are located in your installation directory under share/schemas.
The Java binding for ALE provides XML serializer and deserializer classes for translating between the XML representation and the Java representation of the ECSpec and ECReports types. Applications use these facilities to process reports received via the Edge Server's asynchronous event cycle delivery mechanisms, and for other purposes. The sample applications bundled with WebLogic RFID Edge Server illustrate the use of the serializer and deserializer classes. See Using XML Serializers and Deserializers from Java for more information.
The remainder of this section presents examples of ECSpec and ECReports as rendered into XML:
These examples include additional line breaks and whitespace for the sake of readability. WebLogic RFID Edge Server permits (but does not require) this whitespace when reading XML; usually the server omits this whitespace when writing XML.
Here is an example ECSpec rendered into XML:
<?xml version="1.0" encoding="UTF-8"?>
<ale:ECSpec xmlns:ale="urn:epcglobal:ale:xsd:1"
xmlns:aleext="http://schemas.connecterra.com/EPCglobal-extensions/ale"
creationDate="2004-11-15T16:18:43.500Z"
schemaVersion="1.0"
includeSpecInReports="false" >
<logicalReaders>
<logicalReader>ConnecTerra1</logicalReader>
</logicalReaders>
<boundarySpec>
<duration unit="MS">2000</duration>
</boundarySpec>
<reportSpecs>
<reportSpec reportName="SubscribeSample Report">
<reportSet set="CURRENT" />
<output includeCount="true"
includeEPC="false"
includeRawDecimal="false"
includeRawHex="false"
includeTag="true" />
</reportSpec>
</reportSpecs>
<aleext:applicationData>application-specific data here</aleext:applicationData>
</ale:ECSpec>
Here is an example ECReports rendered into XML:
<ale:ECReports ALEID="EdgeServerID" creationDate="2005-01-06T16:47:57.296Z" date="2005-01-06T16:47:57.296Z"
schemaURL="http://schemas.connecterra.com/EPCglobal/ale-1_0.xsd"
schemaVersion="1"
specName="sampleECSpec"
terminationCondition="DURATION"
totalMilliseconds="2015"
xmlns:ale="urn:epcglobal:ale:xsd:1"
xmlns:aleext="http://schemas.connecterra.com/EPCglobal-extensions/ale">
<reports>
<report reportName="SubscribeSample Report">
<group>
<groupList>
<member>
<tag>urn:epc:tag:gid-64-i:10.50.5</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.40.4</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.10.1</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.30.3</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.70.7</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.20.2</tag>
</member>
<member>
<tag>urn:epc:tag:gid-64-i:10.60.6</tag>
</member>
</groupList>
<groupCount>
<count>7</count>
</groupCount>
</group>
</report>
</reports>
<aleext:applicationData>application-specific data here</aleext:applicationData>
<aleext:failedLogicalReaders/>
<aleext:physicalReaders>
<aleext:physicalReader>SimReadr</aleext:physicalReader>
</aleext:physicalReaders>
<aleext:totalReadCycles>8</aleext:totalReadCycles>
</ale:ECReports>
When you use the Java binding of the ALE API, there are additional Java interfaces and classes available to you beyond what is described previously in this chapter. This section gives a brief introduction to those additional interfaces and classes. For full documentation, see the Javadoc.
To use the ALE tag reading API from Java, you create an instance of the SOAPALEClient class provided in the com.connecterra.ale.client package. This class implements the ALE interface as described in ALE: Main Tag Reading Interface with UML Diagrams and provides all of the methods described there. It also provides an additional method, getALEFactory, which returns a factory for creating instances of other types, described below. The SOAPALEClient interacts with a WebLogic RFID Edge Server over the network using SOAP over HTTP. When you construct an instance of SOAPALEClient, you provide a service URL for the Edge Server with which you want to interact.
When using the SOAPALEClient class, you need to create instances of ECSpec and other types described in this chapter. The ALEFactory interface (in package com.connecterra.ale.api) provides methods for creating instances of those types. You obtain an instance of the ALEFactory interface by calling the getALEFactory method provided by the SOAPALEClient class. When passing arguments to methods of a specific SOAPALEClient instance, you must always use the factory instance provided by that SOAPALEClient instance.
The Java binding of the ALE API provides some additional utility classes for reading and writing XML representations of the data types used in the ALE API. With these classes, you can convert a Java object representation of a particular data type into XML ("serialization"), and likewise convert an XML representation of a particular data type back into a Java object ("deserialization"). The XML schemas are in the product installation directory at:
/share/schemas/EPCglobal-ale-1_0.xsd
/share/schemas/EPCglobal.xsd
/share/schemas/EPCglobal-ale-1_0-RFTagAware-extensions.xsd
To read and write XML for types used in the ALE tag reading API, you use an instance of the XMLSerializationFactory provided in the com.connecterra.ale.encoding package. There is only one static instance of this class, which you obtain by using the static method getInstance(), passing the argument XMLSerializationSyntax.EPCglobal_ale_1_0. Using the XMLSerializationFactory instance, you can create instances of XMLSerializer and XMLDeserializer to serialize and deserialize instances of the following classes: ECSpec, ECReports, ECSpecInfo, ECSubscriptionInfo, and ECSubscriptionControls.
In support of the UHF Generation 2 Air Interface Protocol, BEA provides the following properties:
ECReportSpec has a new <includeMemory field="URI"> element, which can be specified multiple times. An includeMemory property is a list of URI objects, each of which corresponds to a tag memory section to read. Java access is provided by the following methods:
When this element is specified, the associated ECReportGroupListMember in the report will have a <memory field="URI">...</memory> element whose contents are a URI representing the contents of the requested memory segment. When the field in the includeMemory element is an EPC field, the contents are converted to a URI following the procedure as presented in the EPCglobal EPC Tag Data Standard. If the EPC must be returned raw, it is an EPC raw hex URI.
The value read is right-aligned; the LSB of the memory read is the LSB of the returned value, even when the width of the field is not a multiple of 8 bits.
The getMemoryItems() interface is an addition to the ECReportGroupListMember; the new interface provides access to the memory values returned in the ECReport from the Edge Server.
|