001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 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    }