/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
|
* or http://forgerock.org/license/CDDLv1.0.html.
|
* See the License for the specific language governing permissions
|
* and limitations under the License.
|
*
|
* When distributing Covered Code, include this CDDL HEADER in each
|
* file and include the License file at legal-notices/CDDLv1_0.txt.
|
* If applicable, add the following below this CDDL HEADER, with the
|
* fields enclosed by brackets "[]" replaced with your own identifying
|
* information:
|
* Portions Copyright [yyyy] [name of copyright owner]
|
*
|
* CDDL HEADER END
|
*
|
*
|
* Copyright 2013 ForgeRock AS.
|
*/
|
package com.forgerock.opendj.ldap;
|
|
import java.util.LinkedList;
|
import java.util.List;
|
|
import org.forgerock.opendj.ldap.ConnectionEventListener;
|
import org.forgerock.opendj.ldap.ErrorResultException;
|
import org.forgerock.opendj.ldap.responses.ExtendedResult;
|
|
/**
|
* 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:
|
* <ul>
|
* <li>connection is <b>valid</b> (isClosed()=false, isFailed()=false): can fail
|
* or be closed
|
* <li>connection has failed due to an <b>error</b> (isClosed()=false,
|
* isFailed()=true): can be closed
|
* <li>connection has been <b>closed</b> by the application (isClosed()=true,
|
* isFailed()=false): terminal state
|
* <li>connection has failed due to an <b>error</b> and has been <b>closed</b>
|
* by the application (isClosed()=true, isFailed()=true): terminal state
|
* </ul>
|
* All methods are synchronized and container classes may also synchronize on
|
* the state where needed. The state transition methods,
|
* {@link #notifyConnectionClosed()} and
|
* {@link #notifyConnectionError(boolean, ErrorResultException)}, correspond to
|
* methods in the {@link ConnectionEventListener} interface except that they
|
* return a boolean indicating whether the transition was successful or not.
|
*/
|
public final class ConnectionState {
|
/*
|
* FIXME: The synchronization in this class has been kept simple for now.
|
* However, ideally we should notify listeners without synchronizing on the
|
* state in case a listener takes a long time to complete.
|
*/
|
|
/*
|
* FIXME: This class should be used by connection pool and ldap connection
|
* implementations as well.
|
*/
|
|
/**
|
* Use the State design pattern to manage state transitions.
|
*/
|
private enum State {
|
|
/**
|
* Connection has not encountered an error nor has it been closed
|
* (initial state).
|
*/
|
VALID() {
|
@Override
|
void addConnectionEventListener(final ConnectionState cs,
|
final ConnectionEventListener listener) {
|
cs.listeners.add(listener);
|
}
|
|
@Override
|
boolean isClosed() {
|
return false;
|
}
|
|
@Override
|
boolean isFailed() {
|
return false;
|
}
|
|
@Override
|
boolean isValid() {
|
return true;
|
}
|
|
@Override
|
boolean notifyConnectionClosed(final ConnectionState cs) {
|
for (final ConnectionEventListener listener : cs.listeners) {
|
listener.handleConnectionClosed();
|
}
|
cs.state = CLOSED;
|
return true;
|
}
|
|
@Override
|
boolean notifyConnectionError(final ConnectionState cs,
|
final boolean isDisconnectNotification, final ErrorResultException error) {
|
// Transition from valid to error state.
|
cs.failedDueToDisconnect = isDisconnectNotification;
|
cs.connectionError = error;
|
for (final ConnectionEventListener listener : cs.listeners) {
|
// Use the reason provided in the disconnect notification.
|
listener.handleConnectionError(isDisconnectNotification, error);
|
}
|
cs.state = ERROR;
|
return true;
|
}
|
|
@Override
|
void notifyUnsolicitedNotification(final ConnectionState cs,
|
final ExtendedResult notification) {
|
for (final ConnectionEventListener listener : cs.listeners) {
|
listener.handleUnsolicitedNotification(notification);
|
}
|
}
|
},
|
|
/**
|
* Connection has encountered an error, but has not been closed.
|
*/
|
ERROR() {
|
@Override
|
void addConnectionEventListener(final ConnectionState cs,
|
final ConnectionEventListener listener) {
|
listener.handleConnectionError(cs.failedDueToDisconnect, cs.connectionError);
|
cs.listeners.add(listener);
|
}
|
|
@Override
|
boolean isClosed() {
|
return false;
|
}
|
|
@Override
|
boolean isFailed() {
|
return true;
|
}
|
|
@Override
|
boolean isValid() {
|
return false;
|
}
|
|
@Override
|
boolean notifyConnectionClosed(final ConnectionState cs) {
|
for (final ConnectionEventListener listener : cs.listeners) {
|
listener.handleConnectionClosed();
|
}
|
cs.state = ERROR_CLOSED;
|
return true;
|
}
|
},
|
|
/**
|
* Connection has been closed (terminal state).
|
*/
|
CLOSED() {
|
@Override
|
void addConnectionEventListener(final ConnectionState cs,
|
final ConnectionEventListener listener) {
|
listener.handleConnectionClosed();
|
}
|
|
@Override
|
boolean isClosed() {
|
return true;
|
}
|
|
@Override
|
boolean isFailed() {
|
return false;
|
}
|
|
@Override
|
boolean isValid() {
|
return false;
|
}
|
},
|
|
/**
|
* Connection has encountered an error and has been closed (terminal
|
* state).
|
*/
|
ERROR_CLOSED() {
|
@Override
|
void addConnectionEventListener(final ConnectionState cs,
|
final ConnectionEventListener listener) {
|
listener.handleConnectionError(cs.failedDueToDisconnect, cs.connectionError);
|
listener.handleConnectionClosed();
|
}
|
|
@Override
|
boolean isClosed() {
|
return true;
|
}
|
|
@Override
|
boolean isFailed() {
|
return true;
|
}
|
|
@Override
|
boolean isValid() {
|
return false;
|
}
|
};
|
|
abstract void addConnectionEventListener(ConnectionState cs,
|
final ConnectionEventListener listener);
|
|
abstract boolean isClosed();
|
|
abstract boolean isFailed();
|
|
abstract boolean isValid();
|
|
boolean notifyConnectionClosed(final ConnectionState cs) {
|
return false;
|
}
|
|
boolean notifyConnectionError(final ConnectionState cs,
|
final boolean isDisconnectNotification, final ErrorResultException error) {
|
return false;
|
}
|
|
void notifyUnsolicitedNotification(final ConnectionState cs,
|
final ExtendedResult notification) {
|
// Do nothing by default.
|
}
|
}
|
|
/**
|
* Non-{@code null} once the connection has failed due to a connection
|
* error. Volatile so that it can be read without synchronization.
|
*/
|
private volatile ErrorResultException connectionError = null;
|
|
/**
|
* {@code true} if the connection has failed due to a disconnect
|
* notification.
|
*/
|
private boolean failedDueToDisconnect = false;
|
|
/**
|
* Registered event listeners.
|
*/
|
private final List<ConnectionEventListener> listeners =
|
new LinkedList<ConnectionEventListener>();
|
|
/**
|
* Internal state implementation.
|
*/
|
private volatile State state = State.VALID;
|
|
/**
|
* Creates a new connection state which is initially valid.
|
*/
|
public ConnectionState() {
|
// Nothing to do.
|
}
|
|
/**
|
* 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.
|
*
|
* @param 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
|
* {@code isClosed() == true}.
|
* @throws NullPointerException
|
* If the {@code listener} was {@code null}.
|
*/
|
public synchronized void addConnectionEventListener(final ConnectionEventListener listener) {
|
state.addConnectionEventListener(this, listener);
|
}
|
|
/**
|
* Returns the error that caused the connection to fail, or {@code null} if
|
* the connection has not failed.
|
*
|
* @return The error that caused the connection to fail, or {@code null} if
|
* the connection has not failed.
|
*/
|
public ErrorResultException getConnectionError() {
|
return connectionError;
|
}
|
|
/**
|
* Indicates whether or not this connection has been explicitly closed by
|
* calling {@code close}. This method will not return {@code true} if a
|
* fatal error has occurred on the connection unless {@code close} has been
|
* called.
|
*
|
* @return {@code true} if this connection has been explicitly closed by
|
* calling {@code close}, or {@code false} otherwise.
|
*/
|
public boolean isClosed() {
|
return state.isClosed();
|
}
|
|
/**
|
* Returns {@code true} if the associated connection has not been closed and
|
* no fatal errors have been detected.
|
*
|
* @return {@code true} if this connection is valid, {@code false}
|
* otherwise.
|
*/
|
public boolean isValid() {
|
return state.isValid();
|
}
|
|
/**
|
* Attempts to transition this connection state to closed and invokes event
|
* listeners if successful.
|
*
|
* @return {@code true} if the state changed to closed, or {@code false} if
|
* the state was already closed.
|
* @see ConnectionEventListener#handleConnectionClosed()
|
*/
|
public synchronized boolean notifyConnectionClosed() {
|
return state.notifyConnectionClosed(this);
|
}
|
|
/**
|
* Attempts to transition this connection state to error and invokes event
|
* listeners if successful.
|
*
|
* @param isDisconnectNotification
|
* {@code true} if the error was triggered by a disconnect
|
* notification sent by the server, otherwise {@code false}.
|
* @param error
|
* The exception that is about to be thrown to the application.
|
* @return {@code true} if the state changed to error, or {@code false} if
|
* the state was already error or closed.
|
* @see ConnectionEventListener#handleConnectionError(boolean,
|
* ErrorResultException)
|
*/
|
public synchronized boolean notifyConnectionError(final boolean isDisconnectNotification,
|
final ErrorResultException error) {
|
return state.notifyConnectionError(this, isDisconnectNotification, error);
|
}
|
|
/**
|
* Notifies event listeners of the provided unsolicited notification if the
|
* state is valid.
|
*
|
* @param notification
|
* The unsolicited notification.
|
* @see ConnectionEventListener#handleUnsolicitedNotification(ExtendedResult)
|
*/
|
public synchronized void notifyUnsolicitedNotification(final ExtendedResult notification) {
|
state.notifyUnsolicitedNotification(this, notification);
|
}
|
|
/**
|
* 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.
|
*
|
* @param listener
|
* The listener which no longer wants to be notified when events
|
* occur on this connection.
|
* @throws NullPointerException
|
* If the {@code listener} was {@code null}.
|
*/
|
public synchronized void removeConnectionEventListener(final ConnectionEventListener listener) {
|
listeners.remove(listener);
|
}
|
|
}
|
