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
26package javax.naming.directory;
27
28import 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
167public 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}
1040