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-2017 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 * 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}