Difference between revisions of "Application Level Events (ALE) User's Guide"
From RifidiWiki
(→Define a Composite reader) |
(→Define a Composite reader) |
||
Line 157: | Line 157: | ||
==Define a Composite reader== | ==Define a Composite reader== | ||
− | The readers that are going to be part of a composite reader must be first created as a base readers | + | The readers that are going to be part of a composite reader must be first created as a base readers, so the previous steps to create a base reader, have to be called prior to define composite readers |
===In ALE client=== | ===In ALE client=== |
Revision as of 21:46, 25 February 2016
Note: Leverage similar approach to REST - below is just my thoughts - open to other ways to approach
Contents
- 1 Introduction
- 2 Configuration
- 3 How to Test ALE Operations
- 4 ALE Operations Basic Flow
- 5 ALELR Operations Basic Flow
- 6 ALE Implementation
- 6.1 Ale Operations
- 6.1.1 define(String specName, String specFilePath)
- 6.1.2 undefine(String specName)
- 6.1.3 getECSpec(String specName)
- 6.1.4 getECSpecNames()
- 6.1.5 subscribe(String specName, String notificationURI)
- 6.1.6 unsubscribe(String specName, String notificationURI)
- 6.1.7 poll(String specName)
- 6.1.8 immediate(String specFilePath)
- 6.1.9 getSubscribers(String specName)
- 6.1.10 getStandardVersion()
- 6.1.11 getVendorVersion()
- 6.2 Error conditions
- 6.1 Ale Operations
- 7 ALELR Operations
- 7.1 define(String readerName, LRSpec spec)
- 7.2 undefine(String readerName)
- 7.3 update(String readerName, LRSpec spec)
- 7.4 getLogicalReaderNames()
- 7.5 getLRSpec(String readerName)
- 7.6 addReaders(String readerName, String[] readers)
- 7.7 setReaders(String readerName, String[] readers)
- 7.8 removeReaders(String readerName, String[] readers)
- 7.9 setProperties(String readerName, LRProperty[] properties)
- 7.10 getPropertyValue(String readerName, String propertyName)
- 7.11 getStandardVersion()
- 7.12 getVendorVersion()
- 8 Example Rifidi App/Client
Introduction
This section describes implementations of the EPCglobal ALE interface v1.0. The Application Level Events (ALE) specification describes an interface through which client applications may obtain filtered, consolidated EPC data from a variety of sources.
The ALE layer exists in a context including RFID readers, Users (administrative) and Client applications as shown below. Initially the administrators are responsible for installing and configuring the RFID environment. Once the environment is configured, EPC data (tag reads) are sent from the Readers to the ALE layer.
The processing done at this layer typically involves: (1) receiving EPCs from one or more data sources such as readers; (2) accumulating data over intervals of time, filtering to eliminate duplicate EPCs and EPCs that are not of interest, and counting and grouping EPCs to reduce the volume of data; and (3) reporting in various forms. The interface described herein, and the functionality it implies, is called “Application Level Events,” or ALE.
Configuration
#Port must be set -Dorg.rifidi.ale.port=8112 #ALE and ALELR web services start by default but this can be changed -Dorg.rifidi.ale.enabled=true
How to Test ALE Operations
Set up testing
Execute
1. Start Rifidi server
Start the Rifidi server
2. Start Rifidi emulator
Start the Rifidi emulator, create an LLRP reader type, start it, and then create some Gen2 tags, and drag and drop some of them to emulated reader's antenna
3. Validate ALE and ALELR Web services are running
To validate ALE Web service, go to http://localhost:8112/aleservice?wsdl and you should see the web service definition
To validate ALELR Web service, go to http://localhost:8112/alelrservice?wsdl and you should see the web service definition
If you do not get web service response, make sure you have set required JVM arguments, as described in configuration steps
4. Open web client application
You can follow this guide in order to install the ALE web client ALE Web Client Setup
After successful deployment of ALE web client, point your web browser to http://localhost:8081/fc-webclient-1.2.0/services/ALEWebClient.jsp and you should see the web application to test ale and alelr web services:
5. Call setEndPoint(String endPointName) for ALE
Call setEndPoint(String endPointName) for ALE: Clic on setEndPoint(String endPointName) link in left ALE panel, then type the url http://localhost:8112/aleservice as the endpoint attribute, then clic Invoke
After this, verify the end point was appropriate set, by calling getEndPoint(), and you should see the endpoint address you set before:
6. Call setEndPoint(String endPointName) for ALELR
Call setEndPoint(String endPointName) for ALELR: Click on setEndPoint(String endPointName) linl in left ALELR panel, then type the url http://localhost:8112/alelrservice as the endpoint attribute, then clic Invoke
After this, verify the end point was appropriate set, by calling getEndPoint(), and you should see the endpoint address you set before:
Validate
ALE Operations Basic Flow
A few sample scenarios are illustrated below to demonstrate the use of the ALE interface messages. Below is a representative list of the kinds of scenarios ALE supports.
- Defining Subscribe ECName, ECSpec
- Direct Subscription. Defined by A, Report to: A
- Indirect Subscription Defined by A, Report to: B
- Poll(ECName)
- Immediate(ECSpec)
Scenario 1a: Direct Subscription
The scenario shown below involves a client application specifying the EPC data it is interested in collecting. After specifying the ECSpec, it then subscribes to receive the resulting ECReports. The ECSpec shown in this scenario specifies that event cycles should repeat periodically. The ECReportSpec requests reports for additions and deletions, and reportIfEmpty is set to false.
- The client calls the define method of the ALE interface. The ECSpec specifies that the event cycle is to begin using repeatPeriod as the boundary specification and to end using duration as the boundary specification (but any valid boundary conditions could be specified). The ECReportSpec and ECFilterSpec contained within the ECSpec are defined to include the EPC data sent later in step 3.
- The client calls the subscribe method of the ALE interface, including a URI that identifies the client itself as the destination for the ECReports. At this point the ECSpec is considered “Requested.” Since the start condition is given by repeatPeriod, the ECSpec immediately transitions to the “Active” state.
- During period1 no new tags (additions) were reported by the Reader, and no deletions were noted, thus no ECReports is generated.
- In period2, an EPC that does meet the filter conditions specified in the ECSpec is reported to the ALE layer by one of the Readers indicated in the ECSpec.
- At the end of period2, the requested ECReports is generated and sent to the client.
- In period3, no EPCs are reported, and no ECReports are generated
- In period4 the client calls the unsubscribe method of the ALE interface. As this client is the only subscriber, the ECSpec transitions to the “Unrequested” state, and no further ECReports are generated.
- Because the ECSpec is Unrequested, the client can undefine the ECSpec without any error
Scenario 1b: Indirect Subscription
The scenario shown below involves a client application specifying the EPC data that is of interest to another observer. After specifying the ECSpec, the client subscribes a third party observer to receive the resulting ECReports. The ECSpec shown in this scenario specifies the event cycle to start and stop using a trigger mechanism.
- The ALE client calls the define methods of the ALE interface. The ECSpec contains a valid startTrigger and stopTrigger as boundary specifications – though any valid boundary conditions could be specified. The ECReportSpec and ECFilterSpec contained within the ECSpec is defined to include the EPC data sent later in step 4.
- The ALE client calls the subscribe method of the ALE interface which includes the URI of the intended observer. At this point the ECSpec is considered “Requested.”
- After the start trigger is received, the ECSpec is considered “Active.” Subsequent EPCs that meet the filter conditions in the ECSpec will be collected by the ALE layer.
- An EPC that does meet the filter conditions in the ECSpec is reported to the ALE layer.
- The stop trigger is received. The ECSpec transitions to the “Requested” state.
- The ECReports is generated and sent asynchronously to the observer.
Scenario 2, 3: Poll, Immediate
The scenario shown illustrates an ALE client using the poll method of the ALE interface to synchronously obtain the EPC data it is interested in collecting. The ECSpec shown in this scenario specifies the event cycle boundary to be a duration of time. Later in the scenario the ALE client uses the immediate method of the ALE interface, again synchronously obtaining EPC data. The combination of poll and immediate is not required, and only serves to illustrate a possibility.
- The ALE client calls the define method of the ALE interface. The ECSpec contains a valid duration as the boundary specification – though any valid boundary conditions could be specified. The ECReportSpec and ECFilterSpec contained within the ECSpec are defined to include the EPC data sent later in steps 3 and 4. At this point the ECSpec is considered “Unrequested.”
- The ALE client calls the poll method of the ALE interface, naming the ECSpec previously defined in Step 1. At this point the ECSpec is transitioned to the “Active” state, and the event cycle begins for the duration specified in the ECSpec. During the duration of the event cycle the ALE client is blocked waiting for a response to the poll method.
- An EPC which meets the filter conditions of the ECSpec is received during the event cycle. At the end of the event cycle, the ECReports is generated and returned to the ALE client as the response to the poll method. At this point the ECSpec transitions to the “Unrequested” state.
- An EPC that meets the filter conditions of the ECSpec is reported to the ALE layer, but since there is no “Active” ECSpec, this EPC will not be reported.
- The ALE client invokes the poll method of the ALE interface a second time. This is similar to the process described above in Steps 2 and 3, but since no EPC is received, no EPC data is returned in the ECReports.
- Later, the ALE client calls the immediate method of the ALE interface. This is very similar to the use of poll, except that when the client calls immediate it provides the ECSpec as part of the method call, as opposed to referring to a previously defined ECSpec. Since a new ECSpec is provided with the immediate method, it can contain any valid combination of parameters and report options.
ALELR Operations Basic Flow
A few sample scenarios are illustrated below to demonstrate the use of the ALELR interface messages. Below is a representative list of the kinds of scenarios ALELR supports.
- Defining Logical Reader
- Define a Base reader
- Define a Composite reader
Define a Base reader
Prior to these steps you need to set up the readers and readzones in Rifidi server. If you need all the antennas for a Reader to be included in collecting data, then create a Reader in Rifidi dashboard If you need just some specific antennas for a Reader to be included in collecting data, then create a Readzone in Rifidi dashboard
In Rifidi dashboard
- Create a Reader
- Create a session for reader and start the session
- Create a command to collect tag data, for example a LLRP-Configure command type
- Submit the command on session
- Create readzone defining associated reader and antennas
Then if optionally you need to create read zones:
In ALE client
- Call define method giving as readerName the same name that was assigned to a Reader (or a readzone) in Rifidi server.
Define a Composite reader
The readers that are going to be part of a composite reader must be first created as a base readers, so the previous steps to create a base reader, have to be called prior to define composite readers
In ALE client
- Call define method. The readerName in this case may be any value.
ALE Implementation
The ALE clients are applications or services that process EPC tag information. Several methods are defined within the ALE interface which allow clients to specify the data they wish to receive and the conditions for the production of the reports containing the data. These methods are:
Note: for each operation example request/response/wsdl
Ale Operations
define(String specName, String specFilePath)
Creates a new ECSpec having the name specName
, according to spec
undefine(String specName)
Removes the ECSpec named specName
that was previously created by the define
method
getECSpec(String specName)
Returns the ECSpec
that was provided when the ECSpec named specName
was created by the define
method.
getECSpecNames()
Returns an unordered list of the names of all ECSpecs that are visible to the caller.
subscribe(String specName, String notificationURI)
Adds a subscriber having the specified notificationURI
to the set of current subscribers of the ECSpec named specName
. The notificationURI
parameter both identifies a specific binding of the ALECallback
interface and specifies addressing information meaningful to that binding.
unsubscribe(String specName, String notificationURI)
Removes a subscriber having the specified notificationURI
from the set of current subscribers of the ECSpec named specName
.
poll(String specName)
Requests an activation of the ECSpec named specName
, returning the results from the next event cycle to complete.
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 notificationURI).
After calling poll service, the expected response is an xml like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:ECReports specName="ReportGenerator_0_0" date="2016-01-17T21:36:40.966-05:00" ALEID="RIFIDI-ALE604974863" totalMilliseconds="9500" terminationCondition="DURATION" xmlns:ns2="urn:epcglobal:ale:wsdl:1" xmlns:ns3="urn:epcglobal:ale:xsd:1"> <reports> <report reportName="Cycle_1"> <group> <groupList> <member><epc>300e34d6e51161826493ff7e</epc></member> </groupList> </group> </report> </reports> </ns3:ECReports>
immediate(String specFilePath)
Creates an unnamed ECSpec according to spec, and immediately requests its activation. This is equivalent to defining an ECSpec, performing a single poll operation, and then undefining it.
After calling immediate service, the expected response is an xml like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:ECReports specName="ReportGenerator_0_0" date="2016-01-18T16:32:36.500-05:00" ALEID="RIFIDI-ALE-293181330" totalMilliseconds="9500" terminationCondition="DURATION" xmlns:ns2="urn:epcglobal:ale:xsd:1" xmlns:ns3="urn:epcglobal:ale:wsdl:1"> <reports> <report reportName="Cycle_1"> <group> <groupList> <member><epc>300e34d6e51161826493ff7e</epc></member> </groupList> </group> </report> </reports> </ns2:ECReports>
getSubscribers(String specName)
Returns an unordered, possibly empty list of the notification URIs corresponding to each of the current subscribers for the ECSpec named specName
.
getStandardVersion()
Returns a string that identifies what version of the specification this implementation of the Reading API complies with.
getVendorVersion()
Returns a string that identifies what vendor extensions this implementation of the Reading API provides.
Error conditions
Methods of the ALE Reading API signal error conditions to the client by means of exceptions. The following exceptions are defined. All the exception types in the following table are extensions of a common ALEException
base type, which contains one string element giving the reason for the exception.
SecurityException
The operation was not permitted due to an access control violation or other security concern.
DuplicateNameException
The specified ECSpec name already exists. Note that the existence of a CCSpec having the same name does not cause this exception; ECSpecs and CCSpecs are in different namespaces.
ECSpecValidationException
The specified ECSpec is invalid. The define and immediate methods of the ALE API SHALL raise an ECSpecValidationException if any of the following are true:
- The specified
specName
is an empty string or is not accepted by the implementation - The
logicalReaders
parameter ofECSpec
is null, omitted, is an empty list, or contains any logical reader names that are not known to the implementation. - The
boundarySpec
parameter ofECSpec
is null or omitted. - The
duration
,stableSetInterval
, orrepeatPeriod
parameter ofECBoundarySpec
is negative. - The value of the
startTrigger
orstopTrigger
parameter ofECBoundarySpec
, or any element of thestartTriggerList
orstopTriggerList
parameter ofECBoundarySpec
does not conform to URI syntax as defined by [RFC2396], or is a URI that is not supported by the ALE implementation. Note that an empty string does not conform to URI syntax as defined by [RFC2396]. - No stopping condition is specified in
ECBoundarySpec
; i.e.,stopTrigger
is omitted or null,stopTriggerList
is empty,whenDataAvailable
is false, and neitherduration
norstableSetInterval
nor any vendor extension stopping condition is specified. - The
reportSpecs
parameter ofECSpec
is null, omitted, or empty. - Any
ECReportSpec
instance has areportName
that is an empty string or that is not accepted by the implementation. - Two
ECReportSpec
instances have identical values for theirreportName
fields. - Any member of
includePatterns
orexcludePatterns
withinECFilterSpec
does not conform to theepc-tag
format’s filter syntax - Two members of the
fieldList
parameter of anyECReportOutputSpec
instance have the same name. - The
fieldspec
parameter of anyECFilterListMember
instance is invalid. - The
patList
parameter of anyECFilterListMember
instance is empty, null, or omitted, or any element ofpatList
does not conform to the syntax rules for patterns implied by the specifiedfieldspec
. - The
fieldspec
parameter ofECGroupSpec
is invalid. - The
fieldspec
parameter ofECGroupSpec
implies a datatype and format for which no grouping pattern syntax is defined. - Any grouping pattern within the
patternList
parameter ofECGroupSpec
does not conform to the syntax for grouping patterns implied by the specifiedfieldspec
. - Any two grouping patterns within the
patternList
parameter ofECGroupSpec
are not disjoint, according to the definition of disjointedness defined by the datatype and format implied by the specifiedfieldspec
. - Any member of the
fieldList
parameter withinECReportOutputSpec
is an invalid fieldspec. - Any member of the
primaryKeyFields
parameter ofECSpec
is not a known fieldname. - The implementation does not support the specified
primaryKeyFields
value ofECSpec
with the specified logical readers. An implementation SHALL NOT, however, raise the exception ifprimaryKeyFields
is omitted or its value is a list consisting of the single elementepc
. - For any
ECReportOutputSpec
instance, all five booleansincludeEPC
,includeTag
,includeRawHex
,includeRawDecimal
, andincludeCount
are false,fieldList
is empty or omitted, and there is no vendor extension toECReportOutputSpec
. - Any value of
ECStatProfileName
is not recognized, or is recognized but the 2693 specified statistics report is not supported.
InvalidURIException
The URI specified for a subscriber does not conform to URI syntax as specified in [RFC2396], does not name a binding of the ALECallback
interface recognized by the implementation, or violates syntax or other rules imposed by a particular binding.
NoSuchNameException
The specified ECSpec name does not exist.
NoSuchSubscriberException
The specified subscriber does not exist.
DuplicateSubscriptionException
The specified ECSpec name and subscriber URI is identical to a previous subscription that was created and not yet unsubscribed.
ImplementationException
A generic exception raised by the implementation for reasons that are implementation-specific. This exception contains one additional element: a severity member whose values are either ERROR or SEVERE. ERROR indicates that the ALE implementation is left in the same state it had before the operation was attempted. SEVERE indicates that the ALE implementation is left in an indeterminate state.
ALELR Operations
define(String readerName, LRSpec spec)
Creates a new logical reader named name
according to spec
.
undefine(String readerName)
Removes the logical reader named name
update(String readerName, LRSpec spec)
Changes the definition of the logical reader named name
to match the specification in the spec
parameter. This is different than calling undefine
followed by define, because update
may be called even if there are defined ECSpecs, CCSpecs, or other logical readers that refer to this logical reader.
getLogicalReaderNames()
Returns an unordered list of the names of all logical readers that are visible to the caller. This list SHALL include both composite readers and base readers.
getLRSpec(String readerName)
Returns an LRSpec
that describes the logical reader named name
.
addReaders(String readerName, String[] readers)
Adds the specified logical readers to the list of component readers for the composite logical reader named name
. This is equivalent to calling getLRSpec
, modifying the LRSpec
that is returned to include the specified logical readers in the reader list, and then calling update
with the modified LRSpec
.
setReaders(String readerName, String[] readers)
Changes the list of component readers for the composite logical reader named name
to the specified list. This is equivalent to calling getLRSpec
, modifying the LRSpec
that is returned by replacing the reader list with the specified list of logical readers, and then calling update
with the modified LRSpec
.
removeReaders(String readerName, String[] readers)
Removes the specified logical readers from the list of component readers for the composite logical reader named name
. Any reader name within readers
that is not currently among the component readers of the specified logical reader is ignored. This is equivalent to calling getLRSpec
, modifying the LRSpec
that is returned by removing any references to logical readers in the specified reader list, and then calling update
with the modified LRSpec
.
setProperties(String readerName, LRProperty[] properties)
Changes properties for the logical reader named name
to the specified list. This is equivalent to calling getLRSpec
, modifying the properties in the LRSpec
according to the table below, and then calling update
with the modified LRSpec
.
getPropertyValue(String readerName, String propertyName)
Returns the current value of the specified property for the specified reader, or null if the specified reader does not have a property with the specified name.
getStandardVersion()
Returns a string that identifies what version of the specification this implementation of the ALE Logical Reader API complies with.
getVendorVersion()
Returns a string that identifies what vendor extensions of the ALE Logical Reader API this implementation provides.