DirContext


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