https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.naming.directory;

import javax.naming.*;


The directory service interface, containing
methods for examining and updating attributes
associated with objects, and for searching the directory.



Names

Each name passed as an argument to a DirContext method is relative
to that context.  The empty name is used to name the context itself.
The name parameter may never be null.


Most of the methods have overloaded versions with one taking a
Name parameter and one taking a String.
These overloaded versions are equivalent in that if
the Name and String parameters are just
different representations of the same name, then the overloaded
versions of the same methods behave the same.
In the method descriptions below, only one version is documented.
The second version instead has a link to the first:  the same
documentation applies to both.


See Context for a discussion on the interpretation of the
name argument to the Context methods. These same rules
apply to the name argument to the DirContext methods.



Attribute Models

There are two basic models of what attributes should be
associated with.  First, attributes may be directly associated with a
DirContext object.
In this model, an attribute operation on the named object is
roughly equivalent
to a lookup on the name (which returns the DirContext object),
followed by the attribute operation invoked on the DirContext object
in which the caller supplies an empty name. The attributes can be viewed
as being stored along with the object (note that this does not imply that
the implementation must do so).


The second model is that attributes are associated with a
name (typically an atomic name) in a DirContext.
In this model, an attribute operation on the named object is
roughly equivalent to a lookup on the name of the parent DirContext of the
named object, followed by the attribute operation invoked on the parent
in which the caller supplies the terminal atomic name.
The attributes can be viewed as being stored in the parent DirContext
(again, this does not imply that the implementation must do so).
Objects that are not DirContexts can have attributes, as long as
their parents are DirContexts.


JNDI support both of these models.
It is up to the individual service providers to decide where to
"store" attributes.
JNDI clients are safest when they do not make assumptions about
whether an object's attributes are stored as part of the object, or stored
within the parent object and associated with the object's name.



Attribute Type Names

In the getAttributes() and search() methods,
you can supply the attributes to return by supplying a list of
attribute names (strings).
The attributes that you get back might not have the same names as the
attribute names you have specified. This is because some directories
support features that cause them to return other attributes.  Such
features include attribute subclassing, attribute name synonyms, and
attribute language codes.


In attribute subclassing, attributes are defined in a class hierarchy.
In some directories, for example, the "name" attribute might be the
superclass of all name-related attributes, including "commonName" and
"surName".  Asking for the "name" attribute might return both the
"commonName" and "surName" attributes.


With attribute type synonyms, a directory can assign multiple names to
the same attribute. For example, "cn" and "commonName" might both
refer to the same attribute. Asking for "cn" might return the
"commonName" attribute.


Some directories support the language codes for attributes.
Asking such a directory for the "description" attribute, for example,
might return all of the following attributes:

    

  • description

  • description;lang-en

  • description;lang-de

  • description;lang-fr





Operational Attributes



Some directories have the notion of "operational attributes" which are
attributes associated with a directory object for administrative
purposes. An example of operational attributes is the access control
list for an object.


In the getAttributes() and search() methods,
you can specify that all attributes associated with the requested objects
be returned by supply null as the list of attributes to return.
The attributes returned do not include operational attributes.
In order to retrieve operational attributes, you must name them explicitly.



Named Context



There are certain methods in which the name must resolve to a context
(for example, when searching a single level context). The documentation
of such methods
use the term named context to describe their name parameter.
For these methods, if the named object is not a DirContext,
NotContextException is thrown.
Aside from these methods, there is no requirement that the
named object be a DirContext.



Parameters



An Attributes, SearchControls, or array object
passed as a parameter to any method will not be modified by the
service provider.  The service provider may keep a reference to it
for the duration of the operation, including any enumeration of the
method's results and the processing of any referrals generated.
The caller should not modify the object during this time.
An Attributes object returned by any method is owned by
the caller.  The caller may subsequently modify it; the service
provider will not.



Exceptions



All the methods in this interface can throw a NamingException or
any of its subclasses. See NamingException and their subclasses
for details on each exception.

Author:Rosanna Lee, Scott Seligman, R. Vasudevan
See Also:
Since:1.3
/**
 * The directory service interface, containing
 * methods for examining and updating attributes
 * associated with objects, and for searching the directory.
 * <p>
 * <h4>Names</h4>
 * Each name passed as an argument to a <tt>DirContext</tt> method is relative
 * to that context.  The empty name is used to name the context itself.
 * The name parameter may never be null.
 * <p>
 * Most of the methods have overloaded versions with one taking a
 * <code>Name</code> parameter and one taking a <code>String</code>.
 * These overloaded versions are equivalent in that if
 * the <code>Name</code> and <code>String</code> parameters are just
 * different representations of the same name, then the overloaded
 * versions of the same methods behave the same.
 * In the method descriptions below, only one version is documented.
 * The second version instead has a link to the first:  the same
 * documentation applies to both.
 * <p>
 * See <tt>Context</tt> for a discussion on the interpretation of the
 * name argument to the <tt>Context</tt> methods. These same rules
 * apply to the name argument to the <tt>DirContext</tt> methods.
 * <p>
 * <h4>Attribute Models</h4>
 * There are two basic models of what attributes should be
 * associated with.  First, attributes may be directly associated with a
 * DirContext object.
 * In this model, an attribute operation on the named object is
 * roughly equivalent
 * to a lookup on the name (which returns the DirContext object),
 * followed by the attribute operation invoked on the DirContext object
 * in which the caller supplies an empty name. The attributes can be viewed
 * as being stored along with the object (note that this does not imply that
 * the implementation must do so).
 * <p>
 * The second model is that attributes are associated with a
 * name (typically an atomic name) in a DirContext.
 * In this model, an attribute operation on the named object is
 * roughly equivalent to a lookup on the name of the parent DirContext of the
 * named object, followed by the attribute operation invoked on the parent
 * in which the caller supplies the terminal atomic name.
 * The attributes can be viewed as being stored in the parent DirContext
 * (again, this does not imply that the implementation must do so).
 * Objects that are not DirContexts can have attributes, as long as
 * their parents are DirContexts.
 * <p>
 * JNDI support both of these models.
 * It is up to the individual service providers to decide where to
 * "store" attributes.
 * JNDI clients are safest when they do not make assumptions about
 * whether an object's attributes are stored as part of the object, or stored
 * within the parent object and associated with the object's name.
 * <p>
 * <h4>Attribute Type Names</h4>
 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
 * you can supply the attributes to return by supplying a list of
 * attribute names (strings).
 * The attributes that you get back might not have the same names as the
 * attribute names you have specified. This is because some directories
 * support features that cause them to return other attributes.  Such
 * features include attribute subclassing, attribute name synonyms, and
 * attribute language codes.
 * <p>
 * In attribute subclassing, attributes are defined in a class hierarchy.
 * In some directories, for example, the "name" attribute might be the
 * superclass of all name-related attributes, including "commonName" and
 * "surName".  Asking for the "name" attribute might return both the
 * "commonName" and "surName" attributes.
 * <p>
 * With attribute type synonyms, a directory can assign multiple names to
 * the same attribute. For example, "cn" and "commonName" might both
 * refer to the same attribute. Asking for "cn" might return the
 * "commonName" attribute.
 * <p>
 * Some directories support the language codes for attributes.
 * Asking such a directory for the "description" attribute, for example,
 * might return all of the following attributes:
 * <ul>
 * <li>description
 * <li>description;lang-en
 * <li>description;lang-de
 * <li>description;lang-fr
 * </ul>
 *
 * <p>
 *<h4>Operational Attributes</h4>
 *<p>
 * Some directories have the notion of "operational attributes" which are
 * attributes associated with a directory object for administrative
 * purposes. An example of operational attributes is the access control
 * list for an object.
 * <p>
 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
 * you can specify that all attributes associated with the requested objects
 * be returned by supply <tt>null</tt> as the list of attributes to return.
 * The attributes returned do <em>not</em> include operational attributes.
 * In order to retrieve operational attributes, you must name them explicitly.
 *
 * <p>
 * <h4>Named Context</h4>
 * <p>
 * There are certain methods in which the name must resolve to a context
 * (for example, when searching a single level context). The documentation
 * of such methods
 * use the term <em>named context</em> to describe their name parameter.
 * For these methods, if the named object is not a DirContext,
 * <code>NotContextException</code> is thrown.
 * Aside from these methods, there is no requirement that the
 * <em>named object</em> be a DirContext.
 *<p>
 *<h4>Parameters</h4>
 *<p>
 * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
 * passed as a parameter to any method will not be modified by the
 * service provider.  The service provider may keep a reference to it
 * for the duration of the operation, including any enumeration of the
 * method's results and the processing of any referrals generated.
 * The caller should not modify the object during this time.
 * An <tt>Attributes</tt> object returned by any method is owned by
 * the caller.  The caller may subsequently modify it; the service
 * provider will not.
 *<p>
 *<h4>Exceptions</h4>
 *<p>
 * All the methods in this interface can throw a NamingException or
 * any of its subclasses. See NamingException and their subclasses
 * for details on each exception.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @author R. Vasudevan
 *
 * @see javax.naming.Context
 * @since 1.3
 */

public interface DirContext extends Context {

    
Retrieves all of the attributes associated with a named object.
See the class description regarding attribute models, attribute
type names, and operational attributes.

Params:
  • name – 
         the name of the object from which to retrieve attributes
Throws:
See Also:
Returns: the set of attributes associated with name.
         Returns an empty attribute set if name has no attributes;
         never null.
/**
     * Retrieves all of the attributes associated with a named object.
     * See the class description regarding attribute models, attribute
     * type names, and operational attributes.
     *
     * @param name
     *          the name of the object from which to retrieve attributes
     * @return  the set of attributes associated with <code>name</code>.
     *          Returns an empty attribute set if name has no attributes;
     *          never null.
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #getAttributes(String)
     * @see #getAttributes(Name, String[])
     */
    public Attributes getAttributes(Name name) throws NamingException;

    
Retrieves all of the attributes associated with a named object. See getAttributes(Name) for details. 
Params:
  • name – 
         the name of the object from which to retrieve attributes
Throws:
Returns: the set of attributes associated with name
/**
     * Retrieves all of the attributes associated with a named object.
     * See {@link #getAttributes(Name)} for details.
     *
     * @param name
     *          the name of the object from which to retrieve attributes
     * @return  the set of attributes associated with <code>name</code>
     *
     * @throws  NamingException if a naming exception is encountered
     */
    public Attributes getAttributes(String name) throws NamingException;

    
Retrieves selected attributes associated with a named object.
See the class description regarding attribute models, attribute
type names, and operational attributes.

 If the object does not have an attribute
specified, the directory will ignore the nonexistent attribute
and return those requested attributes that the object does have.

 A directory might return more attributes than was requested
(see Attribute Type Names in the class description),
but is not allowed to return arbitrary, unrelated attributes.

 See also Operational Attributes in the class
description.

Params:
  • name – 
         the name of the object from which to retrieve attributes
  • attrIds – 
         the identifiers of the attributes to retrieve.
         null indicates that all attributes should be retrieved;
         an empty array indicates that none should be retrieved.
Throws:
Returns: the requested attributes; never null
/**
     * Retrieves selected attributes associated with a named object.
     * See the class description regarding attribute models, attribute
     * type names, and operational attributes.
     *
     * <p> If the object does not have an attribute
     * specified, the directory will ignore the nonexistent attribute
     * and return those requested attributes that the object does have.
     *
     * <p> A directory might return more attributes than was requested
     * (see <strong>Attribute Type Names</strong> in the class description),
     * but is not allowed to return arbitrary, unrelated attributes.
     *
     * <p> See also <strong>Operational Attributes</strong> in the class
     * description.
     *
     * @param name
     *          the name of the object from which to retrieve attributes
     * @param attrIds
     *          the identifiers of the attributes to retrieve.
     *          null indicates that all attributes should be retrieved;
     *          an empty array indicates that none should be retrieved.
     * @return  the requested attributes; never null
     *
     * @throws  NamingException if a naming exception is encountered
     */
    public Attributes getAttributes(Name name, String[] attrIds)
            throws NamingException;

    
Retrieves selected attributes associated with a named object. See getAttributes(Name, String[]) for details. 
Params:
  • name – 
         The name of the object from which to retrieve attributes
  • attrIds – 
         the identifiers of the attributes to retrieve.
         null indicates that all attributes should be retrieved;
         an empty array indicates that none should be retrieved.
Throws:
Returns: the requested attributes; never null
/**
     * Retrieves selected attributes associated with a named object.
     * See {@link #getAttributes(Name, String[])} for details.
     *
     * @param name
     *          The name of the object from which to retrieve attributes
     * @param attrIds
     *          the identifiers of the attributes to retrieve.
     *          null indicates that all attributes should be retrieved;
     *          an empty array indicates that none should be retrieved.
     * @return  the requested attributes; never null
     *
     * @throws  NamingException if a naming exception is encountered
     */
    public Attributes getAttributes(String name, String[] attrIds)
            throws NamingException;

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


If attribute does not exist,
create the attribute.  The resulting attribute has a union of the
specified value set and the prior value set.
Adding an attribute with no value will throw
InvalidAttributeValueException if the attribute must have
at least  one value.  For a single-valued attribute where that attribute
already exists, throws AttributeInUseException.
If attempting to add more than one value to a single-valued attribute,
throws InvalidAttributeValueException.


The value of this constant is 1.

See Also:
/**
     * This constant specifies to add an attribute with the specified values.
     * <p>
     * If attribute does not exist,
     * create the attribute.  The resulting attribute has a union of the
     * specified value set and the prior value set.
     * Adding an attribute with no value will throw
     * <code>InvalidAttributeValueException</code> if the attribute must have
     * at least  one value.  For a single-valued attribute where that attribute
     * already exists, throws <code>AttributeInUseException</code>.
     * If attempting to add more than one value to a single-valued attribute,
     * throws <code>InvalidAttributeValueException</code>.
     * <p>
     * The value of this constant is <tt>1</tt>.
     *
     * @see ModificationItem
     * @see #modifyAttributes
     */
    public final static int ADD_ATTRIBUTE = 1;

    
This constant specifies to replace an attribute with specified values.


If attribute already exists,
replaces all existing values with new specified values.  If the
attribute does not exist, creates it.  If no value is specified,
deletes all the values of the attribute.
Removal of the last value will remove the attribute if the attribute
is required to have at least one value.  If
attempting to add more than one value to a single-valued attribute,
throws InvalidAttributeValueException.


The value of this constant is 2.

See Also:
/**
     * This constant specifies to replace an attribute with specified values.
     *<p>
     * If attribute already exists,
     * replaces all existing values with new specified values.  If the
     * attribute does not exist, creates it.  If no value is specified,
     * deletes all the values of the attribute.
     * Removal of the last value will remove the attribute if the attribute
     * is required to have at least one value.  If
     * attempting to add more than one value to a single-valued attribute,
     * throws <code>InvalidAttributeValueException</code>.
     * <p>
     * The value of this constant is <tt>2</tt>.
     *
     * @see ModificationItem
     * @see #modifyAttributes
     */
    public final static int REPLACE_ATTRIBUTE = 2;

    
This constant specifies to delete
the specified attribute values from the attribute.


The resulting attribute has the set difference of its prior value set
and the specified value set.
If no values are specified, deletes the entire attribute.
If the attribute does not exist, or if some or all members of the
specified value set do not exist, this absence may be ignored
and the operation succeeds, or a NamingException may be thrown to
indicate the absence.
Removal of the last value will remove the attribute if the
attribute is required to have at least one value.


The value of this constant is 3.

See Also:
/**
     * This constant specifies to delete
     * the specified attribute values from the attribute.
     *<p>
     * The resulting attribute has the set difference of its prior value set
     * and the specified value set.
     * If no values are specified, deletes the entire attribute.
     * If the attribute does not exist, or if some or all members of the
     * specified value set do not exist, this absence may be ignored
     * and the operation succeeds, or a NamingException may be thrown to
     * indicate the absence.
     * Removal of the last value will remove the attribute if the
     * attribute is required to have at least one value.
     * <p>
     * The value of this constant is <tt>3</tt>.
     *
     * @see ModificationItem
     * @see #modifyAttributes
     */
    public final static int REMOVE_ATTRIBUTE = 3;

    
Modifies the attributes associated with a named object.
The order of the modifications is not specified.  Where
possible, the modifications are performed atomically.

Params:
  • name – 
         the name of the object whose attributes will be updated
  • mod_op – 
         the modification operation, one of:
                 ADD_ATTRIBUTE,
                 REPLACE_ATTRIBUTE,
                 REMOVE_ATTRIBUTE.
  • attrs – 
         the attributes to be used for the modification; may not be null
Throws:
See Also:
/**
     * Modifies the attributes associated with a named object.
     * The order of the modifications is not specified.  Where
     * possible, the modifications are performed atomically.
     *
     * @param name
     *          the name of the object whose attributes will be updated
     * @param mod_op
     *          the modification operation, one of:
     *                  <code>ADD_ATTRIBUTE</code>,
     *                  <code>REPLACE_ATTRIBUTE</code>,
     *                  <code>REMOVE_ATTRIBUTE</code>.
     * @param attrs
     *          the attributes to be used for the modification; may not be null
     *
     * @throws  AttributeModificationException if the modification cannot
     *          be completed successfully
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #modifyAttributes(Name, ModificationItem[])
     */
    public void modifyAttributes(Name name, int mod_op, Attributes attrs)
            throws NamingException;

    
Modifies the attributes associated with a named object. See modifyAttributes(Name, int, Attributes) for details. 
Params:
  • name – 
         the name of the object whose attributes will be updated
  • mod_op – 
         the modification operation, one of:
                 ADD_ATTRIBUTE,
                 REPLACE_ATTRIBUTE,
                 REMOVE_ATTRIBUTE.
  • attrs – 
         the attributes to be used for the modification; may not be null
Throws:
/**
     * Modifies the attributes associated with a named object.
     * See {@link #modifyAttributes(Name, int, Attributes)} for details.
     *
     * @param name
     *          the name of the object whose attributes will be updated
     * @param mod_op
     *          the modification operation, one of:
     *                  <code>ADD_ATTRIBUTE</code>,
     *                  <code>REPLACE_ATTRIBUTE</code>,
     *                  <code>REMOVE_ATTRIBUTE</code>.
     * @param attrs
     *          the attributes to be used for the modification; may not be null
     *
     * @throws  AttributeModificationException if the modification cannot
     *          be completed successfully
     * @throws  NamingException if a naming exception is encountered
     */
    public void modifyAttributes(String name, int mod_op, Attributes attrs)
            throws NamingException;

    
Modifies the attributes associated with a named object using
an ordered list of modifications.
The modifications are performed
in the order specified.  Each modification specifies a
modification operation code and an attribute on which to
operate.  Where possible, the modifications are
performed atomically.

Params:
  • name – 
         the name of the object whose attributes will be updated
  • mods – 
         an ordered sequence of modifications to be performed;
         may not be null
Throws:
See Also:
/**
     * Modifies the attributes associated with a named object using
     * an ordered list of modifications.
     * The modifications are performed
     * in the order specified.  Each modification specifies a
     * modification operation code and an attribute on which to
     * operate.  Where possible, the modifications are
     * performed atomically.
     *
     * @param name
     *          the name of the object whose attributes will be updated
     * @param mods
     *          an ordered sequence of modifications to be performed;
     *          may not be null
     *
     * @throws  AttributeModificationException if the modifications
     *          cannot be completed successfully
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #modifyAttributes(Name, int, Attributes)
     * @see ModificationItem
     */
    public void modifyAttributes(Name name, ModificationItem[] mods)
            throws NamingException;

    
Modifies the attributes associated with a named object using an ordered list of modifications. See modifyAttributes(Name, ModificationItem[]) for details. 
Params:
  • name – 
         the name of the object whose attributes will be updated
  • mods – 
         an ordered sequence of modifications to be performed;
         may not be null
Throws:
/**
     * Modifies the attributes associated with a named object using
     * an ordered list of modifications.
     * See {@link #modifyAttributes(Name, ModificationItem[])} for details.
     *
     * @param name
     *          the name of the object whose attributes will be updated
     * @param mods
     *          an ordered sequence of modifications to be performed;
     *          may not be null
     *
     * @throws  AttributeModificationException if the modifications
     *          cannot be completed successfully
     * @throws  NamingException if a naming exception is encountered
     */
    public void modifyAttributes(String name, ModificationItem[] mods)
            throws NamingException;

    
Binds a name to an object, along with associated attributes.
If attrs is null, the resulting binding will have
the attributes associated with obj if obj is a
DirContext, and no attributes otherwise.
If attrs is non-null, the resulting binding will have
attrs as its attributes; any attributes associated with
obj are ignored.

Params:
  • name – 
         the name to bind; may not be empty
  • obj – 
         the object to bind; possibly null
  • attrs – 
         the attributes to associate with the binding
Throws:
See Also:
/**
     * Binds a name to an object, along with associated attributes.
     * If <tt>attrs</tt> is null, the resulting binding will have
     * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a
     * <tt>DirContext</tt>, and no attributes otherwise.
     * If <tt>attrs</tt> is non-null, the resulting binding will have
     * <tt>attrs</tt> as its attributes; any attributes associated with
     * <tt>obj</tt> are ignored.
     *
     * @param name
     *          the name to bind; may not be empty
     * @param obj
     *          the object to bind; possibly null
     * @param attrs
     *          the attributes to associate with the binding
     *
     * @throws  NameAlreadyBoundException if name is already bound
     * @throws  InvalidAttributesException if some "mandatory" attributes
     *          of the binding are not supplied
     * @throws  NamingException if a naming exception is encountered
     *
     * @see Context#bind(Name, Object)
     * @see #rebind(Name, Object, Attributes)
     */
    public void bind(Name name, Object obj, Attributes attrs)
            throws NamingException;

    
Binds a name to an object, along with associated attributes. See bind(Name, Object, Attributes) for details. 
Params:
  • name – 
         the name to bind; may not be empty
  • obj – 
         the object to bind; possibly null
  • attrs – 
         the attributes to associate with the binding
Throws:
/**
     * Binds a name to an object, along with associated attributes.
     * See {@link #bind(Name, Object, Attributes)} for details.
     *
     * @param name
     *          the name to bind; may not be empty
     * @param obj
     *          the object to bind; possibly null
     * @param attrs
     *          the attributes to associate with the binding
     *
     * @throws  NameAlreadyBoundException if name is already bound
     * @throws  InvalidAttributesException if some "mandatory" attributes
     *          of the binding are not supplied
     * @throws  NamingException if a naming exception is encountered
     */
    public void bind(String name, Object obj, Attributes attrs)
            throws NamingException;

    
Binds a name to an object, along with associated attributes,
overwriting any existing binding.
If attrs is null and obj is a DirContext,
the attributes from obj are used.
If attrs is null and obj is not a DirContext,
any existing attributes associated with the object already bound
in the directory remain unchanged.
If attrs is non-null, any existing attributes associated with
the object already bound in the directory are removed and attrs
is associated with the named object.  If obj is a
DirContext and attrs is non-null, the attributes
of obj are ignored.

Params:
  • name – 
         the name to bind; may not be empty
  • obj – 
         the object to bind; possibly null
  • attrs – 
         the attributes to associate with the binding
Throws:
See Also:
/**
     * Binds a name to an object, along with associated attributes,
     * overwriting any existing binding.
     * If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,
     * the attributes from <tt>obj</tt> are used.
     * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,
     * any existing attributes associated with the object already bound
     * in the directory remain unchanged.
     * If <tt>attrs</tt> is non-null, any existing attributes associated with
     * the object already bound in the directory are removed and <tt>attrs</tt>
     * is associated with the named object.  If <tt>obj</tt> is a
     * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes
     * of <tt>obj</tt> are ignored.
     *
     * @param name
     *          the name to bind; may not be empty
     * @param obj
     *          the object to bind; possibly null
     * @param attrs
     *          the attributes to associate with the binding
     *
     * @throws  InvalidAttributesException if some "mandatory" attributes
     *          of the binding are not supplied
     * @throws  NamingException if a naming exception is encountered
     *
     * @see Context#bind(Name, Object)
     * @see #bind(Name, Object, Attributes)
     */
    public void rebind(Name name, Object obj, Attributes attrs)
            throws NamingException;

    
Binds a name to an object, along with associated attributes, overwriting any existing binding. See rebind(Name, Object, Attributes) for details. 
Params:
  • name – 
         the name to bind; may not be empty
  • obj – 
         the object to bind; possibly null
  • attrs – 
         the attributes to associate with the binding
Throws:
/**
     * Binds a name to an object, along with associated attributes,
     * overwriting any existing binding.
     * See {@link #rebind(Name, Object, Attributes)} for details.
     *
     * @param name
     *          the name to bind; may not be empty
     * @param obj
     *          the object to bind; possibly null
     * @param attrs
     *          the attributes to associate with the binding
     *
     * @throws  InvalidAttributesException if some "mandatory" attributes
     *          of the binding are not supplied
     * @throws  NamingException if a naming exception is encountered
     */
    public void rebind(String name, Object obj, Attributes attrs)
            throws NamingException;

    
Creates and binds a new context, along with associated attributes.
This method creates a new subcontext with the given name, binds it in
the target context (that named by all but terminal atomic
component of the name), and associates the supplied attributes
with the newly created object.
All intermediate and target contexts must already exist.
If attrs is null, this method is equivalent to
Context.createSubcontext().

Params:
  • name – 
         the name of the context to create; may not be empty
  • attrs – 
         the attributes to associate with the newly created context
Throws:
See Also:
Returns: the newly created context
/**
     * Creates and binds a new context, along with associated attributes.
     * This method creates a new subcontext with the given name, binds it in
     * the target context (that named by all but terminal atomic
     * component of the name), and associates the supplied attributes
     * with the newly created object.
     * All intermediate and target contexts must already exist.
     * If <tt>attrs</tt> is null, this method is equivalent to
     * <tt>Context.createSubcontext()</tt>.
     *
     * @param name
     *          the name of the context to create; may not be empty
     * @param attrs
     *          the attributes to associate with the newly created context
     * @return  the newly created context
     *
     * @throws  NameAlreadyBoundException if the name is already bound
     * @throws  InvalidAttributesException if <code>attrs</code> does not
     *          contain all the mandatory attributes required for creation
     * @throws  NamingException if a naming exception is encountered
     *
     * @see Context#createSubcontext(Name)
     */
    public DirContext createSubcontext(Name name, Attributes attrs)
            throws NamingException;

    
Creates and binds a new context, along with associated attributes. See createSubcontext(Name, Attributes) for details. 
Params:
  • name – 
         the name of the context to create; may not be empty
  • attrs – 
         the attributes to associate with the newly created context
Throws:
Returns: the newly created context
/**
     * Creates and binds a new context, along with associated attributes.
     * See {@link #createSubcontext(Name, Attributes)} for details.
     *
     * @param name
     *          the name of the context to create; may not be empty
     * @param attrs
     *          the attributes to associate with the newly created context
     * @return  the newly created context
     *
     * @throws  NameAlreadyBoundException if the name is already bound
     * @throws  InvalidAttributesException if <code>attrs</code> does not
     *          contain all the mandatory attributes required for creation
     * @throws  NamingException if a naming exception is encountered
     */
    public DirContext createSubcontext(String name, Attributes attrs)
            throws NamingException;

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

    
Retrieves the schema associated with the named object.
The schema describes rules regarding the structure of the namespace
and the attributes stored within it.  The schema
specifies what types of objects can be added to the directory and where
they can be added; what mandatory and optional attributes an object
can have. The range of support for schemas is directory-specific.

 This method returns the root of the schema information tree
that is applicable to the named object. Several named objects
(or even an entire directory) might share the same schema.

 Issues such as structure and contents of the schema tree,
permission to modify to the contents of the schema
tree, and the effect of such modifications on the directory
are dependent on the underlying directory.

Params:
  • name – 
         the name of the object whose schema is to be retrieved
Throws:
Returns: the schema associated with the context; never null
/**
     * Retrieves the schema associated with the named object.
     * The schema describes rules regarding the structure of the namespace
     * and the attributes stored within it.  The schema
     * specifies what types of objects can be added to the directory and where
     * they can be added; what mandatory and optional attributes an object
     * can have. The range of support for schemas is directory-specific.
     *
     * <p> This method returns the root of the schema information tree
     * that is applicable to the named object. Several named objects
     * (or even an entire directory) might share the same schema.
     *
     * <p> Issues such as structure and contents of the schema tree,
     * permission to modify to the contents of the schema
     * tree, and the effect of such modifications on the directory
     * are dependent on the underlying directory.
     *
     * @param name
     *          the name of the object whose schema is to be retrieved
     * @return  the schema associated with the context; never null
     * @throws  OperationNotSupportedException if schema not supported
     * @throws  NamingException if a naming exception is encountered
     */
    public DirContext getSchema(Name name) throws NamingException;

    
Retrieves the schema associated with the named object. See getSchema(Name) for details. 
Params:
  • name – 
         the name of the object whose schema is to be retrieved
Throws:
Returns: the schema associated with the context; never null
/**
     * Retrieves the schema associated with the named object.
     * See {@link #getSchema(Name)} for details.
     *
     * @param name
     *          the name of the object whose schema is to be retrieved
     * @return  the schema associated with the context; never null
     * @throws  OperationNotSupportedException if schema not supported
     * @throws  NamingException if a naming exception is encountered
     */
    public DirContext getSchema(String name) throws NamingException;

    
Retrieves a context containing the schema objects of the
named object's class definitions.


One category of information found in directory schemas is
class definitions.  An "object class" definition
specifies the object's type and what attributes (mandatory
and optional) the object must/can have. Note that the term
"object class" being referred to here is in the directory sense
rather than in the Java sense.
For example, if the named object is a directory object of
"Person" class, getSchemaClassDefinition() would return a
DirContext representing the (directory's) object class
definition of "Person".


The information that can be retrieved from an object class definition
is directory-dependent.


Prior to JNDI 1.2, this method
returned a single schema object representing the class definition of
the named object.
Since JNDI 1.2, this method returns a DirContext containing
all of the named object's class definitions.

Params:
  • name – 
         the name of the object whose object class
         definition is to be retrieved
Throws:
Returns: the DirContext containing the named
         object's class definitions; never null
/**
     * Retrieves a context containing the schema objects of the
     * named object's class definitions.
     *<p>
     * One category of information found in directory schemas is
     * <em>class definitions</em>.  An "object class" definition
     * specifies the object's <em>type</em> and what attributes (mandatory
     * and optional) the object must/can have. Note that the term
     * "object class" being referred to here is in the directory sense
     * rather than in the Java sense.
     * For example, if the named object is a directory object of
     * "Person" class, <tt>getSchemaClassDefinition()</tt> would return a
     * <tt>DirContext</tt> representing the (directory's) object class
     * definition of "Person".
     *<p>
     * The information that can be retrieved from an object class definition
     * is directory-dependent.
     *<p>
     * Prior to JNDI 1.2, this method
     * returned a single schema object representing the class definition of
     * the named object.
     * Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing
     * all of the named object's class definitions.
     *
     * @param name
     *          the name of the object whose object class
     *          definition is to be retrieved
     * @return  the <tt>DirContext</tt> containing the named
     *          object's class definitions; never null
     *
     * @throws  OperationNotSupportedException if schema not supported
     * @throws  NamingException if a naming exception is encountered
     */
    public DirContext getSchemaClassDefinition(Name name)
            throws NamingException;

    
Retrieves a context containing the schema objects of the named object's class definitions. See getSchemaClassDefinition(Name) for details. 
Params:
  • name – 
         the name of the object whose object class
         definition is to be retrieved
Throws:
Returns: the DirContext containing the named
         object's class definitions; never null
/**
     * Retrieves a context containing the schema objects of the
     * named object's class definitions.
     * See {@link #getSchemaClassDefinition(Name)} for details.
     *
     * @param name
     *          the name of the object whose object class
     *          definition is to be retrieved
     * @return  the <tt>DirContext</tt> containing the named
     *          object's class definitions; never null
     *
     * @throws  OperationNotSupportedException if schema not supported
     * @throws  NamingException if a naming exception is encountered
     */
    public DirContext getSchemaClassDefinition(String name)
            throws NamingException;

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

    
Searches in a single context for objects that contain a
specified set of attributes, and retrieves selected attributes.
The search is performed using the default
SearchControls settings.


For an object to be selected, each attribute in
matchingAttributes must match some attribute of the
object.  If matchingAttributes is empty or
null, all objects in the target context are returned.


An attribute A1 in
matchingAttributes is considered to match an
attribute A2 of an object if
A1 and A2 have the same
identifier, and each value of A1 is equal
to some value of A2.  This implies that the
order of values is not significant, and that
A2 may contain "extra" values not found in
A1 without affecting the comparison.  It
also implies that if A1 has no values, then
testing for a match is equivalent to testing for the presence
of an attribute A2 with the same
identifier.


The precise definition of "equality" used in comparing attribute values
is defined by the underlying directory service.  It might use the
Object.equals method, for example, or might use a schema
to specify a different equality operation.
For matching based on operations other than equality (such as
substring comparison) use the version of the search
method that takes a filter argument.


When changes are made to this DirContext,
the effect on enumerations returned by prior calls to this method
is undefined.


If the object does not have the attribute
specified, the directory will ignore the nonexistent attribute
and return the requested attributes that the object does have.


A directory might return more attributes than was requested
(see Attribute Type Names in the class description),
but is not allowed to return arbitrary, unrelated attributes.


See also Operational Attributes in the class
description.

Params:
  • name – 
         the name of the context to search
  • matchingAttributes – 
         the attributes to search for.  If empty or null,
         all objects in the target context are returned.
  • attributesToReturn – 
         the attributes to return.  null indicates that
         all attributes are to be returned;
         an empty array indicates that none are to be returned.
Throws:
See Also:
Returns:
         a non-null enumeration of SearchResult objects.
         Each SearchResult contains the attributes
         identified by attributesToReturn
         and the name of the corresponding object, named relative
         to the context named by name.
/**
     * Searches in a single context for objects that contain a
     * specified set of attributes, and retrieves selected attributes.
     * The search is performed using the default
     * <code>SearchControls</code> settings.
     * <p>
     * For an object to be selected, each attribute in
     * <code>matchingAttributes</code> must match some attribute of the
     * object.  If <code>matchingAttributes</code> is empty or
     * null, all objects in the target context are returned.
     *<p>
     * An attribute <em>A</em><sub>1</sub> in
     * <code>matchingAttributes</code> is considered to match an
     * attribute <em>A</em><sub>2</sub> of an object if
     * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same
     * identifier, and each value of <em>A</em><sub>1</sub> is equal
     * to some value of <em>A</em><sub>2</sub>.  This implies that the
     * order of values is not significant, and that
     * <em>A</em><sub>2</sub> may contain "extra" values not found in
     * <em>A</em><sub>1</sub> without affecting the comparison.  It
     * also implies that if <em>A</em><sub>1</sub> has no values, then
     * testing for a match is equivalent to testing for the presence
     * of an attribute <em>A</em><sub>2</sub> with the same
     * identifier.
     *<p>
     * The precise definition of "equality" used in comparing attribute values
     * is defined by the underlying directory service.  It might use the
     * <code>Object.equals</code> method, for example, or might use a schema
     * to specify a different equality operation.
     * For matching based on operations other than equality (such as
     * substring comparison) use the version of the <code>search</code>
     * method that takes a filter argument.
     * <p>
     * When changes are made to this <tt>DirContext</tt>,
     * the effect on enumerations returned by prior calls to this method
     * is undefined.
     *<p>
     * If the object does not have the attribute
     * specified, the directory will ignore the nonexistent attribute
     * and return the requested attributes that the object does have.
     *<p>
     * A directory might return more attributes than was requested
     * (see <strong>Attribute Type Names</strong> in the class description),
     * but is not allowed to return arbitrary, unrelated attributes.
     *<p>
     * See also <strong>Operational Attributes</strong> in the class
     * description.
     *
     * @param name
     *          the name of the context to search
     * @param matchingAttributes
     *          the attributes to search for.  If empty or null,
     *          all objects in the target context are returned.
     * @param attributesToReturn
     *          the attributes to return.  null indicates that
     *          all attributes are to be returned;
     *          an empty array indicates that none are to be returned.
     * @return
     *          a non-null enumeration of <tt>SearchResult</tt> objects.
     *          Each <tt>SearchResult</tt> contains the attributes
     *          identified by <code>attributesToReturn</code>
     *          and the name of the corresponding object, named relative
     *          to the context named by <code>name</code>.
     * @throws  NamingException if a naming exception is encountered
     *
     * @see SearchControls
     * @see SearchResult
     * @see #search(Name, String, Object[], SearchControls)
     */
    public NamingEnumeration<SearchResult>
        search(Name name,
               Attributes matchingAttributes,
               String[] attributesToReturn)
        throws NamingException;

    
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. See search(Name, Attributes, String[]) for details. 
Params:
  • name – 
         the name of the context to search
  • matchingAttributes – 
         the attributes to search for
  • attributesToReturn – 
         the attributes to return
Throws:
Returns: a non-null enumeration of SearchResult objects
/**
     * Searches in a single context for objects that contain a
     * specified set of attributes, and retrieves selected attributes.
     * See {@link #search(Name, Attributes, String[])} for details.
     *
     * @param name
     *          the name of the context to search
     * @param matchingAttributes
     *          the attributes to search for
     * @param attributesToReturn
     *          the attributes to return
     * @return  a non-null enumeration of <tt>SearchResult</tt> objects
     * @throws  NamingException if a naming exception is encountered
     */
    public NamingEnumeration<SearchResult>
        search(String name,
               Attributes matchingAttributes,
               String[] attributesToReturn)
        throws NamingException;

    
Searches in a single context for objects that contain a
specified set of attributes.
This method returns all the attributes of such objects.
It is equivalent to supplying null as
the atributesToReturn parameter to the method
search(Name, Attributes, String[]).

 See search(Name, Attributes, String[]) for a full description. 
Params:
  • name – 
         the name of the context to search
  • matchingAttributes – 
         the attributes to search for
Throws:
See Also:
Returns: an enumeration of SearchResult objects
/**
     * Searches in a single context for objects that contain a
     * specified set of attributes.
     * This method returns all the attributes of such objects.
     * It is equivalent to supplying null as
     * the <tt>atributesToReturn</tt> parameter to the method
     * <code>search(Name, Attributes, String[])</code>.
     * <br>
     * See {@link #search(Name, Attributes, String[])} for a full description.
     *
     * @param name
     *          the name of the context to search
     * @param matchingAttributes
     *          the attributes to search for
     * @return  an enumeration of <tt>SearchResult</tt> objects
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #search(Name, Attributes, String[])
     */
    public NamingEnumeration<SearchResult>
        search(Name name, Attributes matchingAttributes)
        throws NamingException;

    
Searches in a single context for objects that contain a specified set of attributes. See search(Name, Attributes) for details. 
Params:
  • name – 
         the name of the context to search
  • matchingAttributes – 
         the attributes to search for
Throws:
Returns: an enumeration of SearchResult objects
/**
     * Searches in a single context for objects that contain a
     * specified set of attributes.
     * See {@link #search(Name, Attributes)} for details.
     *
     * @param name
     *          the name of the context to search
     * @param matchingAttributes
     *          the attributes to search for
     * @return  an enumeration of <tt>SearchResult</tt> objects
     * @throws  NamingException if a naming exception is encountered
     */
    public NamingEnumeration<SearchResult>
        search(String name, Attributes matchingAttributes)
        throws NamingException;

    
Searches in the named context or object for entries that satisfy the
given search filter.  Performs the search as specified by
the search controls.


The format and interpretation of filter follows RFC 2254
with the
following interpretations for attr and value
mentioned in the RFC.


attr is the attribute's identifier.


value is the string representation the attribute's value.
The translation of this string representation into the attribute's value
is directory-specific.


For the assertion "someCount=127", for example, attr
is "someCount" and value is "127".
The provider determines, based on the attribute ID ("someCount")
(and possibly its schema), that the attribute's value is an integer.
It then parses the string "127" appropriately.


Any non-ASCII characters in the filter string should be
represented by the appropriate Java (Unicode) characters, and
not encoded as UTF-8 octets.  Alternately, the
"backslash-hexcode" notation described in RFC 2254 may be used.


If the directory does not support a string representation of
some or all of its attributes, the form of search that
accepts filter arguments in the form of Objects can be used instead.
The service provider for such a directory would then translate
the filter arguments to its service-specific representation
for filter evaluation.
See search(Name, String, Object[], SearchControls).


RFC 2254 defines certain operators for the filter, including substring
matches, equality, approximate match, greater than, less than.  These
operators are mapped to operators with corresponding semantics in the
underlying directory. For example, for the equals operator, suppose
the directory has a matching rule defining "equality" of the
attributes in the filter. This rule would be used for checking
equality of the attributes specified in the filter with the attributes
of objects in the directory. Similarly, if the directory has a
matching rule for ordering, this rule would be used for
making "greater than" and "less than" comparisons.


Not all of the operators defined in RFC 2254 are applicable to all
attributes.  When an operator is not applicable, the exception
InvalidSearchFilterException is thrown.


The result is returned in an enumeration of SearchResults.
Each SearchResult contains the name of the object
and other information about the object (see SearchResult).
The name is either relative to the target context of the search
(which is named by the name parameter), or
it is a URL string. If the target context is included in
the enumeration (as is possible when
cons specifies a search scope of
SearchControls.OBJECT_SCOPE or
SearchControls.SUBSTREE_SCOPE), its name is the empty
string. The SearchResult may also contain attributes of the
matching object if the cons argument specified that attributes
be returned.


If the object does not have a requested attribute, that
nonexistent attribute will be ignored.  Those requested
attributes that the object does have will be returned.


A directory might return more attributes than were requested
(see Attribute Type Names in the class description)
but is not allowed to return arbitrary, unrelated attributes.


See also Operational Attributes in the class
description.

Params:
  • name – 
         the name of the context or object to search
  • filter – 
         the filter expression to use for the search; may not be null
  • cons – 
         the search controls that control the search.  If null,
         the default search controls are used (equivalent
         to (new SearchControls())).
Throws:
See Also:
Returns: an enumeration of SearchResults of
         the objects that satisfy the filter; never null
/**
     * Searches in the named context or object for entries that satisfy the
     * given search filter.  Performs the search as specified by
     * the search controls.
     * <p>
     * The format and interpretation of <code>filter</code> follows RFC 2254
     * with the
     * following interpretations for <code>attr</code> and <code>value</code>
     * mentioned in the RFC.
     * <p>
     * <code>attr</code> is the attribute's identifier.
     * <p>
     * <code>value</code> is the string representation the attribute's value.
     * The translation of this string representation into the attribute's value
     * is directory-specific.
     * <p>
     * For the assertion "someCount=127", for example, <code>attr</code>
     * is "someCount" and <code>value</code> is "127".
     * The provider determines, based on the attribute ID ("someCount")
     * (and possibly its schema), that the attribute's value is an integer.
     * It then parses the string "127" appropriately.
     *<p>
     * Any non-ASCII characters in the filter string should be
     * represented by the appropriate Java (Unicode) characters, and
     * not encoded as UTF-8 octets.  Alternately, the
     * "backslash-hexcode" notation described in RFC 2254 may be used.
     *<p>
     * If the directory does not support a string representation of
     * some or all of its attributes, the form of <code>search</code> that
     * accepts filter arguments in the form of Objects can be used instead.
     * The service provider for such a directory would then translate
     * the filter arguments to its service-specific representation
     * for filter evaluation.
     * See <code>search(Name, String, Object[], SearchControls)</code>.
     * <p>
     * RFC 2254 defines certain operators for the filter, including substring
     * matches, equality, approximate match, greater than, less than.  These
     * operators are mapped to operators with corresponding semantics in the
     * underlying directory. For example, for the equals operator, suppose
     * the directory has a matching rule defining "equality" of the
     * attributes in the filter. This rule would be used for checking
     * equality of the attributes specified in the filter with the attributes
     * of objects in the directory. Similarly, if the directory has a
     * matching rule for ordering, this rule would be used for
     * making "greater than" and "less than" comparisons.
     *<p>
     * Not all of the operators defined in RFC 2254 are applicable to all
     * attributes.  When an operator is not applicable, the exception
     * <code>InvalidSearchFilterException</code> is thrown.
     * <p>
     * The result is returned in an enumeration of <tt>SearchResult</tt>s.
     * Each <tt>SearchResult</tt> contains the name of the object
     * and other information about the object (see SearchResult).
     * The name is either relative to the target context of the search
     * (which is named by the <code>name</code> parameter), or
     * it is a URL string. If the target context is included in
     * the enumeration (as is possible when
     * <code>cons</code> specifies a search scope of
     * <code>SearchControls.OBJECT_SCOPE</code> or
     * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty
     * string. The <tt>SearchResult</tt> may also contain attributes of the
     * matching object if the <tt>cons</tt> argument specified that attributes
     * be returned.
     *<p>
     * If the object does not have a requested attribute, that
     * nonexistent attribute will be ignored.  Those requested
     * attributes that the object does have will be returned.
     *<p>
     * A directory might return more attributes than were requested
     * (see <strong>Attribute Type Names</strong> in the class description)
     * but is not allowed to return arbitrary, unrelated attributes.
     *<p>
     * See also <strong>Operational Attributes</strong> in the class
     * description.
     *
     * @param name
     *          the name of the context or object to search
     * @param filter
     *          the filter expression to use for the search; may not be null
     * @param cons
     *          the search controls that control the search.  If null,
     *          the default search controls are used (equivalent
     *          to <tt>(new SearchControls())</tt>).
     * @return  an enumeration of <tt>SearchResult</tt>s of
     *          the objects that satisfy the filter; never null
     *
     * @throws  InvalidSearchFilterException if the search filter specified is
     *          not supported or understood by the underlying directory
     * @throws  InvalidSearchControlsException if the search controls
     *          contain invalid settings
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #search(Name, String, Object[], SearchControls)
     * @see SearchControls
     * @see SearchResult
     */
    public NamingEnumeration<SearchResult>
        search(Name name,
               String filter,
               SearchControls cons)
        throws NamingException;

    
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See search(Name, String, SearchControls) for details. 
Params:
  • name – 
         the name of the context or object to search
  • filter – 
         the filter expression to use for the search; may not be null
  • cons – 
         the search controls that control the search.  If null,
         the default search controls are used (equivalent
         to (new SearchControls())).
Throws:
Returns: an enumeration of SearchResults for
         the objects that satisfy the filter.
/**
     * Searches in the named context or object for entries that satisfy the
     * given search filter.  Performs the search as specified by
     * the search controls.
     * See {@link #search(Name, String, SearchControls)} for details.
     *
     * @param name
     *          the name of the context or object to search
     * @param filter
     *          the filter expression to use for the search; may not be null
     * @param cons
     *          the search controls that control the search.  If null,
     *          the default search controls are used (equivalent
     *          to <tt>(new SearchControls())</tt>).
     *
     * @return  an enumeration of <tt>SearchResult</tt>s for
     *          the objects that satisfy the filter.
     * @throws  InvalidSearchFilterException if the search filter specified is
     *          not supported or understood by the underlying directory
     * @throws  InvalidSearchControlsException if the search controls
     *          contain invalid settings
     * @throws  NamingException if a naming exception is encountered
     */
    public NamingEnumeration<SearchResult>
        search(String name,
               String filter,
               SearchControls cons)
        throws NamingException;

    
Searches in the named context or object for entries that satisfy the
given search filter.  Performs the search as specified by
the search controls.


The interpretation of filterExpr is based on RFC
2254.  It may additionally contain variables of the form
{i} -- where i is an integer -- that
refer to objects in the filterArgs array.  The
interpretation of filterExpr is otherwise
identical to that of the filter parameter of the
method search(Name, String, SearchControls).


When a variable {i} appears in a search filter, it
indicates that the filter argument filterArgs[i]
is to be used in that place.  Such variables may be used
wherever an attr, value, or
matchingrule production appears in the filter grammar
of RFC 2254, section 4.  When a string-valued filter argument
is substituted for a variable, the filter is interpreted as if
the string were given in place of the variable, with any
characters having special significance within filters (such as
'*') having been escaped according to the rules of
RFC 2254.


For directories that do not use a string representation for
some or all of their attributes, the filter argument
corresponding to an attribute value may be of a type other than
String.  Directories that support unstructured binary-valued
attributes, for example, should accept byte arrays as filter
arguments.  The interpretation (if any) of filter arguments of
any other type is determined by the service provider for that
directory, which maps the filter operations onto operations with
corresponding semantics in the underlying directory.


This method returns an enumeration of the results.
Each element in the enumeration contains the name of the object
and other information about the object (see SearchResult).
The name is either relative to the target context of the search
(which is named by the name parameter), or
it is a URL string. If the target context is included in
the enumeration (as is possible when
cons specifies a search scope of
SearchControls.OBJECT_SCOPE or
SearchControls.SUBSTREE_SCOPE),
its name is the empty string.


The SearchResult may also contain attributes of the matching
object if the cons argument specifies that attributes be
returned.


If the object does not have a requested attribute, that
nonexistent attribute will be ignored.  Those requested
attributes that the object does have will be returned.


A directory might return more attributes than were requested
(see Attribute Type Names in the class description)
but is not allowed to return arbitrary, unrelated attributes.


If a search filter with invalid variable substitutions is provided
to this method, the result is undefined.
When changes are made to this DirContext,
the effect on enumerations returned by prior calls to this method
is undefined.


See also Operational Attributes in the class
description.

Params:
  • name – 
         the name of the context or object to search
  • filterExpr – 
         the filter expression to use for the search.
         The expression may contain variables of the
         form "{i}" where i
         is a nonnegative integer.  May not be null.
  • filterArgs – 
         the array of arguments to substitute for the variables
         in filterExpr.  The value of
         filterArgs[i] will replace each
         occurrence of "{i}".
         If null, equivalent to an empty array.
  • cons – 
         the search controls that control the search.  If null,
         the default search controls are used (equivalent
         to (new SearchControls())).
Throws:
See Also:
Returns: an enumeration of SearchResults of the objects
         that satisfy the filter; never null
/**
     * Searches in the named context or object for entries that satisfy the
     * given search filter.  Performs the search as specified by
     * the search controls.
     *<p>
     * The interpretation of <code>filterExpr</code> is based on RFC
     * 2254.  It may additionally contain variables of the form
     * <code>{i}</code> -- where <code>i</code> is an integer -- that
     * refer to objects in the <code>filterArgs</code> array.  The
     * interpretation of <code>filterExpr</code> is otherwise
     * identical to that of the <code>filter</code> parameter of the
     * method <code>search(Name, String, SearchControls)</code>.
     *<p>
     * When a variable <code>{i}</code> appears in a search filter, it
     * indicates that the filter argument <code>filterArgs[i]</code>
     * is to be used in that place.  Such variables may be used
     * wherever an <em>attr</em>, <em>value</em>, or
     * <em>matchingrule</em> production appears in the filter grammar
     * of RFC 2254, section 4.  When a string-valued filter argument
     * is substituted for a variable, the filter is interpreted as if
     * the string were given in place of the variable, with any
     * characters having special significance within filters (such as
     * <code>'*'</code>) having been escaped according to the rules of
     * RFC 2254.
     *<p>
     * For directories that do not use a string representation for
     * some or all of their attributes, the filter argument
     * corresponding to an attribute value may be of a type other than
     * String.  Directories that support unstructured binary-valued
     * attributes, for example, should accept byte arrays as filter
     * arguments.  The interpretation (if any) of filter arguments of
     * any other type is determined by the service provider for that
     * directory, which maps the filter operations onto operations with
     * corresponding semantics in the underlying directory.
     *<p>
     * This method returns an enumeration of the results.
     * Each element in the enumeration contains the name of the object
     * and other information about the object (see <code>SearchResult</code>).
     * The name is either relative to the target context of the search
     * (which is named by the <code>name</code> parameter), or
     * it is a URL string. If the target context is included in
     * the enumeration (as is possible when
     * <code>cons</code> specifies a search scope of
     * <code>SearchControls.OBJECT_SCOPE</code> or
     * <code>SearchControls.SUBSTREE_SCOPE</code>),
     * its name is the empty string.
     *<p>
     * The <tt>SearchResult</tt> may also contain attributes of the matching
     * object if the <tt>cons</tt> argument specifies that attributes be
     * returned.
     *<p>
     * If the object does not have a requested attribute, that
     * nonexistent attribute will be ignored.  Those requested
     * attributes that the object does have will be returned.
     *<p>
     * A directory might return more attributes than were requested
     * (see <strong>Attribute Type Names</strong> in the class description)
     * but is not allowed to return arbitrary, unrelated attributes.
     *<p>
     * If a search filter with invalid variable substitutions is provided
     * to this method, the result is undefined.
     * When changes are made to this DirContext,
     * the effect on enumerations returned by prior calls to this method
     * is undefined.
     *<p>
     * See also <strong>Operational Attributes</strong> in the class
     * description.
     *
     * @param name
     *          the name of the context or object to search
     * @param filterExpr
     *          the filter expression to use for the search.
     *          The expression may contain variables of the
     *          form "<code>{i}</code>" where <code>i</code>
     *          is a nonnegative integer.  May not be null.
     * @param filterArgs
     *          the array of arguments to substitute for the variables
     *          in <code>filterExpr</code>.  The value of
     *          <code>filterArgs[i]</code> will replace each
     *          occurrence of "<code>{i}</code>".
     *          If null, equivalent to an empty array.
     * @param cons
     *          the search controls that control the search.  If null,
     *          the default search controls are used (equivalent
     *          to <tt>(new SearchControls())</tt>).
     * @return  an enumeration of <tt>SearchResult</tt>s of the objects
     *          that satisfy the filter; never null
     *
     * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
     *          <code>{i}</code> expressions where <code>i</code> is outside
     *          the bounds of the array <code>filterArgs</code>
     * @throws  InvalidSearchControlsException if <tt>cons</tt> contains
     *          invalid settings
     * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with
     *          <tt>filterArgs</tt> represents an invalid search filter
     * @throws  NamingException if a naming exception is encountered
     *
     * @see #search(Name, Attributes, String[])
     * @see java.text.MessageFormat
     */
    public NamingEnumeration<SearchResult>
        search(Name name,
               String filterExpr,
               Object[] filterArgs,
               SearchControls cons)
        throws NamingException;

    
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See search(Name, String, Object[], SearchControls) for details. 
Params:
  • name – 
         the name of the context or object to search
  • filterExpr – 
         the filter expression to use for the search.
         The expression may contain variables of the
         form "{i}" where i
         is a nonnegative integer.  May not be null.
  • filterArgs – 
         the array of arguments to substitute for the variables
         in filterExpr.  The value of
         filterArgs[i] will replace each
         occurrence of "{i}".
         If null, equivalent to an empty array.
  • cons – 
         the search controls that control the search.  If null,
         the default search controls are used (equivalent
         to (new SearchControls())).
Throws:
Returns: an enumeration of SearchResults of the objects
         that satisfy the filter; never null
/**
     * Searches in the named context or object for entries that satisfy the
     * given search filter.  Performs the search as specified by
     * the search controls.
     * See {@link #search(Name, String, Object[], SearchControls)} for details.
     *
     * @param name
     *          the name of the context or object to search
     * @param filterExpr
     *          the filter expression to use for the search.
     *          The expression may contain variables of the
     *          form "<code>{i}</code>" where <code>i</code>
     *          is a nonnegative integer.  May not be null.
     * @param filterArgs
     *          the array of arguments to substitute for the variables
     *          in <code>filterExpr</code>.  The value of
     *          <code>filterArgs[i]</code> will replace each
     *          occurrence of "<code>{i}</code>".
     *          If null, equivalent to an empty array.
     * @param cons
     *          the search controls that control the search.  If null,
     *          the default search controls are used (equivalent
     *          to <tt>(new SearchControls())</tt>).
     * @return  an enumeration of <tt>SearchResult</tt>s of the objects
     *          that satisfy the filter; never null
     *
     * @throws  ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
     *          <code>{i}</code> expressions where <code>i</code> is outside
     *          the bounds of the array <code>filterArgs</code>
     * @throws  InvalidSearchControlsException if <tt>cons</tt> contains
     *          invalid settings
     * @throws  InvalidSearchFilterException if <tt>filterExpr</tt> with
     *          <tt>filterArgs</tt> represents an invalid search filter
     * @throws  NamingException if a naming exception is encountered
     */
    public NamingEnumeration<SearchResult>
        search(String name,
               String filterExpr,
               Object[] filterArgs,
               SearchControls cons)
        throws NamingException;
}