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-2016 UnboundID Corp.
026 */
027package com.unboundid.directory.sdk.common.types;
028
029
030
031import com.unboundid.directory.sdk.common.api.OperationCompletedListener;
032import com.unboundid.directory.sdk.common.operation.Request;
033import com.unboundid.ldap.sdk.LDAPException;
034import com.unboundid.util.NotExtensible;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038import java.util.List;
039import java.util.Map;
040
041
042/**
043 * This interface defines a set of methods that may be used to obtain
044 * information about an operation being processed by the server.
045 */
046@NotExtensible()
047@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
048public interface OperationContext
049{
050  /**
051   * Retrieves the identifier that has been assigned to the associated client
052   * connection.
053   *
054   * @return  The identifier that has been assigned to the associated client
055   *          connection.
056   */
057  long getConnectionID();
058
059
060
061  /**
062   * Retrieves the identifier that has been assigned to this operation for the
063   * associated client connection.
064   *
065   * @return  The identifier that has been assigned to this operation for the
066   *          associated client connection.
067   */
068  long getOperationID();
069
070
071
072
073  /**
074   * Retrieves the message ID for this operation from the client request.
075   *
076   * @return  The message ID for this operation from the client request.
077   */
078  int getMessageID();
079
080
081
082  /**
083   * Retrieves the operation type for this operation.
084   *
085   * @return  The operation type for this operation.
086   */
087  OperationType getOperationType();
088
089
090
091  /**
092   * Retrieves the request for the associated operation.  The caller should not
093   * make any attempt to alter the request that is returned.
094   *
095   * @return  The request for the associated operation.
096   */
097  Request getRequest();
098
099
100
101  /**
102   * Retrieves information about the server in which this operation is being
103   * processed.
104   *
105   * @return  Information about the server in which this operation is being
106   *          processed.
107   */
108  ServerContext getServerContext();
109
110
111
112  /**
113   * Indicates whether this operation was initiated within the server rather
114   * than by an external client.
115   *
116   * @return  {@code true} if this operation was initiated within the server, or
117   *          {@code false} if it was requested by an external client.
118   */
119  boolean isInternalOperation();
120
121
122
123  /**
124   * Indicates whether this is an administrative operation. An operation is
125   * considered administrative if the
126   * {@code StartAdministrativeSessionExtendedRequest} extended request was
127   * used on the connection, or the
128   * {@code AdministrativeOperationRequestControl} request control was used on
129   * the operation.
130   *
131   * @return  {@code true} if this operation is an administrative operation.
132   */
133  boolean isAdministrativeOperation();
134
135
136
137  /**
138   * Indicates whether this operation was initiated via replication rather than
139   * within the local server.
140   *
141   * @return  {@code true} if this operation was initiated via replication, or
142   *          {@code false} if it was initiated locally within this server.
143   */
144  boolean isReplicationOperation();
145
146
147
148  /**
149   * Retrieves the DN of the user as whom the request is authorized.  Note that
150   * this may change over the course of processing the operation (e.g., if the
151   * request includes a proxied authorization or intermediate client control).
152   *
153   * @return  The DN of the user as whom the request is authorized.  It may be
154   *          an empty string if the operation is to be authorized as an
155   *          unauthenticated user.
156   */
157  String getAuthorizationDN();
158
159
160
161  /**
162   * Retrieves the object attached to the associated operation with the given
163   * name.
164   *
165   * @param  name  The case-sensitive name of the attachment to retrieve.  It
166   *               must not be {@code null}.
167   *
168   * @return  The requested attachment, or {@code null} if the operation does
169   *          not have an attachment with the provided name.
170   */
171  Object getAttachment(final String name);
172
173
174
175  /**
176   * Sets an attachment for the associated operation.
177   *
178   * @param  name   The name of the attachment to set.  It must not be
179   *                {@code null}.
180   * @param  value  The value to set for the attachment.  It may be {@code null}
181   *                if any existing attachment with the specified name should be
182   *                removed.
183   */
184  void setAttachment(final String name, final Object value);
185
186
187
188  /**
189   * Retrieves information about the client that requested this operation.
190   *
191   * @return  Information about the client that requested this operation.
192   */
193  ClientContext getClientContext();
194
195
196
197  /**
198   * Indicates whether this operation was requested over a secure connection.
199   * If the request included the intermediate client control, then its value
200   * will also be used in determining whether communication with downstream
201   * clients is also secure.
202   *
203   * @return  {@code true} if this operation was requested over a secure
204   *          connection, or {@code false} if not.
205   */
206  boolean isSecure();
207
208
209
210  /**
211   * Retrieves an internal connection that is authenticated as the same user
212   * that requested this operation and may be subject to access control.
213   * <BR><BR>
214   * Note that the returned connection will use the client connection policy
215   * defined as the default policy for internal operations.  If you wish to use
216   * the client connection policy associated with the connection on which this
217   * operation was requested, use the
218   * {@link #getInternalUserConnection(boolean)} method.
219   *
220   * @return  An internal connection that is authenticated as the same user that
221   *          requested this operation.
222   *
223   * @throws  LDAPException  If a problem occurs while attempting to obtain or
224   *                         authenticate the connection.
225   */
226  InternalConnection getInternalUserConnection()
227       throws LDAPException;
228
229
230
231  /**
232   * Retrieves an internal connection that is authenticated as the same user
233   * that requested this operation and may be subject to access control.  It may
234   * optionally use the client connection policy from the associated client
235   * connection.
236   *
237   * @param  usePolicyFromConnection  If {@code true}, the internal connection
238   *                                  will use the same client connection policy
239   *                                  as the associated client connection.  If
240   *                                  {@code false}, the internal connection
241   *                                  will use the server's default client
242   *                                  connection policy for internal
243   *                                  connections.
244   *
245   * @return  An internal connection that is authenticated as the same user that
246   *          requested this operation.
247   *
248   * @throws  LDAPException  If a problem occurs while attempting to obtain or
249   *                         authenticate the connection.
250   */
251  InternalConnection getInternalUserConnection(
252                          final boolean usePolicyFromConnection)
253       throws LDAPException;
254
255
256
257  /**
258   * Retrieves an internal connection that is authenticated as a root user
259   * that is not subject to access control.
260   * <BR><BR>
261   * Note that the returned connection will use the client connection policy
262   * defined as the default policy for internal operations.  If you wish to use
263   * the client connection policy associated with the connection on which this
264   * operation was requested, use the
265   * {@link #getInternalRootConnection(boolean)} method.
266   *
267   * @return  An internal connection that is authenticated as a root user.
268   */
269  InternalConnection getInternalRootConnection();
270
271
272
273  /**
274   * Retrieves an internal connection that is authenticated as a root user
275   * that is not subject to access control.  It may optionally use the client
276   * connection policy from the associated client connection.
277   *
278   * @param  usePolicyFromConnection  If {@code true}, the internal connection
279   *                                  will use the same client connection policy
280   *                                  as the associated client connection.  If
281   *                                  {@code false}, the internal connection
282   *                                  will use the server's default client
283   *                                  connection policy for internal
284   *                                  connections.
285   *
286   * @return  An internal connection that is authenticated as a root user.
287   */
288  InternalConnection getInternalRootConnection(
289       final boolean usePolicyFromConnection);
290
291
292
293  /**
294   * Retrieves a string representation of this operation.
295   *
296   * @return  A string representation of this operation.
297   */
298  String toString();
299
300
301
302  /**
303   * Specifies an additional log element for this operation, which
304   * should be written to the log.
305   *  @param  key    The key of the log element being added
306   *  @param  value  The value of the log element being added
307   */
308  void addCustomLogElement(String key, Object value);
309
310
311  /**
312   * Returns any additional log elements for this operation, which
313   * should be written to the log.
314   *
315   * @return map of additional log elements to a list of values.
316   */
317  Map<String, List<String>> getCustomLogElements();
318
319
320
321  /**
322   * Registers the provided listener to be notified when the server completes
323   * an operation.
324   *
325   * @param  listener  The server operation completed listener to be registered.
326   *                   It must not be {@code null}.
327   *
328   * @return  An object representing the operation completed listener that has
329   *          been registered with the server.
330   */
331  RegisteredOperationCompletedListener registerOperationCompletedListener(
332      final OperationCompletedListener listener);
333
334
335
336  /**
337   * Deregisters the provided server operation completed listener with the
338   * server.  This will have no effect if the provided listener is not
339   * registered.
340   *
341   * @param  listener  The server operation completed listener to be
342   *                   deregistered.  It must not be {@code null}.
343   */
344  void deregisterOperationCompletedListener(
345      final RegisteredOperationCompletedListener listener);
346}