/* * 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. * <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. * * @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 <tt>1</tt>. * * @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 <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. *<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. * * @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 <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 {@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 <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 {@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 <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 attrsLines 1–500 of 1039. Load more
/* * 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. * <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. * * @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 <tt>1</tt>. * * @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 <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. *<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. * * @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 <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 {@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 <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 {@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 <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