com.jpeterson.x10
Interface Gateway

All Known Implementing Classes:
GatewayImpl

public interface Gateway


Field Summary
static long ALLOCATED
          Bit of state that is set when a Gateway is in the allocated state.
static long ALLOCATING_RESOURCES
          Bit of state that is set when a Gateway is being allocated - the transition state between DEALLOCATED to ALLOCATED following a call to the allocate method.
static long DEALLOCATED
          Bit of state that is set when a Gateway is in the deallocated state.
static long DEALLOCATING_RESOURCES
          Bit of state that is set when a Gateway is being deallocated - the transition state between ALLOCATED to DEALLOCATED.
static long PAUSED
          Bit of state that is set when a Gateway is in the ALLOCATED state and is PAUSED.
static long RESUMED
          Bit of state that is set when a Gateway is in the ALLOCATED state and is RESUMED.
 
Method Summary
 void addGatewayListener(GatewayListener listener)
          Request notifications of events related to the Gateway.
 void allocate()
          Alocate the resources required for the Gateway and put it into the ALLOCATED state.
 void deallocate()
          Free the resources of the gateway that were acquired during allocation and during operation and return the gateway to the DEALLOCATED state.
 long getGatewayState()
          Returns a OR'ed set of flags indicating the current state of a Gateway.
 void pause()
          Pause the event transmission for the gateway and put the Gateway into the PAUSED state.
 void removeGatewayListener(GatewayListener listener)
          Remove a listener from this Gateway.
 void resume()
          Put the Gateway in the RESUMED state to resume event transmission or reception for a paused gateway.
 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.
 

Field Detail

DEALLOCATED

public static final long DEALLOCATED
Bit of state that is set when a Gateway is in the deallocated state. A deallocated gateway does not have the resources necessary for it to carry out its basic functions.

In the DEALLOCATED state, many of the methods of a Gateway throw an exception when called. The DEALLOCATED state has no sub-states.

A Gateway is always created in the DEALLOCATED state. A DEALLOCATED can transition to the ALLOCATED state via the ALLOCATING_RESOURCES state following a call to the allocate method. A Gateway returns to the DEALLOCATED state via the DEALLOCATING_RESOURCES state with a call to the deallocate method.

See Also:
allocate, deallocate, getGatewayState, waitGatewayState

ALLOCATING_RESOURCES

public static final long ALLOCATING_RESOURCES
Bit of state that is set when a Gateway is being allocated - the transition state between DEALLOCATED to ALLOCATED following a call to the allocate method. The ALLOCATING_RESOURCES state has no sub-states. In the ALLOCATING_RESOURCES state, many of the methods of Gateway, Transmitter, and Receiver will block unitl the Gateway reaches the ALLOCATED state and the action can be performed.
See Also:
getGatewayState, waitGatewayState

ALLOCATED

public static final long ALLOCATED
Bit of state that is set when a Gateway is in the allocated state. A gateway in the ALLOCATED state has acquired the resources required for it to carry out its core functions.

A Gateway is always created in the DEALLOCATED state. It reaches the ALLOCATED state via the ALLOCATING_RESOURCES state with a call to the allocate method.

See Also:
Transmitter, Receiver, getGatewayState, waitGatewayState

DEALLOCATING_RESOURCES

public static final long DEALLOCATING_RESOURCES
Bit of state that is set when a Gateway is being deallocated - the transition state between ALLOCATED to DEALLOCATED. The DEALLOCATING_RESOURCES state has no sub-states. In the DEALLOCATING_RESOURCE state, most methods of Gateway, Transmitter and Receiver throw an exception.
See Also:
getGatewayState, waitGatewayState

PAUSED

public static final long PAUSED
Bit of state that is set when a Gateway is in the ALLOCATED state and is PAUSED. In the PAUSED state, event transmission or reception is stopped.

An ALLOCATED gateway is always in either the PAUSED or RESUMED state. The PAUSED and RESUMED states are sub-states of the ALLOCATED state.

See Also:
RESUMED, ALLOCATED, getGatewayState, waitGatewayState

RESUMED

public static final long RESUMED
Bit of state that is set when a Gateway is in the ALLOCATED state and is RESUMED. In the RESUMED state, event transmission or reception is active.

An ALLOCATED gateway is always in either the PAUSED or RESUMED state. The PAUSED and RESUMED states are sub-states of the ALLOCATED state.

See Also:
RESUMED, ALLOCATED, getGatewayState, waitGatewayState
Method Detail

getGatewayState

public long getGatewayState()
Returns a OR'ed set of flags indicating the current state of a Gateway. The format of the returned state value is described above.

A GatewayEvent is issued each time the Gateway changes state.

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

See Also:
getGatewayState, waitGatewayState, getNewGatewayState, getOldGatewayState

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. The format of the state value is described above.

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.

Throws:
java.lang.InterruptedException - if another thread has interrupted this thread
java.lang.IllegalArgumentException - if the specified state is unreachable
See Also:
testGatewayState, getGatewayState

testGatewayState

public boolean testGatewayState(long state)
                         throws java.lang.IllegalArgumentException
Returns true if the current gateway state matches the specified state. The format of the state value is described above.

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 is the Transmitter queue is empty, irrespective of the allocation states.

 if (trans.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.
Throws:
java.lang.IllegalArgumentException - - if the specified state is unreachable

allocate

public void allocate()
              throws GatewayException,
                     GatewayStateError
Alocate the resources required for the Gateway and put it into the ALLOCATED state. When this method returns successfully the ALLOCATED bit of the gateway state is set, and the testGatewayState(Gateway.ALLOCATED) method returns true. During the processing of the method, the Gateway is temporarily in the ALLOCATING_RESOURCES state.

When the Gateway reaches the ALLOCATED state other engine states are determined:

  • PAUSED or RESUMED: the pause state depends upon the existing state of the gateway. In a multi-app environment, the pause/resume state of the gateway is shared by all apps.
  • A Transmitter always starts in the QUEUE_EMPTY state when newly allocated
While this method is being processed events are issued to any GatewayListeners attached to the Gateway to indicate state changes. First, as the Gateway changes from the DEALLOCATED to the ALLOCATING_RESOURCES state, a GATEWAY_ALLOCATING_RESOURCES event is issued. As the allocation process completes, the gateway moves from the ALLOCATING_RESOURCES state to the ALLOCATED state and an GATEWAY_ALLOCATED event is issued.

The allocate method should be called for a Gateway in the DEALLOCATED state. The method has no effect for a Gateway in either the ALLOCATING_RESOURCES or ALLOCATED states. The method throws an exception in the DEALLOCATING_RESOURCES state.

If any problems are encountered during the allocation process so that the gateway cannot be allocated, the gateway returns to the DEALLOCATED state (with a GATEWAY_DEALLOCATED event), and an GatewayException is thrown.

Allocating the resources for a gateway may be fast (less than a second) or slow (several 10s of seconds) depending upon a range of factors. Since the allocate method does not return until allocation is completed applications may want to perform allocation in a background thread and proceed with other activities.

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
Free the resources of the gateway that were acquired during allocation and during operation and return the gateway to the DEALLOCATED state. When this method returns the DEALLOCATED bit of gateway state is set so the testGatewayState(Gateway.DEALLOCATED) method returns true. During the processing of the method, the Gateway is temporarily in the DEALLOCATING_RESOURCES state.

A deallocated gateway can be re-started with a subsequent call to allocate.

Gateways need to clean up current activities before being deallocated. A Transmitter must be in the QUEUE_EMPTY state before being deallocated. If the queue is not empty, any objects on the transmit queue must be cancelled with appropriate events issued.

While this method is being processed events are issued to any GatewayListeners attached to the Gateway to indicate state changes. First, as the Gateway changes from the ALLOCATED to the DEALLOCATING_RESOURCES state, a GATEWAY_DEALLOCATING_RESOURCES event is issued. As the deallocation process completes, the gateway moves from the DEALLOCATING_RESOURCES state to the DEALLOCATED state and an GATEWAY_DEALLOCATED event is issued.

The deallocate method should only be called for a Gateway in the ALLOCATED state. The method has no effect for a Gateway in either the DEALLOCATING_RESOURCES or DEALLOCATED states. The method throws an exception in the ALLOCATING_RESOURCES state.

Deallocating resources for a gateway is not always immediate. Since the deallocate method does not return until complete, applications may want to perform deallocation in a separate thread.

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 the event transmission for the gateway and put the Gateway into the PAUSED state. Pausing a gateway pauses the underlying gateway for all applications that are connected to that gateway. Gateways are typically paused and resumed by request from a user.

Applications may pause a gateway indefinately. When a gateway moves from the RESUMED state to the PAUSED state, an GATEWAY_PAUSED event is issued to each GatewayListener attached to the Gateway. The PAUSED bit of the gateway state is set to true when paused, and can be tested by the getGatewayState method and other gateway state methods.

The PAUSED state is a sub-state of the ALLOCATED state. An ALLOCATED Gateway is always in either the PAUSED or the RESUMED state.

It is not an exception to pause a Gateway that is already paused.

The pause method oeprates as defined for gateways in the ALLOCATED state. When pause is called for a gateway in the ALLOCATING_RESOURCES state, the method blocks (waits) until the ALLOCATED state is reached and then operates normally. An error is thrown when pause is called for a gateway in either the DEALLOCATED or DEALLOCATING_RESOURCES states.

The pause method does not always return immediately. Some application need to execute pause in a separate thread.

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
Put the Gateway in the RESUMED state to resume event transmission or reception for a paused gateway. Resuming a gateway resumes the underlying gateway for all applications that are connected to that gateway. Gateways are typically paused and resumed by request from a user.

The specific pause/resume bejavior of tramistters and receivers is defined in the documentation for the pause method.

When a gateway moves from the PAUSED state to the RESUMED state, a GATEWAY_RESUMED event is issued to each GatewayListener attached to the Gateway. The RESUMED bit of the gateway state is set to true when resumed, and can be tested by the getGatewayState method and other gateway state methods.

The RESUMED state is a sub-state of the ALLOCATED state. An ALLOCATED Gateway is always in either the PAUSED or the RESUMED state.

It is not an exception to resume a gateway that is already in the RESUMED state.

The resume method operates as defined for gateways in the ALLOCATED state. When resume is called for a gateway in the ALLOCATING_RESOURCES state, the method blocks (waits) until the ALLOCATED state is reached and then operates normally. An error is thrown when resume is called for a gateway in either the DEALLOCATED or DEALLOCATING_RESOURCES state.

The resume method does not always return immediately. Some applications need to execute resume in a separate thread.

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)
Request notifications of events related to the Gateway. An application can attache multiple listeners to a Gateway. A single listener can be attached to multiple gateways.

The GatewayListener is extended for both transmission and reception. Typically, a ReceptionListener is attached to a Receiver and a TransmissionListener is attached to a Transmitter.

A GatewayListener can be attached or removed in any state of a Gateway.

Parameters:
listener - the listener that will reveive GatewayEvents
See Also:
Receiver, ReceptionListener, Transmitter, TransmissionListener

removeGatewayListener

public void removeGatewayListener(GatewayListener listener)
Remove a listener from this Gateway. A GatewayListener can be attached or removed in any state of a Gateway.
Parameters:
listener - the listener to be removed