|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
public static final long DEALLOCATED
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.
allocate
,
deallocate
,
getGatewayState
,
waitGatewayState
public static final long ALLOCATING_RESOURCES
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.getGatewayState
,
waitGatewayState
public static final long ALLOCATED
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.
Transmitter
,
Receiver
,
getGatewayState
,
waitGatewayState
public static final long DEALLOCATING_RESOURCES
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.getGatewayState
,
waitGatewayState
public static final long PAUSED
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.
RESUMED
,
ALLOCATED
,
getGatewayState
,
waitGatewayState
public static final long RESUMED
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.
RESUMED
,
ALLOCATED
,
getGatewayState
,
waitGatewayState
Method Detail |
public long getGatewayState()
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.
getGatewayState
,
waitGatewayState
,
getNewGatewayState
,
getOldGatewayState
public void waitGatewayState(long state) throws java.lang.InterruptedException, java.lang.IllegalArgumentException
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.
testGatewayState
,
getGatewayState
public boolean testGatewayState(long state) throws java.lang.IllegalArgumentException
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.
Theif (trans.testGatewayState(Transmitter.QUEUE_EMPTY)) ...
testGatewayState
method is equivalent to:
Theif ((gateway.getGatewayState() & state) == state)
testGatewayState
method can be called successfully
in any Gateway
state.public void allocate() throws GatewayException, GatewayStateError
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
public void deallocate() throws GatewayException, GatewayStateError
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.
ALLOCATING_RESOURCES
stateallocate
,
GATEWAY_DEALLOCATED
,
QUEUE_EMPTY
public void pause() throws GatewayStateError
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.
DEALLOCATED
or
DEALLOCATING_RESOURCES
statesresume
,
getGatewayState
,
GATEWAY_PAUSED
public void resume() throws GatewayStateError
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.
DEALLOCATED
or
DEALLOCATING_RESOURCES
states.pause
,
getGatewayState
,
GATEWAY_RESUMED
public void addGatewayListener(GatewayListener listener)
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
.
listener
- the listener that will reveive GatewayEvents
Receiver
,
ReceptionListener
,
Transmitter
,
TransmissionListener
public void removeGatewayListener(GatewayListener listener)
Gateway
. A
GatewayListener
can be attached or removed in any state of
a Gateway
.listener
- the listener to be removed
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |