public final class DOF
extends java.lang.Object
DOFSystem
), servers (DOFServer
), and connections (DOFConnection
). While systems
initiate and process operations, it is the DOF that determines where to route those operations
(which other systems, connections, or servers associated with that DOF will receive the traffic).
The DOF uses operation state, routing tables, security constraints, and similar information to make
this determination.
Because each DOF represents a separate networking node, even when two DOFs reside in the same application, each is a separate logical node in the network. So for example, while security-compatible systems on the same DOF can communicate directly, systems on separate DOFs require connections and servers to communicate—even if both DOFs are in the same application.
The DOF is created using its constructor (DOF(Config)
) and is initialized during creation. Some configuration parameters can be changed after creation to
modify the behavior of an existing DOF and any objects created by it (for example, see setConnectionLimit(int)
). However, changing other configuration
parameters associated with the DOF requires taking the node down, destroying the DOF, and building a new DOF with a new configuration. For information
about all configuration parameters, see DOF.Config.Builder
.
The DOF is used to create:
DOFSystem
with createSystem()
DOFConnection
with createConnection(org.opendof.core.oal.DOFConnection.Config)
DOFServer
with createServer(org.opendof.core.oal.DOFServer.Config)
DOFDomain
with createDomain(org.opendof.core.oal.DOFDomain.Config)
DOFAuthenticator
with createAuthenticator(org.opendof.core.oal.DOFAuthenticator.Config)
Modifier and Type | Class and Description |
---|---|
static class |
DOF.Config
The Config class specifies the initial configuration to use when creating a DOF.
|
static class |
DOF.DefaultProtocolFactory
The default protocol factory implements
DOFProtocolFactory and is the factory that is used unless
you create your own. |
static interface |
DOF.DomainListener
The DomainListener interface enables you to be notified when a route to the Authentication Server
for a remote domain is discovered.
|
static interface |
DOF.InterestListener
The DOF.InterestListener interface enables you to create functionality for monitoring all interest requests.
|
static class |
DOF.Log
The Log class contains logging methods for both sending (
DOF.Log ) and receiving (DOF.Log.Listener ) log messages. |
static interface |
DOF.PermissionListener
The PermissionListener interface enables you to be notified when a terminal permission is granted or denied.
|
static class |
DOF.Runtime
The Runtime class enables access to runtime information about the associated DOF, including traffic statistics and information
about active connections and servers.
|
static class |
DOF.SecurityDesire
The SecurityDesire enumeration types represent the security levels that can be imposed on connections
DOFConnection and servers DOFServer . |
static interface |
DOF.State
A State instance represents a snapshot of the DOF's configuration information as it exists at the moment when you call
getState() . |
static interface |
DOF.TrafficStats
A TrafficStats instance contains information about a DOF's traffic-related statistical data, including packet counts and bytes counts.
|
static interface |
DOF.UncaughtExceptionListener
The definition of the listener for uncaught exceptions.
|
Modifier and Type | Field and Description |
---|---|
static int |
TIMEOUT_NEVER
Specifies an infinite timeout.
|
static int |
UNLIMITED
Integer.MAX_VALUE, so that the default number of simultaneous connections the DOF allows is at
its maximum setting.
|
Constructor and Description |
---|
DOF()
Creates a DOF instance with a default config.
|
DOF(DOF.Config config)
Creates a DOF instance that uses the specified configuration.
|
Modifier and Type | Method and Description |
---|---|
void |
addDomainListener(DOF.DomainListener domainListener)
Adds a
DOF.DomainListener to the DOF, which is used to monitor the DOF's known security domains. |
void |
addInterestListener(DOF.InterestListener listener)
Adds a
DOF.InterestListener to the DOF. |
void |
addPermissionListener(DOF.PermissionListener permissionListener)
Add a
DOF.PermissionListener to the DOF, which will be notified of permission grants and denials. |
void |
addUncaughtExceptionListener(DOF.UncaughtExceptionListener listener)
Adds a
DOF.UncaughtExceptionListener to the DOF. |
void |
cancelAllOperations()
Cancels all outstanding operations sourced by this DOF.
|
void |
close(DOFConnection connection)
Forces a connection to close.
|
DOFAuthenticator |
createAuthenticator(DOFAuthenticator.Config authConfig)
Creates a
DOFAuthenticator that uses the specified configuration. |
DOFConnection |
createConnection(DOFConnection.Config config)
Creates a
DOFConnection that uses the specified configuration. |
DOFDomain |
createDomain(DOFDomain.Config config)
Creates a
DOFDomain that uses the specified configuration. |
DOFServer |
createServer(DOFServer.Config config)
Creates a
DOFServer that uses the specified configuration. |
DOFSystem |
createSystem()
Creates a
DOFSystem that uses the default configuration. |
DOFSystem |
createSystem(DOFSystem.Config config)
Creates a
DOFSystem that uses the specified configuration. |
DOFSystem |
createSystem(DOFSystem.Config config,
int timeout)
Creates a
DOFSystem that uses the specified configuration. |
void |
destroy()
Frees resources allocated during the creation of a DOF.
|
DOFAuthenticator |
getAuthenticator(DOFObjectID.Domain domainID)
Gets an authenticator for a specified domain.
|
java.util.Collection<DOFAuthenticator> |
getAuthenticators()
Gets a list of all DOFAuthenticators known to the DOF.
|
java.util.List<DOFDomain> |
getDomains()
Gets a list of all domains associated with the DOF.
|
DOF.Runtime |
getRuntime()
Gets this DOF's runtime, which contains data about the internal runtime state of the DOF.
|
DOF.State |
getState()
Creates a
DOF.State object, which represents a snapshot of the DOF's configuration information as it exists at the moment when you call
this method. |
java.util.List<DOFSystem> |
getSystems()
Gets a list of all systems associated with the DOF.
|
void |
removeDomainListener(DOF.DomainListener domainListener)
Removes a
DOF.DomainListener from the DOF. |
void |
removeInterestListener(DOF.InterestListener listener)
Removes a
DOF.InterestListener . |
void |
removePermissionListener(DOF.PermissionListener permissionListener)
Remove a
DOF.PermissionListener from the DOF. |
void |
removeUncaughtExceptionListener(DOF.UncaughtExceptionListener listener)
Removes a
DOF.UncaughtExceptionListener . |
void |
resolve(DOFCredentials credentials,
int timeout)
Attempts to resolve the given credentials.
|
void |
setConnectionLimit(int limit)
Changes the maximum number of simultaneous connections the DOF supports.
|
void |
setName(java.lang.String name)
Changes the name of a DOF.
|
void |
setNodeDown()
Notifies the network that the DOF calling this method is about to be destroyed.
|
void |
setProtocolFactory(DOFProtocolFactory factory)
Changes the protocol factory.
|
void |
setRank(short rank)
Changes the DOF's desire to manage a secure multicast group.
|
void |
setThreadPoolSize(short max)
Changes the maximum number of threads the DOF can create.
|
void |
stop(DOFServer server)
Forces a server to stop.
|
void |
updateAuthenticator(DOFAuthenticator.Config authConfig)
Updates an existing DOFAuthenticator with the specified configuration.
|
public static final int TIMEOUT_NEVER
public static final int UNLIMITED
DOF.Config.Builder.setConnectionLimit(int)
to set a different value.public DOF()
createSystem()
).
It is very rare that an application would require more than a single DOF, but multiples can be created.
Each DOF created must be destroyed by calling the destroy()
method.destroy()
public DOF(DOF.Config config)
createSystem()
).
It is very rare that an application would require more than a single DOF, but multiples can be created.
Each DOF created must be destroyed by calling the destroy()
method.config
- An instance of DOF.Config
that represents a source of configuration parameters for the DOF. Use DOF.Config.Builder
to create an instance of DOF.Config. You may pass a null value to use the default configuration.java.lang.IllegalArgumentException
- Indicates that the configuration has errors, including a DOF name that is already in use or other invalid arguments.destroy()
public void destroy()
DOF(Config)
public void setNodeDown()
destroy()
method. Continuing to send DOF operations to the rest of the network after sending a setNodeDown call
will cause your DOF's state to be out of sync with other nodes and may result in unpredictable behavior.
The DOF.destroy method effectively also calls the setNodeDown method. You do not need to call setNodeDown before DOF.destroy unless you manually
destroy connections and servers (using DOFConnection.destroy()
and DOFServer.destroy()
) immediately before calling the DOF.destroy method (in
other words, you destroy connectivity before calling DOF.destroy). It is unusual to need to manually destroy connections and servers at
program termination (the DOF.destroy method also destroys these objects); however, if you are doing so, calling setNodeDown first is recommended.
You should not use the setNodeDown method before destroying connections and servers unless you intend to also destroy
the DOF. The setNodeDown method does not replace DOF.destroy. You must still call DOF.destroy after calling setNodeDown.
The setNodeDown method does not operate as a way to stop the DOF temporarily. The DOF cannot be restarted after making this call.public void setName(java.lang.String name)
DOF.Config.Builder.setName(java.lang.String)
method. Use this method to change the original value. See the Builder method for more information.name
- A string that identifies the DOF instance.public void setConnectionLimit(int limit)
DOF.Config.Builder.setConnectionLimit(int)
method. Use this method to change the original value.
Because this is a runtime change, the number of currently established connections may already exceed the value you set in this method.
If this occurs, it will not cause the node to drop any existing connections; however, the node will be unable to initiate or accept any new
connections until the total number of connections drops below the new maximum.
See the Builder method for more information.limit
- The connection limit.UNLIMITED
public void setThreadPoolSize(short max)
DOF.Config.Builder.setThreadPoolSize(short)
method. Use this method to change the original value. See the Builder method for more information.max
- The maximum number of threads.DOF.Config.DEFAULT_THREADPOOL_SIZE
public void setRank(short rank)
DOF.Config.Builder.setRank(short)
method. Use this method to change the original value. See the Builder method for more information.rank
- The DOF's rank.DOF.Config.DEFAULT_RANK
public DOF.State getState()
DOF.State
object, which represents a snapshot of the DOF's configuration information as it exists at the moment when you call
this method. After using this method to get the snapshot, you can use the getter methods
of DOF.State to retrieve specific information about the DOF's configuration, as well as some runtime information. Because the DOF's configuration information
and runtime statistics may change, you should call this method again each time you want updated information.public DOFSystem createSystem()
DOFSystem
that uses the default configuration. Calling this overload is identical to calling createSystem(DOFSystem.Config, int)
and passing the arguments (null, 0)
. For a full list of DOFSystem defaults, see DOFSystem.Config.Builder.Builder(). For more information
about creating systems, see createSystem(DOFSystem.Config, int).DOFSystem.destroy()
public DOFSystem createSystem(DOFSystem.Config config)
DOFSystem
that uses the specified configuration. You must create DOFSystem instances in order to create DOFObject
instances, which are needed
to perform the majority of operations DOF provides. DOFSystems are associated with the DOF instance used to create them, and only that DOF can route its
operations (see DOF).
Each DOFSystem instance must be destroyed when it is no longer needed. See DOFSystem.destroy()
and destroy()
.
This method will return immediately, but the system may not be authorized initially.config
- An instance of DOFSystem.Config
that represents a source of configuration parameters for the DOFSystem. Use DOFSystem.Config.Builder
to create an instance of DOFSystem.Config. You may pass a null value to use the default configuration.createSystem()
public DOFSystem createSystem(DOFSystem.Config config, int timeout) throws DOFException
DOFSystem
that uses the specified configuration. You must create DOFSystem instances in order to create DOFObject
instances, which are needed
to perform the majority of operations DOF provides. DOFSystems are associated with the DOF instance used to create them, and only that DOF can route its
operations (see DOF).
Each DOFSystem instance must be destroyed when it is no longer needed. See DOFSystem.destroy()
and destroy()
.
This method will block until the system is authorized or timeout expires.config
- An instance of DOFSystem.Config
that represents a source of configuration parameters for the DOFSystem. Use DOFSystem.Config.Builder
to create an instance of DOFSystem.Config. You may pass a null value to use the default configuration.timeout
- Controls how long (in milliseconds) to wait for authentication when credentials have been set in the configuration. If the configuration does not
include credentials, the timeout may be zero.DOFException
- If unable to authenticate the system when credentials have been set in the configuration.createSystem()
public DOFConnection createConnection(DOFConnection.Config config)
DOFConnection
that uses the specified configuration. The connection is associated with the DOF
instance that creates it, and only that DOF can route operations through it (see DOF).
This method may be used to create the following types of connections:
This method may not be used to create the following types of connections:
DOFConnection.Type.GROUP
. Use DOFServer.createConnection(org.opendof.core.oal.DOFConnection.Config)
.DOFConnection.Type.HUB
. Use DOFServer.createConnection(org.opendof.core.oal.DOFConnection.Config)
.DOFConnection.Type.POINT
. Use DOFConnection.createConnection(org.opendof.core.oal.DOFConnection.Config)
DOFConnection.Type
.
Connections do not connect automatically when created. After creating the connection, call DOFConnection.connect(int)
or DOFConnection.beginConnect(int)
.
To disconnect temporarily, call DOFConnection.disconnect()
. Disconnected connections can be reconnected using
DOFConnection.connect or DOFConnection.beginConnect. When the DOFConnection instance is no longer needed, it must be destroyed.
See DOFConnection.destroy()
and destroy()
. Destroyed connections cannot be reconnected.
The internal library tracks references to duplicate connections, so this method can safely be called multiple times with the
same configuration without consuming extra resources. Such duplicate connections are frequently needed, especially by nodes
that create connections dynamically in response to other method calls.config
- An instance of DOFConnection.Config
that represents a source of configuration parameters for the DOFConnection.
Use DOFConnection.Config.Builder
to create an instance of DOFConnection.Config. This must not be null.close(org.opendof.core.oal.DOFConnection)
,
DOFOperation.Control.setTargetConnection(org.opendof.core.oal.DOFConnection)
public DOFServer createServer(DOFServer.Config config)
DOFServer
that uses the specified configuration. The server is associated with the DOF instance that creates
it, and only that DOF can accept connections or route operations through it (see DOF).
Servers do not start automatically when created. After creating the server, call DOFServer.start(int)
or DOFServer.beginStart(int)
.
To stop the server temporarily, call DOFServer.stop()
. Stopped servers can be restarted using DOFServer.start or DOFServer.beginStart.
Each DOFServer instance must be destroyed when it is no longer needed. See DOFServer.destroy()
and destroy()
. Destroyed
servers cannot be restarted.
The internal library tracks references to duplicate servers, so this method can safely be called multiple times with the
same configuration without consuming extra resources. Such duplicate servers are frequently needed, especially by nodes
that create servers dynamically in response to other method calls.
This method may be used to create unicast servers, but not to create multicast servers. Use DOFServer.createServer(org.opendof.core.oal.DOFServer.Config)
to create multicast servers.
config
- An instance of DOFServer.Config
that represents a source of configuration parameters for the DOFServer.
Use DOFServer.Config.Builder
to create an instance of DOFServer.Config. This must not be null and must not have a multicast address.stop(org.opendof.core.oal.DOFServer)
public void addDomainListener(DOF.DomainListener domainListener)
DOF.DomainListener
to the DOF, which is used to monitor the DOF's known security domains.domainListener
- The listener to add.DOFDomain
,
removeDomainListener(org.opendof.core.oal.DOF.DomainListener)
public void removeDomainListener(DOF.DomainListener domainListener)
DOF.DomainListener
from the DOF. When the listener is removed, this method causes
DOF.DomainListener.removed(org.opendof.core.oal.DOF, org.opendof.core.oal.DOFException)
to be called.domainListener
- The listener to remove.addDomainListener(org.opendof.core.oal.DOF.DomainListener)
public void addPermissionListener(DOF.PermissionListener permissionListener)
DOF.PermissionListener
to the DOF, which will be notified of permission grants and denials.permissionListener
- The listener to add.public void removePermissionListener(DOF.PermissionListener permissionListener)
DOF.PermissionListener
from the DOF. //TODO should it call a removed method?public DOF.Runtime getRuntime()
DOF.Runtime
, use its methods to retrieve specific information. For example,
the following line of code would retrieve a collection of all connections created by myDof:
Collection<DOFConnection> myConnections = myDof.getRuntime() .getConnections();See the methods of
DOF.Runtime
for information about all data that can be retrieved.public DOFAuthenticator createAuthenticator(DOFAuthenticator.Config authConfig)
DOFAuthenticator
that uses the specified configuration. The DOFAuthenticator class must be implemented on
nodes that need to perform as Authentication Servers. All secure domains must have at least one Authentication Server.
Each authenticator created must be destroyed when it is no longer needed. See DOFAuthenticator.destroy()
and destroy()
.authConfig
- An instance of DOFAuthenticator.Config
that represents a source of configuration parameters for the DOFAuthenticator.
Use DOFAuthenticator.Config.Builder
to create an instance of DOFAuthenticator.Config. This must not be null.public void setProtocolFactory(DOFProtocolFactory factory)
DOF.Config.Builder.setProtocolFactory(org.opendof.core.oal.DOFProtocolFactory)
method. Use this method to change the original value. See the Builder method for more information.factory
- The protocol factory. Must not be null.DOF.DefaultProtocolFactory
public void updateAuthenticator(DOFAuthenticator.Config authConfig) throws DOFSecurityException
authConfig
- The configuration to use to update the authenticator. This must not be null.DOFSecurityException
- If the domain identifier in the configuration does not match an existing authenticator.DOFAuthenticator.getState()
,
DOFAuthenticator.State.getDomainID()
public void cancelAllOperations()
DOF.Config.Builder.setSourceID(org.opendof.core.oal.DOFObjectID.Source)
should include this call in its startup routine to prevent
sourcing new operations that have the same identifier as operations sourced by a previous instance of the DOF. This helps a DOF
resynchronize its state with other nodes if it crashes and is brought back online.
This method should be called after establishing communication with other nodes but before sending any other operations.
It is recommended that after calling this method, you wait before sending other operations since delivery order is
not guaranteed.
This method does not cancel any existing local operations.
public void close(DOFConnection connection)
DOFConnection.disconnect()
disconnects the connection only when the number of references
to disconnect calls is equal to the number of references to DOFConnection.connect(int)
and DOFConnection.beginConnect(int)
calls.connection
- The connection to close. This must not be null.public void stop(DOFServer server)
DOFServer.stop()
stops the server only when the number of references
to stop calls is equal to the number of references to DOFServer.start(int)
and DOFServer.beginStart(int)
calls.server
- The server to stop. This must not be null.public java.util.Collection<DOFAuthenticator> getAuthenticators()
public DOFAuthenticator getAuthenticator(DOFObjectID.Domain domainID)
domainID
- The identifier for the domain of the authenticator.public java.util.List<DOFSystem> getSystems()
public void resolve(DOFCredentials credentials, int timeout) throws DOFErrorException
credentials
- The credentials to resolve. Must not be null.timeout
- The amount of time to wait for the credentials to be resolved. Must not be less than zero.DOFErrorException
- If the credentials failed to be resolved in the time given.public DOFDomain createDomain(DOFDomain.Config config)
DOFDomain
that uses the specified configuration. The DOFDomain can be used to monitor connectivity to a
secure domain's Authentication Server.
The internal library tracks references to duplicate domains, so this method can safely be called multiple times with the
same configuration without consuming extra resources. Multiple references to a DOFDomain can easily occur, because the library automatically creates
DOFDomain instances when you pass a DOFDomain.Config in the following methods:
DOFConnection.Config.Builder.addDomain(org.opendof.core.oal.DOFDomain.Config)
DOFConnection.Config.Builder.addDomains(org.opendof.core.oal.DOFDomain.Config...)
DOFConnection.addDomain(org.opendof.core.oal.DOFDomain.Config)
DOFServer.Config.Builder.addDomain(org.opendof.core.oal.DOFDomain.Config)
DOFServer.Config.Builder.addDomains(org.opendof.core.oal.DOFDomain.Config...)
DOFDomain.destroy()
and destroy()
.
config
- An instance of DOFDomain.Config
that represents a source of configuration parameters for the DOFDomain.
Use DOFDomain.Config.Builder
to create an instance of DOFDomain.Config. This must not be null.public java.util.List<DOFDomain> getDomains()
DOFDomain
public void addInterestListener(DOF.InterestListener listener)
DOF.InterestListener
to the DOF. Interest listeners are used by nodes (usually providers or proxies) that want
to monitor all interest requests.listener
- The interest listener to add. This must not be null.DOFSystem.ActivateInterestListener
,
DOFConnection.StreamRequestListener
public void removeInterestListener(DOF.InterestListener listener)
DOF.InterestListener
. When the listener is removed, this method causes
DOF.InterestListener.removed(org.opendof.core.oal.DOF, org.opendof.core.oal.DOFException)
to be called.listener
- The listener to remove. This must not be null.addInterestListener(org.opendof.core.oal.DOF.InterestListener)
public void addUncaughtExceptionListener(DOF.UncaughtExceptionListener listener)
DOF.UncaughtExceptionListener
to the DOF. Uncaught exception listeners are called when an application
callback throws an exception. This can be a RuntimeException
or an Error
.listener
- The uncaught exception listener to add. This must not be null.public void removeUncaughtExceptionListener(DOF.UncaughtExceptionListener listener)
DOF.UncaughtExceptionListener
. When the listener is removed, this method causes
DOF.UncaughtExceptionListener.removed(org.opendof.core.oal.DOF, org.opendof.core.oal.DOFException)
to be called.listener
- The listener to remove. This must not be null.addUncaughtExceptionListener(org.opendof.core.oal.DOF.UncaughtExceptionListener)