1 /* 2 * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.naming.directory; 27 28 import javax.naming.*; 29 30 /** 31 * The directory service interface, containing 32 * methods for examining and updating attributes 33 * associated with objects, and for searching the directory. 34 * 35 * <h2>Names</h2> 36 * Each name passed as an argument to a {@code DirContext} method is relative 37 * to that context. The empty name is used to name the context itself. 38 * The name parameter may never be null. 39 * <p> 40 * Most of the methods have overloaded versions with one taking a 41 * <code>Name</code> parameter and one taking a <code>String</code>. 42 * These overloaded versions are equivalent in that if 43 * the <code>Name</code> and <code>String</code> parameters are just 44 * different representations of the same name, then the overloaded 45 * versions of the same methods behave the same. 46 * In the method descriptions below, only one version is documented. 47 * The second version instead has a link to the first: the same 48 * documentation applies to both. 49 * <p> 50 * See {@code Context} for a discussion on the interpretation of the 51 * name argument to the {@code Context} methods. These same rules 52 * apply to the name argument to the {@code DirContext} methods. 53 * 54 * <h2>Attribute Models</h2> 55 * There are two basic models of what attributes should be 56 * associated with. First, attributes may be directly associated with a 57 * DirContext object. 58 * In this model, an attribute operation on the named object is 59 * roughly equivalent 60 * to a lookup on the name (which returns the DirContext object), 61 * followed by the attribute operation invoked on the DirContext object 62 * in which the caller supplies an empty name. The attributes can be viewed 63 * as being stored along with the object (note that this does not imply that 64 * the implementation must do so). 65 * <p> 66 * The second model is that attributes are associated with a 67 * name (typically an atomic name) in a DirContext. 68 * In this model, an attribute operation on the named object is 69 * roughly equivalent to a lookup on the name of the parent DirContext of the 70 * named object, followed by the attribute operation invoked on the parent 71 * in which the caller supplies the terminal atomic name. 72 * The attributes can be viewed as being stored in the parent DirContext 73 * (again, this does not imply that the implementation must do so). 74 * Objects that are not DirContexts can have attributes, as long as 75 * their parents are DirContexts. 76 * <p> 77 * JNDI support both of these models. 78 * It is up to the individual service providers to decide where to 79 * "store" attributes. 80 * JNDI clients are safest when they do not make assumptions about 81 * whether an object's attributes are stored as part of the object, or stored 82 * within the parent object and associated with the object's name. 83 * 84 * <h2>Attribute Type Names</h2> 85 * In the {@code getAttributes()} and {@code search()} methods, 86 * you can supply the attributes to return by supplying a list of 87 * attribute names (strings). 88 * The attributes that you get back might not have the same names as the 89 * attribute names you have specified. This is because some directories 90 * support features that cause them to return other attributes. Such 91 * features include attribute subclassing, attribute name synonyms, and 92 * attribute language codes. 93 * <p> 94 * In attribute subclassing, attributes are defined in a class hierarchy. 95 * In some directories, for example, the "name" attribute might be the 96 * superclass of all name-related attributes, including "commonName" and 97 * "surName". Asking for the "name" attribute might return both the 98 * "commonName" and "surName" attributes. 99 * <p> 100 * With attribute type synonyms, a directory can assign multiple names to 101 * the same attribute. For example, "cn" and "commonName" might both 102 * refer to the same attribute. Asking for "cn" might return the 103 * "commonName" attribute. 104 * <p> 105 * Some directories support the language codes for attributes. 106 * Asking such a directory for the "description" attribute, for example, 107 * might return all of the following attributes: 108 * <ul> 109 * <li>description 110 * <li>description;lang-en 111 * <li>description;lang-de 112 * <li>description;lang-fr 113 * </ul> 114 * 115 * 116 *<h2>Operational Attributes</h2> 117 *<p> 118 * Some directories have the notion of "operational attributes" which are 119 * attributes associated with a directory object for administrative 120 * purposes. An example of operational attributes is the access control 121 * list for an object. 122 * <p> 123 * In the {@code getAttributes()} and {@code search()} methods, 124 * you can specify that all attributes associated with the requested objects 125 * be returned by supply {@code null} as the list of attributes to return. 126 * The attributes returned do <em>not</em> include operational attributes. 127 * In order to retrieve operational attributes, you must name them explicitly. 128 * 129 * 130 * <h2>Named Context</h2> 131 * <p> 132 * There are certain methods in which the name must resolve to a context 133 * (for example, when searching a single level context). The documentation 134 * of such methods 135 * use the term <em>named context</em> to describe their name parameter. 136 * For these methods, if the named object is not a DirContext, 137 * <code>NotContextException</code> is thrown. 138 * Aside from these methods, there is no requirement that the 139 * <em>named object</em> be a DirContext. 140 * 141 *<h2>Parameters</h2> 142 *<p> 143 * An {@code Attributes}, {@code SearchControls}, or array object 144 * passed as a parameter to any method will not be modified by the 145 * service provider. The service provider may keep a reference to it 146 * for the duration of the operation, including any enumeration of the 147 * method's results and the processing of any referrals generated. 148 * The caller should not modify the object during this time. 149 * An {@code Attributes} object returned by any method is owned by 150 * the caller. The caller may subsequently modify it; the service 151 * provider will not. 152 * 153 *<h2>Exceptions</h2> 154 *<p> 155 * All the methods in this interface can throw a NamingException or 156 * any of its subclasses. See NamingException and their subclasses 157 * for details on each exception. 158 * 159 * @author Rosanna Lee 160 * @author Scott Seligman 161 * @author R. Vasudevan 162 * 163 * @see javax.naming.Context 164 * @since 1.3 165 */ 166 167 public interface DirContext extends Context { 168 169 /** 170 * Retrieves all of the attributes associated with a named object. 171 * See the class description regarding attribute models, attribute 172 * type names, and operational attributes. 173 * 174 * @param name 175 * the name of the object from which to retrieve attributes 176 * @return the set of attributes associated with <code>name</code>. 177 * Returns an empty attribute set if name has no attributes; 178 * never null. 179 * @throws NamingException if a naming exception is encountered 180 * 181 * @see #getAttributes(String) 182 * @see #getAttributes(Name, String[]) 183 */ 184 public Attributes getAttributes(Name name) throws NamingException; 185 186 /** 187 * Retrieves all of the attributes associated with a named object. 188 * See {@link #getAttributes(Name)} for details. 189 * 190 * @param name 191 * the name of the object from which to retrieve attributes 192 * @return the set of attributes associated with <code>name</code> 193 * 194 * @throws NamingException if a naming exception is encountered 195 */ 196 public Attributes getAttributes(String name) throws NamingException; 197 198 /** 199 * Retrieves selected attributes associated with a named object. 200 * See the class description regarding attribute models, attribute 201 * type names, and operational attributes. 202 * 203 * <p> If the object does not have an attribute 204 * specified, the directory will ignore the nonexistent attribute 205 * and return those requested attributes that the object does have. 206 * 207 * <p> A directory might return more attributes than was requested 208 * (see <strong>Attribute Type Names</strong> in the class description), 209 * but is not allowed to return arbitrary, unrelated attributes. 210 * 211 * <p> See also <strong>Operational Attributes</strong> in the class 212 * description. 213 * 214 * @param name 215 * the name of the object from which to retrieve attributes 216 * @param attrIds 217 * the identifiers of the attributes to retrieve. 218 * null indicates that all attributes should be retrieved; 219 * an empty array indicates that none should be retrieved. 220 * @return the requested attributes; never null 221 * 222 * @throws NamingException if a naming exception is encountered 223 */ 224 public Attributes getAttributes(Name name, String[] attrIds) 225 throws NamingException; 226 227 /** 228 * Retrieves selected attributes associated with a named object. 229 * See {@link #getAttributes(Name, String[])} for details. 230 * 231 * @param name 232 * The name of the object from which to retrieve attributes 233 * @param attrIds 234 * the identifiers of the attributes to retrieve. 235 * null indicates that all attributes should be retrieved; 236 * an empty array indicates that none should be retrieved. 237 * @return the requested attributes; never null 238 * 239 * @throws NamingException if a naming exception is encountered 240 */ 241 public Attributes getAttributes(String name, String[] attrIds) 242 throws NamingException; 243 244 /** 245 * This constant specifies to add an attribute with the specified values. 246 * <p> 247 * If attribute does not exist, 248 * create the attribute. The resulting attribute has a union of the 249 * specified value set and the prior value set. 250 * Adding an attribute with no value will throw 251 * <code>InvalidAttributeValueException</code> if the attribute must have 252 * at least one value. For a single-valued attribute where that attribute 253 * already exists, throws <code>AttributeInUseException</code>. 254 * If attempting to add more than one value to a single-valued attribute, 255 * throws <code>InvalidAttributeValueException</code>. 256 * <p> 257 * The value of this constant is {@code 1}. 258 * 259 * @see ModificationItem 260 * @see #modifyAttributes 261 */ 262 public final static int ADD_ATTRIBUTE = 1; 263 264 /** 265 * This constant specifies to replace an attribute with specified values. 266 *<p> 267 * If attribute already exists, 268 * replaces all existing values with new specified values. If the 269 * attribute does not exist, creates it. If no value is specified, 270 * deletes all the values of the attribute. 271 * Removal of the last value will remove the attribute if the attribute 272 * is required to have at least one value. If 273 * attempting to add more than one value to a single-valued attribute, 274 * throws <code>InvalidAttributeValueException</code>. 275 * <p> 276 * The value of this constant is {@code 2}. 277 * 278 * @see ModificationItem 279 * @see #modifyAttributes 280 */ 281 public final static int REPLACE_ATTRIBUTE = 2; 282 283 /** 284 * This constant specifies to delete 285 * the specified attribute values from the attribute. 286 *<p> 287 * The resulting attribute has the set difference of its prior value set 288 * and the specified value set. 289 * If no values are specified, deletes the entire attribute. 290 * If the attribute does not exist, or if some or all members of the 291 * specified value set do not exist, this absence may be ignored 292 * and the operation succeeds, or a NamingException may be thrown to 293 * indicate the absence. 294 * Removal of the last value will remove the attribute if the 295 * attribute is required to have at least one value. 296 * <p> 297 * The value of this constant is {@code 3}. 298 * 299 * @see ModificationItem 300 * @see #modifyAttributes 301 */ 302 public final static int REMOVE_ATTRIBUTE = 3; 303 304 /** 305 * Modifies the attributes associated with a named object. 306 * The order of the modifications is not specified. Where 307 * possible, the modifications are performed atomically. 308 * 309 * @param name 310 * the name of the object whose attributes will be updated 311 * @param mod_op 312 * the modification operation, one of: 313 * <code>ADD_ATTRIBUTE</code>, 314 * <code>REPLACE_ATTRIBUTE</code>, 315 * <code>REMOVE_ATTRIBUTE</code>. 316 * @param attrs 317 * the attributes to be used for the modification; may not be null 318 * 319 * @throws AttributeModificationException if the modification cannot 320 * be completed successfully 321 * @throws NamingException if a naming exception is encountered 322 * 323 * @see #modifyAttributes(Name, ModificationItem[]) 324 */ 325 public void modifyAttributes(Name name, int mod_op, Attributes attrs) 326 throws NamingException; 327 328 /** 329 * Modifies the attributes associated with a named object. 330 * See {@link #modifyAttributes(Name, int, Attributes)} for details. 331 * 332 * @param name 333 * the name of the object whose attributes will be updated 334 * @param mod_op 335 * the modification operation, one of: 336 * <code>ADD_ATTRIBUTE</code>, 337 * <code>REPLACE_ATTRIBUTE</code>, 338 * <code>REMOVE_ATTRIBUTE</code>. 339 * @param attrs 340 * the attributes to be used for the modification; may not be null 341 * 342 * @throws AttributeModificationException if the modification cannot 343 * be completed successfully 344 * @throws NamingException if a naming exception is encountered 345 */ 346 public void modifyAttributes(String name, int mod_op, Attributes attrs) 347 throws NamingException; 348 349 /** 350 * Modifies the attributes associated with a named object using 351 * an ordered list of modifications. 352 * The modifications are performed 353 * in the order specified. Each modification specifies a 354 * modification operation code and an attribute on which to 355 * operate. Where possible, the modifications are 356 * performed atomically. 357 * 358 * @param name 359 * the name of the object whose attributes will be updated 360 * @param mods 361 * an ordered sequence of modifications to be performed; 362 * may not be null 363 * 364 * @throws AttributeModificationException if the modifications 365 * cannot be completed successfully 366 * @throws NamingException if a naming exception is encountered 367 * 368 * @see #modifyAttributes(Name, int, Attributes) 369 * @see ModificationItem 370 */ 371 public void modifyAttributes(Name name, ModificationItem[] mods) 372 throws NamingException; 373 374 /** 375 * Modifies the attributes associated with a named object using 376 * an ordered list of modifications. 377 * See {@link #modifyAttributes(Name, ModificationItem[])} for details. 378 * 379 * @param name 380 * the name of the object whose attributes will be updated 381 * @param mods 382 * an ordered sequence of modifications to be performed; 383 * may not be null 384 * 385 * @throws AttributeModificationException if the modifications 386 * cannot be completed successfully 387 * @throws NamingException if a naming exception is encountered 388 */ 389 public void modifyAttributes(String name, ModificationItem[] mods) 390 throws NamingException; 391 392 /** 393 * Binds a name to an object, along with associated attributes. 394 * If {@code attrs} is null, the resulting binding will have 395 * the attributes associated with {@code obj} if {@code obj} is a 396 * {@code DirContext}, and no attributes otherwise. 397 * If {@code attrs} is non-null, the resulting binding will have 398 * {@code attrs} as its attributes; any attributes associated with 399 * {@code obj} are ignored. 400 * 401 * @param name 402 * the name to bind; may not be empty 403 * @param obj 404 * the object to bind; possibly null 405 * @param attrs 406 * the attributes to associate with the binding 407 * 408 * @throws NameAlreadyBoundException if name is already bound 409 * @throws InvalidAttributesException if some "mandatory" attributes 410 * of the binding are not supplied 411 * @throws NamingException if a naming exception is encountered 412 * 413 * @see Context#bind(Name, Object) 414 * @see #rebind(Name, Object, Attributes) 415 */ 416 public void bind(Name name, Object obj, Attributes attrs) 417 throws NamingException; 418 419 /** 420 * Binds a name to an object, along with associated attributes. 421 * See {@link #bind(Name, Object, Attributes)} for details. 422 * 423 * @param name 424 * the name to bind; may not be empty 425 * @param obj 426 * the object to bind; possibly null 427 * @param attrs 428 * the attributes to associate with the binding 429 * 430 * @throws NameAlreadyBoundException if name is already bound 431 * @throws InvalidAttributesException if some "mandatory" attributes 432 * of the binding are not supplied 433 * @throws NamingException if a naming exception is encountered 434 */ 435 public void bind(String name, Object obj, Attributes attrs) 436 throws NamingException; 437 438 /** 439 * Binds a name to an object, along with associated attributes, 440 * overwriting any existing binding. 441 * If {@code attrs} is null and {@code obj} is a {@code DirContext}, 442 * the attributes from {@code obj} are used. 443 * If {@code attrs} is null and {@code obj} is not a {@code DirContext}, 444 * any existing attributes associated with the object already bound 445 * in the directory remain unchanged. 446 * If {@code attrs} is non-null, any existing attributes associated with 447 * the object already bound in the directory are removed and {@code attrs} 448 * is associated with the named object. If {@code obj} is a 449 * {@code DirContext} and {@code attrs} is non-null, the attributes 450 * of {@code obj} are ignored. 451 * 452 * @param name 453 * the name to bind; may not be empty 454 * @param obj 455 * the object to bind; possibly null 456 * @param attrs 457 * the attributes to associate with the binding 458 * 459 * @throws InvalidAttributesException if some "mandatory" attributes 460 * of the binding are not supplied 461 * @throws NamingException if a naming exception is encountered 462 * 463 * @see Context#bind(Name, Object) 464 * @see #bind(Name, Object, Attributes) 465 */ 466 public void rebind(Name name, Object obj, Attributes attrs) 467 throws NamingException; 468 469 /** 470 * Binds a name to an object, along with associated attributes, 471 * overwriting any existing binding. 472 * See {@link #rebind(Name, Object, Attributes)} for details. 473 * 474 * @param name 475 * the name to bind; may not be empty 476 * @param obj 477 * the object to bind; possibly null 478 * @param attrs 479 * the attributes to associate with the binding 480 * 481 * @throws InvalidAttributesException if some "mandatory" attributes 482 * of the binding are not supplied 483 * @throws NamingException if a naming exception is encountered 484 */ 485 public void rebind(String name, Object obj, Attributes attrs) 486 throws NamingException; 487 488 /** 489 * Creates and binds a new context, along with associated attributes. 490 * This method creates a new subcontext with the given name, binds it in 491 * the target context (that named by all but terminal atomic 492 * component of the name), and associates the supplied attributes 493 * with the newly created object. 494 * All intermediate and target contexts must already exist. 495 * If {@code attrs} is null, this method is equivalent to 496 * {@code Context.createSubcontext()}. 497 * 498 * @param name 499 * the name of the context to create; may not be empty 500 * @param attrs 501 * the attributes to associate with the newly created context 502 * @return the newly created context 503 * 504 * @throws NameAlreadyBoundException if the name is already bound 505 * @throws InvalidAttributesException if <code>attrs</code> does not 506 * contain all the mandatory attributes required for creation 507 * @throws NamingException if a naming exception is encountered 508 * 509 * @see Context#createSubcontext(Name) 510 */ 511 public DirContext createSubcontext(Name name, Attributes attrs) 512 throws NamingException; 513 514 /** 515 * Creates and binds a new context, along with associated attributes. 516 * See {@link #createSubcontext(Name, Attributes)} for details. 517 * 518 * @param name 519 * the name of the context to create; may not be empty 520 * @param attrs 521 * the attributes to associate with the newly created context 522 * @return the newly created context 523 * 524 * @throws NameAlreadyBoundException if the name is already bound 525 * @throws InvalidAttributesException if <code>attrs</code> does not 526 * contain all the mandatory attributes required for creation 527 * @throws NamingException if a naming exception is encountered 528 */ 529 public DirContext createSubcontext(String name, Attributes attrs) 530 throws NamingException; 531 532 // -------------------- schema operations 533 534 /** 535 * Retrieves the schema associated with the named object. 536 * The schema describes rules regarding the structure of the namespace 537 * and the attributes stored within it. The schema 538 * specifies what types of objects can be added to the directory and where 539 * they can be added; what mandatory and optional attributes an object 540 * can have. The range of support for schemas is directory-specific. 541 * 542 * <p> This method returns the root of the schema information tree 543 * that is applicable to the named object. Several named objects 544 * (or even an entire directory) might share the same schema. 545 * 546 * <p> Issues such as structure and contents of the schema tree, 547 * permission to modify to the contents of the schema 548 * tree, and the effect of such modifications on the directory 549 * are dependent on the underlying directory. 550 * 551 * @param name 552 * the name of the object whose schema is to be retrieved 553 * @return the schema associated with the context; never null 554 * @throws OperationNotSupportedException if schema not supported 555 * @throws NamingException if a naming exception is encountered 556 */ 557 public DirContext getSchema(Name name) throws NamingException; 558 559 /** 560 * Retrieves the schema associated with the named object. 561 * See {@link #getSchema(Name)} for details. 562 * 563 * @param name 564 * the name of the object whose schema is to be retrieved 565 * @return the schema associated with the context; never null 566 * @throws OperationNotSupportedException if schema not supported 567 * @throws NamingException if a naming exception is encountered 568 */ 569 public DirContext getSchema(String name) throws NamingException; 570 571 /** 572 * Retrieves a context containing the schema objects of the 573 * named object's class definitions. 574 *<p> 575 * One category of information found in directory schemas is 576 * <em>class definitions</em>. An "object class" definition 577 * specifies the object's <em>type</em> and what attributes (mandatory 578 * and optional) the object must/can have. Note that the term 579 * "object class" being referred to here is in the directory sense 580 * rather than in the Java sense. 581 * For example, if the named object is a directory object of 582 * "Person" class, {@code getSchemaClassDefinition()} would return a 583 * {@code DirContext} representing the (directory's) object class 584 * definition of "Person". 585 *<p> 586 * The information that can be retrieved from an object class definition 587 * is directory-dependent. 588 *<p> 589 * Prior to JNDI 1.2, this method 590 * returned a single schema object representing the class definition of 591 * the named object. 592 * Since JNDI 1.2, this method returns a {@code DirContext} containing 593 * all of the named object's class definitions. 594 * 595 * @param name 596 * the name of the object whose object class 597 * definition is to be retrieved 598 * @return the {@code DirContext} containing the named 599 * object's class definitions; never null 600 * 601 * @throws OperationNotSupportedException if schema not supported 602 * @throws NamingException if a naming exception is encountered 603 */ 604 public DirContext getSchemaClassDefinition(Name name) 605 throws NamingException; 606 607 /** 608 * Retrieves a context containing the schema objects of the 609 * named object's class definitions. 610 * See {@link #getSchemaClassDefinition(Name)} for details. 611 * 612 * @param name 613 * the name of the object whose object class 614 * definition is to be retrieved 615 * @return the {@code DirContext} containing the named 616 * object's class definitions; never null 617 * 618 * @throws OperationNotSupportedException if schema not supported 619 * @throws NamingException if a naming exception is encountered 620 */ 621 public DirContext getSchemaClassDefinition(String name) 622 throws NamingException; 623 624 // -------------------- search operations 625 626 /** 627 * Searches in a single context for objects that contain a 628 * specified set of attributes, and retrieves selected attributes. 629 * The search is performed using the default 630 * <code>SearchControls</code> settings. 631 * <p> 632 * For an object to be selected, each attribute in 633 * <code>matchingAttributes</code> must match some attribute of the 634 * object. If <code>matchingAttributes</code> is empty or 635 * null, all objects in the target context are returned. 636 *<p> 637 * An attribute <em>A</em><sub>1</sub> in 638 * <code>matchingAttributes</code> is considered to match an 639 * attribute <em>A</em><sub>2</sub> of an object if 640 * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same 641 * identifier, and each value of <em>A</em><sub>1</sub> is equal 642 * to some value of <em>A</em><sub>2</sub>. This implies that the 643 * order of values is not significant, and that 644 * <em>A</em><sub>2</sub> may contain "extra" values not found in 645 * <em>A</em><sub>1</sub> without affecting the comparison. It 646 * also implies that if <em>A</em><sub>1</sub> has no values, then 647 * testing for a match is equivalent to testing for the presence 648 * of an attribute <em>A</em><sub>2</sub> with the same 649 * identifier. 650 *<p> 651 * The precise definition of "equality" used in comparing attribute values 652 * is defined by the underlying directory service. It might use the 653 * <code>Object.equals</code> method, for example, or might use a schema 654 * to specify a different equality operation. 655 * For matching based on operations other than equality (such as 656 * substring comparison) use the version of the <code>search</code> 657 * method that takes a filter argument. 658 * <p> 659 * When changes are made to this {@code DirContext}, 660 * the effect on enumerations returned by prior calls to this method 661 * is undefined. 662 *<p> 663 * If the object does not have the attribute 664 * specified, the directory will ignore the nonexistent attribute 665 * and return the requested attributes that the object does have. 666 *<p> 667 * A directory might return more attributes than was requested 668 * (see <strong>Attribute Type Names</strong> in the class description), 669 * but is not allowed to return arbitrary, unrelated attributes. 670 *<p> 671 * See also <strong>Operational Attributes</strong> in the class 672 * description. 673 * 674 * @param name 675 * the name of the context to search 676 * @param matchingAttributes 677 * the attributes to search for. If empty or null, 678 * all objects in the target context are returned. 679 * @param attributesToReturn 680 * the attributes to return. null indicates that 681 * all attributes are to be returned; 682 * an empty array indicates that none are to be returned. 683 * @return 684 * a non-null enumeration of {@code SearchResult} objects. 685 * Each {@code SearchResult} contains the attributes 686 * identified by <code>attributesToReturn</code> 687 * and the name of the corresponding object, named relative 688 * to the context named by <code>name</code>. 689 * @throws NamingException if a naming exception is encountered 690 * 691 * @see SearchControls 692 * @see SearchResult 693 * @see #search(Name, String, Object[], SearchControls) 694 */ 695 public NamingEnumeration<SearchResult> 696 search(Name name, 697 Attributes matchingAttributes, 698 String[] attributesToReturn) 699 throws NamingException; 700 701 /** 702 * Searches in a single context for objects that contain a 703 * specified set of attributes, and retrieves selected attributes. 704 * See {@link #search(Name, Attributes, String[])} for details. 705 * 706 * @param name 707 * the name of the context to search 708 * @param matchingAttributes 709 * the attributes to search for 710 * @param attributesToReturn 711 * the attributes to return 712 * @return a non-null enumeration of {@code SearchResult} objects 713 * @throws NamingException if a naming exception is encountered 714 */ 715 public NamingEnumeration<SearchResult> 716 search(String name, 717 Attributes matchingAttributes, 718 String[] attributesToReturn) 719 throws NamingException; 720 721 /** 722 * Searches in a single context for objects that contain a 723 * specified set of attributes. 724 * This method returns all the attributes of such objects. 725 * It is equivalent to supplying null as 726 * the {@code attributesToReturn} parameter to the method 727 * <code>search(Name, Attributes, String[])</code>. 728 * <br> 729 * See {@link #search(Name, Attributes, String[])} for a full description. 730 * 731 * @param name 732 * the name of the context to search 733 * @param matchingAttributes 734 * the attributes to search for 735 * @return an enumeration of {@code SearchResult} objects 736 * @throws NamingException if a naming exception is encountered 737 * 738 * @see #search(Name, Attributes, String[]) 739 */ 740 public NamingEnumeration<SearchResult> 741 search(Name name, Attributes matchingAttributes) 742 throws NamingException; 743 744 /** 745 * Searches in a single context for objects that contain a 746 * specified set of attributes. 747 * See {@link #search(Name, Attributes)} for details. 748 * 749 * @param name 750 * the name of the context to search 751 * @param matchingAttributes 752 * the attributes to search for 753 * @return an enumeration of {@code SearchResult} objects 754 * @throws NamingException if a naming exception is encountered 755 */ 756 public NamingEnumeration<SearchResult> 757 search(String name, Attributes matchingAttributes) 758 throws NamingException; 759 760 /** 761 * Searches in the named context or object for entries that satisfy the 762 * given search filter. Performs the search as specified by 763 * the search controls. 764 * <p> 765 * The format and interpretation of <code>filter</code> follows RFC 2254 766 * with the 767 * following interpretations for <code>attr</code> and <code>value</code> 768 * mentioned in the RFC. 769 * <p> 770 * <code>attr</code> is the attribute's identifier. 771 * <p> 772 * <code>value</code> is the string representation the attribute's value. 773 * The translation of this string representation into the attribute's value 774 * is directory-specific. 775 * <p> 776 * For the assertion "someCount=127", for example, <code>attr</code> 777 * is "someCount" and <code>value</code> is "127". 778 * The provider determines, based on the attribute ID ("someCount") 779 * (and possibly its schema), that the attribute's value is an integer. 780 * It then parses the string "127" appropriately. 781 *<p> 782 * Any non-ASCII characters in the filter string should be 783 * represented by the appropriate Java (Unicode) characters, and 784 * not encoded as UTF-8 octets. Alternately, the 785 * "backslash-hexcode" notation described in RFC 2254 may be used. 786 *<p> 787 * If the directory does not support a string representation of 788 * some or all of its attributes, the form of <code>search</code> that 789 * accepts filter arguments in the form of Objects can be used instead. 790 * The service provider for such a directory would then translate 791 * the filter arguments to its service-specific representation 792 * for filter evaluation. 793 * See <code>search(Name, String, Object[], SearchControls)</code>. 794 * <p> 795 * RFC 2254 defines certain operators for the filter, including substring 796 * matches, equality, approximate match, greater than, less than. These 797 * operators are mapped to operators with corresponding semantics in the 798 * underlying directory. For example, for the equals operator, suppose 799 * the directory has a matching rule defining "equality" of the 800 * attributes in the filter. This rule would be used for checking 801 * equality of the attributes specified in the filter with the attributes 802 * of objects in the directory. Similarly, if the directory has a 803 * matching rule for ordering, this rule would be used for 804 * making "greater than" and "less than" comparisons. 805 *<p> 806 * Not all of the operators defined in RFC 2254 are applicable to all 807 * attributes. When an operator is not applicable, the exception 808 * <code>InvalidSearchFilterException</code> is thrown. 809 * <p> 810 * The result is returned in an enumeration of {@code SearchResult}s. 811 * Each {@code SearchResult} contains the name of the object 812 * and other information about the object (see SearchResult). 813 * The name is either relative to the target context of the search 814 * (which is named by the <code>name</code> parameter), or 815 * it is a URL string. If the target context is included in 816 * the enumeration (as is possible when 817 * <code>cons</code> specifies a search scope of 818 * <code>SearchControls.OBJECT_SCOPE</code> or 819 * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty 820 * string. The {@code SearchResult} may also contain attributes of the 821 * matching object if the {@code cons} argument specified that attributes 822 * be returned. 823 *<p> 824 * If the object does not have a requested attribute, that 825 * nonexistent attribute will be ignored. Those requested 826 * attributes that the object does have will be returned. 827 *<p> 828 * A directory might return more attributes than were requested 829 * (see <strong>Attribute Type Names</strong> in the class description) 830 * but is not allowed to return arbitrary, unrelated attributes. 831 *<p> 832 * See also <strong>Operational Attributes</strong> in the class 833 * description. 834 * 835 * @param name 836 * the name of the context or object to search 837 * @param filter 838 * the filter expression to use for the search; may not be null 839 * @param cons 840 * the search controls that control the search. If null, 841 * the default search controls are used (equivalent 842 * to {@code (new SearchControls())}). 843 * @return an enumeration of {@code SearchResult}s of 844 * the objects that satisfy the filter; never null 845 * 846 * @throws InvalidSearchFilterException if the search filter specified is 847 * not supported or understood by the underlying directory 848 * @throws InvalidSearchControlsException if the search controls 849 * contain invalid settings 850 * @throws NamingException if a naming exception is encountered 851 * 852 * @see #search(Name, String, Object[], SearchControls) 853 * @see SearchControls 854 * @see SearchResult 855 */ 856 public NamingEnumeration<SearchResult> 857 search(Name name, 858 String filter, 859 SearchControls cons) 860 throws NamingException; 861 862 /** 863 * Searches in the named context or object for entries that satisfy the 864 * given search filter. Performs the search as specified by 865 * the search controls. 866 * See {@link #search(Name, String, SearchControls)} for details. 867 * 868 * @param name 869 * the name of the context or object to search 870 * @param filter 871 * the filter expression to use for the search; may not be null 872 * @param cons 873 * the search controls that control the search. If null, 874 * the default search controls are used (equivalent 875 * to {@code (new SearchControls())}). 876 * 877 * @return an enumeration of {@code SearchResult}s for 878 * the objects that satisfy the filter. 879 * @throws InvalidSearchFilterException if the search filter specified is 880 * not supported or understood by the underlying directory 881 * @throws InvalidSearchControlsException if the search controls 882 * contain invalid settings 883 * @throws NamingException if a naming exception is encountered 884 */ 885 public NamingEnumeration<SearchResult> 886 search(String name, 887 String filter, 888 SearchControls cons) 889 throws NamingException; 890 891 /** 892 * Searches in the named context or object for entries that satisfy the 893 * given search filter. Performs the search as specified by 894 * the search controls. 895 *<p> 896 * The interpretation of <code>filterExpr</code> is based on RFC 897 * 2254. It may additionally contain variables of the form 898 * <code>{i}</code> -- where <code>i</code> is an integer -- that 899 * refer to objects in the <code>filterArgs</code> array. The 900 * interpretation of <code>filterExpr</code> is otherwise 901 * identical to that of the <code>filter</code> parameter of the 902 * method <code>search(Name, String, SearchControls)</code>. 903 *<p> 904 * When a variable <code>{i}</code> appears in a search filter, it 905 * indicates that the filter argument <code>filterArgs[i]</code> 906 * is to be used in that place. Such variables may be used 907 * wherever an <em>attr</em>, <em>value</em>, or 908 * <em>matchingrule</em> production appears in the filter grammar 909 * of RFC 2254, section 4. When a string-valued filter argument 910 * is substituted for a variable, the filter is interpreted as if 911 * the string were given in place of the variable, with any 912 * characters having special significance within filters (such as 913 * <code>'*'</code>) having been escaped according to the rules of 914 * RFC 2254. 915 *<p> 916 * For directories that do not use a string representation for 917 * some or all of their attributes, the filter argument 918 * corresponding to an attribute value may be of a type other than 919 * String. Directories that support unstructured binary-valued 920 * attributes, for example, should accept byte arrays as filter 921 * arguments. The interpretation (if any) of filter arguments of 922 * any other type is determined by the service provider for that 923 * directory, which maps the filter operations onto operations with 924 * corresponding semantics in the underlying directory. 925 *<p> 926 * This method returns an enumeration of the results. 927 * Each element in the enumeration contains the name of the object 928 * and other information about the object (see <code>SearchResult</code>). 929 * The name is either relative to the target context of the search 930 * (which is named by the <code>name</code> parameter), or 931 * it is a URL string. If the target context is included in 932 * the enumeration (as is possible when 933 * <code>cons</code> specifies a search scope of 934 * <code>SearchControls.OBJECT_SCOPE</code> or 935 * <code>SearchControls.SUBSTREE_SCOPE</code>), 936 * its name is the empty string. 937 *<p> 938 * The {@code SearchResult} may also contain attributes of the matching 939 * object if the {@code cons} argument specifies that attributes be 940 * returned. 941 *<p> 942 * If the object does not have a requested attribute, that 943 * nonexistent attribute will be ignored. Those requested 944 * attributes that the object does have will be returned. 945 *<p> 946 * A directory might return more attributes than were requested 947 * (see <strong>Attribute Type Names</strong> in the class description) 948 * but is not allowed to return arbitrary, unrelated attributes. 949 *<p> 950 * If a search filter with invalid variable substitutions is provided 951 * to this method, the result is undefined. 952 * When changes are made to this DirContext, 953 * the effect on enumerations returned by prior calls to this method 954 * is undefined. 955 *<p> 956 * See also <strong>Operational Attributes</strong> in the class 957 * description. 958 * 959 * @param name 960 * the name of the context or object to search 961 * @param filterExpr 962 * the filter expression to use for the search. 963 * The expression may contain variables of the 964 * form "<code>{i}</code>" where <code>i</code> 965 * is a nonnegative integer. May not be null. 966 * @param filterArgs 967 * the array of arguments to substitute for the variables 968 * in <code>filterExpr</code>. The value of 969 * <code>filterArgs[i]</code> will replace each 970 * occurrence of "<code>{i}</code>". 971 * If null, equivalent to an empty array. 972 * @param cons 973 * the search controls that control the search. If null, 974 * the default search controls are used (equivalent 975 * to {@code (new SearchControls())}). 976 * @return an enumeration of {@code SearchResult}s of the objects 977 * that satisfy the filter; never null 978 * 979 * @throws ArrayIndexOutOfBoundsException if {@code filterExpr} contains 980 * <code>{i}</code> expressions where <code>i</code> is outside 981 * the bounds of the array <code>filterArgs</code> 982 * @throws InvalidSearchControlsException if {@code cons} contains 983 * invalid settings 984 * @throws InvalidSearchFilterException if {@code filterExpr} with 985 * {@code filterArgs} represents an invalid search filter 986 * @throws NamingException if a naming exception is encountered 987 * 988 * @see #search(Name, Attributes, String[]) 989 * @see java.text.MessageFormat 990 */ 991 public NamingEnumeration<SearchResult> 992 search(Name name, 993 String filterExpr, 994 Object[] filterArgs, 995 SearchControls cons) 996 throws NamingException; 997 998 /** 999 * Searches in the named context or object for entries that satisfy the 1000 * given search filter. Performs the search as specified by 1001 * the search controls. 1002 * See {@link #search(Name, String, Object[], SearchControls)} for details. 1003 * 1004 * @param name 1005 * the name of the context or object to search 1006 * @param filterExpr 1007 * the filter expression to use for the search. 1008 * The expression may contain variables of the 1009 * form "<code>{i}</code>" where <code>i</code> 1010 * is a nonnegative integer. May not be null. 1011 * @param filterArgs 1012 * the array of arguments to substitute for the variables 1013 * in <code>filterExpr</code>. The value of 1014 * <code>filterArgs[i]</code> will replace each 1015 * occurrence of "<code>{i}</code>". 1016 * If null, equivalent to an empty array. 1017 * @param cons 1018 * the search controls that control the search. If null, 1019 * the default search controls are used (equivalent 1020 * to {@code (new SearchControls())}). 1021 * @return an enumeration of {@code SearchResult}s of the objects 1022 * that satisfy the filter; never null 1023 * 1024 * @throws ArrayIndexOutOfBoundsException if {@code filterExpr} contains 1025 * <code>{i}</code> expressions where <code>i</code> is outside 1026 * the bounds of the array <code>filterArgs</code> 1027 * @throws InvalidSearchControlsException if {@code cons} contains 1028 * invalid settings 1029 * @throws InvalidSearchFilterException if {@code filterExpr} with 1030 * {@code filterArgs} represents an invalid search filter 1031 * @throws NamingException if a naming exception is encountered 1032 */ 1033 public NamingEnumeration<SearchResult> 1034 search(String name, 1035 String filterExpr, 1036 Object[] filterArgs, 1037 SearchControls cons) 1038 throws NamingException; 1039 }