org.opends.server.api
Class ConnectionHandler<T extends ConnectionHandlerCfg>

java.lang.Object
  extended by java.lang.Thread
      extended by org.opends.server.api.DirectoryThread
          extended by org.opends.server.api.ConnectionHandler<T>
Type Parameters:
T - The type of connection handler configuration handled by this connection handler implementation.
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
InternalConnectionHandler, JmxConnectionHandler, LDAPConnectionHandler, LDIFConnectionHandler

@PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=true,
           mayInvoke=false)
public abstract class ConnectionHandler<T extends ConnectionHandlerCfg>
extends DirectoryThread

This class defines the set of methods and structures that must be implemented by a Directory Server connection handler.


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
protected ConnectionHandler(java.lang.String threadName)
          Creates a new instance of this connection handler.
 
Method Summary
abstract  void finalizeConnectionHandler(Message finalizeReason, boolean closeConnections)
          Closes this connection handler so that it will no longer accept new client connections.
abstract  java.util.Collection<ClientConnection> getClientConnections()
          Retrieves the set of active client connections that have been established through this connection handler.
 ConnectionHandlerMonitor getConnectionHandlerMonitor()
          Retrieves the monitor instance for this connection handler.
abstract  java.lang.String getConnectionHandlerName()
          Retrieves a name that may be used to refer to this connection handler.
abstract  java.util.Collection<HostPort> getListeners()
          Retrieves information about the listener(s) that will be used to accept client connections.
abstract  java.lang.String getProtocol()
          Retrieves the name of the protocol used to communicate with clients.
abstract  void initializeConnectionHandler(T configuration)
          Initializes this connection handler provider based on the information in the provided connection handler configuration.
 boolean isConfigurationAcceptable(ConnectionHandlerCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the provided configuration is acceptable for this connection handler.
abstract  void run()
          Operates in a loop, accepting new connections and ensuring that requests on those connections are handled properly.
 void setConnectionHandlerMonitor(ConnectionHandlerMonitor monitor)
          Sets the monitor instance for this connection handler.
 java.lang.String toString()
          Retrieves a string representation of this connection handler.
abstract  void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this connection handler to the provided buffer.
 
Methods inherited from class org.opends.server.api.DirectoryThread
getAssociatedTask, getCreationStackTrace, getDebugProperties, getParentThread, setAssociatedTask
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ConnectionHandler

protected ConnectionHandler(java.lang.String threadName)
Creates a new instance of this connection handler. This must be called by all connection handlers, and all connection handlers must provide default constructors (i.e., those that do not take any arguments) that invoke this constructor.

Parameters:
threadName - The name to use for this thread.
Method Detail

finalizeConnectionHandler

public abstract void finalizeConnectionHandler(Message finalizeReason,
                                               boolean closeConnections)
Closes this connection handler so that it will no longer accept new client connections. It may or may not disconnect existing client connections based on the provided flag. Note, however, that some connection handler implementations may not have any way to continue processing requests from existing connections, in which case they should always be closed regardless of the value of the closeConnections flag.

Parameters:
finalizeReason - The reason that this connection handler should be finalized.
closeConnections - Indicates whether any established client connections associated with the connection handler should also be closed.

getConnectionHandlerName

public abstract java.lang.String getConnectionHandlerName()
Retrieves a name that may be used to refer to this connection handler. Every connection handler instance (even handlers of the same type) must have a unique name.

Returns:
A unique name that may be used to refer to this connection handler.

getProtocol

public abstract java.lang.String getProtocol()
Retrieves the name of the protocol used to communicate with clients. It should take into account any special naming that may be needed to express any security mechanisms or other constraints in place (e.g., "LDAPS" for LDAP over SSL).

Returns:
The name of the protocol used to communicate with clients.

getListeners

public abstract java.util.Collection<HostPort> getListeners()
Retrieves information about the listener(s) that will be used to accept client connections.

Returns:
Information about the listener(s) that will be used to accept client connections, or an empty list if this connection handler does not accept connections from network clients.

getClientConnections

public abstract java.util.Collection<ClientConnection> getClientConnections()
Retrieves the set of active client connections that have been established through this connection handler.

Returns:
The set of active client connections that have been established through this connection handler.

initializeConnectionHandler

public abstract void initializeConnectionHandler(T configuration)
                                          throws ConfigException,
                                                 InitializationException
Initializes this connection handler provider based on the information in the provided connection handler configuration.

Parameters:
configuration - The connection handler configuration that contains the information to use to initialize this connection handler.
Throws:
ConfigException - If an unrecoverable problem arises in the process of performing the initialization as a result of the server configuration.
InitializationException - If a problem occurs during initialization that is not related to the server configuration.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(ConnectionHandlerCfg configuration,
                                         java.util.List<Message> unacceptableReasons)
Indicates whether the provided configuration is acceptable for this connection handler. It should be possible to call this method on an uninitialized connection handler instance in order to determine whether the connection handler would be able to use the provided configuration.

Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.

Parameters:
configuration - The connection handler configuration for which to make the determination.
unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
Returns:
true if the provided configuration is acceptable for this connection handler, or false if not.

run

public abstract void run()
Operates in a loop, accepting new connections and ensuring that requests on those connections are handled properly.

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

getConnectionHandlerMonitor

public final ConnectionHandlerMonitor getConnectionHandlerMonitor()
Retrieves the monitor instance for this connection handler.

Returns:
The monitor instance for this connection handler, or null if none has been provided.

setConnectionHandlerMonitor

public final void setConnectionHandlerMonitor(ConnectionHandlerMonitor monitor)
Sets the monitor instance for this connection handler.

Parameters:
monitor - The monitor instance for this connection handler.

toString

public java.lang.String toString()
Retrieves a string representation of this connection handler.

Overrides:
toString in class java.lang.Thread
Returns:
A string representation of this connection handler.

toString

public abstract void toString(java.lang.StringBuilder buffer)
Appends a string representation of this connection handler to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.