Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD