![]() ![]() ![]() ![]() ![]() ![]() ![]() |
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.xsd
Defines 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 5-1 shows how the methods described in "ALE: Main Tag Reading Interface with UML Diagrams" on page 5-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. Contact BEA customer support 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/addExcludePattern
See ECFilterSpec.
get/setGroupSpec
See ECGroupSpec.
includeList
, includeCount
See 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.
![]() ![]() ![]() |