com.connecterra.ale.reader
Class ChannelManager

java.lang.Object
  com.connecterra.ale.reader.ChannelManager

public class ChannelManager
extends Object

This class manages a set of channels used to communicate with a device. It separates the responsibilities of channel maintenance and device state maintenance, so channel implementations can be reused and device drivers do not need to concern themselves with initialization and retry semantics. A state machine ensures that all channels are active and the device is initialized before attempting to execute any operations on the device. The ChannelManager delegates channel-specific operations to classes which extend DeviceChannel and delegates device-specific operations to an object which implements the ChannelManager.Proxy interface.

In general, a ChannelManager is used as follows:

1. The ChannelManager is created by a device.
2. Based on configuration provided by the user, one or more DeviceChannels are created and added to the manager. Note that neither creating or registering a channel will actually attempt to activate or use the channel, although it may attempt to resolve some configuration information, such as loading classes or resolving hostnames.
3. Operations are executed on the manager. Before executing any operation, the manager will DeviceChannel.activate() each channel, then ChannelManager.Proxy.initialize() the Proxy. If activation, initialization, or execution has a communication problem and throws an IOException, then the manager will retry once before giving up.

The manager uses the proxy's logger to issue log messages when state transitions occur.

The manager is not reentrant. The caller is responsible for ensuring that access to the ChannelManager and to the I/O methods in the DeviceChannels are properly synchronized to avoid simultaneous calls. Exceptions to this are noted in method documentation.

In addition to the above reentrancy rules, channels may need to execute invoke callbacks when input is received asynchronously from devices by listeners. Such callbacks are invoked from within a Runnable passed to the ChannelManager.Proxy.listenerExecute(java.lang.Runnable) method. Because these callbacks may use I/O methods on DeviceChannels, the implementation must therefore ensure that the Runnable is not executed at the same time as any methods on ChannelManager or DeviceChannel. For maximum performance, some sort of work queue is recommended.

Nested Class Summary

static interface	ChannelManager.Operation This interface is implemented by classes which represent work to be performed after activation and initialization.
static interface	ChannelManager.Proxy This class is implemented by consumers of the ChannelManager mechanism.
static class	ChannelManager.State The manager implements a state machine which has these states.

Constructor Summary

ChannelManager(ChannelManager.Proxy p)
Creates a new ChannelManager instance with the specified ChannelManager.Proxy.

Method Summary

void	addChannel(DeviceChannel c) Adds a DeviceChannel to the manager.
void	execute(ChannelManager.Operation op) This method is called to do some work which communicates with the device.
long	getLastUsedTime()
ChannelManager.State	getState()
void	reactivateChannels() Deactivates each channel, activates each channel, then initializes the proxy.
void	removeAllChannels() Removes all DeviceChannels from the manager.
void	removeChannel(DeviceChannel c) Removes a DeviceChannel from the manager.
void	setProxy(ChannelManager.Proxy p) Sets the manager's proxy instance.
void	terminate() Makes a best-effort attempt to close all the channels.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChannelManager

public ChannelManager(ChannelManager.Proxy p)

Creates a new ChannelManager instance with the specified ChannelManager.Proxy.

Parameters:

p - the Proxy instance

Method Detail

setProxy

public void setProxy(ChannelManager.Proxy p)

Sets the manager's proxy instance.

Parameters:

p - a Proxy value

addChannel

public void addChannel(DeviceChannel c)

Adds a DeviceChannel to the manager. This method may only be Called in the INACTIVE state.

Parameters:

c - a DeviceChannel value

Throws:

IllegalStateException - if called when the state is not INACTIVE.

removeChannel

public void removeChannel(DeviceChannel c)

Removes a DeviceChannel from the manager. This method may only be Called in the INACTIVE state.

Parameters:

c - a DeviceChannel value

Throws:

IllegalStateException - if called when the state is not INACTIVE.

removeAllChannels

public void removeAllChannels()

Removes all DeviceChannels from the manager. This method may only be Called in the INACTIVE state.

Throws:

IllegalStateException - if called when the state is not INACTIVE.

execute

public void execute(ChannelManager.Operation op)

This method is called to do some work which communicates with the device. When this method is called in the DEACTIVATING, ACTIVATING, or TERMINATED state, nothing happens.

If the method is called in the INACTIVE or OFFLINE state, then the manager will activate each channel in turn, then call the ChannelManager.Proxy.initialize() method.

The* op's {#link Operation#execute} method is run.

If any of the prior steps throws an IOException, all of the channels are deactivated, and the process restarts as if from the INACTIVE state one more time.

Parameters:

op - an Operation value

reactivateChannels

public void reactivateChannels()

Deactivates each channel, activates each channel, then initializes the proxy. No retry is attempted.

terminate

public void terminate()

Makes a best-effort attempt to close all the channels. After this method is called, nothing else should happen. This method may be invoked even while another thread is running a method on this object.

getState

public ChannelManager.State getState()

Returns:

a State value representing the current state

getLastUsedTime

public long getLastUsedTime()

Returns:

The time any of the channels was last successfully used, in the same representation as System.currentTimeMillis().