001 /*
002 * Copyright 2007-2013 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2008-2013 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021 package com.unboundid.ldap.sdk;
022
023
024
025 import com.unboundid.util.Extensible;
026 import com.unboundid.util.ThreadSafety;
027 import com.unboundid.util.ThreadSafetyLevel;
028
029
030
031 /**
032 * This interface defines an API that may be implemented by a class that should
033 * be notified whenever an LDAP connection is closed for any reason. (whether
034 * the connection was closed at the request of the client via a method like
035 * {@link LDAPConnection#close}, terminated by the server, or closed due to an
036 * internal error). This interface may be used by applications to attempt to
037 * automatically re-establish connections as soon as they are terminated,
038 * potentially falling over to another server.
039 * <BR><BR>
040 * It is acceptable to attempt to re-connect the connection that has been
041 * disconnected, but in general that should only be attempted if
042 * {@link DisconnectType#isExpected(DisconnectType)} returns {@code true} for
043 * the provided {@code disconnectType} value. The disconnect handler will be
044 * temporarily de-registered from the connection so that closing the connection
045 * in the course of processing the {@link DisconnectHandler#handleDisconnect}
046 * method will not cause it to be recursively re-invoked.
047 * <BR><BR>
048 * Implementations of this interface should be threadsafe to ensure that
049 * multiple connections will be able to safely use the same
050 * {@code DisconnectHandler} instance.
051 */
052 @Extensible()
053 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
054 public interface DisconnectHandler
055 {
056 /**
057 * Performs any processing that may be necessary in response to the closure
058 * of the provided connection.
059 *
060 * @param connection The connection that has been closed.
061 * @param host The address of the server to which the connection
062 * had been established.
063 * @param port The port of the server to which the connection had
064 * been established.
065 * @param disconnectType The disconnect type, which provides general
066 * information about the nature of the disconnect.
067 * @param message A message that may be associated with the
068 * disconnect. It may be {@code null} if no message
069 * is available.
070 * @param cause A {@code Throwable} that was caught and triggered
071 * the disconnect. It may be {@code null} if the
072 * disconnect was not triggered by a client-side
073 * exception or error.
074 */
075 void handleDisconnect(final LDAPConnection connection, final String host,
076 final int port, final DisconnectType disconnectType,
077 final String message, final Throwable cause);
078 }