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}