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-2013 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 operation was initiated via replication rather than 122 * within the local server. 123 * 124 * @return {@code true} if this operation was initiated via replication, or 125 * {@code false} if it was initiated locally within this server. 126 */ 127 boolean isReplicationOperation(); 128 129 130 131 /** 132 * Retrieves the DN of the user as whom the request is authorized. Note that 133 * this may change over the course of processing the operation (e.g., if the 134 * request includes a proxied authorization or intermediate client control). 135 * 136 * @return The DN of the user as whom the request is authorized. It may be 137 * an empty string if the operation is to be authorized as an 138 * unauthenticated user. 139 */ 140 String getAuthorizationDN(); 141 142 143 144 /** 145 * Retrieves the object attached to the associated operation with the given 146 * name. 147 * 148 * @param name The case-sensitive name of the attachment to retrieve. It 149 * must not be {@code null}. 150 * 151 * @return The requested attachment, or {@code null} if the operation does 152 * not have an attachment with the provided name. 153 */ 154 Object getAttachment(final String name); 155 156 157 158 /** 159 * Sets an attachment for the associated operation. 160 * 161 * @param name The name of the attachment to set. It must not be 162 * {@code null}. 163 * @param value The value to set for the attachment. It may be {@code null} 164 * if any existing attachment with the specified name should be 165 * removed. 166 */ 167 void setAttachment(final String name, final Object value); 168 169 170 171 /** 172 * Retrieves information about the client that requested this operation. 173 * 174 * @return Information about the client that requested this operation. 175 */ 176 ClientContext getClientContext(); 177 178 179 180 /** 181 * Indicates whether this operation was requested over a secure connection. 182 * If the request included the intermediate client control, then its value 183 * will also be used in determining whether communication with downstream 184 * clients is also secure. 185 * 186 * @return {@code true} if this operation was requested over a secure 187 * connection, or {@code false} if not. 188 */ 189 boolean isSecure(); 190 191 192 193 /** 194 * Retrieves an internal connection that is authenticated as the same user 195 * that requested this operation and may be subject to access control. 196 * <BR><BR> 197 * Note that the returned connection will use the client connection policy 198 * defined as the default policy for internal operations. If you wish to use 199 * the client connection policy associated with the connection on which this 200 * operation was requested, use the 201 * {@link #getInternalUserConnection(boolean)} method. 202 * 203 * @return An internal connection that is authenticated as the same user that 204 * requested this operation. 205 * 206 * @throws LDAPException If a problem occurs while attempting to obtain or 207 * authenticate the connection. 208 */ 209 InternalConnection getInternalUserConnection() 210 throws LDAPException; 211 212 213 214 /** 215 * Retrieves an internal connection that is authenticated as the same user 216 * that requested this operation and may be subject to access control. It may 217 * optionally use the client connection policy from the associated client 218 * connection. 219 * 220 * @param usePolicyFromConnection If {@code true}, the internal connection 221 * will use the same client connection policy 222 * as the associated client connection. If 223 * {@code false}, the internal connection 224 * will use the server's default client 225 * connection policy for internal 226 * connections. 227 * 228 * @return An internal connection that is authenticated as the same user that 229 * requested this operation. 230 * 231 * @throws LDAPException If a problem occurs while attempting to obtain or 232 * authenticate the connection. 233 */ 234 InternalConnection getInternalUserConnection( 235 final boolean usePolicyFromConnection) 236 throws LDAPException; 237 238 239 240 /** 241 * Retrieves an internal connection that is authenticated as a root user 242 * that is not subject to access control. 243 * <BR><BR> 244 * Note that the returned connection will use the client connection policy 245 * defined as the default policy for internal operations. If you wish to use 246 * the client connection policy associated with the connection on which this 247 * operation was requested, use the 248 * {@link #getInternalRootConnection(boolean)} method. 249 * 250 * @return An internal connection that is authenticated as a root user. 251 */ 252 InternalConnection getInternalRootConnection(); 253 254 255 256 /** 257 * Retrieves an internal connection that is authenticated as a root user 258 * that is not subject to access control. It may optionally use the client 259 * connection policy from the associated client connection. 260 * 261 * @param usePolicyFromConnection If {@code true}, the internal connection 262 * will use the same client connection policy 263 * as the associated client connection. If 264 * {@code false}, the internal connection 265 * will use the server's default client 266 * connection policy for internal 267 * connections. 268 * 269 * @return An internal connection that is authenticated as a root user. 270 */ 271 InternalConnection getInternalRootConnection( 272 final boolean usePolicyFromConnection); 273 274 275 276 /** 277 * Retrieves a string representation of this operation. 278 * 279 * @return A string representation of this operation. 280 */ 281 String toString(); 282 }