# Programming with the ALE and ALEPC APIs

# Reading Tags by Using the ALE API

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.

- Overview of the ALE API Implementation
- ALE: Main Tag Reading Interface with UML Diagrams
- Primary ALE API Data Types
- ECSpec Data Type
- ECReports Data Type
- Other ALE API Types: BEA Extensions
- XML Representations
- Using the ALE Tag Reading API from Java
- Gen2 Read Support

## Overview of the ALE API Implementation

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:

`dataMember1 : Type1`
`dataMember2 : Type2`
`---`
`method1(ArgName:ArgType, ArgName:ArgType, ...) : ReturnType`
`method2(ArgName:ArgType, ArgName:ArgType, ...) : ReturnType`

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 EPCglobal ALE specification.
- BEA extensions to the EPCglobal ALE specification.

The ALE API is realized in several equivalent forms within the RFID Edge Server:

- There is a binding of the ALE API to a SOAP Web service, described by a WSDL file.
- The complex data types have a standard representation as XML documents, defined by an XSD schema.
- There is a binding of the ALE API to Java, in which the ALE API takes the form of a collection of Java interface and class definitions.

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.

- For specifics of the Java binding, see the online Javadoc.
- For specifics of the WSDL binding, see the WSDL file in your installation directory under `./share/schemas`:

    EPCglobal-ale-1_0.wsdl

- For specifics of the XML representation of the complex data types, see the following XSD files in your installation directory under `./share/schemas`:

- `EPCglobal-ale-1_0.xsd`

Defines EPCglobal ALE schema; references BEA extensions.

- `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`

Defines the schema extensions.

Also see XML Representations.

## ALE: Main Tag Reading Interface with UML Diagrams

`ALE` is the main Application Level Events (ALE) application programming interface.

Java implementation package: `com.connecterra.ale.api`

---
EPCglobal ALE
`define(ecSpecName: String, spec:ECSpec) : void`
`undefine(ecSpecName: String) : void`
`getECSpec(ecSpecName: String) : ECSpec`
`getECSpecNames() : List // returns a List of strings naming ECSpec instances`
`subscribe(ecSpecName: String, notificationURI:URI) : void`
`unsubscribe(ecSpecName: String, notificationUri:URI) : void`
`getSubscribers(ecSpecName: String) : List // returns a List of subscriber URIs`
`poll(ecSpecName: String) : ECReports`
`immediate(spec:ECSpec) : ECReports`
`getStandardVersion() : String`
`getVendorVersion() : String`
WebLogic RFID Edge Server Extensions
`getECSpecInfo(ecSpecName: String) : ECSpecInfo`
`redefine (ecSpecName: String, spec:ECSpec) : void`
`subscribe(ecSpecName: String, notificationURI: URI, controls: ECSubscriptionControls) : void`
`suspend (ecSpecName: String) : void`
`unsuspend (ecSpecName: String) : void`
`listLogicalReaderNames() : List // returns a List of Strings in sorted order naming all logical readers known to the ALE engine`
`getECSubscriptionInfo(ecSpecName: String, notificationURI:URI) : ECSubscriptionInfo`

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:

- A standing `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).

- An `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:

- The ECSpec has previously been defined using `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.
- The ECSpec has previously been defined using `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.
- The ECSpec was defined using the `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:

- The `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`.
- The `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.

### State Diagram

Figure 4-1 shows how the methods described in "ALE: Main Tag Reading Interface with UML Diagrams" on page 4-3 affect an ECSpec.

Figure 4-1 State Diagram

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`.

## Primary ALE API Data Types

The primary data types associated with the ALE API are:

- `ECSpec`, which specifies how an event cycle is to be calculated and reported
- `ECReports`, 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.

## ECSpec 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`:

- State Diagram
- ECBoundarySpec
- ECReportSpec
- ECReportSetSpec
- ECFilterSpec
- ECGroupSpec
- ECReportOutputSpec

An `ECSpec` contains:

- A list of readers whose reader cycles are to be included in the event cycle. Each member of this list is either a single logical reader or the name of a composite reader.
- A specification of how the boundaries of event cycles are to be determined.
- A list of report specifications, each of which describes a report to be generated from this event cycle.
- A Boolean value that indicates whether or not to include the complete `ECSpec` as part of every `ECReports` instance generated by this `ECSpec`.
- An optional "application data" string, which is copied unmodified into every `ECReports` instance generated from this `ECSpec`.
Figure 4-2 ECSpec UML Diagram

EPCglobal ALE
`readers : List // List of logical or composite reader names`
`boundaries : ECBoundarySpec`
`reportSpecs : List // List of one or more ECReportSpec instances`
`includeSpecInReports : boolean`
WebLogic RFID Edge Server Extensions
`applicationData : String`
`stableCount: int`
`---`

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:

- `com.connecterra.ale.ECSpec.getStableCount() : int`
- `com.connecterra.ale.ECSpec.setStableCount(int) : void`

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.

### ECBoundarySpec

An `ECBoundarySpec` specifies how the beginning and end of event cycles are determined, as described in the following sections:

- ECBoundarySpec Implementation Notes
- ECTime
- ECTimeUnit
- ECTrigger

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`:

- If `startTrigger` is specified, an event cycle is started when:

- The `ECSpec` is in the requested state and the specified start trigger is received.

- If `startTrigger` is not specified and `repeatPeriod` is specified, an event cycle is started when:

- The `ECSpec` transitions from the unrequested state to the requested state; or
- The `repeatPeriod` has elapsed from the start of the last event cycle, and in that interval the `ECSpec` has never transitioned to the unrequested state.

- If neither `startTrigger` nor `repeatPeriod` are specified, an event cycle is started when:

- The `ECSpec` transitions from the unrequested state to the requested state; or
- Immediately after the previous event cycle, if the `ECSpec` is in the requested state.

An event cycle, once started, extends until one of the following is true:

- The `duration` or `durationReadCycles`, when specified, expires.
- When the `stableSetInterval` or `stableSetIntervalReadCycles` is specified, no new EPCs have been reported by any reader in the specified interval.
- The `stopTrigger`, when specified, is received.
- The `ECSpec` transitions to the unrequested state.

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.

#### ECBoundarySpec Implementation Notes

`Java: ECBoundarySpec`,`ECTime`, `ECTimeUnit,` and `ECTrigger` are not visible in the Java API. Instead, they are encapsulated by the `ECSpec` methods:

- `get/setDurationMillis`
- `get/setDurationReadCycles`
- `get/setStableSetIntervalMillis`
- `get/setStableSetIntervalReadCycles`
- `get/setRepeatPeriodMillis`
- `get/setStartTrigger`
- `get/setStopTrigger`

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

`ECTime` denotes a span of time in an `ECBoundarySpec,` measured in physical time units. See ECBoundarySpec and ECBoundarySpec Implementation Notes.

EPCglobal ALE
`duration : long`
`unit : ECTimeUnit`
`---`

#### ECTimeUnit

`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).

EPCglobal ALE
`<<Enumerated Type>>`
`MS // Milliseconds`

#### ECTrigger

`ECTrigger` denotes a URI that specifies a start or stop trigger for an event cycle. See ECBoundarySpec and ECBoundarySpec Implementation Notes.

EPCglobal ALE
trigger: URI
---

### ECReportSpec

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.

EPCglobal ALE
`reportName : String`
`reportSet : ECReportSetSpec`
`filter : ECFilterSpec`
`group : ECGroupSpec`
`output : ECReportOutputSpec`
`reportIfEmpty : boolean`
`reportOnlyOnChange : boolean`
WebLogic RFID Edge Server Extensions
`essential : boolean`
`applicationData : String`
`stableCount : int`
`includedMemoryFields : List // of includedMemoryField : URI` (see includedMemory)
---

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:

- `false` - (default) This report is omitted when empty.
- `true` - This report is always included, even if it is empty.

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.

#### ECReportSpec Implementation Notes

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.

### ECReportSetSpec

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.

<<Enumerated Type>>
`CURRENT`
`ADDITIONS`
`DELETIONS`

### ECFilterSpec

An `ECFilterSpec` specifies what EPCs are to be included in the final report.

`includePatterns : List // List of URI-formatted EPC patterns`
`excludePatterns : List // List of URI-formatted EPC patterns`

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:

- `get/set/addIncludePattern`
- `get/set/addExcludePattern`

See the Javadoc for information on these methods.

#### EPC Patterns

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.

`urn:epc:pat:gid-96:20.300.4000` | Matches the tag for UltraWidget serial number 4000.
`urn:epc:pat:gid-96:20.300.*` | Matches any UltraWidget, regardless of serial number.
`urn:epc:pat:gid-96:20.*.[5000-9999]` | Matches any XYZ Corporation product whose serial number is between 5000 and 9999, inclusive.
`urn:epc:pat:gid-96:*.*.*` | Matches any GID-96.

### ECGroupSpec

ECGroupSpec defines how filtered EPCs are grouped together for reporting.

`patternList : List // List of pattern URIs`
---

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.

#### About Group Reports

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:

Pattern URI Field | Meaning
`X` | Create a different group for each distinct value of this field.
`*` | All values of this field belong to the same group.
Number | Only EPCs having Number in this field will belong to this group.
[Lo-Hi] | Only EPCs whose value for this field falls within the specified range will belong to this group.

#### Examples of Pattern URIs Used as Grouping Patterns

Here are examples of pattern URIs used as grouping patterns:

Pattern URI | Meaning
`urn:epc:pat:sgtin-64:X.*.*.*` | Groups by filter value (for example, case/pallet).
`urn:epc:pat:sgtin-64:*.X.*.*` | Groups by company prefix.
`urn:epc:pat:sgtin-64:*.X.X.*` | Groups by company prefix and item reference (groups by specific product).
`urn:epc:pat:sgtin-64:X.X.X.*` | Groups by company prefix, item reference, and filter.
`urn:epc:pat:sgtin-64:3.X.*.[0-100]` | Creates a different group for each company prefix, including in each such group only EPCs having a filter value of 3 and serial numbers in the range 0 through 100, inclusive.

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:

Group Name | EPCs in Group
`urn:epc:pat:sgtin-64:*.0036000.*.*` | `urn:epc:tag:sgtin-64:3.0036000.123456.400 urn:epc:tag:sgtin-64:3.0036000.123456.500`
`urn:epc:pat:sgtin-64:*.0029000.*.*` | `urn:epc:tag:sgtin-64:3.0029000.111111.100`
[default group] | `urn:epc:tag:sscc-64:3.0012345.31415926`

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:

- `type_i` is not equal to `type_j`
- `type_i = type_j` but there is at least one field k for which `field_i_k` and `field_j_k` are disjoint, as defined by the following table:

| X | * | Number | [Lo-Hi]
X | Not disjoint | Not disjoint | Not disjoint | Not disjoint
* | Not disjoint | Not disjoint | Not disjoint | Not disjoint
Number | Not disjoint | Not disjoint | Disjoint if the numbers are different | Disjoint if the number is not included in the range
[Lo-Hi] | Not disjoint | Not disjoint | Disjoint if the number is not included in the range | Disjoint if the ranges do not overlap

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

- `type_epc = type_i`; and
- For each field k, one of the following is true:

- `field_i_k = X`
- `field_i_k = *`
- `field_i_k` is a number, equal to `field_epc_k`
- `field_i_k` is a range `[Lo-Hi]`, and `Lo` is less than or equal to `field_epc_k`, which is less than or equal to `Hi`

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:

- If `epc` matches `Pat_i` for some i, then:

`G(epc) = urn:epc:pat:type_epc:field_g_1.field_g_2.field_g_3...`

where for each `k, field_g_k = *`, if `field_i_k = *`; or `field_g_k = field_epc_j`, otherwise.

- If `epc` does not match `Pat_i` for any `i`, then `G(epc) =` the default group.

### ECReportOutputSpec

ECReportOutputSpec specifies how the final set of EPCs is to be reported.

`includeEPC : boolean` `includeTag : boolean` `includeRawHex : boolean` `includeRawDecimal : boolean`
`includeCount : boolean`
---

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:

- `setIncludeEPC`
- `setIncludeTag`
- `setIncludeRawHex`
- `setIncludeRawDecimal`
- `setIncludeCount`

See the Javadoc for information on these methods.

## ECReports Data Type

Java implementation package: `com.connecterra.ale.api`

The following sections provide information related to `ECReports`:

- ECTerminationCondition
- ECReport
- ECReportGroup
- ECReportGroupList
- ECReportGroupListMember
- ECReportGroupCount
- ECReportGroupListMemberMemory
Figure 4-3 ECReports UML Diagram

ECReports is the output from an event cycle.

EPCglobal ALE
`specName : String`
`date : dateTime`
`ALEID : String`
`totalMilliseconds : long`
`terminationCondition : ECTerminationCondition`
`spec : ECSpec`
`reports : List // List of ECReport instances`
`schemaURL : URI`
WebLogic RFID Edge Server Extensions
`totalReadCycles : int`
`applicationData : String`
`physicalReaders : List // List of strings, each naming a physical reader`
`failedLogicalReaders : List // List of strings, each naming a logical reader`

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.

ECReports Header Field | Description
--- | ---
`specName` | The name of the `ECSpec` that controlled this event cycle. In the case of an `ECSpec` that was requested using the `immediate` method, this name is one chosen by the Edge Server.
`date` | The date and time when the event cycle ended.
`ALEID` | An identifier for the deployed instance of the Edge Server. This value is set by the `ale.savantID` property in the `edge.props` file and can be set in the installer.
`totalMilliseconds` | The total time, in milliseconds, from the start of the event cycle to the end of the event cycle.
`terminationCondition` | 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.
`spec` | A copy of the `ECSpec` that generated this ECReports instance. Only included if the `ECSpec` has `includeSpecInReports` set to `true`.
`schemaURL` | Specifies a URL for the XML schema for ALE API used in this version of WebLogic RFID Edge Server. This schema includes the BEA extensions to the EPCglobal ALE specification.
`totalReadCycles` | The total time, in read cycles, from the start of the event cycle to the end of the event cycle. When more than one reader contributed read cycles to this event cycle, this number is the number of read cycles contributed by the reader that contributed the fewest number of read cycles.
`applicationData` | A copy of the `applicationData` field of the `ECSpec` that controlled this event cycle.
`physicalReaders` | A list of strings, each identifying one of the physical readers that contributed to this event cycle. The mapping of physical and logical reader names is specified in the `edge.props` file.
`failedLogicalReaders` | A list of strings, each identifying a logical reader that reported failures during this event cycle. This list is always a subset of the `logicalReaders` field of the `ECSpec` that controlled this event cycle. If no failures occurred, `failedLogicalReaders` is empty.

### ECTerminationCondition

Java implementation package: `com.connecterra.ale.api`

`ECTerminationCondition` is an enumerated type that describes how an event cycle was ended.

<<Enumerated Type>>
`EPCglobal ALE`
`TRIGGER`
`DURATION`
`STABLE_SET`
`UNREQUEST`

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.

### ECReport

Java implementation package: `com.connecterra.ale.api`

`ECReport` represents a single report within an `ECReports` instance that is generated by an event cycle.

EPCglobal ALE
reportName: String
groups: List // List of ECReportGroup instances
WebLogic RFID Edge Server Extensions
applicationData: String
---

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.

### ECReportGroup

Java implementation package: `com.connecterra.ale.api`

`ECReportGroup` represents one group within an `ECReport`.

EPCglobal ALE
groupName: String
groupList: ECReportGroupList
groupCount: ECReportGroupCount
---

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.

### ECReportGroupList

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.

EPCglobal ALE
`members : List /`/ List of EPCReportGroupListMember instances
---

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.

### ECReportGroupListMember

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.

EPCglobal ALE
`epc : URI`
`tag : URI`
`rawHex : URI`
`rawDecimal : URI`
---
WebLogic RFID Edge Server Extensions
`memoryItems` : List // See ECReportGroupListMemberMemory.

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.

### ECReportGroupCount

An `ECReportGroupCount` is included in an `ECReportGroup` when the `includeCount` field of the corresponding `ECReportOutputSpec` is true.

EPCglobal ALE
`count : int`
---

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.

### ECReportGroupListMemberMemory

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:

- Absolute addressing (by bank, offset, and length)
- Symbolic name

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.

## Other ALE API Types: BEA Extensions

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.

- ECSpecInfo (WebLogic RFID Edge Server Extension)
- ECSubscriptionInfo (WebLogic RFID Edge Server Extension)
- ECSubscriptionControls (WebLogic RFID Edge Server Extension)

### ECSpecInfo (WebLogic RFID Edge Server Extension)

Java implementation package: `com.connecterra.ale.api`

`ECSpecInfo` gives information about the current state of a defined `ECSpec`.

WebLogic RFID Edge Server Extensions
`subscriberCount : int`
`activationCount : int`
`lastActivated : timestamp`
`lastReported : timestamp`
`isSuspended : boolean`
---

Field | Description
--- | ---
`subscriberCount` | The number of current subscribers for this `ECSpec`.
`activationCount` | The number of times the `ECSpec` has transitioned into the active state since it was first defined.
`lastActivated` | When the `ECSpec` last transitioned into the active state.
`lastReported` | When the `ECSpec` last delivered a report to subscribers. This might be different than `lastActivated` because the settings in `ECReportSpecs` might cause the `ECSpec` not to deliver a report if no matching tags were read.
`isSuspended` | Indicates whether or not the `ECSpec` is in a suspended state.

XML Implementation Notes: `ECSpecInfo` values are expressed in the element `EventCycleSpecInfo`.

### ECSubscriptionInfo (WebLogic RFID Edge Server Extension)

Java implementation package: `com.connecterra.ale.api`

`ECSubscriptionInfo` gives information about a specific subscriber to an `ECSpec`.

`controls : ECSubscriptionControls`
`consecutiveFailureCount : int`
`lastSuccessTime : timestamp`
---

Field | Description
--- | ---
`controls` | The controls that govern when the subscription is automatically unsubscribed in case of delivery failures.
`consecutiveFailureCount` | The number of consecutive times that reports were unable to be delivered. This value is `0` if the most recent report was delivered successfully, `1` if the most recent report was not delivered but the preceding report was delivered, and so forth.
`lastSuccessTime` | The date and time a report was last successfully delivered.

XML Implementation Notes: `ECSubscriptionInfo` values are expressed in the element `EventCycleSubscriptionInfo`.

### ECSubscriptionControls (WebLogic RFID Edge Server Extension)

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.

`failureLimitCount : int`
`failureLimitInterval : long`
---

Field | Description
--- | ---
`failureLimitCount` | The maximum number of failed notification deliveries before a subscription is unsubscribed.
`failureLimitInterval` | The maximum interval of time (in milliseconds) during which notification delivery can fail before a subscription is unsubscribed.

XML Implementation Notes: `ECSubscriptionControl` values are expressed in the element `EventCycleSubscriptionControls`.

## XML Representations

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`

Defines the BEA schema extensions.

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:

- ECSpec - Example
- ECReports - Example

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.

### ECSpec - Example

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>

### ECReports - Example

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>

## Using the ALE Tag Reading API from Java

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.

### Using XML Serializers and Deserializers from Java

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`.

## Gen2 Read Support

In support of the UHF Generation 2 Air Interface Protocol, BEA provides the following properties:

- includedMemory
- getMemoryItem

### includedMemory

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:

- `com.connecterra.ale.api.ECReportSpec.getIncludedMemoryFields() :List`
- `com.connecterra.ale.api.ECReportSpec.set(includedMemoryFields :List) : void`
- `com.connecterra.ale.api.ECReportSpec.addIncludedMemoryField(includedMemoryField :URI) : void`

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.

### getMemoryItem

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.