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}