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-2012 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 * Retrieves information about the client that requested this operation. 160 * 161 * @return Information about the client that requested this operation. 162 */ 163 ClientContext getClientContext(); 164 165 166 167 /** 168 * Indicates whether this operation was requested over a secure connection. 169 * If the request included the intermediate client control, then its value 170 * will also be used in determining whether communication with downstream 171 * clients is also secure. 172 * 173 * @return {@code true} if this operation was requested over a secure 174 * connection, or {@code false} if not. 175 */ 176 boolean isSecure(); 177 178 179 180 /** 181 * Retrieves an internal connection that is authenticated as the same user 182 * that requested this operation and may be subject to access control. 183 * <BR><BR> 184 * Note that the returned connection will use the client connection policy 185 * defined as the default policy for internal operations. If you wish to use 186 * the client connection policy associated with the connection on which this 187 * operation was requested, use the 188 * {@link #getInternalUserConnection(boolean)} method. 189 * 190 * @return An internal connection that is authenticated as the same user that 191 * requested this operation. 192 * 193 * @throws LDAPException If a problem occurs while attempting to obtain or 194 * authenticate the connection. 195 */ 196 InternalConnection getInternalUserConnection() 197 throws LDAPException; 198 199 200 201 /** 202 * Retrieves an internal connection that is authenticated as the same user 203 * that requested this operation and may be subject to access control. It may 204 * optionally use the client connection policy from the associated client 205 * connection. 206 * 207 * @param usePolicyFromConnection If {@code true}, the internal connection 208 * will use the same client connection policy 209 * as the associated client connection. If 210 * {@code false}, the internal connection 211 * will use the server's default client 212 * connection policy for internal 213 * connections. 214 * 215 * @return An internal connection that is authenticated as the same user that 216 * requested this operation. 217 * 218 * @throws LDAPException If a problem occurs while attempting to obtain or 219 * authenticate the connection. 220 */ 221 InternalConnection getInternalUserConnection( 222 final boolean usePolicyFromConnection) 223 throws LDAPException; 224 225 226 227 /** 228 * Retrieves an internal connection that is authenticated as a root user 229 * that is not subject to access control. 230 * <BR><BR> 231 * Note that the returned connection will use the client connection policy 232 * defined as the default policy for internal operations. If you wish to use 233 * the client connection policy associated with the connection on which this 234 * operation was requested, use the 235 * {@link #getInternalRootConnection(boolean)} method. 236 * 237 * @return An internal connection that is authenticated as a root user. 238 */ 239 InternalConnection getInternalRootConnection(); 240 241 242 243 /** 244 * Retrieves an internal connection that is authenticated as a root user 245 * that is not subject to access control. It may optionally use the client 246 * connection policy from the associated client connection. 247 * 248 * @param usePolicyFromConnection If {@code true}, the internal connection 249 * will use the same client connection policy 250 * as the associated client connection. If 251 * {@code false}, the internal connection 252 * will use the server's default client 253 * connection policy for internal 254 * connections. 255 * 256 * @return An internal connection that is authenticated as a root user. 257 */ 258 InternalConnection getInternalRootConnection( 259 final boolean usePolicyFromConnection); 260 261 262 263 /** 264 * Retrieves a string representation of this operation. 265 * 266 * @return A string representation of this operation. 267 */ 268 String toString(); 269 }