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-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.types; 028 029 030 031 import com.unboundid.directory.sdk.common.operation.Request; 032 import com.unboundid.ldap.sdk.LDAPException; 033 import com.unboundid.util.NotExtensible; 034 import com.unboundid.util.ThreadSafety; 035 import com.unboundid.util.ThreadSafetyLevel; 036 037 038 039 /** 040 * This interface defines a set of methods that may be used to obtain 041 * information about an operation being processed by the server. 042 */ 043 @NotExtensible() 044 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 045 public interface OperationContext 046 { 047 /** 048 * Retrieves the identifier that has been assigned to the associated client 049 * connection. 050 * 051 * @return The identifier that has been assigned to the associated client 052 * connection. 053 */ 054 long getConnectionID(); 055 056 057 058 /** 059 * Retrieves the identifier that has been assigned to this operation for the 060 * associated client connection. 061 * 062 * @return The identifier that has been assigned to this operation for the 063 * associated client connection. 064 */ 065 long getOperationID(); 066 067 068 069 070 /** 071 * Retrieves the message ID for this operation from the client request. 072 * 073 * @return The message ID for this operation from the client request. 074 */ 075 int getMessageID(); 076 077 078 079 /** 080 * Retrieves the operation type for this operation. 081 * 082 * @return The operation type for this operation. 083 */ 084 OperationType getOperationType(); 085 086 087 088 /** 089 * Retrieves the request for the associated operation. The caller should not 090 * make any attempt to alter the request that is returned. 091 * 092 * @return The request for the associated operation. 093 */ 094 Request getRequest(); 095 096 097 098 /** 099 * Retrieves information about the server in which this operation is being 100 * processed. 101 * 102 * @return Information about the server in which this operation is being 103 * processed. 104 */ 105 ServerContext getServerContext(); 106 107 108 109 /** 110 * Indicates whether this operation was initiated within the server rather 111 * than by an external client. 112 * 113 * @return {@code true} if this operation was initiated within the server, or 114 * {@code false} if it was requested by an external client. 115 */ 116 boolean isInternalOperation(); 117 118 119 120 /** 121 * Indicates whether this is an administrative operation. An operation is 122 * considered administrative if the 123 * {@code StartAdministrativeSessionExtendedRequest} extended request was 124 * used on the connection, or the 125 * {@code AdministrativeOperationRequestControl} request control was used on 126 * the operation. 127 * 128 * @return {@code true} if this operation is an administrative operation. 129 */ 130 boolean isAdministrativeOperation(); 131 132 133 134 /** 135 * Indicates whether this operation was initiated via replication rather than 136 * within the local server. 137 * 138 * @return {@code true} if this operation was initiated via replication, or 139 * {@code false} if it was initiated locally within this server. 140 */ 141 boolean isReplicationOperation(); 142 143 144 145 /** 146 * Retrieves the DN of the user as whom the request is authorized. Note that 147 * this may change over the course of processing the operation (e.g., if the 148 * request includes a proxied authorization or intermediate client control). 149 * 150 * @return The DN of the user as whom the request is authorized. It may be 151 * an empty string if the operation is to be authorized as an 152 * unauthenticated user. 153 */ 154 String getAuthorizationDN(); 155 156 157 158 /** 159 * Retrieves the object attached to the associated operation with the given 160 * name. 161 * 162 * @param name The case-sensitive name of the attachment to retrieve. It 163 * must not be {@code null}. 164 * 165 * @return The requested attachment, or {@code null} if the operation does 166 * not have an attachment with the provided name. 167 */ 168 Object getAttachment(final String name); 169 170 171 172 /** 173 * Sets an attachment for the associated operation. 174 * 175 * @param name The name of the attachment to set. It must not be 176 * {@code null}. 177 * @param value The value to set for the attachment. It may be {@code null} 178 * if any existing attachment with the specified name should be 179 * removed. 180 */ 181 void setAttachment(final String name, final Object value); 182 183 184 185 /** 186 * Retrieves information about the client that requested this operation. 187 * 188 * @return Information about the client that requested this operation. 189 */ 190 ClientContext getClientContext(); 191 192 193 194 /** 195 * Indicates whether this operation was requested over a secure connection. 196 * If the request included the intermediate client control, then its value 197 * will also be used in determining whether communication with downstream 198 * clients is also secure. 199 * 200 * @return {@code true} if this operation was requested over a secure 201 * connection, or {@code false} if not. 202 */ 203 boolean isSecure(); 204 205 206 207 /** 208 * Retrieves an internal connection that is authenticated as the same user 209 * that requested this operation and may be subject to access control. 210 * <BR><BR> 211 * Note that the returned connection will use the client connection policy 212 * defined as the default policy for internal operations. If you wish to use 213 * the client connection policy associated with the connection on which this 214 * operation was requested, use the 215 * {@link #getInternalUserConnection(boolean)} method. 216 * 217 * @return An internal connection that is authenticated as the same user that 218 * requested this operation. 219 * 220 * @throws LDAPException If a problem occurs while attempting to obtain or 221 * authenticate the connection. 222 */ 223 InternalConnection getInternalUserConnection() 224 throws LDAPException; 225 226 227 228 /** 229 * Retrieves an internal connection that is authenticated as the same user 230 * that requested this operation and may be subject to access control. It may 231 * optionally use the client connection policy from the associated client 232 * connection. 233 * 234 * @param usePolicyFromConnection If {@code true}, the internal connection 235 * will use the same client connection policy 236 * as the associated client connection. If 237 * {@code false}, the internal connection 238 * will use the server's default client 239 * connection policy for internal 240 * connections. 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 final boolean usePolicyFromConnection) 250 throws LDAPException; 251 252 253 254 /** 255 * Retrieves an internal connection that is authenticated as a root user 256 * that is not subject to access control. 257 * <BR><BR> 258 * Note that the returned connection will use the client connection policy 259 * defined as the default policy for internal operations. If you wish to use 260 * the client connection policy associated with the connection on which this 261 * operation was requested, use the 262 * {@link #getInternalRootConnection(boolean)} method. 263 * 264 * @return An internal connection that is authenticated as a root user. 265 */ 266 InternalConnection getInternalRootConnection(); 267 268 269 270 /** 271 * Retrieves an internal connection that is authenticated as a root user 272 * that is not subject to access control. It may optionally use the client 273 * connection policy from the associated client connection. 274 * 275 * @param usePolicyFromConnection If {@code true}, the internal connection 276 * will use the same client connection policy 277 * as the associated client connection. If 278 * {@code false}, the internal connection 279 * will use the server's default client 280 * connection policy for internal 281 * connections. 282 * 283 * @return An internal connection that is authenticated as a root user. 284 */ 285 InternalConnection getInternalRootConnection( 286 final boolean usePolicyFromConnection); 287 288 289 290 /** 291 * Retrieves a string representation of this operation. 292 * 293 * @return A string representation of this operation. 294 */ 295 String toString(); 296 }