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