com.connecterra.ale.alevent
Class EngineALEImpl

java.lang.Object
  com.connecterra.ale.alevent.EngineALEImpl

All Implemented Interfaces:

ALE

public class EngineALEImpl

extends java.lang.Object

implements ALE

This class implements the Applicaiton Level Events (ALE) processing engine. Because it implements the ALE interface, it may be called directly by an application which shares a JVM with the ALE engine. More commonly, however, an application is deployed in a different JVM, and accesses the ALE Engine by using one of the remote client classes provided in the com.connecterra.ale.client package.

Constructor Summary

EngineALEImpl(com.connecterra.util.RawConfig rc, com.connecterra.ale.persistence.PersistenceManager pm, NotificationManager nm, com.connecterra.ale.reader.ReaderManager rm, com.connecterra.ale.reader.CompositeReaderManager crm, com.connecterra.ale.trigger.TriggerManager tm, AlarmClock ac, java.util.logging.Logger logger, com.connecterra.ale.subscription.SubscriptionControls msc, com.connecterra.ale.subscription.SubscriptionControls dsc, java.lang.String aleID)

Method Summary

void	define(java.lang.String name, ECSpec spec) 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 name) Look up and return a previously defined event cycle specification by name.
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 name) Look up and return a previously defined event cycle specification by name.
ECSpecInfo	getECSpecInfo(java.lang.String name) 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 name, java.net.URI uri) Returns administrative information about an event cycle subscriber.
int	getEventCyclesCompletedCount()
ThreadPoolScheduler	getScheduler()
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.
boolean	isUsingCompositeReader(java.lang.String name)
boolean	isUsingLogicalReader(com.connecterra.ale.reader.LogicalReader[] lrs)
boolean	isUsingTrigger(java.lang.String triggerName)
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 name) Returns a list of URIs which are subscribed to asynchronous reports for the specified ECSpec name.
ECReports	poll(java.lang.String name) Activates a previously defined event cycle specification for one event cycle, synchronously returning a report.
void	redefine(java.lang.String name, ECSpec spec) Replace the ECSpec having the specified name with a new ECSpec.
void	redefinedCompositeReader(java.lang.String name) Notification method called whenever the ALE Configuration API is used to define, redefine, or undefine composite readers.
void	redefinedLogicalReaders(com.connecterra.ale.reader.LogicalReader[] oldLRs, com.connecterra.ale.reader.LogicalReader[] newLRs) Notification method called whenever the ALE Configuration API is used to define, redefine, or undefine logical readers (via defining, redefining, or undefining a physical reader).
void	redefinedTrigger(java.lang.String triggerName, com.connecterra.ale.trigger.TriggerDriver oldTD, com.connecterra.ale.trigger.TriggerDriver newTD)
void	shutdown() This is a public, non-ALE method used to shutdown ALE processing.
void	subscribe(java.lang.String name, java.net.URI uri) Subscribe to asynchronous report delivery from an event cycle specification.
void	subscribe(java.lang.String name, 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 name) Undefine an event cycle specification.
void	unsubscribe(java.lang.String name, 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

EngineALEImpl

public EngineALEImpl(com.connecterra.util.RawConfig rc,
                     com.connecterra.ale.persistence.PersistenceManager pm,
                     NotificationManager nm,
                     com.connecterra.ale.reader.ReaderManager rm,
                     com.connecterra.ale.reader.CompositeReaderManager crm,
                     com.connecterra.ale.trigger.TriggerManager tm,
                     AlarmClock ac,
                     java.util.logging.Logger logger,
                     com.connecterra.ale.subscription.SubscriptionControls msc,
                     com.connecterra.ale.subscription.SubscriptionControls dsc,
                     java.lang.String aleID)
              throws com.connecterra.util.ConfigValidationException

Method Detail

getScheduler

public ThreadPoolScheduler getScheduler()

getALEFactory

public ALEFactory getALEFactory()

Description copied from interface: ALE

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

Specified by:

getALEFactory in interface ALE

See Also:

ALE.getALEFactory()

getStandardVersion

public java.lang.String getStandardVersion()

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

See Also:

ALE.getStandardVersion()

getVendorVersion

public java.lang.String getVendorVersion()

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

See Also:

ALE.getVendorVersion()

getEventCyclesCompletedCount

public int getEventCyclesCompletedCount()

getALEID

public java.lang.String getALEID()

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.

define

public void define(java.lang.String name,
                   ECSpec spec)
            throws DuplicateNameException,
                   ECSpecValidationException,
                   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:

name - The name of the specification.

spec - The specification to define.

Throws:

ECSpecValidationException - if the ECSpec is invalid.

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

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

See Also:

ECSpec

redefine

public void redefine(java.lang.String name,
                     ECSpec spec)
              throws NoSuchNameException,
                     ECSpecValidationException,
                     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:

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

See Also:

ECSpec

suspend

public void suspend(java.lang.String ecSpecName)
             throws NoSuchNameException,
                    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

See Also:

ECSpecInfo.isSuspended()

unsuspend

public void unsuspend(java.lang.String ecSpecName)
               throws NoSuchNameException,
                      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:

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 name)
              throws NoSuchNameException,
                     EngineException

Description copied from interface: ALE

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

Specified by:

undefine in interface ALE

Parameters:

name - The name of the specification to undefine.

Throws:

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)

getECSpec

public ECSpec getECSpec(java.lang.String name)
                 throws NoSuchNameException,
                        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

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

See Also:

ECSpec

get

public ECSpec get(java.lang.String name)
           throws 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:

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

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

getECSpecNames

public java.util.List getECSpecNames()

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.

listECSpecNames

public java.util.List listECSpecNames()

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.

subscribe

public void subscribe(java.lang.String name,
                      java.net.URI uri)
               throws NoSuchNameException,
                      InvalidURIException,
                      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:

name -

uri -

Throws:

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

See Also:

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

subscribe

public void subscribe(java.lang.String name,
                      java.net.URI uri,
                      ECSubscriptionControls controls)
               throws NoSuchNameException,
                      InvalidURIException,
                      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:

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

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

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 name,
                        java.net.URI uri)
                 throws NoSuchNameException,
                        NoSuchSubscriberException,
                        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:

name - The name of the specification to unsubscribe from.

uri - The destination that will no longer receive reports.

Throws:

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

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

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

See Also:

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

getSubscribers

public java.util.List getSubscribers(java.lang.String specName)
                              throws NoSuchNameException,
                                     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:

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()

listSubscribers

public java.util.List listSubscribers(java.lang.String name)
                               throws NoSuchNameException,
                                      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:

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

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

See Also:

ECSpecInfo.getSubscriberCount()

getECSpecInfo

public ECSpecInfo getECSpecInfo(java.lang.String name)
                         throws NoSuchNameException,
                                EngineException

Description copied from interface: ALE

Returns administrative information about an event cycle specification.

Specified by:

getECSpecInfo in interface ALE

Parameters:

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

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

See Also:

ECSpecInfo

getECSubscriptionInfo

public ECSubscriptionInfo getECSubscriptionInfo(java.lang.String name,
                                                java.net.URI uri)
                                         throws NoSuchNameException,
                                                NoSuchSubscriberException,
                                                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:

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

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

See Also:

ECSubscriptionInfo

poll

public ECReports poll(java.lang.String name)
               throws java.lang.InterruptedException,
                      NoSuchNameException,
                      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:

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

Returns:

The reports generated from the event cycle.

Throws:

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 spec)
                    throws java.lang.InterruptedException,
                           ECSpecValidationException,
                           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:

spec - The event cycle specification.

Returns:

The reports generated from one activation of the specification.

Throws:

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()

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.

isUsingLogicalReader

public boolean isUsingLogicalReader(com.connecterra.ale.reader.LogicalReader[] lrs)

redefinedLogicalReaders

public void redefinedLogicalReaders(com.connecterra.ale.reader.LogicalReader[] oldLRs,
                                    com.connecterra.ale.reader.LogicalReader[] newLRs)

Notification method called whenever the ALE Configuration API is used to define, redefine, or undefine logical readers (via defining, redefining, or undefining a physical reader).

isUsingCompositeReader

public boolean isUsingCompositeReader(java.lang.String name)

redefinedCompositeReader

public void redefinedCompositeReader(java.lang.String name)

Notification method called whenever the ALE Configuration API is used to define, redefine, or undefine composite readers.

isUsingTrigger

public boolean isUsingTrigger(java.lang.String triggerName)

redefinedTrigger

public void redefinedTrigger(java.lang.String triggerName,
                             com.connecterra.ale.trigger.TriggerDriver oldTD,
                             com.connecterra.ale.trigger.TriggerDriver newTD)

shutdown

public void shutdown()

This is a public, non-ALE method used to shutdown ALE processing. It will hold a lock which will cause other ALE methods to block until the suspend is complete, then those methods will return an EngineException.