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 2011-2012 ForgeRock AS
025 */
026
027package org.forgerock.opendj.ldap;
028
029/**
030 * The context associated with a request currently being processed by a request
031 * handler. A request context can be used to query state information about the
032 * request, such as whether or not it has been cancelled, as well as registering
033 * to be notified if the request has been cancelled. Implementations may provide
034 * additional information, such as the associated schema, time-stamp
035 * information, etc.
036 */
037public interface RequestContext {
038
039    /**
040     * Registers the provided cancellation listener with this request context so
041     * that it can be notified if a cancellation request is received and
042     * processing of the request should be aborted if possible.
043     * <p>
044     * Requests may be cancelled as a result of an abandon request or a cancel
045     * extended request sent from the client, or by the server itself (e.g.
046     * during server shutdown).
047     * <p>
048     * This method provides a event notification mechanism which can be used by
049     * asynchronous request handler implementations to detect cancellation of
050     * requests.
051     *
052     * @param listener
053     *            The listener which wants to be notified if a cancellation
054     *            request is received and processing of the request should be
055     *            aborted if possible.
056     * @throws NullPointerException
057     *             If the {@code listener} was {@code null}.
058     * @see #checkIfCancelled
059     */
060    void addCancelRequestListener(CancelRequestListener listener);
061
062    /**
063     * Throws {@link CancelledResultException} if a cancellation request has
064     * been received and processing of the request should be aborted if
065     * possible.
066     * <p>
067     * Requests may be cancelled as a result of an abandon request or a cancel
068     * extended request sent from the client, or by the server itself (e.g.
069     * during server shutdown).
070     * <p>
071     * This method provides a polling mechanism which can be used by synchronous
072     * request handler implementations to detect cancellation of requests.
073     *
074     * @param signalTooLate
075     *            {@code true} to signal that, after this method returns,
076     *            processing of the request will have proceeded too far for it
077     *            to be aborted by subsequent cancellation requests.
078     * @throws CancelledResultException
079     *             If a cancellation request has been received and processing of
080     *             the request should be aborted if possible.
081     * @see #addCancelRequestListener
082     */
083    void checkIfCancelled(boolean signalTooLate) throws CancelledResultException;
084
085    /**
086     * Returns the message ID of the request, if available. Protocols, such as
087     * LDAP and internal connections, include a unique message ID with each
088     * request which may be useful for logging and auditing.
089     *
090     * @return The message ID of the request, or {@code -1} if there is no
091     *         message ID associated with the request.
092     */
093    int getMessageID();
094
095    /**
096     * Removes the provided cancellation listener from this request context so
097     * that it will not be notified if a cancellation request has been received.
098     *
099     * @param listener
100     *            The listener which no longer wants to be notified if a
101     *            cancellation request has been received.
102     * @throws NullPointerException
103     *             If the {@code listener} was {@code null}.
104     */
105    void removeCancelRequestListener(CancelRequestListener listener);
106}