001/*
002 * Copyright 2007-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2014 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 */
021package com.unboundid.ldap.sdk;
022
023
024
025import com.unboundid.util.Extensible;
026import com.unboundid.util.ThreadSafety;
027import 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)
054public 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}