com.connecterra.alepc.api
Interface ALEPC

All Known Implementing Classes:

AxisALEPCClient, EngineALEPCImpl

public interface ALEPC

The Application Level Events (ALE) tag programming API. The term "tag programming" refers to the act of causing an EPC value to become associated with some physical entity, such as an RFID tag or a printed label.

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

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 specName, PCSpec spec) Defines a new programming cycle specification for use with the poll(java.lang.String, java.util.Map) and subscribe(java.lang.String, java.net.URI, com.connecterra.alepc.api.PCSubscriptionControls) methods.
void	defineEPCCache(java.lang.String cacheName, EPCCacheSpec spec, EPCPatterns replenishment) Defines an EPC cache that can be used by programming cycles to obtain EPC values for programming operations.
EPCPatterns	depleteEPCCache(java.lang.String cacheName) Causes the indicated EPC cache to become depleted (empty).
PCSpec	get(java.lang.String specName) Look up and return a previously defined programming cycle specification by name.
java.lang.String	getALEID() Gets the ID of this ALE server.
EPCCacheSpec	getEPCCache(java.lang.String cacheName) Look up and return a previously defined EPC cache specification by name.
EPCCacheSpecInfo	getEPCCacheSpecInfo(java.lang.String cacheName, boolean includeCacheContent) Returns adminstrative information about an EPC cache.
PCSubscriptionInfo	getEPCCacheSubscriptionInfo(java.lang.String cacheName, java.net.URI subscriber) Returns administrative information about an EPC cache subscription.
PCSpecInfo	getPCSpecInfo(java.lang.String specName) Returns adminstrative information about a programming cycle specification.
PCSubscriptionInfo	getPCSubscriptionInfo(java.lang.String specName, java.net.URI subscriber) Returns administrative information about a programming cycle subscription.
PCWriteReport	immediate(PCSpec spec) Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report.
PCWriteReport	immediate(PCSpec spec, java.util.Map parameters) Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report.
PCWriteReport	immediate(PCSpec spec, java.net.URI epcVal) Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report.
java.util.List	listEPCCacheSpecNames() Returns a list of the names of all EPC caches currently defined.
java.util.List	listEPCCacheSubscribers(java.lang.String cacheName) Returns a list of URIs which are subscribed to asynchronous reports for the specified EPC cache name.
java.util.List	listLogicalReaderNames() Returns a list of all logical reader names.
java.util.List	listPCSpecNames() Returns a list of the names of all programming cycle specifications currently defined.
java.util.List	listSubscribers(java.lang.String specName) Returns a list of URIs which are subscribed to asynchronous reports for the specified PCSpec name.
PCWriteReport	poll(java.lang.String specName) Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report.
PCWriteReport	poll(java.lang.String specName, java.util.Map parameters) Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report.
PCWriteReport	poll(java.lang.String specName, java.net.URI epcVal) Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report.
void	redefine(java.lang.String specName, PCSpec newSpec) Replace the PCSpec for a programming cycle with a new PCSpec.
void	redefineEPCCache(java.lang.String cacheName, EPCCacheSpec newSpec) Replace the EPCCacheSpec having the specified name with a new EPCCacheSpec.
void	replenishEPCCache(java.lang.String cacheName, EPCPatterns replenishment) Appends a set of EPC pattern URIs to the indicated EPC cache.
void	subscribe(java.lang.String specName, java.net.URI uri, PCSubscriptionControls controls) Subscribe to asynchronous report delivery from a programming cycle specification.
void	subscribeEPCCache(java.lang.String cacheName, java.net.URI uri, PCSubscriptionControls controls) Subscribe to asynchronous report delivery from an EPC cache.
void	suspend(java.lang.String specName) Suspend the named programming cycle specification.
void	undefine(java.lang.String specName) Undefine a programming cycle specification.
EPCPatterns	undefineEPCCache(java.lang.String cacheName) Undefines an EPC cache.
void	unsubscribe(java.lang.String specName, java.net.URI uri) Unsubscribe a specified destination from receving asynchronous delivery of reports from a specified programming cycle specification.
void	unsubscribeEPCCache(java.lang.String cacheName, java.net.URI uri) Unsubscribe a specified destination from receving asynchronous delivery of reports from a specified EPC cache.
void	unsuspend(java.lang.String specName) Return a suspended programming 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.

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 specName,
                   PCSpec spec)
            throws DuplicateNameException,
                   PCSpecValidationException,
                   NoSuchCacheException,
                   java.rmi.RemoteException,
                   EngineException

Defines a new programming cycle specification for use with the poll(java.lang.String, java.util.Map) and subscribe(java.lang.String, java.net.URI, com.connecterra.alepc.api.PCSubscriptionControls) methods.

Parameters:

specName - The name of the specification.

spec - The specification to define.

Throws:

DuplicateNameException - if a PCSpec having the same name is already defined.

NoSuchCacheException - if the PCSpec references an EPC cache that is not defined.

PCSpecValidationException - if the PCSpec 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

redefine

public void redefine(java.lang.String specName,
                     PCSpec newSpec)
              throws NoSuchSpecException,
                     PCSpecValidationException,
                     NoSuchCacheException,
                     java.rmi.RemoteException,
                     EngineException

Replace the PCSpec for a programming cycle with a new PCSpec. All subscriptions and other metadata remain unchanged. If the programming cycle is active, it is terminated, and will not begin until the start condition occurs again.

This call is not atomic: there will be a short duration between the tear-down of the old programming 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 PCSpec will be in place.

Parameters:

specName - The name of the specification.

newSpec - The specification to replace the existing one.

Throws:

NoSuchSpecException - if there no PCSpec defined having the specified name.

NoSuchCacheException - if the PCSpec references an EPC cache that is not defined.

PCSpecValidationException - if the PCSpec 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

suspend

public void suspend(java.lang.String specName)
             throws NoSuchSpecException,
                    java.rmi.RemoteException,
                    EngineException

Suspend the named programming cycle specification. If the programming cycle specification is active, it is terminated. If poll(java.lang.String, java.util.Map) is called on a suspended programming cycle specification, it will throw an EngineException. If the programming cycle specification is already suspended, this call does nothing.

Parameters:

specName - The name of the specification to suspend.

Throws:

NoSuchSpecException - if there no PCSpec 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:

PCSpecInfo.isSuspended()

unsuspend

public void unsuspend(java.lang.String specName)
               throws NoSuchSpecException,
                      java.rmi.RemoteException,
                      EngineException

Return a suspended programming cycle specification to its normal state. The programming cycle specification will be activated when its start conditions next occur. If the programming cycle specification is not suspended, this call does nothing.

Parameters:

specName - The name of the specification to unsuspend.

Throws:

NoSuchSpecException - if there no PCSpec 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

undefine

public void undefine(java.lang.String specName)
              throws NoSuchSpecException,
                     java.rmi.RemoteException,
                     EngineException

Undefine a programming cycle specification. All existing subscriptions will be removed.

Parameters:

specName - The name of the specification to undefine.

Throws:

NoSuchSpecException - if there no PCSpec 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

get

public PCSpec get(java.lang.String specName)
           throws java.rmi.RemoteException,
                  EngineException

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

Parameters:

specName - The name of the specification to look up.

Returns:

The PCSpec for the specified name, or null if there is no programming 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

getPCSpecInfo

public PCSpecInfo getPCSpecInfo(java.lang.String specName)
                         throws NoSuchSpecException,
                                java.rmi.RemoteException,
                                EngineException

Returns adminstrative information about a programming cycle specification.

Parameters:

specName - The name of the programming cycle specification

Returns:

A PCSpecInfo instance giving administrative information about the specified programming cycle specification.

Throws:

NoSuchSpecException - if there no PCSpec 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:

PCSpecInfo

listPCSpecNames

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

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

Returns:

A list of strings naming the currently defined programming 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 specName,
                      java.net.URI uri,
                      PCSubscriptionControls controls)
               throws NoSuchSpecException,
                      InvalidURIException,
                      java.rmi.RemoteException,
                      EngineException

Subscribe to asynchronous report delivery from a programming cycle specification. These subscribers will receive PCWriteReport notifications whenever a programming cycle for the named PCSpec is completed.

The subscription defined by this call 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.

Parameters:

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

NoSuchSpecException - if there no PCSpec defined having the specified name.

InvalidURIException - if the specified URI cannot be interpreted, or has no notification 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

unsubscribe

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

Unsubscribe a specified destination from receving asynchronous delivery of reports from a specified programming cycle specification.

Parameters:

specName - The name of the specification to unsubscribe from.

uri - The destination that will no longer receive reports.

Throws:

NoSuchSpecException - if there no PCSpec defined having the specified name.

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

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

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

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

listSubscribers

public java.util.List listSubscribers(java.lang.String specName)
                               throws NoSuchSpecException,
                                      java.rmi.RemoteException,
                                      EngineException

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

Parameters:

specName - The name of the specification.

Returns:

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

Throws:

NoSuchSpecException - if there no PCSpec 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:

PCSpecInfo.getSubscriberCount()

getPCSubscriptionInfo

public PCSubscriptionInfo getPCSubscriptionInfo(java.lang.String specName,
                                                java.net.URI subscriber)
                                         throws NoSuchSpecException,
                                                NoSuchSubscriberException,
                                                InvalidURIException,
                                                java.rmi.RemoteException,
                                                EngineException

Returns administrative information about a programming cycle subscription.

Parameters:

specName - The name of the programming cycle specification

Returns:

A PCSubscriptionInfo instance giving administrative information about the specified programming cycle subscription.

Throws:

NoSuchSpecException - if there no PCSpec defined having the specified name.

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

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:

PCSubscriptionInfo

poll

public PCWriteReport poll(java.lang.String specName,
                          java.util.Map parameters)
                   throws InvalidURIException,
                          java.lang.InterruptedException,
                          NoSuchSpecException,
                          NoSuchCacheException,
                          java.rmi.RemoteException,
                          EngineException

Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report. A new activation of the programming cycle is begun immediately or when the start trigger is received (if the programming cycle specification specifies a start trigger).

Parameters:

specName - The name of the programming cycle specification to activate.

parameters - A Map (String keys to String values) for parameters to be used in processing the PCSpec

Returns:

The report generated from the programming cycle.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchSpecException - if there no PCSpec defined having the specified name.

NoSuchCacheException - if the PCSpec does not contain an EPC cache name, and an epcVal is not supplied.

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

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

poll

public PCWriteReport poll(java.lang.String specName,
                          java.net.URI epcVal)
                   throws InvalidURIException,
                          java.lang.InterruptedException,
                          NoSuchSpecException,
                          NoSuchCacheException,
                          java.rmi.RemoteException,
                          EngineException

Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report. A new activation of the programming cycle is begun immediately or when the start trigger is received (if the programming cycle specification specifies a start trigger).

Parameters:

specName - The name of the programming cycle specification to activate.

epcVal - The EPC value to program. May be null, in which case the EPC value to write is obtained from the PCSpec's EPC cache.

Returns:

The report generated from the programming cycle.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchSpecException - if there no PCSpec defined having the specified name.

NoSuchCacheException - if the PCSpec does not contain an EPC cache name, and an epcVal is not supplied.

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

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

poll

public PCWriteReport poll(java.lang.String specName)
                   throws InvalidURIException,
                          java.lang.InterruptedException,
                          NoSuchSpecException,
                          NoSuchCacheException,
                          java.rmi.RemoteException,
                          EngineException

Activates a previously defined programming cycle specification for one programming cycle, synchronously returning a report. A new activation of the programming cycle is begun immediately or when the start trigger is received (if the programming cycle specification specifies a start trigger).

Parameters:

specName - The name of the programming cycle specification to activate.

Returns:

The report generated from the programming cycle.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchSpecException - if there no PCSpec defined having the specified name.

NoSuchCacheException - if the PCSpec does not contain an EPC cache name, and an epcVal is not supplied.

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

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

immediate

public PCWriteReport immediate(PCSpec spec,
                               java.util.Map parameters)
                        throws InvalidURIException,
                               java.lang.InterruptedException,
                               PCSpecValidationException,
                               NoSuchCacheException,
                               java.rmi.RemoteException,
                               EngineException

Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report. This is similar to first defining a specification using define(java.lang.String, com.connecterra.alepc.api.PCSpec), activating it for one programming cycle using poll(java.lang.String, java.util.Map), and undefining it using undefine(java.lang.String), except that programming cycle specifications created using this method will not be visible to listPCSpecNames() or getPCSpecInfo(java.lang.String).

Parameters:

spec - The programming cycle specification.

parameters - A Map (String keys to String values) for parameters to be used in processing the PCSpec

Returns:

The report generated from one activation of the specification.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchCacheException - if the PCSpec references an EPC cache that is not defined, and an epcVal is not supplied.

PCSpecValidationException - if the PCSpec 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.

immediate

public PCWriteReport immediate(PCSpec spec,
                               java.net.URI epcVal)
                        throws InvalidURIException,
                               java.lang.InterruptedException,
                               PCSpecValidationException,
                               NoSuchCacheException,
                               java.rmi.RemoteException,
                               EngineException

Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report. This is similar to first defining a specification using define(java.lang.String, com.connecterra.alepc.api.PCSpec), activating it for one programming cycle using poll(java.lang.String, java.util.Map), and undefining it using undefine(java.lang.String), except that programming cycle specifications created using this method will not be visible to listPCSpecNames() or getPCSpecInfo(java.lang.String).

Parameters:

spec - The programming cycle specification.

epcVal - The EPC value to program. May be null, in which case the EPC value to write is obtained from the PCSpec's EPC cache.

Returns:

The report generated from one activation of the specification.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchCacheException - if the PCSpec references an EPC cache that is not defined, and an epcVal is not supplied.

PCSpecValidationException - if the PCSpec 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.

immediate

public PCWriteReport immediate(PCSpec spec)
                        throws InvalidURIException,
                               java.lang.InterruptedException,
                               PCSpecValidationException,
                               NoSuchCacheException,
                               java.rmi.RemoteException,
                               EngineException

Immediately define a programming cycle specification and activate it for one programming cycle, synchronously returning a report. This is similar to first defining a specification using define(java.lang.String, com.connecterra.alepc.api.PCSpec), activating it for one programming cycle using poll(java.lang.String, java.util.Map), and undefining it using undefine(java.lang.String), except that programming cycle specifications created using this method will not be visible to listPCSpecNames() or getPCSpecInfo(java.lang.String).

Parameters:

spec - The programming cycle specification.

Returns:

The report generated from one activation of the specification.

Throws:

InvalidURIException - if the supplied URI is not a valid EPC value.

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

NoSuchCacheException - if the PCSpec references an EPC cache that is not defined, and an epcVal is not supplied.

PCSpecValidationException - if the PCSpec 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.

defineEPCCache

public void defineEPCCache(java.lang.String cacheName,
                           EPCCacheSpec spec,
                           EPCPatterns replenishment)
                    throws DuplicateNameException,
                           CacheSpecValidationException,
                           InvalidPatternsException,
                           java.rmi.RemoteException,
                           EngineException

Defines an EPC cache that can be used by programming cycles to obtain EPC values for programming operations.

Parameters:

cacheName - The name of the EPC cache.

spec - The EPC cache specification to define.

replenishment - An optional replenishment for the newly defined EPC cache. May be null or empty, in which case the EPC cache starts off empty.

Throws:

DuplicateNameException - if a EPC cache having the same name is already defined.

CacheSpecValidationException - if the EPCCacheSpec is invalid.

InvalidPatternsException - if the supplied replenishment is invalid. If this exception is thrown, the EPCCache will have been defined, but it will be empty.

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

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

redefineEPCCache

public void redefineEPCCache(java.lang.String cacheName,
                             EPCCacheSpec newSpec)
                      throws NoSuchCacheException,
                             CacheSpecValidationException,
                             java.rmi.RemoteException,
                             EngineException

Replace the EPCCacheSpec having the specified name with a new EPCCacheSpec. All subscriptions and other metadata remain unchanged, and the cache contents are not altered.

Parameters:

cacheName - The name of the EPC cache.

newSpec - The specification to replace the existing one.

Throws:

NoSuchCacheException - if there no EPCCacheSpec defined having the specified name.

CacheSpecValidationException - if the EPCCacheSpec 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

undefineEPCCache

public EPCPatterns undefineEPCCache(java.lang.String cacheName)
                             throws NoSuchCacheException,
                                    CacheInUseException,
                                    java.rmi.RemoteException,
                                    EngineException

Undefines an EPC cache. All existing subscriptions to this EPC cache are removed.

Parameters:

cacheName - The name of the EPC cache to undefine.

Returns:

An EPCPatterns containing a sequence of EPC pattern URIs which specify the EPC value(s) that were remaining in the EPC cache immediately prior to the undefine operation.

Throws:

NoSuchCacheException - if there no EPC cache defined having the specified name.

CacheInUseException - if there are any PCSpecs that name this EPC cache.

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

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

getEPCCache

public EPCCacheSpec getEPCCache(java.lang.String cacheName)
                         throws java.rmi.RemoteException,
                                EngineException

Look up and return a previously defined EPC cache specification by name.

Parameters:

cacheName - The name of the EPC cache specification to look up.

Returns:

The EPCCacheSpec for the specified name, or null if there is no EPC cache 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

getEPCCacheSpecInfo

public EPCCacheSpecInfo getEPCCacheSpecInfo(java.lang.String cacheName,
                                            boolean includeCacheContent)
                                     throws NoSuchCacheException,
                                            java.rmi.RemoteException,
                                            EngineException

Returns adminstrative information about an EPC cache.

Parameters:

cacheName - The name of the EPC cache to look up.

includeCacheContent - Indicates whether the EPCCacheSpecInfo.getCacheContent() attribute should be populated.

Returns:

A EPCCacheSpecInfo instance giving administrative information about the specified EPC cache.

Throws:

NoSuchCacheException - if there no EPC cache 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:

EPCCacheSpecInfo

listEPCCacheSpecNames

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

Returns a list of the names of all EPC caches currently defined.

Returns:

A list of strings naming the currently defined EPC caches.

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

replenishEPCCache

public void replenishEPCCache(java.lang.String cacheName,
                              EPCPatterns replenishment)
                       throws NoSuchCacheException,
                              InvalidPatternsException,
                              java.rmi.RemoteException,
                              EngineException

Appends a set of EPC pattern URIs to the indicated EPC cache.

Parameters:

cacheName - The name of the EPC cache.

replenishment - A collection of EPC pattern URIs to be appended to the named EPC cache.

Throws:

NoSuchCacheException - if there no EPC cache defined having the specified name.

InvalidPatternsException - if the supplied EPCPatterns 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

depleteEPCCache

public EPCPatterns depleteEPCCache(java.lang.String cacheName)
                            throws NoSuchCacheException,
                                   java.rmi.RemoteException,
                                   EngineException

Causes the indicated EPC cache to become depleted (empty). Returns the pre-depleted contents of the EPC cache.

This call blocks until any in-progress programming cycles have completed. In this way, a failed programming cycle's EPC value, which gets returned to the EPC cache, will be incorporated into the deplete operation.

Parameters:

cacheName - The name of the EPC cache to be depleted.

Returns:

A container of EPC pattern URIs which specify the EPC value(s) that were remaining in the EPC cache immediately prior to the deplete operation.

Throws:

NoSuchCacheException - if there no EPC cache 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

subscribeEPCCache

public void subscribeEPCCache(java.lang.String cacheName,
                              java.net.URI uri,
                              PCSubscriptionControls controls)
                       throws NoSuchCacheException,
                              InvalidURIException,
                              java.rmi.RemoteException,
                              EngineException

Subscribe to asynchronous report delivery from an EPC cache. An EPC cache issues EPCCacheReports when its size drops below a specified low-content threshold.

The subscription defined by this call 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.

Parameters:

cacheName - The name of the EPC cache 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:

NoSuchCacheException - if there no EPC cache defined having the specified name.

InvalidURIException - if the specified URI cannot be interpreted, or has no notification 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

unsubscribeEPCCache

public void unsubscribeEPCCache(java.lang.String cacheName,
                                java.net.URI uri)
                         throws NoSuchCacheException,
                                NoSuchSubscriberException,
                                InvalidURIException,
                                java.rmi.RemoteException,
                                EngineException

Unsubscribe a specified destination from receving asynchronous delivery of reports from a specified EPC cache.

Parameters:

cacheName - The name of the EPC cache 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.

NoSuchCacheException - if there no EPC cache defined having the specified name.

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

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

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

listEPCCacheSubscribers

public java.util.List listEPCCacheSubscribers(java.lang.String cacheName)
                                       throws NoSuchCacheException,
                                              java.rmi.RemoteException,
                                              EngineException

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

Parameters:

cacheName - The name of the EPC cache.

Returns:

A List of URI instances, each a subscriber of the specified EPC cache.

Throws:

NoSuchCacheException - if there no EPC cache 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:

EPCCacheSpecInfo.getSubscriberCount()

getEPCCacheSubscriptionInfo

public PCSubscriptionInfo getEPCCacheSubscriptionInfo(java.lang.String cacheName,
                                                      java.net.URI subscriber)
                                               throws NoSuchCacheException,
                                                      NoSuchSubscriberException,
                                                      java.rmi.RemoteException,
                                                      EngineException

Returns administrative information about an EPC cache subscription.

Parameters:

cacheName - The name of the EPC cache

Returns:

A PCSubscriptionInfo instance giving administrative information about the specified EPC cache subscription.

Throws:

NoSuchCacheException - if there no EPC cache defined having the specified name.

NoSuchSubscriberException - if the URI specified is not subscribed to the specified EPC cache

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:

PCSubscriptionInfo

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 programming cycle specifications for EPC programming.

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