mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Matthew Swift
25.33.2012 263d085885df024dca9250cc03c807912b0a7662
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/RequestContext.java
@@ -6,17 +6,16 @@
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
@@ -27,8 +26,6 @@
package org.forgerock.opendj.ldap;
/**
 * The context associated with a request currently being processed by a request
 * handler. A request context can be used to query state information about the
@@ -37,80 +34,73 @@
 * additional information, such as the associated schema, time-stamp
 * information, etc.
 */
public interface RequestContext
{
public interface RequestContext {
  /**
   * Registers the provided cancellation listener with this request context so
   * that it can be notified if a cancellation request is received and
   * processing of the request should be aborted if possible.
   * <p>
   * Requests may be cancelled as a result of an abandon request or a cancel
   * extended request sent from the client, or by the server itself (e.g. during
   * server shutdown).
   * <p>
   * This method provides a event notification mechanism which can be used by
   * asynchronous request handler implementations to detect cancellation of
   * requests.
   *
   * @param listener
   *          The listener which wants to be notified if a cancellation request
   *          is received and processing of the request should be aborted if
   *          possible.
   * @throws NullPointerException
   *           If the {@code listener} was {@code null}.
   * @see #checkIfCancelled
   */
  void addCancelRequestListener(CancelRequestListener listener);
    /**
     * Registers the provided cancellation listener with this request context so
     * that it can be notified if a cancellation request is received and
     * processing of the request should be aborted if possible.
     * <p>
     * Requests may be cancelled as a result of an abandon request or a cancel
     * extended request sent from the client, or by the server itself (e.g.
     * during server shutdown).
     * <p>
     * This method provides a event notification mechanism which can be used by
     * asynchronous request handler implementations to detect cancellation of
     * requests.
     *
     * @param listener
     *            The listener which wants to be notified if a cancellation
     *            request is received and processing of the request should be
     *            aborted if possible.
     * @throws NullPointerException
     *             If the {@code listener} was {@code null}.
     * @see #checkIfCancelled
     */
    void addCancelRequestListener(CancelRequestListener listener);
    /**
     * Throws {@link CancelledResultException} if a cancellation request has
     * been received and processing of the request should be aborted if
     * possible.
     * <p>
     * Requests may be cancelled as a result of an abandon request or a cancel
     * extended request sent from the client, or by the server itself (e.g.
     * during server shutdown).
     * <p>
     * This method provides a polling mechanism which can be used by synchronous
     * request handler implementations to detect cancellation of requests.
     *
     * @param signalTooLate
     *            {@code true} to signal that, after this method returns,
     *            processing of the request will have proceeded too far for it
     *            to be aborted by subsequent cancellation requests.
     * @throws CancelledResultException
     *             If a cancellation request has been received and processing of
     *             the request should be aborted if possible.
     * @see #addCancelRequestListener
     */
    void checkIfCancelled(boolean signalTooLate) throws CancelledResultException;
    /**
     * Returns the message ID of the request, if available. Protocols, such as
     * LDAP and internal connections, include a unique message ID with each
     * request which may be useful for logging and auditing.
     *
     * @return The message ID of the request, or {@code -1} if there is no
     *         message ID associated with the request.
     */
    int getMessageID();
  /**
   * Throws {@link CancelledResultException} if a cancellation request has been
   * received and processing of the request should be aborted if possible.
   * <p>
   * Requests may be cancelled as a result of an abandon request or a cancel
   * extended request sent from the client, or by the server itself (e.g. during
   * server shutdown).
   * <p>
   * This method provides a polling mechanism which can be used by synchronous
   * request handler implementations to detect cancellation of requests.
   *
   * @param signalTooLate
   *          {@code true} to signal that, after this method returns, processing
   *          of the request will have proceeded too far for it to be aborted by
   *          subsequent cancellation requests.
   * @throws CancelledResultException
   *           If a cancellation request has been received and processing of the
   *           request should be aborted if possible.
   * @see #addCancelRequestListener
   */
  void checkIfCancelled(boolean signalTooLate)
      throws CancelledResultException;
  /**
   * Returns the message ID of the request, if available. Protocols, such as
   * LDAP and internal connections, include a unique message ID with each
   * request which may be useful for logging and auditing.
   *
   * @return The message ID of the request, or {@code -1} if there is no message
   *         ID associated with the request.
   */
  int getMessageID();
  /**
   * Removes the provided cancellation listener from this request context so
   * that it will not be notified if a cancellation request has been received.
   *
   * @param listener
   *          The listener which no longer wants to be notified if a
   *          cancellation request has been received.
   * @throws NullPointerException
   *           If the {@code listener} was {@code null}.
   */
  void removeCancelRequestListener(CancelRequestListener listener);
    /**
     * Removes the provided cancellation listener from this request context so
     * that it will not be notified if a cancellation request has been received.
     *
     * @param listener
     *            The listener which no longer wants to be notified if a
     *            cancellation request has been received.
     * @throws NullPointerException
     *             If the {@code listener} was {@code null}.
     */
    void removeCancelRequestListener(CancelRequestListener listener);
}