1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * 19 */ 20 package org.apache.directory.server.core.interceptor.context; 21 22 23 import java.util.Collection; 24 import java.util.List; 25 26 import javax.naming.ldap.Control; 27 28 import org.apache.directory.server.core.CoreSession; 29 import org.apache.directory.server.core.authn.LdapPrincipal; 30 import org.apache.directory.server.core.entry.ClonedServerEntry; 31 import org.apache.directory.server.core.entry.ServerEntry; 32 import org.apache.directory.server.core.interceptor.Interceptor; 33 import org.apache.directory.shared.ldap.entry.Modification; 34 import org.apache.directory.shared.ldap.name.LdapDN; 35 36 37 /** 38 * This interface represent the context passed as an argument to each interceptor. 39 * It will contain data used by all the operations. 40 * 41 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 42 * @version $Rev$, $Date$ 43 */ 44 public interface OperationContext 45 { 46 /** 47 * Checks to see if this operation is the first operation in a chain of 48 * operations performed on the DirectoryService. The first operation in 49 * a sequence of operations, is not a byproduct of another operation 50 * unlike operations following in the sequence. The other operations 51 * following the first, occur as a side effect to complete this first 52 * operation. 53 * 54 * @return true if the operation is the first, false otherwise 55 */ 56 boolean isFirstOperation(); 57 58 59 /** 60 * Gets the first, direct operation issued against the DirectoryService. 61 * 62 * @return the first, direct operation issued 63 */ 64 OperationContext getFirstOperation(); 65 66 67 /** 68 * Gets the previous, operation issued on the DirectoryService. 69 * 70 * @return the previous, operation issued 71 */ 72 OperationContext getPreviousOperation(); 73 74 75 /** 76 * Gets the next, indirect operation issued on the DirectoryService. 77 * 78 * @return the next, indirect operation issued 79 */ 80 OperationContext getNextOperation(); 81 82 83 /** 84 * Gets the last, operation issued on the DirectoryService. 85 * 86 * @return the last, operation issued 87 */ 88 OperationContext getLastOperation(); 89 90 91 /** 92 * Gets the effective principal for this operation which may not be the 93 * same as the authenticated principal when the session for this context 94 * has an explicit authorization id, or this operation was applied with 95 * the proxy authorization control. 96 * 97 * @see CoreSession#getAuthenticatedPrincipal() 98 * @see CoreSession#getEffectivePrincipal() 99 * @return the effective principal for this operation 100 */ 101 LdapPrincipal getEffectivePrincipal(); 102 103 104 /** 105 * @return The associated DN 106 */ 107 LdapDN getDn(); 108 109 110 /** 111 * Set the context DN 112 * 113 * @param dn The DN to set 114 */ 115 void setDn( LdapDN dn ); 116 117 118 /** 119 * Gets the server entry associated with the target DN of this 120 * OperationContext. The entry associated with the DN may be altered 121 * during the course of processing an LDAP operation through the 122 * InterceptorChain. This place holder is put here to prevent the need 123 * for repetitive lookups of the target entry. Furthermore the returned 124 * entry may be altered by any Interceptor in the chain and this is why a 125 * ClonedServerEntry is returned instead of a ServerEntry. A 126 * ClonedServerEntry has an immutable reference to the original state of 127 * the target entry. The original state can be accessed via a call to 128 * {@link ClonedServerEntry#getOriginalEntry()}. The return value may be 129 * null in which case any lookup performed to access it may set it to 130 * prevent the need for subsequent lookups. 131 * 132 * Also note that during the course of handling some operations such as 133 * those that rename, move or rename and move the entry, may alter the DN 134 * of this entry. Interceptor implementors should not presume the DN or 135 * the values contained in this entry are currently what is present in the 136 * DIT. The original entry contained in the ClonedServerEntry shoudl be 137 * used as the definitive source of information about the state of the 138 * entry in the DIT before returning from the Partition subsystem. 139 * 140 * @return target entry associated with the DN of this OperationContext 141 */ 142 ClonedServerEntry getEntry(); 143 144 145 /** 146 * Sets the server entry associated with the target DN of this 147 * OperationContext. 148 * 149 * @param entry the entry whose DN is associated with this OperationContext. 150 */ 151 void setEntry( ClonedServerEntry entry ); 152 153 154 /** 155 * Adds a response control to this operation. 156 * 157 * @param responseControl the response control to add to this operation 158 */ 159 void addResponseControl( Control responseControl ); 160 161 162 /** 163 * Checks to see if a response control is present on this operation. 164 * 165 * @param numericOid the numeric OID of the control also known as it's type OID 166 * @return true if the control is associated with this operation, false otherwise 167 */ 168 boolean hasResponseControl( String numericOid ); 169 170 171 /** 172 * Gets a response control if present for this request. 173 * 174 * @param numericOid the numeric OID of the control also known as it's type OID 175 * @return the control if present 176 */ 177 Control getResponseControl( String numericOid ); 178 179 180 /** 181 * Gets all the response controls producted during this operation. 182 * 183 * @return an array over all the response controls 184 */ 185 Control[] getResponseControls(); 186 187 188 /** 189 * Checks if any response controls have been generated for this operation. 190 * 191 * @return true if any response controls have been generated, false otherwise 192 */ 193 boolean hasResponseControls(); 194 195 196 /** 197 * Checks the number of response controls have been generated for this operation. 198 * 199 * @return the number of response controls that have been generated 200 */ 201 int getResponseControlCount(); 202 203 204 /** 205 * Adds a request control to this operation. 206 * 207 * @param requestControl the request control to add to this operation 208 */ 209 void addRequestControl( Control requestControl ); 210 211 212 /** 213 * Checks to see if a request control is present on this request. 214 * 215 * @param numericOid the numeric OID of the control also known as it's type OID 216 * @return true if the control is associated with this operation, false otherwise 217 */ 218 boolean hasRequestControl( String numericOid ); 219 220 221 /** 222 * Checks if any request controls exists for this operation. 223 * 224 * @return true if any request controls exist, false otherwise 225 */ 226 boolean hasRequestControls(); 227 228 229 /** 230 * Gets a request control if present for this request. 231 * 232 * @param numericOid the numeric OID of the control also known as it's type OID 233 * @return the control if present 234 */ 235 Control getRequestControl( String numericOid ); 236 237 238 /** 239 * Adds many request controls to this operation. 240 * 241 * @param requestControls the request controls to add to this operation 242 */ 243 void addRequestControls( Control[] requestControls ); 244 245 246 /** 247 * @return the operation's name 248 */ 249 String getName(); 250 251 252 /** 253 * Checks to see if an Interceptor is bypassed for this operation. 254 * 255 * @param interceptorName the interceptorName of the Interceptor to check for bypass 256 * @return true if the Interceptor should be bypassed, false otherwise 257 */ 258 boolean isBypassed( String interceptorName ); 259 260 261 /** 262 * Checks to see if any Interceptors are bypassed by this Invocation. 263 * 264 * @return true if at least one bypass exists 265 */ 266 boolean hasBypass(); 267 268 269 /** 270 * Gets the set of bypassed Interceptors. 271 * 272 * @return the set of bypassed Interceptors 273 */ 274 Collection<String> getByPassed(); 275 276 277 /** 278 * Sets the set of bypassed Interceptors. 279 * 280 * @param byPassed the set of bypassed Interceptors 281 */ 282 void setByPassed( Collection<String> byPassed ); 283 284 285 /** 286 * Gets the session associated with this operation. 287 * 288 * @return the session associated with this operation 289 */ 290 CoreSession getSession(); 291 292 293 // ----------------------------------------------------------------------- 294 // Utility Factory Methods to Create New OperationContexts 295 // ----------------------------------------------------------------------- 296 297 298 LookupOperationContext newLookupContext( LdapDN dn ); 299 300 301 ClonedServerEntry lookup( LdapDN dn, Collection<String> byPass ) throws Exception; 302 303 304 ClonedServerEntry lookup( LookupOperationContext lookupContext ) throws Exception; 305 306 307 void modify( LdapDN dn, List<Modification> mods, Collection<String> byPass ) throws Exception; 308 309 310 void add( ServerEntry entry, Collection<String> byPass ) throws Exception; 311 312 313 void delete( LdapDN dn, Collection<String> byPass ) throws Exception; 314 315 316 /** 317 * Checks to see if an entry exists. 318 * 319 * @param dn the distinguished name of the entry to check 320 * @param byPass collection of {@link Interceptor}'s to bypass for this check 321 * @return true if the entry exists, false if it does not 322 * @throws Exception on failure to perform this operation 323 */ 324 boolean hasEntry( LdapDN dn, Collection<String> byPass ) throws Exception; 325 326 327 // AddOperationContext newAddContext( ServerEntry entry ); 328 329 330 // void add( AddOperationContext addContext ) throws Exception; 331 }