Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at ${DOCSWEBROOT} Copyright 2007 BEA Systems Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD