1 /*
2 * Copyright (c) 1999, 2013, 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 * <h1>Names</h1>
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 * <h1>Attribute Models</h1>
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 * <h1>Attribute Type Names</h1>
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 *<h1>Operational Attributes</h1>
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 * <h1>Named Context</h1>
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 *<h1>Parameters</h1>
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 *<h1>Exceptions</h1>
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 }