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
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2010-2014 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.common.types;
028
029
030
031 import com.unboundid.directory.sdk.common.operation.Request;
032 import com.unboundid.ldap.sdk.LDAPException;
033 import com.unboundid.util.NotExtensible;
034 import com.unboundid.util.ThreadSafety;
035 import com.unboundid.util.ThreadSafetyLevel;
036
037
038
039 /**
040 * This interface defines a set of methods that may be used to obtain
041 * information about an operation being processed by the server.
042 */
043 @NotExtensible()
044 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
045 public interface OperationContext
046 {
047 /**
048 * Retrieves the identifier that has been assigned to the associated client
049 * connection.
050 *
051 * @return The identifier that has been assigned to the associated client
052 * connection.
053 */
054 long getConnectionID();
055
056
057
058 /**
059 * Retrieves the identifier that has been assigned to this operation for the
060 * associated client connection.
061 *
062 * @return The identifier that has been assigned to this operation for the
063 * associated client connection.
064 */
065 long getOperationID();
066
067
068
069
070 /**
071 * Retrieves the message ID for this operation from the client request.
072 *
073 * @return The message ID for this operation from the client request.
074 */
075 int getMessageID();
076
077
078
079 /**
080 * Retrieves the operation type for this operation.
081 *
082 * @return The operation type for this operation.
083 */
084 OperationType getOperationType();
085
086
087
088 /**
089 * Retrieves the request for the associated operation. The caller should not
090 * make any attempt to alter the request that is returned.
091 *
092 * @return The request for the associated operation.
093 */
094 Request getRequest();
095
096
097
098 /**
099 * Retrieves information about the server in which this operation is being
100 * processed.
101 *
102 * @return Information about the server in which this operation is being
103 * processed.
104 */
105 ServerContext getServerContext();
106
107
108
109 /**
110 * Indicates whether this operation was initiated within the server rather
111 * than by an external client.
112 *
113 * @return {@code true} if this operation was initiated within the server, or
114 * {@code false} if it was requested by an external client.
115 */
116 boolean isInternalOperation();
117
118
119
120 /**
121 * Indicates whether this is an administrative operation. An operation is
122 * considered administrative if the
123 * {@code StartAdministrativeSessionExtendedRequest} extended request was
124 * used on the connection, or the
125 * {@code AdministrativeOperationRequestControl} request control was used on
126 * the operation.
127 *
128 * @return {@code true} if this operation is an administrative operation.
129 */
130 boolean isAdministrativeOperation();
131
132
133
134 /**
135 * Indicates whether this operation was initiated via replication rather than
136 * within the local server.
137 *
138 * @return {@code true} if this operation was initiated via replication, or
139 * {@code false} if it was initiated locally within this server.
140 */
141 boolean isReplicationOperation();
142
143
144
145 /**
146 * Retrieves the DN of the user as whom the request is authorized. Note that
147 * this may change over the course of processing the operation (e.g., if the
148 * request includes a proxied authorization or intermediate client control).
149 *
150 * @return The DN of the user as whom the request is authorized. It may be
151 * an empty string if the operation is to be authorized as an
152 * unauthenticated user.
153 */
154 String getAuthorizationDN();
155
156
157
158 /**
159 * Retrieves the object attached to the associated operation with the given
160 * name.
161 *
162 * @param name The case-sensitive name of the attachment to retrieve. It
163 * must not be {@code null}.
164 *
165 * @return The requested attachment, or {@code null} if the operation does
166 * not have an attachment with the provided name.
167 */
168 Object getAttachment(final String name);
169
170
171
172 /**
173 * Sets an attachment for the associated operation.
174 *
175 * @param name The name of the attachment to set. It must not be
176 * {@code null}.
177 * @param value The value to set for the attachment. It may be {@code null}
178 * if any existing attachment with the specified name should be
179 * removed.
180 */
181 void setAttachment(final String name, final Object value);
182
183
184
185 /**
186 * Retrieves information about the client that requested this operation.
187 *
188 * @return Information about the client that requested this operation.
189 */
190 ClientContext getClientContext();
191
192
193
194 /**
195 * Indicates whether this operation was requested over a secure connection.
196 * If the request included the intermediate client control, then its value
197 * will also be used in determining whether communication with downstream
198 * clients is also secure.
199 *
200 * @return {@code true} if this operation was requested over a secure
201 * connection, or {@code false} if not.
202 */
203 boolean isSecure();
204
205
206
207 /**
208 * Retrieves an internal connection that is authenticated as the same user
209 * that requested this operation and may be subject to access control.
210 * <BR><BR>
211 * Note that the returned connection will use the client connection policy
212 * defined as the default policy for internal operations. If you wish to use
213 * the client connection policy associated with the connection on which this
214 * operation was requested, use the
215 * {@link #getInternalUserConnection(boolean)} method.
216 *
217 * @return An internal connection that is authenticated as the same user that
218 * requested this operation.
219 *
220 * @throws LDAPException If a problem occurs while attempting to obtain or
221 * authenticate the connection.
222 */
223 InternalConnection getInternalUserConnection()
224 throws LDAPException;
225
226
227
228 /**
229 * Retrieves an internal connection that is authenticated as the same user
230 * that requested this operation and may be subject to access control. It may
231 * optionally use the client connection policy from the associated client
232 * connection.
233 *
234 * @param usePolicyFromConnection If {@code true}, the internal connection
235 * will use the same client connection policy
236 * as the associated client connection. If
237 * {@code false}, the internal connection
238 * will use the server's default client
239 * connection policy for internal
240 * connections.
241 *
242 * @return An internal connection that is authenticated as the same user that
243 * requested this operation.
244 *
245 * @throws LDAPException If a problem occurs while attempting to obtain or
246 * authenticate the connection.
247 */
248 InternalConnection getInternalUserConnection(
249 final boolean usePolicyFromConnection)
250 throws LDAPException;
251
252
253
254 /**
255 * Retrieves an internal connection that is authenticated as a root user
256 * that is not subject to access control.
257 * <BR><BR>
258 * Note that the returned connection will use the client connection policy
259 * defined as the default policy for internal operations. If you wish to use
260 * the client connection policy associated with the connection on which this
261 * operation was requested, use the
262 * {@link #getInternalRootConnection(boolean)} method.
263 *
264 * @return An internal connection that is authenticated as a root user.
265 */
266 InternalConnection getInternalRootConnection();
267
268
269
270 /**
271 * Retrieves an internal connection that is authenticated as a root user
272 * that is not subject to access control. It may optionally use the client
273 * connection policy from the associated client connection.
274 *
275 * @param usePolicyFromConnection If {@code true}, the internal connection
276 * will use the same client connection policy
277 * as the associated client connection. If
278 * {@code false}, the internal connection
279 * will use the server's default client
280 * connection policy for internal
281 * connections.
282 *
283 * @return An internal connection that is authenticated as a root user.
284 */
285 InternalConnection getInternalRootConnection(
286 final boolean usePolicyFromConnection);
287
288
289
290 /**
291 * Retrieves a string representation of this operation.
292 *
293 * @return A string representation of this operation.
294 */
295 String toString();
296 }