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-2021 Ping Identity Corporation
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   * Retrieves the name of the client connection policy to which the associated
199   * client connection is assigned.
200   *
201   * @return  The name of the client connection policy to which the associated
202   *          client connection is assigned.
203   */
204  String getClientConnectionPolicyName();
205
206
207
208  /**
209   * Retrieves the DN of the entry that defines the client connection policy to
210   * which the associated client connection is assigned.
211   *
212   * @return  The DN of the entry that defines the client connection policy to
213   *          which the associated client connection policy is assigned.
214   */
215  String getClientConnectionPolicyDN();
216
217
218
219  /**
220   * Indicates whether this operation was requested over a secure connection.
221   * If the request included the intermediate client control, then its value
222   * will also be used in determining whether communication with downstream
223   * clients is also secure.
224   *
225   * @return  {@code true} if this operation was requested over a secure
226   *          connection, or {@code false} if not.
227   */
228  boolean isSecure();
229
230
231
232  /**
233   * Retrieves an internal connection that is authenticated as the same user
234   * that requested this operation and may be subject to access control.
235   * <BR><BR>
236   * Note that the returned connection will use the client connection policy
237   * defined as the default policy for internal operations.  If you wish to use
238   * the client connection policy associated with the connection on which this
239   * operation was requested, use the
240   * {@link #getInternalUserConnection(boolean)} method.
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       throws LDAPException;
250
251
252
253  /**
254   * Retrieves an internal connection that is authenticated as the same user
255   * that requested this operation and may be subject to access control.  It may
256   * optionally use the client connection policy from the associated client
257   * connection.
258   *
259   * @param  usePolicyFromConnection  If {@code true}, the internal connection
260   *                                  will use the same client connection policy
261   *                                  as the associated client connection.  If
262   *                                  {@code false}, the internal connection
263   *                                  will use the server's default client
264   *                                  connection policy for internal
265   *                                  connections.
266   *
267   * @return  An internal connection that is authenticated as the same user that
268   *          requested this operation.
269   *
270   * @throws  LDAPException  If a problem occurs while attempting to obtain or
271   *                         authenticate the connection.
272   */
273  InternalConnection getInternalUserConnection(
274                          final boolean usePolicyFromConnection)
275       throws LDAPException;
276
277
278
279  /**
280   * Retrieves an internal connection that is authenticated as a root user
281   * that is not subject to access control.
282   * <BR><BR>
283   * Note that the returned connection will use the client connection policy
284   * defined as the default policy for internal operations.  If you wish to use
285   * the client connection policy associated with the connection on which this
286   * operation was requested, use the
287   * {@link #getInternalRootConnection(boolean)} method.
288   *
289   * @return  An internal connection that is authenticated as a root user.
290   */
291  InternalConnection getInternalRootConnection();
292
293
294
295  /**
296   * Retrieves an internal connection that is authenticated as a root user
297   * that is not subject to access control.  It may optionally use the client
298   * connection policy from the associated client connection.
299   *
300   * @param  usePolicyFromConnection  If {@code true}, the internal connection
301   *                                  will use the same client connection policy
302   *                                  as the associated client connection.  If
303   *                                  {@code false}, the internal connection
304   *                                  will use the server's default client
305   *                                  connection policy for internal
306   *                                  connections.
307   *
308   * @return  An internal connection that is authenticated as a root user.
309   */
310  InternalConnection getInternalRootConnection(
311       final boolean usePolicyFromConnection);
312
313
314
315  /**
316   * Retrieves a string representation of this operation.
317   *
318   * @return  A string representation of this operation.
319   */
320  String toString();
321
322
323
324  /**
325   * Specifies an additional log element for this operation, which
326   * should be written to the log.
327   *  @param  key    The key of the log element being added
328   *  @param  value  The value of the log element being added
329   */
330  void addCustomLogElement(String key, Object value);
331
332
333  /**
334   * Returns any additional log elements for this operation, which
335   * should be written to the log.
336   *
337   * @return map of additional log elements to a list of values.
338   */
339  Map<String, List<String>> getCustomLogElements();
340
341
342
343  /**
344   * Indicates that the provided message should be included in the access log
345   * message for the operation but should not be returned to the client.
346   *
347   * @param  message  The message to include in the log message.  It must not
348   *                  be {@code null}.
349   */
350  void appendAdditionalLogMessage(final String message);
351
352
353
354  /**
355   * Registers the provided listener to be notified when the server completes
356   * an operation.
357   *
358   * @param  listener  The server operation completed listener to be registered.
359   *                   It must not be {@code null}.
360   *
361   * @return  An object representing the operation completed listener that has
362   *          been registered with the server.
363   */
364  RegisteredOperationCompletedListener registerOperationCompletedListener(
365      final OperationCompletedListener listener);
366
367
368
369  /**
370   * Deregisters the provided server operation completed listener with the
371   * server.  This will have no effect if the provided listener is not
372   * registered.
373   *
374   * @param  listener  The server operation completed listener to be
375   *                   deregistered.  It must not be {@code null}.
376   */
377  void deregisterOperationCompletedListener(
378      final RegisteredOperationCompletedListener listener);
379}