KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > directory > 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 JavaDoc 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 JavaDoc getAttributes(String JavaDoc 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 JavaDoc getAttributes(Name name, String JavaDoc[] 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 JavaDoc getAttributes(String JavaDoc name, String JavaDoc[] 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 JavaDoc 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 JavaDoc name, int mod_op, Attributes JavaDoc 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 JavaDoc[] 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 JavaDoc name, ModificationItem JavaDoc[] 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 JavaDoc obj, Attributes JavaDoc 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 JavaDoc name, Object JavaDoc obj, Attributes JavaDoc 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 JavaDoc obj, Attributes JavaDoc 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 JavaDoc name, Object JavaDoc obj, Attributes JavaDoc 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 JavaDoc createSubcontext(Name name, Attributes JavaDoc 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 JavaDoc createSubcontext(String JavaDoc name, Attributes JavaDoc 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 JavaDoc 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 JavaDoc getSchema(String JavaDoc 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 JavaDoc 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 JavaDoc getSchemaClassDefinition(String JavaDoc 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 JavaDoc>
679     search(Name name,
680            Attributes JavaDoc matchingAttributes,
681            String JavaDoc[] 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 JavaDoc>
699     search(String JavaDoc name,
700            Attributes JavaDoc matchingAttributes,
701            String JavaDoc[] 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 JavaDoc>
724     search(Name name, Attributes JavaDoc 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 JavaDoc>
740     search(String JavaDoc name, Attributes JavaDoc 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 JavaDoc>
840     search(Name name,
841            String JavaDoc filter,
842            SearchControls JavaDoc 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 JavaDoc>
869     search(String JavaDoc name,
870            String JavaDoc filter,
871            SearchControls JavaDoc 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 JavaDoc>
975     search(Name name,
976            String JavaDoc filterExpr,
977            Object JavaDoc[] filterArgs,
978            SearchControls JavaDoc 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 JavaDoc>
1017    search(String JavaDoc name,
1018           String JavaDoc filterExpr,
1019           Object JavaDoc[] filterArgs,
1020           SearchControls JavaDoc cons)
1021    throws NamingException;
1022}
1023
Popular Tags