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}