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 2010 Sun Microsystems, Inc.
015 * Portions copyright 2012 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap;
019
020import org.forgerock.opendj.ldap.requests.AbandonRequest;
021import org.forgerock.opendj.ldap.requests.UnbindRequest;
022
023/**
024 * A handler interface for interacting with client connections. A
025 * {@code ServerConnection} is associated with a client connection when the
026 * {@link ServerConnectionFactory#handleAccept(Object) handleAccept} method is
027 * invoked against a {@code ServerConnectionFactory}.
028 * <p>
029 * Implementations are responsible for handling connection life-cycle as well as
030 * request life-cycle. In particular, a {@code ServerConnection} is responsible
031 * for processing abandon and unbind requests, as well as extended operations
032 * such as {@code StartTLS} and {@code Cancel} operations.
033 *
034 * @param <C>
035 *            The type of request context.
036 * @see ServerConnectionFactory
037 */
038public interface ServerConnection<C> extends RequestHandler<C> {
039
040    /**
041     * Invoked when an abandon request is received from a client.
042     *
043     * @param requestContext
044     *            The request context.
045     * @param request
046     *            The abandon request.
047     * @throws UnsupportedOperationException
048     *             If this server connection does not handle abandon requests.
049     */
050    void handleAbandon(C requestContext, AbandonRequest request);
051
052    /**
053     * Invoked when the client closes the connection, possibly using an unbind
054     * request.
055     *
056     * @param requestContext
057     *            The request context which should be ignored if there was no
058     *            associated unbind request.
059     * @param request
060     *            The unbind request, which may be {@code null} if one was not
061     *            sent before the connection was closed.
062     */
063    void handleConnectionClosed(C requestContext, UnbindRequest request);
064
065    /**
066     * Invoked when the server disconnects the client connection, possibly using
067     * a disconnect notification.
068     *
069     * @param resultCode
070     *            The result code which was included with the disconnect
071     *            notification, or {@code null} if no disconnect notification
072     *            was sent.
073     * @param message
074     *            The diagnostic message, which may be empty or {@code null}
075     *            indicating that none was provided.
076     */
077    void handleConnectionDisconnected(ResultCode resultCode, String message);
078
079    /**
080     * Invoked when an error occurs on the connection and it is no longer
081     * usable.
082     *
083     * @param error
084     *            The exception describing the problem that occurred.
085     */
086    void handleConnectionError(Throwable error);
087
088}