001    /*
002     * Copyright 2007-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 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    
026    
027    
028    /**
029     * This interface defines an API that may be implemented by a class that should
030     * be notified whenever an LDAP connection is closed for any reason. (whether
031     * the connection was closed at the request of the client via a method like
032     * {@code LDAPConnection#close}, terminated by the server, or closed due to an
033     * internal error).  This interface may be used by applications to attempt to
034     * automatically re-establish connections as soon as they are terminated,
035     * potentially falling over to another server.
036     * <BR><BR>
037     * It is acceptable to attempt to re-connect the connection that has been
038     * disconnected, but in general that should only be attempted if
039     * {@code DisconnectType#isExpected(DisconnectType)} returns {@code true} for
040     * the provided {@code disconnectType} value.  The disconnect handler will be
041     * temporarily de-registered from the connection so that closing the connection
042     * in the course of processing the {@code DisconnectHandler#handleDisconnect}
043     * method will not cause it to be recursively re-invoked.
044     * <BR><BR>
045     * Implementations of this interface should be threadsafe to ensure that
046     * multiple connections will be able to safely use the same
047     * {@code DisconnectHandler} instance.
048     */
049    public interface DisconnectHandler
050    {
051      /**
052       * Performs any processing that may be necessary in response to the closure
053       * of the provided connection.
054       *
055       * @param  connection      The connection that has been closed.
056       * @param  host            The address of the server to which the connection
057       *                         had been established.
058       * @param  port            The port of the server to which the connection had
059       *                         been established.
060       * @param  disconnectType  The disconnect type, which provides general
061       *                         information about the nature of the disconnect.
062       * @param  message         A message that may be associated with the
063       *                         disconnect.  It may be {@code null} if no message
064       *                         is available.
065       * @param  cause           A {@code Throwable} that was caught and triggered
066       *                         the disconnect.  It may be {@code null} if the
067       *                         disconnect was not triggered by a client-side
068       *                         exception or error.
069       */
070      void handleDisconnect(final LDAPConnection connection, final String host,
071                            final int port, final DisconnectType disconnectType,
072                            final String message, final Throwable cause);
073    }