/*

 * Copyright (c) 1999, 2013, 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.

 *

 * <h1>Names</h1>

 * Each name passed as an argument to a {@code DirContext} 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 {@code Context} for a discussion on the interpretation of the

 * name argument to the {@code Context} methods. These same rules

 * apply to the name argument to the {@code DirContext} methods.

 *

 * <h1>Attribute Models</h1>

 * 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.

 *

 * <h1>Attribute Type Names</h1>

 * In the {@code getAttributes()} and {@code 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.

 * <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>

 *

 *

 *<h1>Operational Attributes</h1>

 *<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 {@code getAttributes()} and {@code search()} methods,

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

 * be returned by supply {@code null} 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.

 *

 *

 * <h1>Named Context</h1>

 * <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.

 *

 *<h1>Parameters</h1>

 *<p>

 * An {@code Attributes}, {@code 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 {@code Attributes} object returned by any method is owned by

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

 * provider will not.

 *

 *<h1>Exceptions</h1>

 *<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.

     *

     * @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 {@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.

     *

     * <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 {@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.

     * <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 {@code 1}.

     *

     * @see ModificationItem

     * @see #modifyAttributes

     */

    public final static int ADD_ATTRIBUTE = 1;

    /**

     * 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 {@code 2}.

     *

     * @see ModificationItem

     * @see #modifyAttributes

     */

    public final static int REPLACE_ATTRIBUTE = 2;

    /**

     * 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 {@code 3}.

     *

     * @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.

     *

     * @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 {@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.

     *

     * @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 {@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 {@code attrs} is null, the resulting binding will have

     * the attributes associated with {@code obj} if {@code obj} is a

     * {@code DirContext}, and no attributes otherwise.

     * If {@code attrs} is non-null, the resulting binding will have

     * {@code attrs} as its attributes; any attributes associated with

     * {@code obj} 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 {@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 {@code attrs} is null and {@code obj} is a {@code DirContext},

     * the attributes from {@code obj} are used.

     * If {@code attrs} is null and {@code obj} is not a {@code DirContext},

     * any existing attributes associated with the object already bound

     * in the directory remain unchanged.

     * If {@code attrs} is non-null, any existing attributes associated with

     * the object already bound in the directory are removed and {@code attrs}

     * is associated with the named object.  If {@code obj} is a

     * {@code DirContext} and {@code attrs} is non-null, the attributes

     * of {@code obj} 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 {@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 {@code attrs} is null, this method is equivalent to

     * {@code Context.createSubcontext()}.

     *

     * @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 {@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