Revision as of 22:31, 10 February 2016

Note: Leverage similar approach to REST - below is just my thoughts - open to other ways to approach

Introduction

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 Media:ale_webclient_guide.docx 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

Here is an example of the basic flow for using ALE operations to get tag reads (current tags, addition and deletion) from a defined set of logical readzone(s) and the difference between using poll and immediate operations.

Scenario 1: Defining base reader

call ALELR define method with parameters:

• readerName: The name of logical reader to be used in Ale, not necessarily matching any reader id you have defined in Rifidi server.
• specFilePath: The specification file that defines the reader to be associated with this logical reader, in XML format, looks like:

Scenario 2: Defining composite reader

Scenario 1: Immediate flow

1. Start the Edge Server

Create Rifidi reader(s), if not already created.

2. Setendpoint ale

http://localhost:8112/aleservice

3. Setendpoint alelr

http://localhost:8112/alelrservice

4. Call the AleLR Define method

5. Call the Ale Define method

6. Call Immediate method

Scenario 2: Poll flow

Scenario 3: Async (MQTT) flow

Scenario 1: Current tags

1. Define the ECSpecCurrent

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:ECSpec xmlns:ns2="urn:epcglobal:ale:xsd:1">
    <logicalReaders>
        <logicalReader>LLRP_1</logicalReader>
    </logicalReaders>
    <boundarySpec>
        <repeatPeriod unit="MS">15000</repeatPeriod>
        <duration unit="MS">10000</duration>
        <stableSetInterval unit="MS">0</stableSetInterval>
    </boundarySpec>
    <reportSpecs>
        <reportSpec>
            <reportSet set="CURRENT"/>
            <output includeRawHex="true" includeRawDecimal="true" includeEPC="true"/>
        </reportSpec>
    </reportSpecs>
</ns2:ECSpec>

2. Define a subscriber, which subscribes to ECSpecCurrent
3. Put one Tag on the reader. Tag must appear in all Reports until Tag is removed from reader
4. Remove Tag from the reader. Tag must not appear in any Report from now on

Scenario 2: Added tags

1. Define the ECSpecAdditions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:ECSpec xmlns:ns2="urn:epcglobal:ale:xsd:1">
    <logicalReaders>
        <logicalReader>LLRP_1</logicalReader>
    </logicalReaders>
    <boundarySpec>
        <repeatPeriod unit="MS">15000</repeatPeriod>
        <duration unit="MS">10000</duration>
        <stableSetInterval unit="MS">0</stableSetInterval>
    </boundarySpec>
    <reportSpecs>
        <reportSpec>
            <reportSet set="ADDITIONS"/>
            <output includeRawHex="true" includeRawDecimal="true" includeEPC="true"/>
        </reportSpec>
    </reportSpecs>
</ns2:ECSpec>

2. Define a subscriber, which subscribes to ECSpecAdditions
3. Put one Tag on reader. Tag must only appear in the first following Report

Scenario 3: Deleted tags

1. Define the ECSpecDeletions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:ECSpec xmlns:ns2="urn:epcglobal:ale:xsd:1">
    <logicalReaders>
        <logicalReader>LLRP_1</logicalReader>
    </logicalReaders>
    <boundarySpec>
        <repeatPeriod unit="MS">15000</repeatPeriod>
        <duration unit="MS">10000</duration>
        <stableSetInterval unit="MS">0</stableSetInterval>
    </boundarySpec>
    <reportSpecs>
        <reportSpec>
            <reportSet set="DELETIONS"/>
            <output includeRawHex="true" includeRawDecimal="true" includeEPC="true"/>
        </reportSpec>
    </reportSpecs>
</ns2:ECSpec>

2. Define a subscriber, which subscribes to ECSpecDeletions
3. Put one Tag on reader. Tag must not appear in the Report
4. Remove Tag from reader. Tag must only appear in the first following Report

Scenario 4: Added and deleted tags

1. Define the ECSpecAdditionsAndDeletions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:ECSpec xmlns:ns2="urn:epcglobal:ale:xsd:1">
    <logicalReaders>
        <logicalReader>LLRP_1</logicalReader>
    </logicalReaders>
    <boundarySpec>
        <repeatPeriod unit="MS">15000</repeatPeriod>
        <duration unit="MS">10000</duration>
        <stableSetInterval unit="MS">0</stableSetInterval>
    </boundarySpec>
    <reportSpecs>
        <reportSpec reportName="Additions">
            <reportSet set="ADDITIONS"/>
            <output includeRawHex="true" includeRawDecimal="true" includeEPC="true"/>
        </reportSpec>
        <reportSpec reportName="Deletions">
            <reportSet set="DELETIONS"/>
            <output includeRawHex="true" includeRawDecimal="true" includeEPC="true"/>
        </reportSpec>
    </reportSpecs>
</ns2:ECSpec>

2. Define a subscriber, which subscribes to the mentioned ECSpec
3. Put one Tag on reader. Tag must only appear in the first following Report
4. Remove Tag from reader. Tag must only appear in the first following Report

ALE Implementation

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.

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.

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 of ECSpec is null, omitted, is an empty list, or contains any logical reader names that are not known to the implementation.
• The boundarySpec parameter of ECSpec is null or omitted.
• The duration, stableSetInterval, or repeatPeriod parameter of ECBoundarySpec is negative.
• The value of the startTrigger or stopTrigger parameter of ECBoundarySpec, or any element of the startTriggerList or stopTriggerList parameter of ECBoundarySpec 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 neither duration nor stableSetInterval nor any vendor extension stopping condition is specified.
• The reportSpecs parameter of ECSpec is null, omitted, or empty.
• Any ECReportSpec instance has a reportName that is an empty string or that is not accepted by the implementation.
• Two ECReportSpec instances have identical values for their reportName fields.
• Any member of includePatterns or excludePatterns within ECFilterSpec does not conform to the epc-tag format’s filter syntax
• Two members of the fieldList parameter of any ECReportOutputSpec instance have the same name.
• The fieldspec parameter of any ECFilterListMember instance is invalid.
• The patList parameter of any ECFilterListMember instance is empty, null, or omitted, or any element of patList does not conform to the syntax rules for patterns implied by the specified fieldspec.
• The fieldspec parameter of ECGroupSpec is invalid.
• The fieldspec parameter of ECGroupSpec implies a datatype and format for which no grouping pattern syntax is defined.
• Any grouping pattern within the patternList parameter of ECGroupSpec does not conform to the syntax for grouping patterns implied by the specified fieldspec.
• Any two grouping patterns within the patternList parameter of ECGroupSpec are not disjoint, according to the definition of disjointedness defined by the datatype and format implied by the specified fieldspec.
• Any member of the fieldList parameter within ECReportOutputSpec is an invalid fieldspec.
• Any member of the primaryKeyFields parameter of ECSpec is not a known fieldname.
• The implementation does not support the specified primaryKeyFields value of ECSpec with the specified logical readers. An implementation SHALL NOT, however, raise the exception if primaryKeyFields is omitted or its value is a list consisting of the single element epc.
• For any ECReportOutputSpec instance, all five booleans includeEPC, includeTag, includeRawHex, includeRawDecimal, and includeCount are false, fieldList is empty or omitted, and there is no vendor extension to ECReportOutputSpec.
• 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.

Example Rifidi App/Client