com.jpeterson.x10
Class GatewayImpl

java.lang.Object
  |
  +--com.jpeterson.x10.GatewayImpl
Direct Known Subclasses:
SerialGateway

public abstract class GatewayImpl
extends java.lang.Object
implements Gateway, ControlEventDispatcher

Base GatewayImpl. Must be subclassed to do something useful. By default, a NullGatewayQueue is registered as the GatewayQueue. If you require event handling synchronized with the AWT event queue, you can manually register an AWTGatewayQueue.


Field Summary
protected  java.util.Vector gatewayListeners
           
protected  GatewayQueue gatewayQueue
           
 
Fields inherited from interface com.jpeterson.x10.Gateway
ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, DEALLOCATING_RESOURCES, PAUSED, RESUMED
 
Constructor Summary
protected GatewayImpl()
           
 
Method Summary
 void addGatewayListener(GatewayListener listener)
          Add a gateway listener.
 void allocate()
          Allocate a gateway.
 void deallocate()
          Deallocate a gateway.
 void dispatchControlEvent(ControlEvent event)
          Method to actually send a GatewayEvent to registered listeners.
 void fireControlEvent(ControlEvent event)
          Queues ControlEvent on registered GatewayQueue for subsequent dispatch to registered gateway listeners.
 GatewayQueue getGatewayQueue()
          Retrieve the gateway queue used to process ControlEvents sent by the method fireControlEvent.
 long getGatewayState()
          Returns a or'ed set of flags indicating the current state of a Gateway.
 void pause()
          Pause a gateway.
 void removeGatewayListener(GatewayListener listener)
          Remove a gateway listener.
 void resume()
          Resume a gateway.
 void setGatewayQueue(GatewayQueue gatewayQueue)
          Set the gateway queue used to process ControlEvents sent by the method fireControlEvent.
protected  void setGatewayState(long state)
          Assign a new gateway state.
protected  void stateTransition(long state)
          Performs state transitions for Gateway.ALLOCATED, Gateway.ALLOCATING_RESOURCES, Gateway.DEALLOCATED, Gateway.DEALLOCATING_RESOURCES, Gateway.PAUSED, Gateway.RESUMED.
 boolean testGatewayState(long state)
          Returns true if the current gateway state matches the specified state.
 void waitGatewayState(long state)
          Blocks the calling thread until the Gateway is in a specified state.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

gatewayQueue

protected GatewayQueue gatewayQueue

gatewayListeners

protected java.util.Vector gatewayListeners
Constructor Detail

GatewayImpl

protected GatewayImpl()
Method Detail

getGatewayState

public long getGatewayState()
Returns a or'ed set of flags indicating the current state of a Gateway.

A GatewayEvent is issued each time the Gateway changes state.

The getGatewayState method can be called successfully in any Gateway state.

Specified by:
getGatewayState in interface Gateway
Tags copied from interface: Gateway
See Also:
getGatewayState, waitGatewayState, getNewGatewayState, getOldGatewayState

setGatewayState

protected void setGatewayState(long state)
Assign a new gateway state. This method works with waitGatewayState() to correctly perform blocking while waiting for specified gateway states.

waitGatewayState

public void waitGatewayState(long state)
                      throws java.lang.InterruptedException,
                             java.lang.IllegalArgumentException
Blocks the calling thread until the Gateway is in a specified state.

All state bits specified in the state parameter must be set in order for the method to return, as defined for the testGatewayState method. If the state parameter defines an unreachable state (e.g. ALLOCATED | DEALLOCATED) an exception is thrown.

The waitGatewayState method can be called successfully in any Gateway state.

Specified by:
waitGatewayState in interface Gateway
Throws:
java.lang.InterruptedException - if another thread has interrupted this thread.
java.lang.IllegalArgumentException - if the specified state is unreachable

stateTransition

protected void stateTransition(long state)
Performs state transitions for Gateway.ALLOCATED, Gateway.ALLOCATING_RESOURCES, Gateway.DEALLOCATED, Gateway.DEALLOCATING_RESOURCES, Gateway.PAUSED, Gateway.RESUMED. This method fires a GatewayEvent for valid state transitions.

testGatewayState

public boolean testGatewayState(long state)
                         throws java.lang.IllegalArgumentException
Returns true if the current gateway state matches the specified state.

The test performed is not an exact match to the current state. Only the specified states are tested. For example the following returns true only if the Transmitter queue is empty, irrespective of the pause/resume and allocation states.

if (transmitter.testGatewayState(Transmitter.QUEUE_EMPTY)) ...

The testGatewayState method is equivalent to:

if ((gateway.getGatewayState() & state) == state)

The testGatewayState method can be called successfully in any Gateway state.

Specified by:
testGatewayState in interface Gateway
Throws:
java.lang.IllegalArgumentException - if the specified state is unreachable

allocate

public void allocate()
              throws GatewayException,
                     GatewayStateError
Allocate a gateway.
Specified by:
allocate in interface Gateway
Tags copied from interface: Gateway
Throws:
GatewayException - if an allocation error occurred or the gateway is not operational.
GatewayStateError - is called for an engine in the DEALLOCATING_RESOURCES state
See Also:
getGatewayState, deallocate, ALLOCATED, GATEWAY_ALLOCATED

deallocate

public void deallocate()
                throws GatewayException,
                       GatewayStateError
Deallocate a gateway.
Specified by:
deallocate in interface Gateway
Tags copied from interface: Gateway
Throws:
GatewayException - if a deallocation error occurs.
GatewayStateError - if called for a gateway in the ALLOCATING_RESOURCES state
See Also:
allocate, GATEWAY_DEALLOCATED, QUEUE_EMPTY

pause

public void pause()
           throws GatewayStateError
Pause a gateway.
Specified by:
pause in interface Gateway
Tags copied from interface: Gateway
Throws:
GatewayStateError - if called for a gateway in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:
resume, getGatewayState, GATEWAY_PAUSED

resume

public void resume()
            throws GatewayStateError
Resume a gateway.
Specified by:
resume in interface Gateway
Tags copied from interface: Gateway
Throws:
GatewayStateError - if called for a gateway in the DEALLOCATED or DEALLOCATING_RESOURCES states.
See Also:
pause, getGatewayState, GATEWAY_RESUMED

addGatewayListener

public void addGatewayListener(GatewayListener listener)
Add a gateway listener.
Specified by:
addGatewayListener in interface Gateway
Tags copied from interface: Gateway
Parameters:
listener - the listener that will reveive GatewayEvents
See Also:
Receiver, ReceptionListener, Transmitter, TransmissionListener

removeGatewayListener

public void removeGatewayListener(GatewayListener listener)
Remove a gateway listener.
Specified by:
removeGatewayListener in interface Gateway
Tags copied from interface: Gateway
Parameters:
listener - the listener to be removed

setGatewayQueue

public void setGatewayQueue(GatewayQueue gatewayQueue)
Set the gateway queue used to process ControlEvents sent by the method fireControlEvent.
Parameters:
gatewayQueue - GatewayQueue assigned to handle ControlEvents.

getGatewayQueue

public GatewayQueue getGatewayQueue()
Retrieve the gateway queue used to process ControlEvents sent by the method fireControlEvent.
Returns:
The gateway queue used to process ControlEvents.

fireControlEvent

public void fireControlEvent(ControlEvent event)
Queues ControlEvent on registered GatewayQueue for subsequent dispatch to registered gateway listeners.
See Also:
setGatewayQueue

dispatchControlEvent

public void dispatchControlEvent(ControlEvent event)
Method to actually send a GatewayEvent to registered listeners.

This method should be overridden by subclass implementations of Transmitter and Receiver to handle their specific events. However, this method must be called to handle any events that they do not.

This method handles plane GatewayEvent and GatewayErrorEvent X10Events.

Specified by:
dispatchControlEvent in interface ControlEventDispatcher
Parameters:
event - the ControlEvent to be propagated to the listeners
See Also:
fireControlEvent