View Javadoc
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 <tt>DirContext</tt> 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 <tt>Context</tt> for a discussion on the interpretation of the
51   * name argument to the <tt>Context</tt> methods. These same rules
52   * apply to the name argument to the <tt>DirContext</tt> 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 <tt>getAttributes()</tt> and <tt>search()</tt> 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 <tt>getAttributes()</tt> and <tt>search()</tt> methods,
124  * you can specify that all attributes associated with the requested objects
125  * be returned by supply <tt>null</tt> 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 <tt>Attributes</tt>, <tt>SearchControls</tt>, 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 <tt>Attributes</tt> 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 <tt>1</tt>.
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 <tt>2</tt>.
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 <tt>3</tt>.
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 <tt>attrs</tt> is null, the resulting binding will have
395      * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a
396      * <tt>DirContext</tt>, and no attributes otherwise.
397      * If <tt>attrs</tt> is non-null, the resulting binding will have
398      * <tt>attrs</tt> as its attributes; any attributes associated with
399      * <tt>obj</tt> 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 <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,
442      * the attributes from <tt>obj</tt> are used.
443      * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,
444      * any existing attributes associated with the object already bound
445      * in the directory remain unchanged.
446      * If <tt>attrs</tt> is non-null, any existing attributes associated with
447      * the object already bound in the directory are removed and <tt>attrs</tt>
448      * is associated with the named object.  If <tt>obj</tt> is a
449      * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes
450      * of <tt>obj</tt> 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 <tt>attrs</tt> is null, this method is equivalent to
496      * <tt>Context.createSubcontext()</tt>.
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, <tt>getSchemaClassDefinition()</tt> would return a
583      * <tt>DirContext</tt> 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 <tt>DirContext</tt> 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 <tt>DirContext</tt> 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 <tt>DirContext</tt> 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 <tt>DirContext</tt>,
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 <tt>SearchResult</tt> objects.
685      *          Each <tt>SearchResult</tt> 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 <tt>SearchResult</tt> 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 <tt>atributesToReturn</tt> 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 <tt>SearchResult</tt> 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 <tt>SearchResult</tt> 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 <tt>SearchResult</tt>s.
811      * Each <tt>SearchResult</tt> 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 <tt>SearchResult</tt> may also contain attributes of the
821      * matching object if the <tt>cons</tt> 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 <tt>(new SearchControls())</tt>).
843      * @return  an enumeration of <tt>SearchResult</tt>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 <tt>(new SearchControls())</tt>).
876      *
877      * @return  an enumeration of <tt>SearchResult</tt>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 <tt>SearchResult</tt> may also contain attributes of the matching
939      * object if the <tt>cons</tt> 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 <tt>(new SearchControls())</tt>).
976      * @return  an enumeration of <tt>SearchResult</tt>s of the objects
977      *          that satisfy the filter; never null
978      *
979      * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> 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 <tt>cons</tt> contains
983      *          invalid settings
984      * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with
985      *          <tt>filterArgs</tt> 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 <tt>(new SearchControls())</tt>).
1021      * @return  an enumeration of <tt>SearchResult</tt>s of the objects
1022      *          that satisfy the filter; never null
1023      *
1024      * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> 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 <tt>cons</tt> contains
1028      *          invalid settings
1029      * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with
1030      *          <tt>filterArgs</tt> 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 }