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