com.connecterra.ale.api
Interface ALE

All Known Implementing Classes:

AxisALEClient, EngineALEImpl, SOAPALEClient

public interface ALE

The Application Level Events (ALE) application programming interface.

Applications obtain concrete implementations of this interface by using constructors provided in other packages.

Updated to support EPCglobal ALE 1.0 specification.

The most commonly used concrete implementations are remote procedure call (RPC) bindings provided in the com.connecterra.ale.client package. It is also possible to link directly with the ALE engine itself, provided by com.connecterra.ale.alevent.ALEEngine.

See Also:

The RFTagAware Programmer Guide

Method Summary

void	define(java.lang.String ecSpecName, ECSpec spec) Define a new event cycle specification for use with the poll(java.lang.String) and subscribe(java.lang.String, java.net.URI, com.connecterra.ale.api.ECSubscriptionControls) methods.
ECSpec	get(java.lang.String ecSpecName) Deprecated. Use getECSpec(java.lang.String)
ALEFactory	getALEFactory() Returns a factory suitable for creating ALE objects to be used with this connection.
java.lang.String	getALEID() Gets the ID of this ALE server.
ECSpec	getECSpec(java.lang.String specName) Look up and return a previously defined event cycle specification by name.
ECSpecInfo	getECSpecInfo(java.lang.String ecSpecName) Returns administrative information about an event cycle specification.
java.util.List	getECSpecNames() Returns a list of the names of all event cycle specifications currently defined.
ECSubscriptionInfo	getECSubscriptionInfo(java.lang.String ecSpecName, java.net.URI subscriber) Returns administrative information about an event cycle subscriber.
java.lang.String	getStandardVersion() Returns a string that identifies what version of the EPCglobal ALE standard that this implementation complies with.
java.util.List	getSubscribers(java.lang.String specName) Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.
java.lang.String	getVendorVersion() Returns a string that identifies the vendor and version of the implementation.
ECReports	immediate(ECSpec spec) Immediately define an event cycle specification and activate it for one event cycle, synchronously returning a report.
java.util.List	listECSpecNames() Deprecated. Use getECSpecNames()
java.util.List	listLogicalReaderNames() Returns a list of all logical reader names.
java.util.List	listSubscribers(java.lang.String ecSpecName) Deprecated. Use getSubscribers(java.lang.String)
ECReports	poll(java.lang.String ecSpecName) Activates a previously defined event cycle specification for one event cycle, synchronously returning a report.
void	redefine(java.lang.String ecSpecName, ECSpec newSpec) Replace the ECSpec having the specified name with a new ECSpec.
void	subscribe(java.lang.String ecSpecName, java.net.URI uri) Subscribe to asynchronous report delivery from an event cycle specification.
void	subscribe(java.lang.String ecSpecName, java.net.URI uri, ECSubscriptionControls controls) Subscribe to asynchronous report delivery from an event cycle specification.
void	suspend(java.lang.String ecSpecName) Suspend the named event cycle specification.
void	undefine(java.lang.String ecSpecName) Undefine an event cycle specification.
void	unsubscribe(java.lang.String ecSpecName, java.net.URI uri) Unsubscribe a specified destination from receiving asynchronous delivery of reports from a specified event cycle specification.
void	unsuspend(java.lang.String ecSpecName) Return a suspended event cycle specification to its normal state.

Method Detail

getALEID

public java.lang.String getALEID()
                          throws EngineException,
                                 java.rmi.RemoteException

Gets the ID of this ALE server.

This method is an extension to the ALE 1.0 specification.

Returns:

The ID of the server.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

define

public void define(java.lang.String ecSpecName,
                   ECSpec spec)
            throws DuplicateNameException,
                   ECSpecValidationException,
                   java.rmi.RemoteException,
                   EngineException

Define a new event cycle specification for use with the poll(java.lang.String) and subscribe(java.lang.String, java.net.URI, com.connecterra.ale.api.ECSubscriptionControls) methods.

Parameters:

ecSpecName - The name of the specification.

spec - The specification to define.

Throws:

DuplicateNameException - if an ECSpec having the same name is already defined.

ECSpecValidationException - if the ECSpec is invalid.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpec

redefine

public void redefine(java.lang.String ecSpecName,
                     ECSpec newSpec)
              throws NoSuchNameException,
                     ECSpecValidationException,
                     java.rmi.RemoteException,
                     EngineException

Replace the ECSpec having the specified name with a new ECSpec. All subscriptions and other metadata remain unchanged. If the event cycle is active, it is terminated, and will not begin until the boundary spec start condition occurs again. This call is not atomic: there will be a short duration between the tear-down of the old event cycle and the setup of the new one. If, for instance, a trigger happens during this time, no activation will occur. However, it is guaranteed that when the call completes, either the old or new ECSpec will be in place.

Parameters:

ecSpecName - The name of the specification.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

ECSpecValidationException - if the ECSpec is invalid.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpec

suspend

public void suspend(java.lang.String ecSpecName)
             throws NoSuchNameException,
                    java.rmi.RemoteException,
                    EngineException

Suspend the named event cycle specification. The event cycle specification will enter the unrequested state. If the event cycle specification is active, it is terminated. Any calls to poll will return abruptly with an EngineException. If poll(java.lang.String) is called on a suspended event cycle, it will throw an EngineException. If the event cycle is already suspended, this call does nothing.

This method is an extension to the ALE 1.0 specification.

Parameters:

ecSpecName - The name of the specification to suspend.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpecInfo.isSuspended()

unsuspend

public void unsuspend(java.lang.String ecSpecName)
               throws NoSuchNameException,
                      java.rmi.RemoteException,
                      EngineException

Return a suspended event cycle specification to its normal state. The event cycle specification will enter the requested state if it has subscriptions, and will be activated when the boundary conditions next occur.

This method is an extension to the ALE 1.0 specification.

Parameters:

ecSpecName - The name of the specification to unsuspend.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

suspend(String)

undefine

public void undefine(java.lang.String ecSpecName)
              throws NoSuchNameException,
                     java.rmi.RemoteException,
                     EngineException

Undefine an event cycle specification. All existing subscriptions will be removed.

Parameters:

ecSpecName - The name of the specification to undefine.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

define(String, ECSpec)

get

public ECSpec get(java.lang.String ecSpecName)
           throws java.rmi.RemoteException,
                  EngineException

Deprecated. Use getECSpec(java.lang.String)

Look up and return a previously defined event cycle specification by name.

Parameters:

ecSpecName - The name of the specification to look up.

Returns:

The ECSpec for the specified name, or null if there is no event cycle specification defined with that name.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

getECSpec

public ECSpec getECSpec(java.lang.String specName)
                 throws java.rmi.RemoteException,
                        EngineException,
                        NoSuchNameException

Look up and return a previously defined event cycle specification by name.

Returns:

The ECSpec for the specified name, or null if there is no event cycle specification defined with that name.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server

EngineException - if there is an internal failure within the ALE implementation

NoSuchNameException - if an ECSpec with the specified name does not exist

See Also:

ECSpec

listECSpecNames

public java.util.List listECSpecNames()
                               throws java.rmi.RemoteException,
                                      EngineException

Deprecated. Use getECSpecNames()

Returns a list of the names of all event cycle specifications currently defined.

Returns:

A list of strings naming the currently defined event cycle specifications.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

getECSpecNames

public java.util.List getECSpecNames()
                              throws java.rmi.RemoteException,
                                     EngineException

Returns a list of the names of all event cycle specifications currently defined.

Returns:

A list of strings naming the currently defined event cycle specifications.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

subscribe

public void subscribe(java.lang.String ecSpecName,
                      java.net.URI uri,
                      ECSubscriptionControls controls)
               throws NoSuchNameException,
                      InvalidURIException,
                      DuplicateSubscriptionException,
                      java.rmi.RemoteException,
                      EngineException

Subscribe to asynchronous report delivery from an event cycle specification. If there were no previous subscribers or active poll(java.lang.String) invocations, then the event cycle specification is activated, causing tag reads to commence. The subscription lasts until explicitly removed by calling the unsubscribe(java.lang.String, java.net.URI) method, or when the failure thresholds specified by controls are exceeded.

If during report generation, the notification delivery for this subscription fails controls.getFailureLimitCount() times in a row with no successes, then the subscription is removed. If zero, the subscription will not be unsubscribed due to an exceeded count, but may be unsubscribed due to the interval.

If during report generation, given a previous notification failure at time T, a notification fails more than controls.getFailureLimitInterval() milliseconds after time T without an intervening success, the subscription will be removed. If this is zero, the subscription will not be unsubscribed due to an exceeded interval, but may be unsubscribed due to the count.

This method is an extension to the ALE 1.0 specification.

Parameters:

ecSpecName - The name of the specification to subscribe to.

uri - The destination for asynchronously delivered reports. See the RFTagAware Programmer Guide for documentation of available notification URIs.

controls - Specifies the parameters which describe the behavior if notification delivery fails. If null, default controls are used (no limit to the failure count or failure interval).

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

InvalidURIException - if the specified URI cannot be interpreted, or has no driver available.

DuplicateSubscriptionException - if the subscription already exists.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

subscribe(String, URI), unsubscribe(String, URI)

subscribe

public void subscribe(java.lang.String ecSpecName,
                      java.net.URI uri)
               throws NoSuchNameException,
                      InvalidURIException,
                      DuplicateSubscriptionException,
                      java.rmi.RemoteException,
                      EngineException

Subscribe to asynchronous report delivery from an event cycle specification. Behaves like subscribe(String, URI, ECSubscriptionControls), with both the invalidate count and invalidate interval set to zero.

Parameters:

ecSpecName -

uri -

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

DuplicateSubscriptionException - if the subscription already exists.

InvalidURIException - if the specified URI cannot be interpreted, or has no driver available.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

subscribe(String, URI, ECSubscriptionControls), unsubscribe(String, URI)

unsubscribe

public void unsubscribe(java.lang.String ecSpecName,
                        java.net.URI uri)
                 throws NoSuchNameException,
                        NoSuchSubscriberException,
                        InvalidURIException,
                        java.rmi.RemoteException,
                        EngineException

Unsubscribe a specified destination from receiving asynchronous delivery of reports from a specified event cycle specification. If this is the last remaining subscriber, and there are no active poll(java.lang.String) invocations, then the event cycle specification is deactivated, ceasing tag reading operations for all readers not otherwise engaged in servicing other event cycles.

Parameters:

ecSpecName - The name of the specification to unsubscribe from.

uri - The destination that will no longer receive reports.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

NoSuchNameException - if there no ECSpec defined having the specified name.

InvalidURIException - if the specified URI cannot be interpreted, or has no driver available.

NoSuchSubscriberException - if there is no subscription to the specified URI.

EngineException - if there is an internal failure within the ALE implementation

See Also:

subscribe(String, URI), subscribe(String, URI, ECSubscriptionControls)

listSubscribers

public java.util.List listSubscribers(java.lang.String ecSpecName)
                               throws NoSuchNameException,
                                      java.rmi.RemoteException,
                                      EngineException

Deprecated. Use getSubscribers(java.lang.String)

Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.

Parameters:

ecSpecName - The name of the specification.

Returns:

A List of URI instances, each a subscriber of the specified event cycle specification.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpecInfo.getSubscriberCount()

getSubscribers

public java.util.List getSubscribers(java.lang.String specName)
                              throws NoSuchNameException,
                                     java.rmi.RemoteException,
                                     EngineException

Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.

Returns:

A List of URI instances, each a subscriber of the specified event cycle specification.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpecInfo.getSubscriberCount()

getECSpecInfo

public ECSpecInfo getECSpecInfo(java.lang.String ecSpecName)
                         throws NoSuchNameException,
                                java.rmi.RemoteException,
                                EngineException

Returns administrative information about an event cycle specification.

Parameters:

ecSpecName - The name of the event cycle specification

Returns:

A ECSpecInfo instance giving administrative information about the specified event cycle specification.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECSpecInfo

getECSubscriptionInfo

public ECSubscriptionInfo getECSubscriptionInfo(java.lang.String ecSpecName,
                                                java.net.URI subscriber)
                                         throws NoSuchNameException,
                                                NoSuchSubscriberException,
                                                InvalidURIException,
                                                java.rmi.RemoteException,
                                                EngineException

Returns administrative information about an event cycle subscriber.

This method is an extension to the ALE 1.0 specification.

Parameters:

ecSpecName - The name of the event cycle specification

Returns:

A ECSubscriptionInfo instance giving administrative information about the specified event cycle subscription.

Throws:

NoSuchNameException - if there no ECSpec defined having the specified name.

NoSuchSubscriberException - if the URI specified is not subscribed to the specified ECSpec

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

InvalidURIException

See Also:

ECSubscriptionInfo

poll

public ECReports poll(java.lang.String ecSpecName)
               throws java.lang.InterruptedException,
                      NoSuchNameException,
                      java.rmi.RemoteException,
                      EngineException

Activates a previously defined event cycle specification for one event cycle, synchronously returning a report. If there are no asynchronous subscribers or other active poll(java.lang.String) invocations, then a new activation of the event cycle is begun immediately or when the start trigger is received (if the event cycle specification specifies a start trigger). If instead there were previous subscribers or other active poll(java.lang.String) invocations, then this method may return reports from an event cycle already in progress.

This method is an extension to the ALE 1.0 specification.

Parameters:

ecSpecName - The name of the event cycle specification to activate.

Returns:

The reports generated from the event cycle.

Throws:

java.lang.InterruptedException - if this method was interrupted by another thread.

NoSuchNameException - if there no ECSpec defined having the specified name.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if the event cycle is suspended or redefined, or if there is an internal failure within the ALE implementation

See Also:

ECReports

immediate

public ECReports immediate(ECSpec spec)
                    throws java.lang.InterruptedException,
                           ECSpecValidationException,
                           java.rmi.RemoteException,
                           EngineException

Immediately define an event cycle specification and activate it for one event cycle, synchronously returning a report. This is similar to first defining a specification using define(java.lang.String, com.connecterra.ale.api.ECSpec), activating it for one event cycle using poll(java.lang.String), and undefining it using undefine(java.lang.String), except that event cycle specifications created using this method will not be visible to listECSpecNames() or getECSpecInfo(java.lang.String).

Parameters:

spec - The event cycle specification.

Returns:

The reports generated from one activation of the specification.

Throws:

java.lang.InterruptedException - if this method was interrupted by another thread.

ECSpecValidationException - if the ECSpec is invalid.

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

See Also:

ECReports

listLogicalReaderNames

public java.util.List listLogicalReaderNames()
                                      throws java.rmi.RemoteException,
                                             EngineException

Returns a list of all logical reader names. These are the logical readers that are available for use with event cycle specifications for tag reading.

Returns:

A List of strings representing logical reader names, in ascending lexicographic sequence.

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server.

EngineException - if there is an internal failure within the ALE implementation

getStandardVersion

public java.lang.String getStandardVersion()
                                    throws java.rmi.RemoteException,
                                           EngineException

Returns a string that identifies what version of the EPCglobal ALE standard that this implementation complies with.

Returns:

standard EPCGLobal version

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server

EngineException - if there is an internal failure within the ALE implementation

getVendorVersion

public java.lang.String getVendorVersion()
                                  throws java.rmi.RemoteException,
                                         EngineException

Returns a string that identifies the vendor and version of the implementation.

Returns:

vendor specific version

Throws:

java.rmi.RemoteException - if there is an error communicating with the ALE server

EngineException - if there is an internal failure within the ALE implementation

getALEFactory

public ALEFactory getALEFactory()

Returns a factory suitable for creating ALE objects to be used with this connection.