Application Level Events (ALE) User's Guide
From RifidiWiki
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.
- Define and Subscribe
- Define and Poll
- Immediate
Scenario 1: Define and Subscribe
The scenario specifies the ECSpec, it then subscribes to receive the resulting ECReports asynchronously.
- Call the define method of the ALE interface.
- Call the subscribe method of the ALE interface, including an URI that identifies the Mqtt server (and topic name if you want to override the default 'ale' topic) as the destination for the ECReports. For example to publish to default topic (ale) type: tcp://localhost:1883 and if you want to subscribe to a different topic (myTopic) type: tcp://localhost:1883/myTopic
- Open a Mqtt client, for example MQTT.fx (http://mqttfx.jfx4ee.org/) and connect to Rifidi Mqtt Server, then subscribe to the topic name defined in subscribe operation.
- You should see the incoming messages according to what you defined in ECSpec.
Scenario 2: Define and Poll
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.
- Call the define method of the ALE interface.
- Calls the poll method of the ALE interface, naming the ECSpec previously defined in Step 1. 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.
Scenario 3: Immediate
The scenario shown illustrates an ALE client using the immediate method of the ALE interface to synchronously obtain the EPC data it is interested in collecting.
- Call the define method of the ALE interface.
- Call the poll 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. During the duration of the event cycle the ALE client is blocked waiting for a response to the immediate 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 immediate method.
ALELR Operations Basic Flow
A few sample scenarios are illustrated below to demonstrate the use of the ALELR interface messages.
- Defining Logical Base Reader
- Defining Logical Composite Reader
Define a Logical 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:
Rifidi dashboard should look like this:
File:Defining ale readzone.jpg
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 Logical Composite Reader
The readers that are going to be part of a composite reader must be first created as base readers, so you have to execute the steps to create a base reader 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.