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 * Retrieves information about the client that requested this operation.
160 *
161 * @return Information about the client that requested this operation.
162 */
163 ClientContext getClientContext();
164
165
166
167 /**
168 * Indicates whether this operation was requested over a secure connection.
169 * If the request included the intermediate client control, then its value
170 * will also be used in determining whether communication with downstream
171 * clients is also secure.
172 *
173 * @return {@code true} if this operation was requested over a secure
174 * connection, or {@code false} if not.
175 */
176 boolean isSecure();
177
178
179
180 /**
181 * Retrieves an internal connection that is authenticated as the same user
182 * that requested this operation and may be subject to access control.
183 * <BR><BR>
184 * Note that the returned connection will use the client connection policy
185 * defined as the default policy for internal operations. If you wish to use
186 * the client connection policy associated with the connection on which this
187 * operation was requested, use the
188 * {@link #getInternalUserConnection(boolean)} method.
189 *
190 * @return An internal connection that is authenticated as the same user that
191 * requested this operation.
192 *
193 * @throws LDAPException If a problem occurs while attempting to obtain or
194 * authenticate the connection.
195 */
196 InternalConnection getInternalUserConnection()
197 throws LDAPException;
198
199
200
201 /**
202 * Retrieves an internal connection that is authenticated as the same user
203 * that requested this operation and may be subject to access control. It may
204 * optionally use the client connection policy from the associated client
205 * connection.
206 *
207 * @param usePolicyFromConnection If {@code true}, the internal connection
208 * will use the same client connection policy
209 * as the associated client connection. If
210 * {@code false}, the internal connection
211 * will use the server's default client
212 * connection policy for internal
213 * connections.
214 *
215 * @return An internal connection that is authenticated as the same user that
216 * requested this operation.
217 *
218 * @throws LDAPException If a problem occurs while attempting to obtain or
219 * authenticate the connection.
220 */
221 InternalConnection getInternalUserConnection(
222 final boolean usePolicyFromConnection)
223 throws LDAPException;
224
225
226
227 /**
228 * Retrieves an internal connection that is authenticated as a root user
229 * that is not subject to access control.
230 * <BR><BR>
231 * Note that the returned connection will use the client connection policy
232 * defined as the default policy for internal operations. If you wish to use
233 * the client connection policy associated with the connection on which this
234 * operation was requested, use the
235 * {@link #getInternalRootConnection(boolean)} method.
236 *
237 * @return An internal connection that is authenticated as a root user.
238 */
239 InternalConnection getInternalRootConnection();
240
241
242
243 /**
244 * Retrieves an internal connection that is authenticated as a root user
245 * that is not subject to access control. It may optionally use the client
246 * connection policy from the associated client connection.
247 *
248 * @param usePolicyFromConnection If {@code true}, the internal connection
249 * will use the same client connection policy
250 * as the associated client connection. If
251 * {@code false}, the internal connection
252 * will use the server's default client
253 * connection policy for internal
254 * connections.
255 *
256 * @return An internal connection that is authenticated as a root user.
257 */
258 InternalConnection getInternalRootConnection(
259 final boolean usePolicyFromConnection);
260
261
262
263 /**
264 * Retrieves a string representation of this operation.
265 *
266 * @return A string representation of this operation.
267 */
268 String toString();
269 }