com.connecterra.ale.client
Class SOAPALEClient

java.lang.Object
  com.connecterra.ale.client.SOAPALEClient

All Implemented Interfaces:

ALE

public class SOAPALEClient

extends java.lang.Object

implements ALE

A concrete implementation of the ALE interface that accesses a remote RFTagAware Edge server using the SOAP protocol.

Constructor Summary

SOAPALEClient(java.net.URL aleServiceURL)
Constructs a new ALE client stub for accessing a remote edge server having a specified URL for its SOAP interface.

Method Summary

void	define(java.lang.String ecSpecName, ECSpec ecSpec) Define a new event cycle specification for use with the poll(java.lang.String) and subscribe(java.lang.String, java.net.URI) methods.
ECSpec	get(java.lang.String ecSpecName) Look up and return a previously defined event cycle specification by name.
ALEFactory	getALEFactory() Returns an ALEFactory instance for use with this client stub.
java.lang.String	getALEID() Gets the ID of this ALE server.
ECSpec	getECSpec(java.lang.String ecSpecName) 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 ecSpecName) Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.
long	getTimeout() Returns the network timeout duration (in milliseconds).
java.lang.String	getVendorVersion() Returns a string that identifies the vendor and version of the implementation.
ECReports	immediate(ECSpec ecSpec) Immediately define an event cycle specification and activate it for one event cycle, synchronously returning a report.
java.util.List	listECSpecNames() Returns a list of the names of all event cycle specifications currently defined.
java.util.List	listLogicalReaderNames() Returns a list of all logical reader names.
java.util.List	listSubscribers(java.lang.String ecSpecName) Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.
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 ecSpec) Replace the ECSpec having the specified name with a new ECSpec.
void	setTimeout(long timeout) Sets the network timeout duration (in milliseconds).
static ALEFactory	staticGetALEFactory() Returns an ALEFactory instance for use with this client stub.
void	subscribe(java.lang.String ecSpecName, java.net.URI notificationURI) Subscribe to asynchronous report delivery from an event cycle specification.
void	subscribe(java.lang.String ecSpecName, java.net.URI notificationURI, 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 notificationURI) 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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SOAPALEClient

public SOAPALEClient(java.net.URL aleServiceURL)
              throws java.rmi.RemoteException

Constructs a new ALE client stub for accessing a remote edge server having a specified URL for its SOAP interface.

Parameters:

aleServiceURL - The ALE Service URL (e.g., http://localhost:6060/axis/services/ALEService) for the remote edge server to be contacted.

Throws:

java.rmi.RemoteException - A remote error occurred while communicating with the ALE Service.

Method Detail

setTimeout

public void setTimeout(long timeout)

Sets the network timeout duration (in milliseconds). After this time elapses, the API calls will return a RemoteException.

getTimeout

public long getTimeout()

Returns the network timeout duration (in milliseconds).

staticGetALEFactory

public static ALEFactory staticGetALEFactory()

Returns an ALEFactory instance for use with this client stub.

getALEFactory

public ALEFactory getALEFactory()

Returns an ALEFactory instance for use with this client stub.

Specified by:

getALEFactory in interface ALE

getALEID

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

Description copied from interface: ALE

Gets the ID of this ALE server.

This method is an extension to the ALE 1.0 specification.

Specified by:

getALEID in interface ALE

Returns:

The ID of the server.

Throws:

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

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

define

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

Description copied from interface: ALE

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

Specified by:

define in interface ALE

Parameters:

ecSpecName - The name of the specification.

ecSpec - The specification to define.

Throws:

ECSpecValidationException - if the ECSpec is invalid.

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

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

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

See Also:

ECSpec

redefine

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

Description copied from interface: ALE

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.

Specified by:

redefine in interface ALE

Parameters:

ecSpecName - The name of the specification.

Throws:

ECSpecValidationException - if the ECSpec is invalid.

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

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

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

See Also:

ECSpec

suspend

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

Description copied from interface: ALE

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

Specified by:

suspend in interface ALE

Parameters:

ecSpecName - The name of the specification to suspend.

Throws:

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

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

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

See Also:

ECSpecInfo.isSuspended()

unsuspend

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

Description copied from interface: ALE

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.

Specified by:

unsuspend in interface ALE

Parameters:

ecSpecName - The name of the specification to unsuspend.

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 there no ECSpec defined having the specified name.

See Also:

ALE.suspend(String)

undefine

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

Description copied from interface: ALE

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

Specified by:

undefine in interface ALE

Parameters:

ecSpecName - The name of the specification to undefine.

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 there no ECSpec defined having the specified name.

See Also:

ALE.define(String, ECSpec)

get

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

Description copied from interface: ALE

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

Specified by:

get in interface ALE

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 ecSpecName)
                 throws NoSuchNameException,
                        java.rmi.RemoteException,
                        EngineException

Description copied from interface: ALE

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

Specified by:

getECSpec in interface ALE

Returns:

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

Throws:

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

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

listECSpecNames

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

Description copied from interface: ALE

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

Specified by:

listECSpecNames in interface ALE

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

Description copied from interface: ALE

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

Specified by:

getECSpecNames in interface ALE

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 notificationURI)
               throws NoSuchNameException,
                      InvalidURIException,
                      DuplicateSubscriptionException,
                      java.rmi.RemoteException,
                      EngineException

Description copied from interface: ALE

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

Specified by:

subscribe in interface ALE

Parameters:

ecSpecName -

notificationURI -

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.

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

DuplicateSubscriptionException - if the subscription already exists.

See Also:

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

subscribe

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

Description copied from interface: ALE

Subscribe to asynchronous report delivery from an event cycle specification. If there were no previous subscribers or active ALE.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 ALE.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.

Specified by:

subscribe in interface ALE

Parameters:

ecSpecName - The name of the specification to subscribe to.

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

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

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

DuplicateSubscriptionException - if the subscription already exists.

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

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

See Also:

ALE.subscribe(String, URI), ALE.unsubscribe(String, URI)

unsubscribe

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

Description copied from interface: ALE

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

Specified by:

unsubscribe in interface ALE

Parameters:

ecSpecName - The name of the specification to unsubscribe from.

notificationURI - The destination that will no longer receive reports.

Throws:

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

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

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

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

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

See Also:

ALE.subscribe(String, URI), ALE.subscribe(String, URI, ECSubscriptionControls)

listSubscribers

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

Description copied from interface: ALE

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

Specified by:

listSubscribers in interface ALE

Parameters:

ecSpecName - The name of the specification.

Returns:

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

Throws:

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

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

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

See Also:

ECSpecInfo.getSubscriberCount()

getSubscribers

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

Description copied from interface: ALE

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

Specified by:

getSubscribers in interface ALE

Returns:

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

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 there no ECSpec defined having the specified name.

See Also:

ECSpecInfo.getSubscriberCount()

getECSpecInfo

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

Description copied from interface: ALE

Returns administrative information about an event cycle specification.

Specified by:

getECSpecInfo in interface ALE

Parameters:

ecSpecName - The name of the event cycle specification

Returns:

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

Throws:

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

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

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,
                                                java.rmi.RemoteException,
                                                InvalidURIException,
                                                EngineException

Description copied from interface: ALE

Returns administrative information about an event cycle subscriber.

This method is an extension to the ALE 1.0 specification.

Specified by:

getECSubscriptionInfo in interface ALE

Parameters:

ecSpecName - The name of the event cycle specification

Returns:

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

Throws:

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

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

InvalidURIException

See Also:

ECSubscriptionInfo

poll

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

Description copied from interface: ALE

Activates a previously defined event cycle specification for one event cycle, synchronously returning a report. If there are no asynchronous subscribers or other active ALE.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 ALE.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.

Specified by:

poll in interface ALE

Parameters:

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

Returns:

The reports generated from the event cycle.

Throws:

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

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

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

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 ecSpec)
                    throws java.lang.InterruptedException,
                           ECSpecValidationException,
                           java.rmi.RemoteException,
                           EngineException

Description copied from interface: ALE

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 ALE.define(java.lang.String, com.connecterra.ale.api.ECSpec), activating it for one event cycle using ALE.poll(java.lang.String), and undefining it using ALE.undefine(java.lang.String), except that event cycle specifications created using this method will not be visible to ALE.listECSpecNames() or ALE.getECSpecInfo(java.lang.String).

Specified by:

immediate in interface ALE

Parameters:

ecSpec - The event cycle specification.

Returns:

The reports generated from one activation of the specification.

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

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

ECSpecValidationException - if the ECSpec is invalid.

See Also:

ECReports

listLogicalReaderNames

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

Description copied from interface: ALE

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.

Specified by:

listLogicalReaderNames in interface ALE

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

Description copied from interface: ALE

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

Specified by:

getStandardVersion in interface ALE

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

See Also:

ALE.getStandardVersion()

getVendorVersion

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

Description copied from interface: ALE

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

Specified by:

getVendorVersion in interface ALE

Returns:

vendor specific version

Throws:

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

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

See Also:

ALE.getVendorVersion()