2362N/A * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The directory service interface, containing 0N/A * methods for examining and updating attributes 0N/A * associated with objects, and for searching the directory. 0N/A * Each name passed as an argument to a <tt>DirContext</tt> method is relative 0N/A * to that context. The empty name is used to name the context itself. 0N/A * The name parameter may never be null. 0N/A * Most of the methods have overloaded versions with one taking a 0N/A * <code>Name</code> parameter and one taking a <code>String</code>. 0N/A * These overloaded versions are equivalent in that if 0N/A * the <code>Name</code> and <code>String</code> parameters are just 0N/A * different representations of the same name, then the overloaded 0N/A * versions of the same methods behave the same. 0N/A * In the method descriptions below, only one version is documented. 0N/A * The second version instead has a link to the first: the same 0N/A * documentation applies to both. 0N/A * See <tt>Context</tt> for a discussion on the interpretation of the 0N/A * name argument to the <tt>Context</tt> methods. These same rules 0N/A * apply to the name argument to the <tt>DirContext</tt> methods. 0N/A * <h4>Attribute Models</h4> 0N/A * There are two basic models of what attributes should be 0N/A * associated with. First, attributes may be directly associated with a 0N/A * DirContext object. 0N/A * In this model, an attribute operation on the named object is 0N/A * roughly equivalent 0N/A * to a lookup on the name (which returns the DirContext object), 0N/A * followed by the attribute operation invoked on the DirContext object 0N/A * in which the caller supplies an empty name. The attributes can be viewed 0N/A * as being stored along with the object (note that this does not imply that 0N/A * the implementation must do so). 0N/A * The second model is that attributes are associated with a 0N/A * name (typically an atomic name) in a DirContext. 0N/A * In this model, an attribute operation on the named object is 0N/A * roughly equivalent to a lookup on the name of the parent DirContext of the 0N/A * named object, followed by the attribute operation invoked on the parent 0N/A * in which the caller supplies the terminal atomic name. 0N/A * The attributes can be viewed as being stored in the parent DirContext 0N/A * (again, this does not imply that the implementation must do so). 0N/A * Objects that are not DirContexts can have attributes, as long as 0N/A * their parents are DirContexts. 0N/A * JNDI support both of these models. 0N/A * It is up to the individual service providers to decide where to 0N/A * "store" attributes. 0N/A * JNDI clients are safest when they do not make assumptions about 0N/A * whether an object's attributes are stored as part of the object, or stored 0N/A * within the parent object and associated with the object's name. 0N/A * <h4>Attribute Type Names</h4> 0N/A * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods, 0N/A * you can supply the attributes to return by supplying a list of 0N/A * attribute names (strings). 0N/A * The attributes that you get back might not have the same names as the 0N/A * attribute names you have specified. This is because some directories 0N/A * support features that cause them to return other attributes. Such 0N/A * features include attribute subclassing, attribute name synonyms, and 0N/A * attribute language codes. 0N/A * In attribute subclassing, attributes are defined in a class hierarchy. 0N/A * In some directories, for example, the "name" attribute might be the 0N/A * superclass of all name-related attributes, including "commonName" and 0N/A * "surName". Asking for the "name" attribute might return both the 0N/A * "commonName" and "surName" attributes. 0N/A * With attribute type synonyms, a directory can assign multiple names to 0N/A * the same attribute. For example, "cn" and "commonName" might both 0N/A * refer to the same attribute. Asking for "cn" might return the 0N/A * "commonName" attribute. 0N/A * Some directories support the language codes for attributes. 0N/A * Asking such a directory for the "description" attribute, for example, 0N/A * might return all of the following attributes: 0N/A * <li>description;lang-en 0N/A * <li>description;lang-de 0N/A * <li>description;lang-fr 0N/A *<h4>Operational Attributes</h4> 0N/A * Some directories have the notion of "operational attributes" which are 0N/A * attributes associated with a directory object for administrative 0N/A * purposes. An example of operational attributes is the access control 0N/A * list for an object. 0N/A * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods, 0N/A * you can specify that all attributes associated with the requested objects 0N/A * be returned by supply <tt>null</tt> as the list of attributes to return. 0N/A * The attributes returned do <em>not</em> include operational attributes. 0N/A * In order to retrieve operational attributes, you must name them explicitly. 0N/A * <h4>Named Context</h4> 0N/A * There are certain methods in which the name must resolve to a context 0N/A * (for example, when searching a single level context). The documentation 0N/A * use the term <em>named context</em> to describe their name parameter. 0N/A * For these methods, if the named object is not a DirContext, 0N/A * <code>NotContextException</code> is thrown. 0N/A * Aside from these methods, there is no requirement that the 0N/A * <em>named object</em> be a DirContext. 0N/A *<h4>Parameters</h4> 0N/A * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object 0N/A * passed as a parameter to any method will not be modified by the 0N/A * service provider. The service provider may keep a reference to it 0N/A * for the duration of the operation, including any enumeration of the 0N/A * method's results and the processing of any referrals generated. 0N/A * The caller should not modify the object during this time. 0N/A * An <tt>Attributes</tt> object returned by any method is owned by 0N/A * the caller. The caller may subsequently modify it; the service 0N/A * provider will not. 0N/A *<h4>Exceptions</h4> 0N/A * All the methods in this interface can throw a NamingException or 0N/A * any of its subclasses. See NamingException and their subclasses 0N/A * for details on each exception. 0N/A * @author Rosanna Lee 0N/A * @author Scott Seligman 0N/A * @author R. Vasudevan 0N/A * @see javax.naming.Context 0N/A * Retrieves all of the attributes associated with a named object. 0N/A * See the class description regarding attribute models, attribute 0N/A * type names, and operational attributes. 0N/A * the name of the object from which to retrieve attributes 0N/A * @return the set of attributes associated with <code>name</code>. 0N/A * Returns an empty attribute set if name has no attributes; 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #getAttributes(String) 0N/A * @see #getAttributes(Name, String[]) 0N/A * Retrieves all of the attributes associated with a named object. 0N/A * See {@link #getAttributes(Name)} for details. 0N/A * the name of the object from which to retrieve attributes 0N/A * @return the set of attributes associated with <code>name</code> 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves selected attributes associated with a named object. 0N/A * See the class description regarding attribute models, attribute 0N/A * type names, and operational attributes. 0N/A * <p> If the object does not have an attribute 0N/A * specified, the directory will ignore the nonexistent attribute 0N/A * and return those requested attributes that the object does have. 0N/A * <p> A directory might return more attributes than was requested 0N/A * (see <strong>Attribute Type Names</strong> in the class description), 0N/A * but is not allowed to return arbitrary, unrelated attributes. 0N/A * <p> See also <strong>Operational Attributes</strong> in the class 0N/A * the name of the object from which to retrieve attributes 0N/A * the identifiers of the attributes to retrieve. 0N/A * null indicates that all attributes should be retrieved; 0N/A * an empty array indicates that none should be retrieved. 0N/A * @return the requested attributes; never null 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves selected attributes associated with a named object. 0N/A * See {@link #getAttributes(Name, String[])} for details. 0N/A * The name of the object from which to retrieve attributes 0N/A * the identifiers of the attributes to retrieve. 0N/A * null indicates that all attributes should be retrieved; 0N/A * an empty array indicates that none should be retrieved. 0N/A * @return the requested attributes; never null 0N/A * @throws NamingException if a naming exception is encountered 0N/A * This constant specifies to add an attribute with the specified values. 0N/A * If attribute does not exist, 0N/A * create the attribute. The resulting attribute has a union of the 0N/A * specified value set and the prior value set. 0N/A * Adding an attribute with no value will throw 0N/A * <code>InvalidAttributeValueException</code> if the attribute must have 0N/A * at least one value. For a single-valued attribute where that attribute 0N/A * already exists, throws <code>AttributeInUseException</code>. 0N/A * If attempting to add more than one value to a single-valued attribute, 0N/A * throws <code>InvalidAttributeValueException</code>. 0N/A * The value of this constant is <tt>1</tt>. 0N/A * @see ModificationItem 0N/A * @see #modifyAttributes 0N/A * This constant specifies to replace an attribute with specified values. 0N/A * If attribute already exists, 0N/A * replaces all existing values with new specified values. If the 0N/A * attribute does not exist, creates it. If no value is specified, 0N/A * deletes all the values of the attribute. 0N/A * Removal of the last value will remove the attribute if the attribute 0N/A * is required to have at least one value. If 0N/A * attempting to add more than one value to a single-valued attribute, 0N/A * throws <code>InvalidAttributeValueException</code>. 0N/A * The value of this constant is <tt>2</tt>. 0N/A * @see ModificationItem 0N/A * @see #modifyAttributes 0N/A * This constant specifies to delete 0N/A * the specified attribute values from the attribute. 0N/A * The resulting attribute has the set difference of its prior value set 0N/A * and the specified value set. 0N/A * If no values are specified, deletes the entire attribute. 0N/A * If the attribute does not exist, or if some or all members of the 0N/A * specified value set do not exist, this absence may be ignored 0N/A * and the operation succeeds, or a NamingException may be thrown to 0N/A * indicate the absence. 0N/A * Removal of the last value will remove the attribute if the 0N/A * attribute is required to have at least one value. 0N/A * The value of this constant is <tt>3</tt>. 0N/A * @see ModificationItem 0N/A * @see #modifyAttributes 0N/A * Modifies the attributes associated with a named object. 0N/A * The order of the modifications is not specified. Where 0N/A * possible, the modifications are performed atomically. 0N/A * the name of the object whose attributes will be updated 0N/A * the modification operation, one of: 0N/A * <code>ADD_ATTRIBUTE</code>, 0N/A * <code>REPLACE_ATTRIBUTE</code>, 0N/A * <code>REMOVE_ATTRIBUTE</code>. 0N/A * the attributes to be used for the modification; may not be null 0N/A * @throws AttributeModificationException if the modification cannot 0N/A * be completed successfully 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #modifyAttributes(Name, ModificationItem[]) 0N/A * Modifies the attributes associated with a named object. 0N/A * See {@link #modifyAttributes(Name, int, Attributes)} for details. 0N/A * the name of the object whose attributes will be updated 0N/A * the modification operation, one of: 0N/A * <code>ADD_ATTRIBUTE</code>, 0N/A * <code>REPLACE_ATTRIBUTE</code>, 0N/A * <code>REMOVE_ATTRIBUTE</code>. 0N/A * the attributes to be used for the modification; may not be null 0N/A * @throws AttributeModificationException if the modification cannot 0N/A * be completed successfully 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Modifies the attributes associated with a named object using 0N/A * an ordered list of modifications. 0N/A * The modifications are performed 0N/A * in the order specified. Each modification specifies a 0N/A * modification operation code and an attribute on which to 0N/A * operate. Where possible, the modifications are 0N/A * performed atomically. 0N/A * the name of the object whose attributes will be updated 0N/A * an ordered sequence of modifications to be performed; 0N/A * @throws AttributeModificationException if the modifications 0N/A * cannot be completed successfully 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #modifyAttributes(Name, int, Attributes) 0N/A * @see ModificationItem 0N/A * Modifies the attributes associated with a named object using 0N/A * an ordered list of modifications. 0N/A * See {@link #modifyAttributes(Name, ModificationItem[])} for details. 0N/A * the name of the object whose attributes will be updated 0N/A * an ordered sequence of modifications to be performed; 0N/A * @throws AttributeModificationException if the modifications 0N/A * cannot be completed successfully 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Binds a name to an object, along with associated attributes. 0N/A * If <tt>attrs</tt> is null, the resulting binding will have 0N/A * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a 0N/A * <tt>DirContext</tt>, and no attributes otherwise. 0N/A * If <tt>attrs</tt> is non-null, the resulting binding will have 0N/A * <tt>attrs</tt> as its attributes; any attributes associated with 0N/A * <tt>obj</tt> are ignored. 0N/A * the name to bind; may not be empty 0N/A * the object to bind; possibly null 0N/A * the attributes to associate with the binding 0N/A * @throws NameAlreadyBoundException if name is already bound 0N/A * @throws InvalidAttributesException if some "mandatory" attributes 0N/A * of the binding are not supplied 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see Context#bind(Name, Object) 0N/A * @see #rebind(Name, Object, Attributes) 0N/A * Binds a name to an object, along with associated attributes. 0N/A * See {@link #bind(Name, Object, Attributes)} for details. 0N/A * the name to bind; may not be empty 0N/A * the object to bind; possibly null 0N/A * the attributes to associate with the binding 0N/A * @throws NameAlreadyBoundException if name is already bound 0N/A * @throws InvalidAttributesException if some "mandatory" attributes 0N/A * of the binding are not supplied 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Binds a name to an object, along with associated attributes, 0N/A * overwriting any existing binding. 0N/A * If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>, 0N/A * the attributes from <tt>obj</tt> are used. 0N/A * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>, 0N/A * any existing attributes associated with the object already bound 0N/A * in the directory remain unchanged. 0N/A * If <tt>attrs</tt> is non-null, any existing attributes associated with 0N/A * the object already bound in the directory are removed and <tt>attrs</tt> 0N/A * is associated with the named object. If <tt>obj</tt> is a 0N/A * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes 0N/A * of <tt>obj</tt> are ignored. 0N/A * the name to bind; may not be empty 0N/A * the object to bind; possibly null 0N/A * the attributes to associate with the binding 0N/A * @throws InvalidAttributesException if some "mandatory" attributes 0N/A * of the binding are not supplied 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see Context#bind(Name, Object) 0N/A * @see #bind(Name, Object, Attributes) 0N/A * Binds a name to an object, along with associated attributes, 0N/A * overwriting any existing binding. 0N/A * See {@link #rebind(Name, Object, Attributes)} for details. 0N/A * the name to bind; may not be empty 0N/A * the object to bind; possibly null 0N/A * the attributes to associate with the binding 0N/A * @throws InvalidAttributesException if some "mandatory" attributes 0N/A * of the binding are not supplied 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Creates and binds a new context, along with associated attributes. 0N/A * This method creates a new subcontext with the given name, binds it in 0N/A * the target context (that named by all but terminal atomic 0N/A * component of the name), and associates the supplied attributes 0N/A * with the newly created object. 0N/A * All intermediate and target contexts must already exist. 0N/A * If <tt>attrs</tt> is null, this method is equivalent to 0N/A * <tt>Context.createSubcontext()</tt>. 0N/A * the name of the context to create; may not be empty 0N/A * the attributes to associate with the newly created context 0N/A * @return the newly created context 0N/A * @throws NameAlreadyBoundException if the name is already bound 0N/A * @throws InvalidAttributesException if <code>attrs</code> does not 0N/A * contain all the mandatory attributes required for creation 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see Context#createSubcontext(Name) 0N/A * Creates and binds a new context, along with associated attributes. 0N/A * See {@link #createSubcontext(Name, Attributes)} for details. 0N/A * the name of the context to create; may not be empty 0N/A * the attributes to associate with the newly created context 0N/A * @return the newly created context 0N/A * @throws NameAlreadyBoundException if the name is already bound 0N/A * @throws InvalidAttributesException if <code>attrs</code> does not 0N/A * contain all the mandatory attributes required for creation 0N/A * @throws NamingException if a naming exception is encountered 0N/A// -------------------- schema operations 0N/A * Retrieves the schema associated with the named object. 0N/A * The schema describes rules regarding the structure of the namespace 0N/A * and the attributes stored within it. The schema 0N/A * specifies what types of objects can be added to the directory and where 0N/A * they can be added; what mandatory and optional attributes an object 0N/A * can have. The range of support for schemas is directory-specific. 0N/A * <p> This method returns the root of the schema information tree 0N/A * that is applicable to the named object. Several named objects 0N/A * (or even an entire directory) might share the same schema. 0N/A * <p> Issues such as structure and contents of the schema tree, 0N/A * permission to modify to the contents of the schema 0N/A * tree, and the effect of such modifications on the directory 0N/A * are dependent on the underlying directory. 0N/A * the name of the object whose schema is to be retrieved 0N/A * @return the schema associated with the context; never null 0N/A * @throws OperationNotSupportedException if schema not supported 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves the schema associated with the named object. 0N/A * See {@link #getSchema(Name)} for details. 0N/A * the name of the object whose schema is to be retrieved 0N/A * @return the schema associated with the context; never null 0N/A * @throws OperationNotSupportedException if schema not supported 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves a context containing the schema objects of the 0N/A * named object's class definitions. 0N/A * One category of information found in directory schemas is 0N/A * <em>class definitions</em>. An "object class" definition 0N/A * specifies the object's <em>type</em> and what attributes (mandatory 0N/A * and optional) the object must/can have. Note that the term 0N/A * "object class" being referred to here is in the directory sense 0N/A * rather than in the Java sense. 0N/A * For example, if the named object is a directory object of 0N/A * "Person" class, <tt>getSchemaClassDefinition()</tt> would return a 0N/A * <tt>DirContext</tt> representing the (directory's) object class 0N/A * definition of "Person". 0N/A * The information that can be retrieved from an object class definition 0N/A * is directory-dependent. 0N/A * Prior to JNDI 1.2, this method 0N/A * returned a single schema object representing the class definition of 0N/A * Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing 0N/A * all of the named object's class definitions. 0N/A * the name of the object whose object class 0N/A * definition is to be retrieved 0N/A * @return the <tt>DirContext</tt> containing the named 0N/A * object's class definitions; never null 0N/A * @throws OperationNotSupportedException if schema not supported 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves a context containing the schema objects of the 0N/A * named object's class definitions. 0N/A * See {@link #getSchemaClassDefinition(Name)} for details. 0N/A * the name of the object whose object class 0N/A * definition is to be retrieved 0N/A * @return the <tt>DirContext</tt> containing the named 0N/A * object's class definitions; never null 0N/A * @throws OperationNotSupportedException if schema not supported 0N/A * @throws NamingException if a naming exception is encountered 0N/A// -------------------- search operations 0N/A * Searches in a single context for objects that contain a 0N/A * specified set of attributes, and retrieves selected attributes. 0N/A * The search is performed using the default 0N/A * <code>SearchControls</code> settings. 0N/A * For an object to be selected, each attribute in 0N/A * <code>matchingAttributes</code> must match some attribute of the 0N/A * object. If <code>matchingAttributes</code> is empty or 0N/A * null, all objects in the target context are returned. 0N/A * An attribute <em>A</em><sub>1</sub> in 0N/A * <code>matchingAttributes</code> is considered to match an 0N/A * attribute <em>A</em><sub>2</sub> of an object if 0N/A * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same 0N/A * identifier, and each value of <em>A</em><sub>1</sub> is equal 0N/A * to some value of <em>A</em><sub>2</sub>. This implies that the 0N/A * order of values is not significant, and that 0N/A * <em>A</em><sub>2</sub> may contain "extra" values not found in 0N/A * <em>A</em><sub>1</sub> without affecting the comparison. It 0N/A * also implies that if <em>A</em><sub>1</sub> has no values, then 0N/A * testing for a match is equivalent to testing for the presence 0N/A * of an attribute <em>A</em><sub>2</sub> with the same 0N/A * The precise definition of "equality" used in comparing attribute values 0N/A * is defined by the underlying directory service. It might use the 0N/A * <code>Object.equals</code> method, for example, or might use a schema 0N/A * to specify a different equality operation. 0N/A * For matching based on operations other than equality (such as 0N/A * substring comparison) use the version of the <code>search</code> 0N/A * method that takes a filter argument. 0N/A * When changes are made to this <tt>DirContext</tt>, 0N/A * the effect on enumerations returned by prior calls to this method 0N/A * If the object does not have the attribute 0N/A * specified, the directory will ignore the nonexistent attribute 0N/A * and return the requested attributes that the object does have. 0N/A * A directory might return more attributes than was requested 0N/A * (see <strong>Attribute Type Names</strong> in the class description), 0N/A * but is not allowed to return arbitrary, unrelated attributes. 0N/A * See also <strong>Operational Attributes</strong> in the class 0N/A * the name of the context to search 0N/A * @param matchingAttributes 0N/A * the attributes to search for. If empty or null, 0N/A * all objects in the target context are returned. 0N/A * @param attributesToReturn 0N/A * the attributes to return. null indicates that 0N/A * all attributes are to be returned; 0N/A * an empty array indicates that none are to be returned. 0N/A * a non-null enumeration of <tt>SearchResult</tt> objects. 0N/A * Each <tt>SearchResult</tt> contains the attributes 0N/A * identified by <code>attributesToReturn</code> 0N/A * and the name of the corresponding object, named relative 0N/A * to the context named by <code>name</code>. 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see SearchControls 0N/A * @see #search(Name, String, Object[], SearchControls) 0N/A * Searches in a single context for objects that contain a 0N/A * specified set of attributes, and retrieves selected attributes. 0N/A * See {@link #search(Name, Attributes, String[])} for details. 0N/A * the name of the context to search 0N/A * @param matchingAttributes 0N/A * the attributes to search for 0N/A * @param attributesToReturn 0N/A * the attributes to return 0N/A * @return a non-null enumeration of <tt>SearchResult</tt> objects 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Searches in a single context for objects that contain a 0N/A * specified set of attributes. 0N/A * This method returns all the attributes of such objects. 0N/A * It is equivalent to supplying null as 0N/A * the <tt>atributesToReturn</tt> parameter to the method 0N/A * <code>search(Name, Attributes, String[])</code>. 0N/A * See {@link #search(Name, Attributes, String[])} for a full description. 0N/A * the name of the context to search 0N/A * @param matchingAttributes 0N/A * the attributes to search for 0N/A * @return an enumeration of <tt>SearchResult</tt> objects 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #search(Name, Attributes, String[]) 0N/A * Searches in a single context for objects that contain a 0N/A * specified set of attributes. 0N/A * See {@link #search(Name, Attributes)} for details. 0N/A * the name of the context to search 0N/A * @param matchingAttributes 0N/A * the attributes to search for 0N/A * @return an enumeration of <tt>SearchResult</tt> objects 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Searches in the named context or object for entries that satisfy the 0N/A * given search filter. Performs the search as specified by 0N/A * the search controls. 0N/A * The format and interpretation of <code>filter</code> follows RFC 2254 0N/A * following interpretations for <code>attr</code> and <code>value</code> 0N/A * mentioned in the RFC. 0N/A * <code>attr</code> is the attribute's identifier. 0N/A * <code>value</code> is the string representation the attribute's value. 0N/A * The translation of this string representation into the attribute's value 0N/A * is directory-specific. 0N/A * For the assertion "someCount=127", for example, <code>attr</code> 0N/A * is "someCount" and <code>value</code> is "127". 0N/A * The provider determines, based on the attribute ID ("someCount") 0N/A * (and possibly its schema), that the attribute's value is an integer. 0N/A * It then parses the string "127" appropriately. 0N/A * Any non-ASCII characters in the filter string should be 0N/A * represented by the appropriate Java (Unicode) characters, and 0N/A * not encoded as UTF-8 octets. Alternately, the 0N/A * "backslash-hexcode" notation described in RFC 2254 may be used. 0N/A * If the directory does not support a string representation of 0N/A * some or all of its attributes, the form of <code>search</code> that 0N/A * accepts filter arguments in the form of Objects can be used instead. 0N/A * The service provider for such a directory would then translate 0N/A * the filter arguments to its service-specific representation 0N/A * for filter evaluation. 0N/A * See <code>search(Name, String, Object[], SearchControls)</code>. 0N/A * RFC 2254 defines certain operators for the filter, including substring 0N/A * matches, equality, approximate match, greater than, less than. These 0N/A * operators are mapped to operators with corresponding semantics in the 0N/A * underlying directory. For example, for the equals operator, suppose 0N/A * the directory has a matching rule defining "equality" of the 0N/A * attributes in the filter. This rule would be used for checking 0N/A * equality of the attributes specified in the filter with the attributes 0N/A * of objects in the directory. Similarly, if the directory has a 0N/A * matching rule for ordering, this rule would be used for 0N/A * making "greater than" and "less than" comparisons. 0N/A * Not all of the operators defined in RFC 2254 are applicable to all 0N/A * attributes. When an operator is not applicable, the exception 0N/A * <code>InvalidSearchFilterException</code> is thrown. 0N/A * The result is returned in an enumeration of <tt>SearchResult</tt>s. 0N/A * Each <tt>SearchResult</tt> contains the name of the object 0N/A * and other information about the object (see SearchResult). 0N/A * The name is either relative to the target context of the search 0N/A * (which is named by the <code>name</code> parameter), or 0N/A * it is a URL string. If the target context is included in 0N/A * the enumeration (as is possible when 0N/A * <code>cons</code> specifies a search scope of 0N/A * <code>SearchControls.OBJECT_SCOPE</code> or 0N/A * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty 0N/A * string. The <tt>SearchResult</tt> may also contain attributes of the 0N/A * matching object if the <tt>cons</tt> argument specified that attributes 0N/A * If the object does not have a requested attribute, that 0N/A * nonexistent attribute will be ignored. Those requested 0N/A * attributes that the object does have will be returned. 0N/A * A directory might return more attributes than were requested 0N/A * (see <strong>Attribute Type Names</strong> in the class description) 0N/A * but is not allowed to return arbitrary, unrelated attributes. 0N/A * See also <strong>Operational Attributes</strong> in the class 0N/A * the name of the context or object to search 0N/A * the filter expression to use for the search; may not be null 0N/A * the search controls that control the search. If null, 0N/A * the default search controls are used (equivalent 0N/A * to <tt>(new SearchControls())</tt>). 0N/A * @return an enumeration of <tt>SearchResult</tt>s of 0N/A * the objects that satisfy the filter; never null 0N/A * @throws InvalidSearchFilterException if the search filter specified is 0N/A * not supported or understood by the underlying directory 0N/A * @throws InvalidSearchControlsException if the search controls 0N/A * contain invalid settings 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #search(Name, String, Object[], SearchControls) 0N/A * @see SearchControls 0N/A * Searches in the named context or object for entries that satisfy the 0N/A * given search filter. Performs the search as specified by 0N/A * the search controls. 0N/A * See {@link #search(Name, String, SearchControls)} for details. 0N/A * the name of the context or object to search 0N/A * the filter expression to use for the search; may not be null 0N/A * the search controls that control the search. If null, 0N/A * the default search controls are used (equivalent 0N/A * to <tt>(new SearchControls())</tt>). 0N/A * @return an enumeration of <tt>SearchResult</tt>s for 0N/A * the objects that satisfy the filter. 0N/A * @throws InvalidSearchFilterException if the search filter specified is 0N/A * not supported or understood by the underlying directory 0N/A * @throws InvalidSearchControlsException if the search controls 0N/A * contain invalid settings 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Searches in the named context or object for entries that satisfy the 0N/A * given search filter. Performs the search as specified by 0N/A * the search controls. 0N/A * The interpretation of <code>filterExpr</code> is based on RFC 0N/A * 2254. It may additionally contain variables of the form 0N/A * <code>{i}</code> -- where <code>i</code> is an integer -- that 0N/A * refer to objects in the <code>filterArgs</code> array. The 0N/A * interpretation of <code>filterExpr</code> is otherwise 0N/A * identical to that of the <code>filter</code> parameter of the 0N/A * method <code>search(Name, String, SearchControls)</code>. 0N/A * When a variable <code>{i}</code> appears in a search filter, it 0N/A * indicates that the filter argument <code>filterArgs[i]</code> 0N/A * is to be used in that place. Such variables may be used 0N/A * wherever an <em>attr</em>, <em>value</em>, or 0N/A * <em>matchingrule</em> production appears in the filter grammar 0N/A * of RFC 2254, section 4. When a string-valued filter argument 0N/A * is substituted for a variable, the filter is interpreted as if 0N/A * the string were given in place of the variable, with any 0N/A * characters having special significance within filters (such as 0N/A * <code>'*'</code>) having been escaped according to the rules of 0N/A * For directories that do not use a string representation for 0N/A * some or all of their attributes, the filter argument 0N/A * corresponding to an attribute value may be of a type other than 0N/A * String. Directories that support unstructured binary-valued 0N/A * attributes, for example, should accept byte arrays as filter 0N/A * arguments. The interpretation (if any) of filter arguments of 0N/A * any other type is determined by the service provider for that 0N/A * directory, which maps the filter operations onto operations with 0N/A * corresponding semantics in the underlying directory. 0N/A * This method returns an enumeration of the results. 0N/A * Each element in the enumeration contains the name of the object 0N/A * and other information about the object (see <code>SearchResult</code>). 0N/A * The name is either relative to the target context of the search 0N/A * (which is named by the <code>name</code> parameter), or 0N/A * it is a URL string. If the target context is included in 0N/A * the enumeration (as is possible when 0N/A * <code>cons</code> specifies a search scope of 0N/A * <code>SearchControls.OBJECT_SCOPE</code> or 0N/A * <code>SearchControls.SUBSTREE_SCOPE</code>), 0N/A * its name is the empty string. 0N/A * The <tt>SearchResult</tt> may also contain attributes of the matching 0N/A * object if the <tt>cons</tt> argument specifies that attributes be 0N/A * If the object does not have a requested attribute, that 0N/A * nonexistent attribute will be ignored. Those requested 0N/A * attributes that the object does have will be returned. 0N/A * A directory might return more attributes than were requested 0N/A * (see <strong>Attribute Type Names</strong> in the class description) 0N/A * but is not allowed to return arbitrary, unrelated attributes. 0N/A * If a search filter with invalid variable substitutions is provided 0N/A * to this method, the result is undefined. 0N/A * When changes are made to this DirContext, 0N/A * the effect on enumerations returned by prior calls to this method 0N/A * See also <strong>Operational Attributes</strong> in the class 0N/A * the name of the context or object to search 0N/A * the filter expression to use for the search. 0N/A * The expression may contain variables of the 0N/A * form "<code>{i}</code>" where <code>i</code> 0N/A * is a nonnegative integer. May not be null. 0N/A * the array of arguments to substitute for the variables 0N/A * in <code>filterExpr</code>. The value of 0N/A * <code>filterArgs[i]</code> will replace each 0N/A * occurrence of "<code>{i}</code>". 0N/A * If null, equivalent to an empty array. 0N/A * the search controls that control the search. If null, 0N/A * the default search controls are used (equivalent 0N/A * to <tt>(new SearchControls())</tt>). 0N/A * @return an enumeration of <tt>SearchResult</tt>s of the objects 0N/A * that satisfy the filter; never null 0N/A * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains 0N/A * <code>{i}</code> expressions where <code>i</code> is outside 0N/A * the bounds of the array <code>filterArgs</code> 0N/A * @throws InvalidSearchControlsException if <tt>cons</tt> contains 0N/A * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with 0N/A * <tt>filterArgs</tt> represents an invalid search filter 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #search(Name, Attributes, String[]) 0N/A * @see java.text.MessageFormat 0N/A * Searches in the named context or object for entries that satisfy the 0N/A * given search filter. Performs the search as specified by 0N/A * the search controls. 0N/A * See {@link #search(Name, String, Object[], SearchControls)} for details. 0N/A * the name of the context or object to search 0N/A * the filter expression to use for the search. 0N/A * The expression may contain variables of the 0N/A * form "<code>{i}</code>" where <code>i</code> 0N/A * is a nonnegative integer. May not be null. 0N/A * the array of arguments to substitute for the variables 0N/A * in <code>filterExpr</code>. The value of 0N/A * <code>filterArgs[i]</code> will replace each 0N/A * occurrence of "<code>{i}</code>". 0N/A * If null, equivalent to an empty array. 0N/A * the search controls that control the search. If null, 0N/A * the default search controls are used (equivalent 0N/A * to <tt>(new SearchControls())</tt>). 0N/A * @return an enumeration of <tt>SearchResult</tt>s of the objects 0N/A * that satisfy the filter; never null 0N/A * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains 0N/A * <code>{i}</code> expressions where <code>i</code> is outside 0N/A * the bounds of the array <code>filterArgs</code> 0N/A * @throws InvalidSearchControlsException if <tt>cons</tt> contains 0N/A * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with 0N/A * <tt>filterArgs</tt> represents an invalid search filter 0N/A * @throws NamingException if a naming exception is encountered