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-2013 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 operation was initiated via replication rather than
122 * within the local server.
123 *
124 * @return {@code true} if this operation was initiated via replication, or
125 * {@code false} if it was initiated locally within this server.
126 */
127 boolean isReplicationOperation();
128
129
130
131 /**
132 * Retrieves the DN of the user as whom the request is authorized. Note that
133 * this may change over the course of processing the operation (e.g., if the
134 * request includes a proxied authorization or intermediate client control).
135 *
136 * @return The DN of the user as whom the request is authorized. It may be
137 * an empty string if the operation is to be authorized as an
138 * unauthenticated user.
139 */
140 String getAuthorizationDN();
141
142
143
144 /**
145 * Retrieves the object attached to the associated operation with the given
146 * name.
147 *
148 * @param name The case-sensitive name of the attachment to retrieve. It
149 * must not be {@code null}.
150 *
151 * @return The requested attachment, or {@code null} if the operation does
152 * not have an attachment with the provided name.
153 */
154 Object getAttachment(final String name);
155
156
157
158 /**
159 * Sets an attachment for the associated operation.
160 *
161 * @param name The name of the attachment to set. It must not be
162 * {@code null}.
163 * @param value The value to set for the attachment. It may be {@code null}
164 * if any existing attachment with the specified name should be
165 * removed.
166 */
167 void setAttachment(final String name, final Object value);
168
169
170
171 /**
172 * Retrieves information about the client that requested this operation.
173 *
174 * @return Information about the client that requested this operation.
175 */
176 ClientContext getClientContext();
177
178
179
180 /**
181 * Indicates whether this operation was requested over a secure connection.
182 * If the request included the intermediate client control, then its value
183 * will also be used in determining whether communication with downstream
184 * clients is also secure.
185 *
186 * @return {@code true} if this operation was requested over a secure
187 * connection, or {@code false} if not.
188 */
189 boolean isSecure();
190
191
192
193 /**
194 * Retrieves an internal connection that is authenticated as the same user
195 * that requested this operation and may be subject to access control.
196 * <BR><BR>
197 * Note that the returned connection will use the client connection policy
198 * defined as the default policy for internal operations. If you wish to use
199 * the client connection policy associated with the connection on which this
200 * operation was requested, use the
201 * {@link #getInternalUserConnection(boolean)} method.
202 *
203 * @return An internal connection that is authenticated as the same user that
204 * requested this operation.
205 *
206 * @throws LDAPException If a problem occurs while attempting to obtain or
207 * authenticate the connection.
208 */
209 InternalConnection getInternalUserConnection()
210 throws LDAPException;
211
212
213
214 /**
215 * Retrieves an internal connection that is authenticated as the same user
216 * that requested this operation and may be subject to access control. It may
217 * optionally use the client connection policy from the associated client
218 * connection.
219 *
220 * @param usePolicyFromConnection If {@code true}, the internal connection
221 * will use the same client connection policy
222 * as the associated client connection. If
223 * {@code false}, the internal connection
224 * will use the server's default client
225 * connection policy for internal
226 * connections.
227 *
228 * @return An internal connection that is authenticated as the same user that
229 * requested this operation.
230 *
231 * @throws LDAPException If a problem occurs while attempting to obtain or
232 * authenticate the connection.
233 */
234 InternalConnection getInternalUserConnection(
235 final boolean usePolicyFromConnection)
236 throws LDAPException;
237
238
239
240 /**
241 * Retrieves an internal connection that is authenticated as a root user
242 * that is not subject to access control.
243 * <BR><BR>
244 * Note that the returned connection will use the client connection policy
245 * defined as the default policy for internal operations. If you wish to use
246 * the client connection policy associated with the connection on which this
247 * operation was requested, use the
248 * {@link #getInternalRootConnection(boolean)} method.
249 *
250 * @return An internal connection that is authenticated as a root user.
251 */
252 InternalConnection getInternalRootConnection();
253
254
255
256 /**
257 * Retrieves an internal connection that is authenticated as a root user
258 * that is not subject to access control. It may optionally use the client
259 * connection policy from the associated client connection.
260 *
261 * @param usePolicyFromConnection If {@code true}, the internal connection
262 * will use the same client connection policy
263 * as the associated client connection. If
264 * {@code false}, the internal connection
265 * will use the server's default client
266 * connection policy for internal
267 * connections.
268 *
269 * @return An internal connection that is authenticated as a root user.
270 */
271 InternalConnection getInternalRootConnection(
272 final boolean usePolicyFromConnection);
273
274
275
276 /**
277 * Retrieves a string representation of this operation.
278 *
279 * @return A string representation of this operation.
280 */
281 String toString();
282 }