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