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}