001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009-2010 Sun Microsystems, Inc.
025 *      Portions Copyright 2014 ForgeRock AS
026 */
027
028package org.forgerock.opendj.ldap;
029
030import java.util.EventListener;
031
032import org.forgerock.opendj.ldap.responses.ExtendedResult;
033
034/**
035 * An object that registers to be notified when a connection is closed by the
036 * application, receives an unsolicited notification, or experiences a fatal
037 * error.
038 */
039public interface ConnectionEventListener extends EventListener {
040    /**
041     * Notifies this connection event listener that the application has called
042     * {@code close} on the connection. The connection event listener will be
043     * notified immediately after the application calls the {@code close} method
044     * on the associated connection.
045     */
046    void handleConnectionClosed();
047
048    /**
049     * Notifies this connection event listener that a fatal error has occurred
050     * and the connection can no longer be used - the server has crashed, for
051     * example. The connection implementation makes this notification just
052     * before it throws the provided {@link LdapException} to the
053     * application.
054     * <p>
055     * <b>Note:</b> disconnect notifications are treated as fatal connection
056     * errors and are handled by this method. In this case
057     * {@code isDisconnectNotification} will be {@code true} and {@code error}
058     * will contain the result code and any diagnostic information contained in
059     * the notification message.
060     *
061     * @param isDisconnectNotification
062     *            {@code true} if the error was triggered by a disconnect
063     *            notification sent by the server, otherwise {@code false}.
064     * @param error
065     *            The exception that is about to be thrown to the application.
066     */
067    void handleConnectionError(boolean isDisconnectNotification, LdapException error);
068
069    /**
070     * Notifies this connection event listener that the connection has just
071     * received the provided unsolicited notification from the server.
072     * <p>
073     * <b>Note:</b> disconnect notifications are treated as fatal connection
074     * errors and are handled by the {@link #handleConnectionError} method.
075     *
076     * @param notification
077     *            The unsolicited notification.
078     */
079    void handleUnsolicitedNotification(ExtendedResult notification);
080}