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; 21 22 23 import java.net.SocketAddress; 24 import java.util.List; 25 import java.util.Set; 26 27 import javax.naming.ldap.Control; 28 29 import org.apache.directory.server.constants.ServerDNConstants; 30 import org.apache.directory.server.core.authn.LdapPrincipal; 31 import org.apache.directory.server.core.entry.ClonedServerEntry; 32 import org.apache.directory.server.core.entry.ServerEntry; 33 import org.apache.directory.server.core.filtering.EntryFilteringCursor; 34 import org.apache.directory.server.core.interceptor.context.OperationContext; 35 import org.apache.directory.shared.ldap.message.SearchRequest; 36 import org.apache.directory.shared.ldap.constants.AuthenticationLevel; 37 import org.apache.directory.shared.ldap.entry.Modification; 38 import org.apache.directory.shared.ldap.filter.ExprNode; 39 import org.apache.directory.shared.ldap.filter.SearchScope; 40 import org.apache.directory.shared.ldap.message.AddRequest; 41 import org.apache.directory.shared.ldap.message.AliasDerefMode; 42 import org.apache.directory.shared.ldap.message.CompareRequest; 43 import org.apache.directory.shared.ldap.message.DeleteRequest; 44 import org.apache.directory.shared.ldap.message.ModifyDnRequest; 45 import org.apache.directory.shared.ldap.message.ModifyRequest; 46 import org.apache.directory.shared.ldap.message.UnbindRequest; 47 import org.apache.directory.shared.ldap.name.LdapDN; 48 import org.apache.directory.shared.ldap.name.Rdn; 49 import org.apache.directory.shared.ldap.schema.AttributeTypeOptions; 50 51 52 /** 53 * An interface representing a session with the core DirectoryService. These 54 * sessions may either be real representing LDAP sessions associated with an 55 * actual LDAP network client, or may be virtual in which case there is no 56 * real LDAP client associated with the session. This interface is used by 57 * the DirectoryService core to track session specific parameters used to make 58 * various decisions during the course of operation handling. 59 * 60 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 61 * @version $Rev$, $Date$ 62 */ 63 public interface CoreSession 64 { 65 /** 66 * Gets the DirectoryService this session is bound to. 67 * 68 * @return the DirectoryService associated with this session 69 */ 70 DirectoryService getDirectoryService(); 71 72 73 /** 74 * Gets the LDAP principal used to authenticate. This is the identity 75 * used to establish this session on authentication. 76 * 77 * @return the LdapPrincipal used to authenticate. 78 */ 79 LdapPrincipal getAuthenticatedPrincipal(); 80 81 82 /** 83 * Gets the LDAP principal used for the effective identity associated with 84 * this session which may not be the same as the authenticated principal. 85 * This principal is often the same as the authenticated principal. 86 * Sometimes however, a user authenticating as one principal, may request 87 * to have all operations performed in the session as if they were another 88 * principal. The SASL mechanism allows setting an authorized principal 89 * which is in effect for the duration of the session. In this case all 90 * operations are performed as if they are being performed by this 91 * principal. This method will then return the authorized principal which 92 * will be different from the authenticated principal. 93 * 94 * Implementations of this interface may have a means to set the 95 * authorized principal which may or may not be the same as the 96 * authenticated principal. Implementations should default to return the 97 * authenticated principal when an authorized principal is not provided. 98 * 99 * @return the LdapPrincipal to use as the effective principal 100 */ 101 LdapPrincipal getEffectivePrincipal(); 102 103 104 /** 105 * Gets whether or not confidentiality is enabled for this session. 106 * 107 * @return true if confidentiality is enabled, false otherwise 108 */ 109 boolean isConfidential(); 110 111 112 /** 113 * Gets whether or not this user is anonymous. 114 * 115 * @return true if the identity is anonymous false otherwise 116 */ 117 boolean isAnonymous(); 118 119 120 /** 121 * Returns true if the effective principal associated with this session is 122 * the administrator. 123 * 124 * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN} 125 * @return true if authorized as the administrator, false otherwise 126 */ 127 boolean isAdministrator(); 128 129 130 /** 131 * Returns true if the effective principal associated with this session is 132 * the administrator or is within the administrators group. 133 * 134 * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN} 135 * @see {@link ServerDNConstants#ADMINISTRATORS_GROUP_DN} 136 * @return true if authorized as an administrator, false otherwise 137 */ 138 boolean isAnAdministrator(); 139 140 141 /** 142 * Gets the authentication level associated with this session. 143 * 144 * @return the authentication level associated with the session 145 */ 146 AuthenticationLevel getAuthenticationLevel(); 147 148 149 /** 150 * Gets the controls enabled for this session. 151 * 152 * @return the session controls as a Set 153 */ 154 Set<Control> getControls(); 155 156 157 /** 158 * Gets all outstanding operations currently being performed that have yet 159 * to be completed. 160 * 161 * @return the set of outstanding operations 162 */ 163 Set<OperationContext> getOutstandingOperations(); 164 165 166 /** 167 * Gets whether or not this session is virtual. Virtual sessions verses 168 * real sessions represent logical sessions established by non-LDAP 169 * services or embedding applications which do not expose the LDAP access. 170 * 171 * @return true if the session is virtual, false otherwise 172 */ 173 boolean isVirtual(); 174 175 176 /** 177 * Gets the socket address of the LDAP client or null if there is no LDAP 178 * client associated with the session. Some calls to the core can be made 179 * by embedding applications or by non-LDAP services using a programmatic 180 * (virtual) session. In these cases no client address is available. 181 * 182 * @return null if the session is virtual, non-null when the session is 183 * associated with a real LDAP client 184 */ 185 SocketAddress getClientAddress(); 186 187 188 /** 189 * Gets the socket address of the LDAP server or null if there is no LDAP 190 * service associated with the session. Some calls to the core can be 191 * made by embedding applications or by non-LDAP services using a 192 * programmatic (virtual) session. In these cases no service address is 193 * available. 194 * 195 * @return null if the session is virtual, non-null when the session is 196 * associated with a real LDAP service 197 */ 198 SocketAddress getServiceAddress(); 199 200 201 // ----------------------------------------------------------------------- 202 // Operation Methods 203 // ----------------------------------------------------------------------- 204 205 206 /** 207 * Adds an entry into the DirectoryService associated with this CoreSession. 208 * 209 * @param entry the entry to add 210 * @exception Exception on failures to add the entry 211 */ 212 void add( ServerEntry entry ) throws Exception; 213 214 215 void add( AddRequest addRequest ) throws Exception; 216 217 218 /** 219 * Checks to see if an attribute in an entry contains a value. 220 * 221 * @param dn the distinguished name of the entry to check 222 * @param oid the OID of the attribute to check for the value 223 * @param value the value to check for 224 * @throws Exception if there are failures while comparing 225 */ 226 void compare( LdapDN dn, String oid, Object value ) throws Exception; 227 228 229 boolean compare( CompareRequest compareRequest ) throws Exception; 230 231 232 /** 233 * Deletes an entry in the server. 234 * 235 * @param dn the distinguished name of the entry to delete 236 * @throws Exception if there are failures while deleting the entry 237 */ 238 void delete( LdapDN dn ) throws Exception; 239 240 241 void delete( DeleteRequest deleteRequest ) throws Exception; 242 243 /** 244 * Checks to see if an entry exists. 245 */ 246 boolean exists( LdapDN dn ) throws Exception; 247 248 249 /** 250 * Looks up an entry in the server returning all attributes: both user and 251 * operational attributes. 252 * 253 * @param dn the name of the entry to lookup 254 * @throws Exception if there are failures while looking up the entry 255 */ 256 ClonedServerEntry lookup( LdapDN dn ) throws Exception; 257 258 ClonedServerEntry lookup( LdapDN dn, String[] atIds ) throws Exception; 259 260 ClonedServerEntry lookup( LdapDN dn, Control[] requestControls, ReferralHandlingMode refMode, 261 LdapDN authorized ) throws Exception; 262 263 264 /** 265 * Modifies an entry within the server by applying a list of modifications 266 * to the entry. 267 * 268 * @param dn the distinguished name of the entry to modify 269 * @param mods the list of modifications to apply 270 * @throws Exception if there are failures while modifying the entry 271 */ 272 void modify( LdapDN dn, List<Modification> mods ) throws Exception; 273 274 275 void modify( ModifyRequest modifyRequest ) throws Exception; 276 277 278 /** 279 * Moves an entry or a branch of entries at a specified distinguished name 280 * to a position under a new parent. 281 * 282 * @param dn the distinguished name of the entry/branch to move 283 * @param newParent the new parent under which the entry/branch is moved 284 * @exception if there are failures while moving the entry/branch 285 */ 286 void move( LdapDN dn, LdapDN newParent ) throws Exception; 287 288 289 void move( ModifyDnRequest modifyDnRequest ) throws Exception; 290 291 292 // void move( LdapDN dn, LdapDN newParent, Control[] requestControls, ReferralHandlingMode refMode, 293 // LdapDN authorized ) throws Exception; 294 295 296 /** 297 * Moves and renames (the relative distinguished name of) an entry (or a 298 * branch if the entry has children) at a specified distinguished name to 299 * a position under a new parent. 300 * 301 * @param dn the distinguished name of the entry/branch to move 302 * @param newParent the new parent under which the entry/branch is moved 303 * @param newRdn the new relative distinguished name of the entry at the 304 * root of the branch 305 * @exception if there are failures while moving and renaming the entry 306 * or branch 307 */ 308 void moveAndRename( LdapDN dn, LdapDN newParent, Rdn newRdn, boolean deleteOldRdn ) throws Exception; 309 310 311 void moveAndRename( ModifyDnRequest modifyDnRequest ) throws Exception; 312 313 314 // void moveAndRename( LdapDN dn, LdapDN newParent, Rdn newRdn, boolean deleteOldRdn, 315 // Control[] requestControls, ReferralHandlingMode refMode, LdapDN authorized ) throws Exception; 316 317 318 /** 319 * Renames an entry by changing it's relative distinguished name. This 320 * has the side effect of changing the distinguished name of all entries 321 * directly or indirectly subordinate to the named entry if it has 322 * descendants. 323 * 324 * @param dn the distinguished name of the entry to rename 325 * @param newRdn the new relative distinguished name for the entry 326 * @param deleteOldRdn whether or not the old value for the relative 327 * distinguished name is to be deleted from the entry 328 * @throws Exception if there are failures while renaming the entry 329 */ 330 void rename( LdapDN dn, Rdn newRdn, boolean deleteOldRdn ) throws Exception; 331 332 333 void rename( ModifyDnRequest modifyDnRequest ) throws Exception; 334 335 336 // void rename( LdapDN dn, Rdn newRdn, boolean deleteOldRdn, 337 // Control[] requestControls, ReferralHandlingMode refMode, LdapDN authorized ) throws Exception; 338 339 340 /** 341 * An optimized search operation using one level search scope which 342 * returns all the children of an entry specified by distinguished name. 343 * This is equivalent to a search operation with one level scope using 344 * the <code>(objectClass=*)</code> filter. 345 * 346 * @param dn the distinguished name of the entry to list the children of 347 * @param aliasDerefMode the alias dereferencing mode used 348 * @param returningAttributes the attributes to return 349 * @throws Exception if there are failures while listing children 350 */ 351 EntryFilteringCursor list( LdapDN dn, AliasDerefMode aliasDerefMode, 352 Set<AttributeTypeOptions> returningAttributes ) throws Exception; 353 354 355 /** 356 * An optimized search operation using one level search scope which 357 * applies size and time limit constraints and returns all the children 358 * of an entry specified by distinguished name if thes limits are not 359 * violated. This is equivalent to a search operation with one level 360 * scope using the <code>(objectClass=*)</code> filter. 361 * 362 * @param dn the distinguished name of the entry to list the children of 363 * @param aliasDerefMode the alias dereferencing mode used 364 * @param returningAttributes the attributes to return 365 * @param sizeLimit the upper bound to the number of entries to return 366 * @param timeLimit the upper bound to the amount of time before 367 * terminating the search 368 * @throws Exception if there are failures while listing children 369 */ 370 EntryFilteringCursor list( LdapDN dn, AliasDerefMode aliasDerefMode, 371 Set<AttributeTypeOptions> returningAttributes, int sizeLimit, int timeLimit ) throws Exception; 372 373 374 /** 375 * Searches the directory using a specified search scope and filter. 376 * 377 * @param dn the distinguished name of the entry to list the children of 378 * @param scope the search scope to apply 379 * @param aliasDerefMode the alias dereferencing mode used 380 * @param returningAttributes the attributes to return 381 * @throws Exception if there are failures while listing children 382 */ 383 EntryFilteringCursor search( LdapDN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode, 384 Set<AttributeTypeOptions> returningAttributes ) throws Exception; 385 386 387 /** 388 * Searches the directory using a specified search scope and filter. 389 * 390 * @param dn the distinguished name of the entry to list the children of 391 * @param aliasDerefMode the alias dereferencing mode used 392 * @param returningAttributes the attributes to return 393 * @param sizeLimit the upper bound to the number of entries to return 394 * @param timeLimit the upper bound to the amount of time before 395 * terminating the search 396 * @throws Exception if there are failures while listing children 397 */ 398 EntryFilteringCursor search( LdapDN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode, 399 Set<AttributeTypeOptions> returningAttributes, int sizeLimit, int timeLimit ) throws Exception; 400 401 402 EntryFilteringCursor search( SearchRequest searchRequest ) throws Exception; 403 404 405 void unbind() throws Exception; 406 407 408 void unbind( UnbindRequest unbindRequest ) throws Exception; 409 }