com.connecterra.ale.reader
Class AbstractPhysicalDevice

java.lang.Object
  com.connecterra.util.event.AbstractEventProcessor
      com.connecterra.ale.reader.AbstractPhysicalDevice

All Implemented Interfaces:

com.bea.rfid.edge.api.telemetry.Telemetered, ChannelManager.Proxy, PhysicalDevice, Controllable, EventProcessor, com.connecterra.util.plugin.Plugin

Direct Known Subclasses:

AbstractPollingPhysicalDevice

public abstract class AbstractPhysicalDevice
extends AbstractEventProcessor
implements PhysicalDevice, com.bea.rfid.edge.api.telemetry.Telemetered, ChannelManager.Proxy

This is the base class for the device driver framework. All device driver implementations must extend this class or one of its derived classes. See the Device Framework and Development Kit document for a basic tutorial on writing a device driver using the framework.

Implementations which extend this class must implement or override the AbstractPhysicalDevice.initialize(PluginConfig), AbstractPhysicalDevice.initializeSession(Requests), AbstractPhysicalDevice.updateRequests(com.connecterra.ale.reader.AbstractPhysicalDevice.Requests, com.connecterra.ale.reader.AbstractPhysicalDevice.Requests), and AbstractPhysicalDevice.sendStatusRequest() methods. The implementation must also provide a public static PluginMeta getPluginMeta() method. This method is used by the framework to prompt the user for appropriate configuration for the driver before it is instantiated.

This class extends AbstractEventProcessor. The event mechanism is the primary means of synchronization for device drivers, and is used by the channel framework. The AbstractEventProcessor always has an AlarmClock, so AbstractEventProcessor.doLater(long, com.connecterra.util.event.Event) can always be used when delayed processing is required.

Nested Class Summary

static interface	AbstractPhysicalDevice.AFIReadingTagProcessor A AbstractPhysicalDevice.TagProcessor should implement this interface if the device provides special support for efficiently reading the AFI value of a tag that has already been inventoried.
static interface	AbstractPhysicalDevice.BankReadTagProcessor TagProcessors should implement this interface if the device can read data from memory banks on the associated tag.
static interface	AbstractPhysicalDevice.BankTagProcessor A convenience interface that combines AbstractPhysicalDevice.BankReadTagProcessor and AbstractPhysicalDevice.BankWriteTagProcessor
static interface	AbstractPhysicalDevice.BankWriteTagProcessor TagProcessors should implement this interface if the device can write data to memory banks on the associated tag.
static interface	AbstractPhysicalDevice.EPCglobalClass1Gen2TagProcessor TagProcessors should implement this interface if the device supports full EPCglobal Class 1 Gen 2 tag functionality.
static interface	AbstractPhysicalDevice.EPCglobalTagProcessor A convenience interface that combines AbstractPhysicalDevice.EPCglobalTagReadProcessor and AbstractPhysicalDevice.EPCglobalTagWriteProcessor
static interface	AbstractPhysicalDevice.EPCglobalTagReadProcessor TagProcessors should implement this interface if the object in question is identified by an EPC or otherwise contains an EPC value.
static interface	AbstractPhysicalDevice.EPCglobalTagWriteProcessor TagProcessors should implement this interface if the device has the capability of modifying the associated tag's EPC value.
static class	AbstractPhysicalDevice.EPCTagData Base class for TagProcessors that are associated with a DeviceUnit, and which contain DeviceTagReports that always store EPC data as the tag identity.
protected class	AbstractPhysicalDevice.Requests Represents all of the subscribed DeviceUnitRequests on a device, and all the tags which have been reported for any of those DeviceUnitRequests.
static class	AbstractPhysicalDevice.TagData Base class for TagProcessors that are associated with a DeviceUnit
static class	AbstractPhysicalDevice.TagProcessor The base class of objects which can be passed to AbstractPhysicalDevice.processOpSpecs(com.connecterra.ale.reader.AbstractPhysicalDevice.TagProcessor, java.util.List).
static class	AbstractPhysicalDevice.TagResultException This exception should be thrown from a TagProcessor exception with an appropriate OpStatus, and failure info String if the OpStatus is not OK.

Nested classes/interfaces inherited from class com.connecterra.util.event.AbstractEventProcessor

AbstractEventProcessor.PeriodicEventHandle

Field Summary

protected ChannelManager

m_channelManager

Constructor Summary

AbstractPhysicalDevice()
Creates a new AbstractPhysicalDevice instance.

Method Summary

static void	addAFIParametersToPluginMeta(DynamicConfigFactory factory, PluginMeta pm) Adds the "Read Tag AFI" and "Forced AFI value" parameters to the PluginMeta.
protected void	addDeviceChannel(DeviceChannel chan) Add a new DeviceChannel to the device.
void	addDeviceUnit(DeviceUnit ant) Add a new DeviceUnit to the physical device.
static void	addForceAFIParameterToPluginMeta(DynamicConfigFactory factory, PluginMeta pm) Adds the "Forced AFI value" parameter to the PluginMeta.
static void	addReadAFIParameterToPluginMeta(DynamicConfigFactory factory, PluginMeta pm) Adds the "Read Tag AFI" parameter to the PluginMeta.
void	addReaderThread(Thread t) Inform the framework about a thread created by the device driver.
void	addTagData(AbstractPhysicalDevice.TagData td)
static void	addToPluginMeta(DynamicConfigFactory factory, PluginMeta pm) Adds appropriate PluginParameterMeta objects to the PluginMeta as needed by the framework.
ChannelManager.State	getChannelState()
DeviceUnit	getDeviceUnit(int num) Returns the DeviceUnit with the given number.
int	getForcedAFIValue()
Logger	getLogger() This logger is used to inform the user of manager state transitions and other relevant information from each of the channels.
Set	getLogicalReaderSet()
String	getPhysicalDeviceName()
void	initialize(PluginConfig config)
protected void	initializeSession()
protected void	initializeSession(AbstractPhysicalDevice.Requests curReqs)
boolean	isForceAFI()
boolean	isReadAFI()
protected List	processOpSpecs(AbstractPhysicalDevice.TagProcessor tp, List opSpecs) Execute the opSpecs on a single TagProcessor.
void	removeReaderThread(Thread t) Inform the framework about a thread which is no longer running, so that cleanup is no logner needed.
void	report(DeviceUnit deviceUnit, boolean cycleComplete)
protected void	sendStatusRequest() This driver method is used to verify communications with the device.
void	setDeviceAttributes(String manufacturer, String model, DeviceCapabilities capabilities) Set the telemetry attributes for device manufacturer name and model.
void	shutdown() Initiate whatever process is necessary to do an orderly shutdown of the subsystem.
void	terminate() Initiate whatever process is necessary to forcibly shut down the subsystem.
String	toString() The ChannelManager uses the toString() method to get a printable name which is used in log messages issued when the channel changes state.
protected void	updateRequests(AbstractPhysicalDevice.Requests prevReqs, AbstractPhysicalDevice.Requests curReqs)
void	waitForShutdown(long timeout) Wait for the shutdown process initiated by Controllable.shutdown() to complete.
void	waitForTermination(long timeout) Wait for the termination process initiated by Controllable.terminate() to complete.

Methods inherited from class com.connecterra.util.event.AbstractEventProcessor

doASAP, doASAPOrBlock, doASAPOrDrop, doASAPOrThrow, doLater, doPeriodic, getEventReceiver

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.connecterra.util.plugin.Plugin

initialize

Methods inherited from interface com.bea.rfid.edge.api.telemetry.Telemetered

getDeviceAttributes, getDeviceType, getTelemetryAssociatedIdentity, telemeter

Methods inherited from interface com.connecterra.ale.reader.ChannelManager.Proxy

initialize, listenerExecute

Methods inherited from interface com.connecterra.util.event.EventProcessor

handleEvent

Field Detail

m_channelManager

protected ChannelManager m_channelManager

Constructor Detail

AbstractPhysicalDevice

public AbstractPhysicalDevice()

Creates a new AbstractPhysicalDevice instance.

Method Detail

addToPluginMeta

public static void addToPluginMeta(DynamicConfigFactory factory,
                                   PluginMeta pm)

Adds appropriate PluginParameterMeta objects to the PluginMeta as needed by the framework. All classes derived from this class should call this class from their own getPluginMeta method.

Currently this adds no parameters, but this could change in the future.

Parameters:

factory - a DynamicConfigFactory value

pm - a PluginMeta value

addReadAFIParameterToPluginMeta

public static void addReadAFIParameterToPluginMeta(DynamicConfigFactory factory,
                                                   PluginMeta pm)

Adds the "Read Tag AFI" parameter to the PluginMeta. This method should be invoked by drivers which have the capability to read the AFI from EPC tags, but where this capability is not "free". This lets the user choose higher performance if the AFI is not needed.

Parameters:

factory - a DynamicConfigFactory value

pm - a PluginMeta value

addForceAFIParameterToPluginMeta

public static void addForceAFIParameterToPluginMeta(DynamicConfigFactory factory,
                                                    PluginMeta pm)

Adds the "Forced AFI value" parameter to the PluginMeta. This method should be invoked by drivers which have the capability to read the AFI from EPC tags, but where this capability is not "free", and by drivers which read EPC tags, but are incapable of reading an AFI at all. This lets the user specify a fixed AFI value if the driver is used in an environment where the AFI is required, known in advance, and can be assumed always to have the same value.

Parameters:

factory - a DynamicConfigFactory value

pm - a PluginMeta value

addAFIParametersToPluginMeta

public static void addAFIParametersToPluginMeta(DynamicConfigFactory factory,
                                                PluginMeta pm)

Adds the "Read Tag AFI" and "Forced AFI value" parameters to the PluginMeta.

Parameters:

factory - a DynamicConfigFactory value

pm - a PluginMeta value

toString

public String toString()

Description copied from interface: ChannelManager.Proxy

The ChannelManager uses the toString() method to get a printable name which is used in log messages issued when the channel changes state.

Specified by:

toString in interface ChannelManager.Proxy

Overrides:

toString in class Object

getPhysicalDeviceName

public String getPhysicalDeviceName()

Specified by:

getPhysicalDeviceName in interface PhysicalDevice

Returns:

the configured name of the physical device

getLogicalReaderSet

public Set getLogicalReaderSet()

Returns:

the Set of LogicalReaders associated with the physical reader

initialize

public void initialize(PluginConfig config)
                throws com.connecterra.ale.reader.DeviceConfigurationException,
                       com.connecterra.ale.resources.PluginLoadException

Throws:

com.connecterra.ale.reader.DeviceConfigurationException

com.connecterra.ale.resources.PluginLoadException

isReadAFI

public boolean isReadAFI()

Returns:

true if the user has selected AFI reads in the reader configuration. Set on Reader Initialization from the Plugin config.

isForceAFI

public boolean isForceAFI()

Returns:

true if the user has forced an AFI value in the reader configuration. Set on Reader Initialization from the Plugin config.

getForcedAFIValue

public int getForcedAFIValue()

Returns:

the forced AFI value from the reader configuration. Set on Reader Initialization from the Plugin config.

setDeviceAttributes

public void setDeviceAttributes(String manufacturer,
                                String model,
                                DeviceCapabilities capabilities)

Set the telemetry attributes for device manufacturer name and model. Also set the capabilities of the device.

Parameters:

manufacturer - a String value

model - a String value

capabilities - a DeviceCapabilities value

addDeviceChannel

protected void addDeviceChannel(DeviceChannel chan)

Add a new DeviceChannel to the device. This should be called by the AbstractPhysicalDevice.initialize(PluginConfig) method, based on configuration.

Parameters:

chan - a DeviceChannel value

initializeSession

protected void initializeSession()
                          throws IOException

Throws:

IOException

addDeviceUnit

public void addDeviceUnit(DeviceUnit ant)

Add a new DeviceUnit to the physical device. This should be called by AbstractPhysicalDevice.initialize(PluginConfig) for each DeviceUnit named in the configuration.

Parameters:

ant - a DeviceUnit value

getDeviceUnit

public DeviceUnit getDeviceUnit(int num)

Returns the DeviceUnit with the given number. The numbering is assigned by the physical device when the DeviceUnit object is created.

Parameters:

num - the device unit number

Returns:

a DeviceUnit value

getLogger

public Logger getLogger()

Description copied from interface: ChannelManager.Proxy

This logger is used to inform the user of manager state transitions and other relevant information from each of the channels.

Specified by:

getLogger in interface ChannelManager.Proxy

Returns:

a Logger value which should be used for all logs pertaining to this device.

initializeSession

protected void initializeSession(AbstractPhysicalDevice.Requests curReqs)
                          throws IOException

Throws:

IOException

updateRequests

protected void updateRequests(AbstractPhysicalDevice.Requests prevReqs,
                              AbstractPhysicalDevice.Requests curReqs)
                       throws IOException

Throws:

IOException

addTagData

public void addTagData(AbstractPhysicalDevice.TagData td)

report

public void report(DeviceUnit deviceUnit,
                   boolean cycleComplete)

sendStatusRequest

protected void sendStatusRequest()
                          throws IOException

This driver method is used to verify communications with the device. It should send a message to the device which will elicit some sort of response, but does not change the device state or cause any operations to take place. A good example is a command to read some identification or version information from the device. This method may read the response synchronously (with the caveats describe in ByteStreamDeviceChannel.getInputStream()), or let an asynchronous listener read the response when it arrives.

Throws:

IOException - if an error occurs

processOpSpecs

protected List processOpSpecs(AbstractPhysicalDevice.TagProcessor tp,
                              List opSpecs)
                       throws IOException

Execute the opSpecs on a single TagProcessor. The specific behavior depends on the implementations of the TagProcessor abstract methods.

Parameters:

tp - TagProcessor the tag to operate on, and how to do it

opSpecs - List of DeviceOpSpec describing what to do to the tag

Returns:

a List of DeviceOpReports, one per opspec

Throws:

IOException

addReaderThread

public void addReaderThread(Thread t)

Inform the framework about a thread created by the device driver. This will allow the framework clean the thread up at shutdown time.

Parameters:

t - a Thread value

removeReaderThread

public void removeReaderThread(Thread t)

Inform the framework about a thread which is no longer running, so that cleanup is no logner needed.

Parameters:

t - a Thread value

shutdown

public void shutdown()

Description copied from interface: Controllable

Initiate whatever process is necessary to do an orderly shutdown of the subsystem. It is not necessary for this process to release resources, such as threads, in use by the subsystem, but it is permitted.

This method should not block for a long time, so that multiple systems can be shut down in parallel.

Specified by:

shutdown in interface Controllable

Overrides:

shutdown in class AbstractEventProcessor

waitForShutdown

public void waitForShutdown(long timeout)
                     throws InterruptedException

Description copied from interface: Controllable

Wait for the shutdown process initiated by Controllable.shutdown() to complete.

Specified by:

waitForShutdown in interface Controllable

Parameters:

timeout - If the timeout elapses before the shutdown process has completed, return anyway.

Throws:

InterruptedException

terminate

public void terminate()

Description copied from interface: Controllable

Initiate whatever process is necessary to forcibly shut down the subsystem. This should kill threads, close network connections, and release any other resources in use by the subsystem.

This method should not block for a long time, so that multiple systems can be shut down in parallel.

Specified by:

terminate in interface Controllable

waitForTermination

public void waitForTermination(long timeout)
                        throws InterruptedException

Description copied from interface: Controllable

Wait for the termination process initiated by Controllable.terminate() to complete.

Specified by:

waitForTermination in interface Controllable

Parameters:

timeout - If the timeout elapses before the shutdown process has completed, return anyway.

Throws:

InterruptedException

getChannelState

public ChannelManager.State getChannelState()

Returns:

the state of the device's ChannelManager