org.forgerock.opendj.ldap.spi

Class ConnectionState

java.lang.Object

org.forgerock.opendj.ldap.spi.ConnectionState

public final class ConnectionState
extends Object

This class can be used to manage the internal state of a connection, ensuring valid and atomic state transitions, as well as connection event listener notification. There are 4 states:

• connection is valid (isClosed()=false, isFailed()=false): can fail or be closed
• connection has failed due to an error (isClosed()=false, isFailed()=true): can be closed
• connection has been closed by the application (isClosed()=true, isFailed()=false): terminal state
• connection has failed due to an error and has been closed by the application (isClosed()=true, isFailed()=true): terminal state

All methods are synchronized and container classes may also synchronize on the state where needed. The state transition methods, ConnectionState.notifyConnectionClosed() and ConnectionState.notifyConnectionError(boolean, LdapException), correspond to methods in the ConnectionEventListener interface except that they return a boolean indicating whether the transition was successful or not.

Constructor Summary

Constructors

Constructor and Description
ConnectionState() Creates a new connection state which is initially valid.

Method Summary

Modifier and Type	Method and Description
void	addConnectionEventListener(ConnectionEventListener listener) Registers the provided connection event listener so that it will be notified when this connection is closed by the application, receives an unsolicited notification, or experiences a fatal error.
LdapException	getConnectionError() Returns the error that caused the connection to fail, or null if the connection has not failed.
boolean	isClosed() Indicates whether this connection has been explicitly closed by calling close.
boolean	isValid() Returns true if the associated connection has not been closed and no fatal errors have been detected.
boolean	notifyConnectionClosed() Attempts to transition this connection state to closed and invokes event listeners if successful.
boolean	notifyConnectionError(boolean isDisconnectNotification, LdapException error) Attempts to transition this connection state to error and invokes event listeners if successful.
void	notifyUnsolicitedNotification(ExtendedResult notification) Notifies event listeners of the provided unsolicited notification if the state is valid.
void	removeConnectionEventListener(ConnectionEventListener listener) Removes the provided connection event listener from this connection so that it will no longer be notified when this connection is closed by the application, receives an unsolicited notification, or experiences a fatal error.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConnectionState

public ConnectionState()

Creates a new connection state which is initially valid.

Method Detail

addConnectionEventListener

public void addConnectionEventListener(ConnectionEventListener listener)

Registers the provided connection event listener so that it will be notified when this connection is closed by the application, receives an unsolicited notification, or experiences a fatal error.

Parameters:

listener - The listener which wants to be notified when events occur on this connection.

Throws:

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the listener was null.

getConnectionError

public LdapException getConnectionError()

Returns the error that caused the connection to fail, or null if the connection has not failed.

Returns:

The error that caused the connection to fail, or null if the connection has not failed.

isClosed

public boolean isClosed()

Indicates whether this connection has been explicitly closed by calling close. This method will not return true if a fatal error has occurred on the connection unless close has been called.

Returns:

true if this connection has been explicitly closed by calling close, or false otherwise.

isValid

public boolean isValid()

Returns true if the associated connection has not been closed and no fatal errors have been detected.

Returns:

true if this connection is valid, false otherwise.

notifyConnectionClosed

public boolean notifyConnectionClosed()

Attempts to transition this connection state to closed and invokes event listeners if successful.

Returns:

true if the state changed to closed, or false if the state was already closed.

See Also:

ConnectionEventListener.handleConnectionClosed()

notifyConnectionError

public boolean notifyConnectionError(boolean isDisconnectNotification,
                                     LdapException error)

Attempts to transition this connection state to error and invokes event listeners if successful.

Parameters:

isDisconnectNotification - true if the error was triggered by a disconnect notification sent by the server, otherwise false.

error - The exception that is about to be thrown to the application.

Returns:

true if the state changed to error, or false if the state was already error or closed.

See Also:

ConnectionEventListener.handleConnectionError(boolean, LdapException)

notifyUnsolicitedNotification

public void notifyUnsolicitedNotification(ExtendedResult notification)

Notifies event listeners of the provided unsolicited notification if the state is valid.

Parameters:

notification - The unsolicited notification.

See Also:

ConnectionEventListener.handleUnsolicitedNotification(ExtendedResult)

removeConnectionEventListener

public void removeConnectionEventListener(ConnectionEventListener listener)

Removes the provided connection event listener from this connection so that it will no longer be notified when this connection is closed by the application, receives an unsolicited notification, or experiences a fatal error.

Parameters:

listener - The listener which no longer wants to be notified when events occur on this connection.

Throws:

NullPointerException - If the listener was null.