1 /*

     2  * Copyright 1999-2005 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package javax.naming.directory;

    27 

    28 import javax.naming.*;

    29 

    30 /**

    31  * The directory service interface, containing

    32  * methods for examining and updating attributes

    33  * associated with objects, and for searching the directory.

    34  * <p>

    35  * <h4>Names</h4>

    36  * Each name passed as an argument to a <tt>DirContext</tt> method is relative

    37  * to that context.  The empty name is used to name the context itself.

    38  * The name parameter may never be null.

    39  * <p>

    40  * Most of the methods have overloaded versions with one taking a

    41  * <code>Name</code> parameter and one taking a <code>String</code>.

    42  * These overloaded versions are equivalent in that if

    43  * the <code>Name</code> and <code>String</code> parameters are just

    44  * different representations of the same name, then the overloaded

    45  * versions of the same methods behave the same.

    46  * In the method descriptions below, only one version is documented.

    47  * The second version instead has a link to the first:  the same

    48  * documentation applies to both.

    49  * <p>

    50  * See <tt>Context</tt> for a discussion on the interpretation of the

    51  * name argument to the <tt>Context</tt> methods. These same rules

    52  * apply to the name argument to the <tt>DirContext</tt> methods.

    53  * <p>

    54  * <h4>Attribute Models</h4>

    55  * There are two basic models of what attributes should be

    56  * associated with.  First, attributes may be directly associated with a

    57  * DirContext object.

    58  * In this model, an attribute operation on the named object is

    59  * roughly equivalent

    60  * to a lookup on the name (which returns the DirContext object),

    61  * followed by the attribute operation invoked on the DirContext object

    62  * in which the caller supplies an empty name. The attributes can be viewed

    63  * as being stored along with the object (note that this does not imply that

    64  * the implementation must do so).

    65  * <p>

    66  * The second model is that attributes are associated with a

    67  * name (typically an atomic name) in a DirContext.

    68  * In this model, an attribute operation on the named object is

    69  * roughly equivalent to a lookup on the name of the parent DirContext of the

    70  * named object, followed by the attribute operation invoked on the parent

    71  * in which the caller supplies the terminal atomic name.

    72  * The attributes can be viewed as being stored in the parent DirContext

    73  * (again, this does not imply that the implementation must do so).

    74  * Objects that are not DirContexts can have attributes, as long as

    75  * their parents are DirContexts.

    76  * <p>

    77  * JNDI support both of these models.

    78  * It is up to the individual service providers to decide where to

    79  * "store" attributes.

    80  * JNDI clients are safest when they do not make assumptions about

    81  * whether an object's attributes are stored as part of the object, or stored

    82  * within the parent object and associated with the object's name.

    83  * <p>

    84  * <h4>Attribute Type Names</h4>

    85  * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,

    86  * you can supply the attributes to return by supplying a list of

    87  * attribute names (strings).

    88  * The attributes that you get back might not have the same names as the

    89  * attribute names you have specified. This is because some directories

    90  * support features that cause them to return other attributes.  Such

    91  * features include attribute subclassing, attribute name synonyms, and

    92  * attribute language codes.

    93  * <p>

    94  * In attribute subclassing, attributes are defined in a class hierarchy.

    95  * In some directories, for example, the "name" attribute might be the

    96  * superclass of all name-related attributes, including "commonName" and

    97  * "surName".  Asking for the "name" attribute might return both the

    98  * "commonName" and "surName" attributes.

    99  * <p>

   100  * With attribute type synonyms, a directory can assign multiple names to

   101  * the same attribute. For example, "cn" and "commonName" might both

   102  * refer to the same attribute. Asking for "cn" might return the

   103  * "commonName" attribute.

   104  * <p>

   105  * Some directories support the language codes for attributes.

   106  * Asking such a directory for the "description" attribute, for example,

   107  * might return all of the following attributes:

   108  * <ul>

   109  * <li>description

   110  * <li>description;lang-en

   111  * <li>description;lang-de

   112  * <li>description;lang-fr

   113  * </ul>

   114  *

   115  * <p>

   116  *<h4>Operational Attributes</h4>

   117  *<p>

   118  * Some directories have the notion of "operational attributes" which are

   119  * attributes associated with a directory object for administrative

   120  * purposes. An example of operational attributes is the access control

   121  * list for an object.

   122  * <p>

   123  * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,

   124  * you can specify that all attributes associated with the requested objects

   125  * be returned by supply <tt>null</tt> as the list of attributes to return.

   126  * The attributes returned do <em>not</em> include operational attributes.

   127  * In order to retrieve operational attributes, you must name them explicitly.

   128  *

   129  * <p>

   130  * <h4>Named Context</h4>

   131  * <p>

   132  * There are certain methods in which the name must resolve to a context

   133  * (for example, when searching a single level context). The documentation

   134  * of such methods

   135  * use the term <em>named context</em> to describe their name parameter.

   136  * For these methods, if the named object is not a DirContext,

   137  * <code>NotContextException</code> is thrown.

   138  * Aside from these methods, there is no requirement that the

   139  * <em>named object</em> be a DirContext.

   140  *<p>

   141  *<h4>Parameters</h4>

   142  *<p>

   143  * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object

   144  * passed as a parameter to any method will not be modified by the

   145  * service provider.  The service provider may keep a reference to it

   146  * for the duration of the operation, including any enumeration of the

   147  * method's results and the processing of any referrals generated.

   148  * The caller should not modify the object during this time.

   149  * An <tt>Attributes</tt> object returned by any method is owned by

   150  * the caller.  The caller may subsequently modify it; the service

   151  * provider will not.

   152  *<p>

   153  *<h4>Exceptions</h4>

   154  *<p>

   155  * All the methods in this interface can throw a NamingException or

   156  * any of its subclasses. See NamingException and their subclasses

   157  * for details on each exception.

   158  *

   159  * @author Rosanna Lee

   160  * @author Scott Seligman

   161  * @author R. Vasudevan

   162  *

   163  * @see javax.naming.Context

   164  * @since 1.3

   165  */

   166 

   167 public interface DirContext extends Context {

   168 

   169     /**

   170      * Retrieves all of the attributes associated with a named object.

   171      * See the class description regarding attribute models, attribute

   172      * type names, and operational attributes.

   173      *

   174      * @param name

   175      *          the name of the object from which to retrieve attributes

   176      * @return  the set of attributes associated with <code>name</code>.

   177      *          Returns an empty attribute set if name has no attributes;

   178      *          never null.

   179      * @throws  NamingException if a naming exception is encountered

   180      *

   181      * @see #getAttributes(String)

   182      * @see #getAttributes(Name, String[])

   183      */

   184     public Attributes getAttributes(Name name) throws NamingException;

   185 

   186     /**

   187      * Retrieves all of the attributes associated with a named object.

   188      * See {@link #getAttributes(Name)} for details.

   189      *

   190      * @param name

   191      *          the name of the object from which to retrieve attributes

   192      * @return  the set of attributes associated with <code>name</code>

   193      *

   194      * @throws  NamingException if a naming exception is encountered

   195      */

   196     public Attributes getAttributes(String name) throws NamingException;

   197 

   198     /**

   199      * Retrieves selected attributes associated with a named object.

   200      * See the class description regarding attribute models, attribute

   201      * type names, and operational attributes.

   202      *

   203      * <p> If the object does not have an attribute

   204      * specified, the directory will ignore the nonexistent attribute

   205      * and return those requested attributes that the object does have.

   206      *

   207      * <p> A directory might return more attributes than was requested

   208      * (see <strong>Attribute Type Names</strong> in the class description),

   209      * but is not allowed to return arbitrary, unrelated attributes.

   210      *

   211      * <p> See also <strong>Operational Attributes</strong> in the class

   212      * description.

   213      *

   214      * @param name

   215      *          the name of the object from which to retrieve attributes

   216      * @param attrIds

   217      *          the identifiers of the attributes to retrieve.

   218      *          null indicates that all attributes should be retrieved;

   219      *          an empty array indicates that none should be retrieved.

   220      * @return  the requested attributes; never null

   221      *

   222      * @throws  NamingException if a naming exception is encountered

   223      */

   224     public Attributes getAttributes(Name name, String[] attrIds)

   225             throws NamingException;

   226 

   227     /**

   228      * Retrieves selected attributes associated with a named object.

   229      * See {@link #getAttributes(Name, String[])} for details.

   230      *

   231      * @param name

   232      *          The name of the object from which to retrieve attributes

   233      * @param attrIds

   234      *          the identifiers of the attributes to retrieve.

   235      *          null indicates that all attributes should be retrieved;

   236      *          an empty array indicates that none should be retrieved.

   237      * @return  the requested attributes; never null

   238      *

   239      * @throws  NamingException if a naming exception is encountered

   240      */

   241     public Attributes getAttributes(String name, String[] attrIds)

   242             throws NamingException;

   243 

   244     /**

   245      * This constant specifies to add an attribute with the specified values.

   246      * <p>

   247      * If attribute does not exist,

   248      * create the attribute.  The resulting attribute has a union of the

   249      * specified value set and the prior value set.

   250      * Adding an attribute with no value will throw

   251      * <code>InvalidAttributeValueException</code> if the attribute must have

   252      * at least  one value.  For a single-valued attribute where that attribute

   253      * already exists, throws <code>AttributeInUseException</code>.

   254      * If attempting to add more than one value to a single-valued attribute,

   255      * throws <code>InvalidAttributeValueException</code>.

   256      * <p>

   257      * The value of this constant is <tt>1</tt>.

   258      *

   259      * @see ModificationItem

   260      * @see #modifyAttributes

   261      */

   262     public final static int ADD_ATTRIBUTE = 1;

   263 

   264     /**

   265      * This constant specifies to replace an attribute with specified values.

   266      *<p>

   267      * If attribute already exists,

   268      * replaces all existing values with new specified values.  If the

   269      * attribute does not exist, creates it.  If no value is specified,

   270      * deletes all the values of the attribute.

   271      * Removal of the last value will remove the attribute if the attribute

   272      * is required to have at least one value.  If

   273      * attempting to add more than one value to a single-valued attribute,

   274      * throws <code>InvalidAttributeValueException</code>.

   275      * <p>

   276      * The value of this constant is <tt>2</tt>.

   277      *

   278      * @see ModificationItem

   279      * @see #modifyAttributes

   280      */

   281     public final static int REPLACE_ATTRIBUTE = 2;

   282 

   283     /**

   284      * This constant specifies to delete

   285      * the specified attribute values from the attribute.

   286      *<p>

   287      * The resulting attribute has the set difference of its prior value set

   288      * and the specified value set.

   289      * If no values are specified, deletes the entire attribute.

   290      * If the attribute does not exist, or if some or all members of the

   291      * specified value set do not exist, this absence may be ignored

   292      * and the operation succeeds, or a NamingException may be thrown to

   293      * indicate the absence.

   294      * Removal of the last value will remove the attribute if the

   295      * attribute is required to have at least one value.

   296      * <p>

   297      * The value of this constant is <tt>3</tt>.

   298      *

   299      * @see ModificationItem

   300      * @see #modifyAttributes

   301      */

   302     public final static int REMOVE_ATTRIBUTE = 3;

   303 

   304     /**

   305      * Modifies the attributes associated with a named object.

   306      * The order of the modifications is not specified.  Where

   307      * possible, the modifications are performed atomically.

   308      *

   309      * @param name

   310      *          the name of the object whose attributes will be updated

   311      * @param mod_op

   312      *          the modification operation, one of:

   313      *                  <code>ADD_ATTRIBUTE</code>,

   314      *                  <code>REPLACE_ATTRIBUTE</code>,

   315      *                  <code>REMOVE_ATTRIBUTE</code>.

   316      * @param attrs

   317      *          the attributes to be used for the modification; may not be null

   318      *

   319      * @throws  AttributeModificationException if the modification cannot

   320      *          be completed successfully

   321      * @throws  NamingException if a naming exception is encountered

   322      *

   323      * @see #modifyAttributes(Name, ModificationItem[])

   324      */

   325     public void modifyAttributes(Name name, int mod_op, Attributes attrs)

   326             throws NamingException;

   327 

   328     /**

   329      * Modifies the attributes associated with a named object.

   330      * See {@link #modifyAttributes(Name, int, Attributes)} for details.

   331      *

   332      * @param name

   333      *          the name of the object whose attributes will be updated

   334      * @param mod_op

   335      *          the modification operation, one of:

   336      *                  <code>ADD_ATTRIBUTE</code>,

   337      *                  <code>REPLACE_ATTRIBUTE</code>,

   338      *                  <code>REMOVE_ATTRIBUTE</code>.

   339      * @param attrs

   340      *          the attributes to be used for the modification; may not be null

   341      *

   342      * @throws  AttributeModificationException if the modification cannot

   343      *          be completed successfully

   344      * @throws  NamingException if a naming exception is encountered

   345      */

   346     public void modifyAttributes(String name, int mod_op, Attributes attrs)

   347             throws NamingException;

   348 

   349     /**

   350      * Modifies the attributes associated with a named object using

   351      * an ordered list of modifications.

   352      * The modifications are performed

   353      * in the order specified.  Each modification specifies a

   354      * modification operation code and an attribute on which to

   355      * operate.  Where possible, the modifications are

   356      * performed atomically.

   357      *

   358      * @param name

   359      *          the name of the object whose attributes will be updated

   360      * @param mods

   361      *          an ordered sequence of modifications to be performed;

   362      *          may not be null

   363      *

   364      * @throws  AttributeModificationException if the modifications

   365      *          cannot be completed successfully

   366      * @throws  NamingException if a naming exception is encountered

   367      *

   368      * @see #modifyAttributes(Name, int, Attributes)

   369      * @see ModificationItem

   370      */

   371     public void modifyAttributes(Name name, ModificationItem[] mods)

   372             throws NamingException;

   373 

   374     /**

   375      * Modifies the attributes associated with a named object using

   376      * an ordered list of modifications.

   377      * See {@link #modifyAttributes(Name, ModificationItem[])} for details.

   378      *

   379      * @param name

   380      *          the name of the object whose attributes will be updated

   381      * @param mods

   382      *          an ordered sequence of modifications to be performed;

   383      *          may not be null

   384      *

   385      * @throws  AttributeModificationException if the modifications

   386      *          cannot be completed successfully

   387      * @throws  NamingException if a naming exception is encountered

   388      */

   389     public void modifyAttributes(String name, ModificationItem[] mods)

   390             throws NamingException;

   391 

   392     /**

   393      * Binds a name to an object, along with associated attributes.

   394      * If <tt>attrs</tt> is null, the resulting binding will have

   395      * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a

   396      * <tt>DirContext</tt>, and no attributes otherwise.

   397      * If <tt>attrs</tt> is non-null, the resulting binding will have

   398      * <tt>attrs</tt> as its attributes; any attributes associated with

   399      * <tt>obj</tt> are ignored.

   400      *

   401      * @param name

   402      *          the name to bind; may not be empty

   403      * @param obj

   404      *          the object to bind; possibly null

   405      * @param attrs

   406      *          the attributes to associate with the binding

   407      *

   408      * @throws  NameAlreadyBoundException if name is already bound

   409      * @throws  InvalidAttributesException if some "mandatory" attributes

   410      *          of the binding are not supplied

   411      * @throws  NamingException if a naming exception is encountered

   412      *

   413      * @see Context#bind(Name, Object)

   414      * @see #rebind(Name, Object, Attributes)

   415      */

   416     public void bind(Name name, Object obj, Attributes attrs)

   417             throws NamingException;

   418 

   419     /**

   420      * Binds a name to an object, along with associated attributes.

   421      * See {@link #bind(Name, Object, Attributes)} for details.

   422      *

   423      * @param name

   424      *          the name to bind; may not be empty

   425      * @param obj

   426      *          the object to bind; possibly null

   427      * @param attrs

   428      *          the attributes to associate with the binding

   429      *

   430      * @throws  NameAlreadyBoundException if name is already bound

   431      * @throws  InvalidAttributesException if some "mandatory" attributes

   432      *          of the binding are not supplied

   433      * @throws  NamingException if a naming exception is encountered

   434      */

   435     public void bind(String name, Object obj, Attributes attrs)

   436             throws NamingException;

   437 

   438     /**

   439      * Binds a name to an object, along with associated attributes,

   440      * overwriting any existing binding.

   441      * If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,

   442      * the attributes from <tt>obj</tt> are used.

   443      * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,

   444      * any existing attributes associated with the object already bound

   445      * in the directory remain unchanged.

   446      * If <tt>attrs</tt> is non-null, any existing attributes associated with

   447      * the object already bound in the directory are removed and <tt>attrs</tt>

   448      * is associated with the named object.  If <tt>obj</tt> is a

   449      * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes

   450      * of <tt>obj</tt> are ignored.

   451      *

   452      * @param name

   453      *          the name to bind; may not be empty

   454      * @param obj

   455      *          the object to bind; possibly null

   456      * @param attrs

   457      *          the attributes to associate with the binding

   458      *

   459      * @throws  InvalidAttributesException if some "mandatory" attributes

   460      *          of the binding are not supplied

   461      * @throws  NamingException if a naming exception is encountered

   462      *

   463      * @see Context#bind(Name, Object)

   464      * @see #bind(Name, Object, Attributes)

   465      */

   466     public void rebind(Name name, Object obj, Attributes attrs)

   467             throws NamingException;

   468 

   469     /**

   470      * Binds a name to an object, along with associated attributes,

   471      * overwriting any existing binding.

   472      * See {@link #rebind(Name, Object, Attributes)} for details.

   473      *

   474      * @param name

   475      *          the name to bind; may not be empty

   476      * @param obj

   477      *          the object to bind; possibly null

   478      * @param attrs

   479      *          the attributes to associate with the binding

   480      *

   481      * @throws  InvalidAttributesException if some "mandatory" attributes

   482      *          of the binding are not supplied

   483      * @throws  NamingException if a naming exception is encountered

   484      */

   485     public void rebind(String name, Object obj, Attributes attrs)

   486             throws NamingException;

   487 

   488     /**

   489      * Creates and binds a new context, along with associated attributes.

   490      * This method creates a new subcontext with the given name, binds it in

   491      * the target context (that named by all but terminal atomic

   492      * component of the name), and associates the supplied attributes

   493      * with the newly created object.

   494      * All intermediate and target contexts must already exist.

   495      * If <tt>attrs</tt> is null, this method is equivalent to

   496      * <tt>Context.createSubcontext()</tt>.

   497      *

   498      * @param name

   499      *          the name of the context to create; may not be empty

   500      * @param attrs

   501      *          the attributes to associate with the newly created context

   502      * @return  the newly created context

   503      *

   504      * @throws  NameAlreadyBoundException if the name is already bound

   505      * @throws  InvalidAttributesException if <code>attrs</code> does not

   506      *          contain all the mandatory attributes required for creation

   507      * @throws  NamingException if a naming exception is encountered

   508      *

   509      * @see Context#createSubcontext(Name)

   510      */

   511     public DirContext createSubcontext(Name name, Attributes attrs)

   512             throws NamingException;

   513 

   514     /**

   515      * Creates and binds a new context, along with associated attributes.

   516      * See {@link #createSubcontext(Name, Attributes)} for details.

   517      *

   518      * @param name

   519      *          the name of the context to create; may not be empty

   520      * @param attrs

   521      *          the attributes to associate with the newly created context

   522      * @return  the newly created context

   523      *

   524      * @throws  NameAlreadyBoundException if the name is already bound

   525      * @throws  InvalidAttributesException if <code>attrs</code> does not

   526      *          contain all the mandatory attributes required for creation

   527      * @throws  NamingException if a naming exception is encountered

   528      */

   529     public DirContext createSubcontext(String name, Attributes attrs)

   530             throws NamingException;

   531 

   532 // -------------------- schema operations

   533 

   534     /**

   535      * Retrieves the schema associated with the named object.

   536      * The schema describes rules regarding the structure of the namespace

   537      * and the attributes stored within it.  The schema

   538      * specifies what types of objects can be added to the directory and where

   539      * they can be added; what mandatory and optional attributes an object

   540      * can have. The range of support for schemas is directory-specific.

   541      *

   542      * <p> This method returns the root of the schema information tree

   543      * that is applicable to the named object. Several named objects

   544      * (or even an entire directory) might share the same schema.

   545      *

   546      * <p> Issues such as structure and contents of the schema tree,

   547      * permission to modify to the contents of the schema

   548      * tree, and the effect of such modifications on the directory

   549      * are dependent on the underlying directory.

   550      *

   551      * @param name

   552      *          the name of the object whose schema is to be retrieved

   553      * @return  the schema associated with the context; never null

   554      * @throws  OperationNotSupportedException if schema not supported

   555      * @throws  NamingException if a naming exception is encountered

   556      */

   557     public DirContext getSchema(Name name) throws NamingException;

   558 

   559     /**

   560      * Retrieves the schema associated with the named object.

   561      * See {@link #getSchema(Name)} for details.

   562      *

   563      * @param name

   564      *          the name of the object whose schema is to be retrieved

   565      * @return  the schema associated with the context; never null

   566      * @throws  OperationNotSupportedException if schema not supported

   567      * @throws  NamingException if a naming exception is encountered

   568      */

   569     public DirContext getSchema(String name) throws NamingException;

   570 

   571     /**

   572      * Retrieves a context containing the schema objects of the

   573      * named object's class definitions.

   574      *<p>

   575      * One category of information found in directory schemas is

   576      * <em>class definitions</em>.  An "object class" definition

   577      * specifies the object's <em>type</em> and what attributes (mandatory

   578      * and optional) the object must/can have. Note that the term

   579      * "object class" being referred to here is in the directory sense

   580      * rather than in the Java sense.

   581      * For example, if the named object is a directory object of

   582      * "Person" class, <tt>getSchemaClassDefinition()</tt> would return a

   583      * <tt>DirContext</tt> representing the (directory's) object class

   584      * definition of "Person".

   585      *<p>

   586      * The information that can be retrieved from an object class definition

   587      * is directory-dependent.

   588      *<p>

   589      * Prior to JNDI 1.2, this method

   590      * returned a single schema object representing the class definition of

   591      * the named object.

   592      * Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing

   593      * all of the named object's class definitions.

   594      *

   595      * @param name

   596      *          the name of the object whose object class

   597      *          definition is to be retrieved

   598      * @return  the <tt>DirContext</tt> containing the named

   599      *          object's class definitions; never null

   600      *

   601      * @throws  OperationNotSupportedException if schema not supported

   602      * @throws  NamingException if a naming exception is encountered

   603      */

   604     public DirContext getSchemaClassDefinition(Name name)

   605             throws NamingException;

   606 

   607     /**

   608      * Retrieves a context containing the schema objects of the

   609      * named object's class definitions.

   610      * See {@link #getSchemaClassDefinition(Name)} for details.

   611      *

   612      * @param name

   613      *          the name of the object whose object class

   614      *          definition is to be retrieved

   615      * @return  the <tt>DirContext</tt> containing the named

   616      *          object's class definitions; never null

   617      *

   618      * @throws  OperationNotSupportedException if schema not supported

   619      * @throws  NamingException if a naming exception is encountered

   620      */

   621     public DirContext getSchemaClassDefinition(String name)

   622             throws NamingException;

   623 

   624 // -------------------- search operations

   625 

   626     /**

   627      * Searches in a single context for objects that contain a

   628      * specified set of attributes, and retrieves selected attributes.

   629      * The search is performed using the default

   630      * <code>SearchControls</code> settings.

   631      * <p>

   632      * For an object to be selected, each attribute in

   633      * <code>matchingAttributes</code> must match some attribute of the

   634      * object.  If <code>matchingAttributes</code> is empty or

   635      * null, all objects in the target context are returned.

   636      *<p>

   637      * An attribute <em>A</em><sub>1</sub> in

   638      * <code>matchingAttributes</code> is considered to match an

   639      * attribute <em>A</em><sub>2</sub> of an object if

   640      * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same

   641      * identifier, and each value of <em>A</em><sub>1</sub> is equal

   642      * to some value of <em>A</em><sub>2</sub>.  This implies that the

   643      * order of values is not significant, and that

   644      * <em>A</em><sub>2</sub> may contain "extra" values not found in

   645      * <em>A</em><sub>1</sub> without affecting the comparison.  It

   646      * also implies that if <em>A</em><sub>1</sub> has no values, then

   647      * testing for a match is equivalent to testing for the presence

   648      * of an attribute <em>A</em><sub>2</sub> with the same

   649      * identifier.

   650      *<p>

   651      * The precise definition of "equality" used in comparing attribute values

   652      * is defined by the underlying directory service.  It might use the

   653      * <code>Object.equals</code> method, for example, or might use a schema

   654      * to specify a different equality operation.

   655      * For matching based on operations other than equality (such as

   656      * substring comparison) use the version of the <code>search</code>

   657      * method that takes a filter argument.

   658      * <p>

   659      * When changes are made to this <tt>DirContext</tt>,

   660      * the effect on enumerations returned by prior calls to this method

   661      * is undefined.

   662      *<p>

   663      * If the object does not have the attribute

   664      * specified, the directory will ignore the nonexistent attribute

   665      * and return the requested attributes that the object does have.

   666      *<p>

   667      * A directory might return more attributes than was requested

   668      * (see <strong>Attribute Type Names</strong> in the class description),

   669      * but is not allowed to return arbitrary, unrelated attributes.

   670      *<p>

   671      * See also <strong>Operational Attributes</strong> in the class

   672      * description.

   673      *

   674      * @param name

   675      *          the name of the context to search

   676      * @param matchingAttributes

   677      *          the attributes to search for.  If empty or null,

   678      *          all objects in the target context are returned.

   679      * @param attributesToReturn

   680      *          the attributes to return.  null indicates that

   681      *          all attributes are to be returned;

   682      *          an empty array indicates that none are to be returned.

   683      * @return

   684      *          a non-null enumeration of <tt>SearchResult</tt> objects.

   685      *          Each <tt>SearchResult</tt> contains the attributes

   686      *          identified by <code>attributesToReturn</code>

   687      *          and the name of the corresponding object, named relative

   688      *          to the context named by <code>name</code>.

   689      * @throws  NamingException if a naming exception is encountered

   690      *

   691      * @see SearchControls

   692      * @see SearchResult

   693      * @see #search(Name, String, Object[], SearchControls)

   694      */

   695     public NamingEnumeration<SearchResult>

   696         search(Name name,

   697                Attributes matchingAttributes,

   698                String[] attributesToReturn)

   699         throws NamingException;

   700 

   701     /**

   702      * Searches in a single context for objects that contain a

   703      * specified set of attributes, and retrieves selected attributes.

   704      * See {@link #search(Name, Attributes, String[])} for details.

   705      *

   706      * @param name

   707      *          the name of the context to search

   708      * @param matchingAttributes

   709      *          the attributes to search for

   710      * @param attributesToReturn

   711      *          the attributes to return

   712      * @return  a non-null enumeration of <tt>SearchResult</tt> objects

   713      * @throws  NamingException if a naming exception is encountered

   714      */

   715     public NamingEnumeration<SearchResult>

   716         search(String name,

   717                Attributes matchingAttributes,

   718                String[] attributesToReturn)

   719         throws NamingException;

   720 

   721     /**

   722      * Searches in a single context for objects that contain a

   723      * specified set of attributes.

   724      * This method returns all the attributes of such objects.

   725      * It is equivalent to supplying null as

   726      * the <tt>atributesToReturn</tt> parameter to the method

   727      * <code>search(Name, Attributes, String[])</code>.

   728      * <br>

   729      * See {@link #search(Name, Attributes, String[])} for a full description.

   730      *

   731      * @param name

   732      *          the name of the context to search

   733      * @param matchingAttributes

   734      *          the attributes to search for

   735      * @return  an enumeration of <tt>SearchResult</tt> objects

   736      * @throws  NamingException if a naming exception is encountered

   737      *

   738      * @see #search(Name, Attributes, String[])

   739      */

   740     public NamingEnumeration<SearchResult>

   741         search(Name name, Attributes matchingAttributes)

   742         throws NamingException;

   743 

   744     /**

   745      * Searches in a single context for objects that contain a

   746      * specified set of attributes.

   747      * See {@link #search(Name, Attributes)} for details.

   748      *

   749      * @param name

   750      *          the name of the context to search

   751      * @param matchingAttributes

   752      *          the attributes to search for

   753      * @return  an enumeration of <tt>SearchResult</tt> objects

   754      * @throws  NamingException if a naming exception is encountered

   755      */

   756     public NamingEnumeration<SearchResult>

   757         search(String name, Attributes matchingAttributes)

   758         throws NamingException;

   759 

   760     /**

   761      * Searches in the named context or object for entries that satisfy the

   762      * given search filter.  Performs the search as specified by

   763      * the search controls.

   764      * <p>

   765      * The format and interpretation of <code>filter</code> follows RFC 2254

   766      * with the

   767      * following interpretations for <code>attr</code> and <code>value</code>

   768      * mentioned in the RFC.

   769      * <p>

   770      * <code>attr</code> is the attribute's identifier.

   771      * <p>

   772      * <code>value</code> is the string representation the attribute's value.

   773      * The translation of this string representation into the attribute's value

   774      * is directory-specific.

   775      * <p>

   776      * For the assertion "someCount=127", for example, <code>attr</code>

   777      * is "someCount" and <code>value</code> is "127".

   778      * The provider determines, based on the attribute ID ("someCount")

   779      * (and possibly its schema), that the attribute's value is an integer.

   780      * It then parses the string "127" appropriately.

   781      *<p>

   782      * Any non-ASCII characters in the filter string should be

   783      * represented by the appropriate Java (Unicode) characters, and

   784      * not encoded as UTF-8 octets.  Alternately, the

   785      * "backslash-hexcode" notation described in RFC 2254 may be used.

   786      *<p>

   787      * If the directory does not support a string representation of

   788      * some or all of its attributes, the form of <code>search</code> that

   789      * accepts filter arguments in the form of Objects can be used instead.

   790      * The service provider for such a directory would then translate

   791      * the filter arguments to its service-specific representation

   792      * for filter evaluation.

   793      * See <code>search(Name, String, Object[], SearchControls)</code>.

   794      * <p>

   795      * RFC 2254 defines certain operators for the filter, including substring

   796      * matches, equality, approximate match, greater than, less than.  These

   797      * operators are mapped to operators with corresponding semantics in the

   798      * underlying directory. For example, for the equals operator, suppose

   799      * the directory has a matching rule defining "equality" of the

   800      * attributes in the filter. This rule would be used for checking

   801      * equality of the attributes specified in the filter with the attributes

   802      * of objects in the directory. Similarly, if the directory has a

   803      * matching rule for ordering, this rule would be used for

   804      * making "greater than" and "less than" comparisons.

   805      *<p>

   806      * Not all of the operators defined in RFC 2254 are applicable to all

   807      * attributes.  When an operator is not applicable, the exception

   808      * <code>InvalidSearchFilterException</code> is thrown.

   809      * <p>

   810      * The result is returned in an enumeration of <tt>SearchResult</tt>s.

   811      * Each <tt>SearchResult</tt> contains the name of the object

   812      * and other information about the object (see SearchResult).

   813      * The name is either relative to the target context of the search

   814      * (which is named by the <code>name</code> parameter), or

   815      * it is a URL string. If the target context is included in

   816      * the enumeration (as is possible when

   817      * <code>cons</code> specifies a search scope of

   818      * <code>SearchControls.OBJECT_SCOPE</code> or

   819      * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty

   820      * string. The <tt>SearchResult</tt> may also contain attributes of the

   821      * matching object if the <tt>cons</tt> argument specified that attributes

   822      * be returned.

   823      *<p>

   824      * If the object does not have a requested attribute, that

   825      * nonexistent attribute will be ignored.  Those requested

   826      * attributes that the object does have will be returned.

   827      *<p>

   828      * A directory might return more attributes than were requested

   829      * (see <strong>Attribute Type Names</strong> in the class description)

   830      * but is not allowed to return arbitrary, unrelated attributes.

   831      *<p>

   832      * See also <strong>Operational Attributes</strong> in the class

   833      * description.

   834      *

   835      * @param name

   836      *          the name of the context or object to search

   837      * @param filter

   838      *          the filter expression to use for the search; may not be null

   839      * @param cons

   840      *          the search controls that control the search.  If null,

   841      *          the default search controls are used (equivalent

   842      *          to <tt>(new SearchControls())</tt>).

   843      * @return  an enumeration of <tt>SearchResult</tt>s of

   844      *          the objects that satisfy the filter; never null

   845      *

   846      * @throws  InvalidSearchFilterException if the search filter specified is

   847      *          not supported or understood by the underlying directory

   848      * @throws  InvalidSearchControlsException if the search controls

   849      *          contain invalid settings

   850      * @throws  NamingException if a naming exception is encountered

   851      *

   852      * @see #search(Name, String, Object[], SearchControls)

   853      * @see SearchControls

   854      * @see SearchResult

   855      */

   856     public NamingEnumeration<SearchResult>

   857         search(Name name,

   858                String filter,

   859                SearchControls cons)

   860         throws NamingException;

   861 

   862     /**

   863      * Searches in the named context or object for entries that satisfy the

   864      * given search filter.  Performs the search as specified by

   865      * the search controls.

   866      * See {@link #search(Name, String, SearchControls)} for details.

   867      *

   868      * @param name

   869      *          the name of the context or object to search

   870      * @param filter

   871      *          the filter expression to use for the search; may not be null

   872      * @param cons

   873      *          the search controls that control the search.  If null,

   874      *          the default search controls are used (equivalent

   875      *          to <tt>(new SearchControls())</tt>).

   876      *

   877      * @return  an enumeration of <tt>SearchResult</tt>s for

   878      *          the objects that satisfy the filter.

   879      * @throws  InvalidSearchFilterException if the search filter specified is

   880      *          not supported or understood by the underlying directory

   881      * @throws  InvalidSearchControlsException if the search controls

   882      *          contain invalid settings

   883      * @throws  NamingException if a naming exception is encountered

   884      */

   885     public NamingEnumeration<SearchResult>

   886         search(String name,

   887                String filter,

   888                SearchControls cons)

   889         throws NamingException;

   890 

   891     /**

   892      * Searches in the named context or object for entries that satisfy the

   893      * given search filter.  Performs the search as specified by

   894      * the search controls.

   895      *<p>

   896      * The interpretation of <code>filterExpr</code> is based on RFC

   897      * 2254.  It may additionally contain variables of the form

   898      * <code>{i}</code> -- where <code>i</code> is an integer -- that

   899      * refer to objects in the <code>filterArgs</code> array.  The

   900      * interpretation of <code>filterExpr</code> is otherwise

   901      * identical to that of the <code>filter</code> parameter of the

   902      * method <code>search(Name, String, SearchControls)</code>.

   903      *<p>

   904      * When a variable <code>{i}</code> appears in a search filter, it

   905      * indicates that the filter argument <code>filterArgs[i]</code>

   906      * is to be used in that place.  Such variables may be used

   907      * wherever an <em>attr</em>, <em>value</em>, or

   908      * <em>matchingrule</em> production appears in the filter grammar

   909      * of RFC 2254, section 4.  When a string-valued filter argument

   910      * is substituted for a variable, the filter is interpreted as if

   911      * the string were given in place of the variable, with any

   912      * characters having special significance within filters (such as

   913      * <code>'*'</code>) having been escaped according to the rules of

   914      * RFC 2254.

   915      *<p>

   916      * For directories that do not use a string representation for

   917      * some or all of their attributes, the filter argument

   918      * corresponding to an attribute value may be of a type other than

   919      * String.  Directories that support unstructured binary-valued

   920      * attributes, for example, should accept byte arrays as filter

   921      * arguments.  The interpretation (if any) of filter arguments of

   922      * any other type is determined by the service provider for that

   923      * directory, which maps the filter operations onto operations with

   924      * corresponding semantics in the underlying directory.

   925      *<p>

   926      * This method returns an enumeration of the results.

   927      * Each element in the enumeration contains the name of the object

   928      * and other information about the object (see <code>SearchResult</code>).

   929      * The name is either relative to the target context of the search

   930      * (which is named by the <code>name</code> parameter), or

   931      * it is a URL string. If the target context is included in

   932      * the enumeration (as is possible when

   933      * <code>cons</code> specifies a search scope of

   934      * <code>SearchControls.OBJECT_SCOPE</code> or

   935      * <code>SearchControls.SUBSTREE_SCOPE</code>),

   936      * its name is the empty string.

   937      *<p>

   938      * The <tt>SearchResult</tt> may also contain attributes of the matching

   939      * object if the <tt>cons</tt> argument specifies that attributes be

   940      * returned.

   941      *<p>

   942      * If the object does not have a requested attribute, that

   943      * nonexistent attribute will be ignored.  Those requested

   944      * attributes that the object does have will be returned.

   945      *<p>

   946      * A directory might return more attributes than were requested

   947      * (see <strong>Attribute Type Names</strong> in the class description)

   948      * but is not allowed to return arbitrary, unrelated attributes.

   949      *<p>

   950      * If a search filter with invalid variable substitutions is provided

   951      * to this method, the result is undefined.

   952      * When changes are made to this DirContext,

   953      * the effect on enumerations returned by prior calls to this method

   954      * is undefined.

   955      *<p>

   956      * See also <strong>Operational Attributes</strong> in the class

   957      * description.

   958      *

   959      * @param name

   960      *          the name of the context or object to search

   961      * @param filterExpr

   962      *          the filter expression to use for the search.

   963      *          The expression may contain variables of the

   964      *          form "<code>{i}</code>" where <code>i</code>

   965      *          is a nonnegative integer.  May not be null.

   966      * @param filterArgs

   967      *          the array of arguments to substitute for the variables

   968      *          in <code>filterExpr</code>.  The value of

   969      *          <code>filterArgs[i]</code> will replace each

   970      *          occurrence of "<code>{i}</code>".

   971      *          If null, equivalent to an empty array.

   972      * @param cons

   973      *          the search controls that control the search.  If null,

   974      *          the default search controls are used (equivalent

   975      *          to <tt>(new SearchControls())</tt>).

   976      * @return  an enumeration of <tt>SearchResult</tt>s of the objects

   977      *          that satisfy the filter; never null

   978      *

   979      * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains

   980      *          <code>{i}</code> expressions where <code>i</code> is outside

   981      *          the bounds of the array <code>filterArgs</code>

   982      * @throws  InvalidSearchControlsException if <tt>cons</tt> contains

   983      *          invalid settings

   984      * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with

   985      *          <tt>filterArgs</tt> represents an invalid search filter

   986      * @throws  NamingException if a naming exception is encountered

   987      *

   988      * @see #search(Name, Attributes, String[])

   989      * @see java.text.MessageFormat

   990      */

   991     public NamingEnumeration<SearchResult>

   992         search(Name name,

   993                String filterExpr,

   994                Object[] filterArgs,

   995                SearchControls cons)

   996         throws NamingException;

   997 

   998     /**

   999      * Searches in the named context or object for entries that satisfy the

  1000      * given search filter.  Performs the search as specified by

  1001      * the search controls.

  1002      * See {@link #search(Name, String, Object[], SearchControls)} for details.

  1003      *

  1004      * @param name

  1005      *          the name of the context or object to search

  1006      * @param filterExpr

  1007      *          the filter expression to use for the search.

  1008      *          The expression may contain variables of the

  1009      *          form "<code>{i}</code>" where <code>i</code>

  1010      *          is a nonnegative integer.  May not be null.

  1011      * @param filterArgs

  1012      *          the array of arguments to substitute for the variables

  1013      *          in <code>filterExpr</code>.  The value of

  1014      *          <code>filterArgs[i]</code> will replace each

  1015      *          occurrence of "<code>{i}</code>".

  1016      *          If null, equivalent to an empty array.

  1017      * @param cons

  1018      *          the search controls that control the search.  If null,

  1019      *          the default search controls are used (equivalent

  1020      *          to <tt>(new SearchControls())</tt>).

  1021      * @return  an enumeration of <tt>SearchResult</tt>s of the objects

  1022      *          that satisfy the filter; never null

  1023      *

  1024      * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains

  1025      *          <code>{i}</code> expressions where <code>i</code> is outside

  1026      *          the bounds of the array <code>filterArgs</code>

  1027      * @throws  InvalidSearchControlsException if <tt>cons</tt> contains

  1028      *          invalid settings

  1029      * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with

  1030      *          <tt>filterArgs</tt> represents an invalid search filter

  1031      * @throws  NamingException if a naming exception is encountered

  1032      */

  1033     public NamingEnumeration<SearchResult>

  1034         search(String name,

  1035                String filterExpr,

  1036                Object[] filterArgs,

  1037                SearchControls cons)

  1038         throws NamingException;

  1039 }