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