public final class DOFConnection
extends java.lang.Object
DOFConnection.StateListener
s registered with this connection may be called because
of state changes to the connection that are caused by other DOFConnections.
Constructing DOFConnection:
DOFConnection instances are constructed through the DOF with DOF.createConnection(org.opendof.core.oal.DOFConnection.Config)
or from
an existing connection with createConnection(org.opendof.core.oal.DOFConnection.Config)
or from
an instance of DOFConnection.State with DOFConnection.State.createConnection()
.
Special connection types:
DOFConnection.Type.DATAGRAM
).DOFConnection.Type.GROUP
).DOFConnection.Type.HUB
and DOFConnection.Type.POINT
).DOF
,
DOFServer
,
DOFConnection.Config
Modifier and Type | Class and Description |
---|---|
static class |
DOFConnection.Config
This class contains configuration information required for a DOFConnection.
|
static interface |
DOFConnection.ConnectOperationListener
This interface is used for the completion notification for asynchronous
connect requests.
|
static class |
DOFConnection.Direction
This enumeration represents the different connection directions.
|
static interface |
DOFConnection.PeerListener
Implement this interface to monitor the addition/removal of peers (within a secure group) at runtime.
|
static interface |
DOFConnection.State
This class represents the instantaneous state of the connection at a given time.
|
static interface |
DOFConnection.StateListener
StateListener is used to receive notifications about a particular connection's state, such as when a connection
is established or terminated.
|
static class |
DOFConnection.StreamRequest
This represents a request for a
DOFConnection.Type.STREAM connection to a specific, target DOFAddress.Type.UNICAST
address based on the desire (expressed by interest operations) for a STREAM connection and the presence of a matching
binding. |
static interface |
DOFConnection.StreamRequestListener
Implement this interface to monitor requests to upgrade a
DOFConnection.Type.DATAGRAM connection to a
DOFConnection.Type.STREAM type. |
static class |
DOFConnection.Type
This enumeration represents the different types of connections.
|
Modifier and Type | Method and Description |
---|---|
void |
addDomain(DOFDomain.Config domainConfig)
Dynamically add the credentials, which are used on a connection that supports authentication, to verify that the host
being connected to is authorized to process authentication requests in the domain that is specified
in the credentials.
|
void |
addPeerListener(DOFConnection.PeerListener peerListener)
Add a peer listener to this connection.
|
void |
addStateListener(DOFConnection.StateListener stateListener)
Add a connection state-change handler to this connection.
|
void |
addTrustedDomain(DOFObjectID.Domain domainID)
Dynamically add in a configured TRP route without credentials.
|
DOFOperation.Connect |
beginConnect(int timeout)
Open a connection, waiting up to timeout for the connection to be established.
|
DOFOperation.Connect |
beginConnect(int timeout,
DOFConnection.ConnectOperationListener operationListener)
Open a connection, waiting up to timeout for the connection to be established.
|
DOFOperation.Connect |
beginConnect(int timeout,
DOFConnection.ConnectOperationListener operationListener,
java.lang.Object context)
Open a connection, waiting up to timeout for the connection to be established.
|
DOFOperation.Connect |
beginReconnect(int timeout)
Re-open a connection, waiting up to timeout for the connection to be reestablished.
|
DOFOperation.Connect |
beginReconnect(int timeout,
DOFConnection.ConnectOperationListener operationListener)
Re-open a connection, waiting up to timeout for the connection to be reestablished.
|
DOFOperation.Connect |
beginReconnect(int timeout,
DOFConnection.ConnectOperationListener operationListener,
java.lang.Object context)
Re-open a connection, waiting up to timeout for the connection to be reestablished.
|
void |
connect(int timeout)
Open a connection, waiting up to timeout for the connection to be established.
|
DOFConnection |
createConnection(DOFConnection.Config config)
Create a
DOFConnection.Type.POINT connection related to this connection. |
void |
destroy()
Destroy a connection, removing references to it.
|
void |
disconnect()
Request that a connection be terminated.
|
boolean |
equals(java.lang.Object obj) |
DOFConnection |
getRelatedConnection()
Return the connection that was created using DOFConnection.createConnection.
|
DOFServer |
getRelatedServer()
Return the server that was created using DOFServer.createConnection.
|
DOFConnection.State |
getState()
Get the current instantaneous state of the connection.
|
int |
hashCode() |
boolean |
isConnected()
Return whether or not the connection is currently connected.
|
void |
reconnect(int timeout)
Reopen a connection, waiting up to timeout for the connection to be reestablished.
|
void |
removeDomain(DOFDomain.Config domainConfigs)
Dynamically remove the connection from the TRP route associated with the credentials.
|
void |
removePeerListener(DOFConnection.PeerListener peerListener)
Remove a peer listener from this connection.
|
void |
removeStateListener(DOFConnection.StateListener stateListener)
Remove a connection state-change handler from this connection.
|
void |
removeTrustedDomain(DOFObjectID.Domain domainID)
Remove the connection from the TRP router for the specified domain.
|
java.lang.String |
toString() |
public void destroy()
public void connect(int timeout) throws DOFException
DOFConnection.StateListener
s reflect the actual state of the connection, where
this routine establishes a desired state.
For example, if the connection is already connected and this routine is called
then the listener will not be called - it would have already been told
of the previous connect. This means that the actual state of the connection
is known to either the listener or by directly asking the DOFConnection
for its current state.
Will also start any related server and open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be
established. If this time passes without a connection then the routine will throw
an exception and the request will be forgotten. Note, however, that the connection
may still occur, and the listener notified, if the underlying transport cannot
cancel the connection request. Must be >= 0.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.DOFErrorException
- This is thrown if the connection times out or if any
other error occurs. Many different exception types may be thrown depending
on the specific failure: DOFErrorException, DOFSecurityException or DOFAuthenticationException.DOFException
public void reconnect(int timeout) throws DOFException
timeout
- Maximum time to wait, in milliseconds, for the connection to be
established. If this time passes without a connection then the routine will throw
an exception and the request will be forgotten. Note, however, that the connection
may still occur, and the listener notified, if the underlying transport cannot
cancel the connection request. Must be >= 0.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.DOFErrorException
- This is thrown if the connection times out or if any
other error occurs. Many different exception types may be thrown depending
on the specific failure: DOFErrorException, DOFSecurityException or DOFAuthenticationException.DOFException
public DOFOperation.Connect beginConnect(int timeout)
DOFOperation.waitComplete()
can be called on the returned operation to wait for it to complete.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.
Will also start any related server and open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be established.public DOFOperation.Connect beginConnect(int timeout, DOFConnection.ConnectOperationListener operationListener)
DOFConnection.ConnectOperationListener
that will be called with information about the completion of the routine.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.
Will also start any related server and open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be
established before calling the listener's complete() method. Note, however, that the connection
may still occur if the underlying transport cannot
cancel the connection request. Must be >= 0. Zero is allowed, in
which case the listener's complete() is immediately called indicating the current state.operationListener
- An associated completion listener. May be null.public DOFOperation.Connect beginConnect(int timeout, DOFConnection.ConnectOperationListener operationListener, java.lang.Object context)
DOFConnection.ConnectOperationListener
that will be called with information about the completion of the routine.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.
Will also start any related server and open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be
established before calling the listener's complete() method. Note, however, that the connection
may still occur if the underlying transport cannot
cancel the connection request. Must be >= 0. Zero is allowed, in
which case the listener's complete() is immediately called indicating the current state.operationListener
- An associated completion listener. May be null.context
- Context data associated with the operation. The context may be retrieved with operation.getContext().public DOFOperation.Connect beginReconnect(int timeout)
DOFOperation.waitComplete()
can be called on the returned operation to wait for it to complete.
We recommend 30 seconds for DOFConnection.Type.POINT
connections.
Will also restart any related server and re-open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be reestablished.public DOFOperation.Connect beginReconnect(int timeout, DOFConnection.ConnectOperationListener operationListener)
DOFConnection.Type.POINT
connections.
Will also restart any related server and re-open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be
reestablished before calling the listener's complete() method. Note, however, that the connection
may still occur if the underlying transport cannot
cancel the connection request. Must be >= 0. Zero is allowed, in
which case the listener complete() is immediately called indicating the current state.operationListener
- An associated completion listener. May be null.public DOFOperation.Connect beginReconnect(int timeout, DOFConnection.ConnectOperationListener operationListener, java.lang.Object context)
DOFConnection.Type.POINT
connections.
Will also restart any related server and re-open any related connection.timeout
- Maximum time to wait, in milliseconds, for the connection to be
reestablished before calling the listener's complete() method. Note, however, that the connection
may still occur if the underlying transport cannot
cancel the connection request. Must be >= 0. Zero is allowed, in
which case the listener complete() is immediately called indicating the current state.operationListener
- An associated completion listener. May be null.context
- Context data associated with the operation. The context may be retrieved with operation.getContext().public void disconnect()
public void addStateListener(DOFConnection.StateListener stateListener)
connect(int)
. That is, your
listener may be called twice with the "connected" state. It is preferable to add the listener before
calling connect(). Your listener will then be called twice: once with a "!connected" state and then again with "connected".stateListener
- The listener that should be called with state changes. This must not be null.removeStateListener(org.opendof.core.oal.DOFConnection.StateListener)
public void addTrustedDomain(DOFObjectID.Domain domainID)
domainID
- The domain identifier for the domain to use for routing purposes. Must not be null.public void addDomain(DOFDomain.Config domainConfig) throws DOFSecurityException
domainConfig
- The credentials for the domain to authorize. Must not be null.DOFSecurityException
- Thrown if validation fails.public void removeDomain(DOFDomain.Config domainConfigs)
domainConfigs
- The credentials to use.public void removeTrustedDomain(DOFObjectID.Domain domainID)
domainID
- The domain identifier for the domain being used for routing purposes. Must not be null.public void removeStateListener(DOFConnection.StateListener stateListener)
stateListener
- The listener that should no longer be notified. This must not be null.addStateListener(org.opendof.core.oal.DOFConnection.StateListener)
public void addPeerListener(DOFConnection.PeerListener peerListener)
DOFConnection.Type.POINT
or DOFConnection.Type.GROUP
member joins the
secure group.peerListener
- The listener that should be called with peer discovery. This must not be null.java.lang.IllegalArgumentException
- If this connection type is not DOFConnection.Type.HUB
or DOFConnection.Type.GROUP
.removePeerListener(org.opendof.core.oal.DOFConnection.PeerListener)
public void removePeerListener(DOFConnection.PeerListener peerListener)
peerListener
- The listener that should be called with peer discovery. This must not be null.java.lang.IllegalArgumentException
- If this connection type is not DOFConnection.Type.HUB
or DOFConnection.Type.GROUP
.addPeerListener(org.opendof.core.oal.DOFConnection.PeerListener)
public DOFConnection.State getState()
public boolean isConnected()
public DOFServer getRelatedServer()
public DOFConnection getRelatedConnection()
public DOFConnection createConnection(DOFConnection.Config config)
DOFConnection.Type.POINT
connection related to this connection. Anything else will fail.
See DOFConnection.Type.POINT
for instructions to properly create a POINT connection.config
- The configuration options of the connection. Must not be null.DOFConnection.Type.POINT
public java.lang.String toString()
toString
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object