1 /* 2 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.naming.directory; 27 28 import javax.naming.*; 29 30 /** 31 * The directory service interface, containing 32 * methods for examining and updating attributes 33 * associated with objects, and for searching the directory. 34 * 35 * <h1>Names</h1> 36 * Each name passed as an argument to a {@code DirContext} method is relative 37 * to that context. The empty name is used to name the context itself. 38 * The name parameter may never be null. 39 * <p> 40 * Most of the methods have overloaded versions with one taking a 41 * <code>Name</code> parameter and one taking a <code>String</code>. 42 * These overloaded versions are equivalent in that if 43 * the <code>Name</code> and <code>String</code> parameters are just 44 * different representations of the same name, then the overloaded 45 * versions of the same methods behave the same. 46 * In the method descriptions below, only one version is documented. 47 * The second version instead has a link to the first: the same 48 * documentation applies to both. 49 * <p> 50 * See {@code Context} for a discussion on the interpretation of the 51 * name argument to the {@code Context} methods. These same rules 52 * apply to the name argument to the {@code DirContext} methods. 53 * 54 * <h1>Attribute Models</h1> 55 * There are two basic models of what attributes should be 56 * associated with. First, attributes may be directly associated with a 57 * DirContext object. 58 * In this model, an attribute operation on the named object is 59 * roughly equivalent 60 * to a lookup on the name (which returns the DirContext object), 61 * followed by the attribute operation invoked on the DirContext object 62 * in which the caller supplies an empty name. The attributes can be viewed 63 * as being stored along with the object (note that this does not imply that 64 * the implementation must do so). 65 * <p> 66 * The second model is that attributes are associated with a 67 * name (typically an atomic name) in a DirContext. 68 * In this model, an attribute operation on the named object is 69 * roughly equivalent to a lookup on the name of the parent DirContext of the 70 * named object, followed by the attribute operation invoked on the parent 71 * in which the caller supplies the terminal atomic name. 72 * The attributes can be viewed as being stored in the parent DirContext 73 * (again, this does not imply that the implementation must do so). 74 * Objects that are not DirContexts can have attributes, as long as 75 * their parents are DirContexts. 76 * <p> 77 * JNDI support both of these models. 78 * It is up to the individual service providers to decide where to 79 * "store" attributes. 80 * JNDI clients are safest when they do not make assumptions about 81 * whether an object's attributes are stored as part of the object, or stored 82 * within the parent object and associated with the object's name. 83 * 84 * <h1>Attribute Type Names</h1> 85 * In the {@code getAttributes()} and {@code search()} methods, 86 * you can supply the attributes to return by supplying a list of 87 * attribute names (strings). 88 * The attributes that you get back might not have the same names as the 89 * attribute names you have specified. This is because some directories 90 * support features that cause them to return other attributes. Such 91 * features include attribute subclassing, attribute name synonyms, and 92 * attribute language codes. 93 * <p> 94 * In attribute subclassing, attributes are defined in a class hierarchy. 95 * In some directories, for example, the "name" attribute might be the 96 * superclass of all name-related attributes, including "commonName" and 97 * "surName". Asking for the "name" attribute might return both the 98 * "commonName" and "surName" attributes. 99 * <p> 100 * With attribute type synonyms, a directory can assign multiple names to 101 * the same attribute. For example, "cn" and "commonName" might both 102 * refer to the same attribute. Asking for "cn" might return the 103 * "commonName" attribute. 104 * <p> 105 * Some directories support the language codes for attributes. 106 * Asking such a directory for the "description" attribute, for example, 107 * might return all of the following attributes: 108 * <ul> 109 * <li>description 110 * <li>description;lang-en 111 * <li>description;lang-de 112 * <li>description;lang-fr 113 * </ul> 114 * 115 * 116 *<h1>Operational Attributes</h1> 117 *<p> 118 * Some directories have the notion of "operational attributes" which are 119 * attributes associated with a directory object for administrative 120 * purposes. An example of operational attributes is the access control 121 * list for an object. 122 * <p> 123 * In the {@code getAttributes()} and {@code search()} methods, 124 * you can specify that all attributes associated with the requested objects 125 * be returned by supply {@code null} as the list of attributes to return. 126 * The attributes returned do <em>not</em> include operational attributes. 127 * In order to retrieve operational attributes, you must name them explicitly. 128 * 129 * 130 * <h1>Named Context</h1> 131 * <p> 132 * There are certain methods in which the name must resolve to a context 133 * (for example, when searching a single level context). The documentation 134 * of such methods 135 * use the term <em>named context</em> to describe their name parameter. 136 * For these methods, if the named object is not a DirContext, 137 * <code>NotContextException</code> is thrown. 138 * Aside from these methods, there is no requirement that the 139 * <em>named object</em> be a DirContext. 140 * 141 *<h1>Parameters</h1> 142 *<p> 143 * An {@code Attributes}, {@code SearchControls}, or array object 144 * passed as a parameter to any method will not be modified by the 145 * service provider. The service provider may keep a reference to it 146 * for the duration of the operation, including any enumeration of the 147 * method's results and the processing of any referrals generated. 148 * The caller should not modify the object during this time. 149 * An {@code Attributes} object returned by any method is owned by 150 * the caller. The caller may subsequently modify it; the service 151 * provider will not. 152 * 153 *<h1>Exceptions</h1> 154 *<p> 155 * All the methods in this interface can throw a NamingException or 156 * any of its subclasses. See NamingException and their subclasses 157 * for details on each exception. 158 * 159 * @author Rosanna Lee 160 * @author Scott Seligman 161 * @author R. Vasudevan 162 * 163 * @see javax.naming.Context 164 * @since 1.3 165 */ 166 167 public interface DirContext extends Context { 168 169 /** 170 * Retrieves all of the attributes associated with a named object. 171 * See the class description regarding attribute models, attribute 172 * type names, and operational attributes. 173 * | 1 /* 2 * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.naming.directory; 27 28 import javax.naming.*; 29 30 /** 31 * The directory service interface, containing 32 * methods for examining and updating attributes 33 * associated with objects, and for searching the directory. 34 * 35 * <h2>Names</h2> 36 * Each name passed as an argument to a {@code DirContext} method is relative 37 * to that context. The empty name is used to name the context itself. 38 * The name parameter may never be null. 39 * <p> 40 * Most of the methods have overloaded versions with one taking a 41 * <code>Name</code> parameter and one taking a <code>String</code>. 42 * These overloaded versions are equivalent in that if 43 * the <code>Name</code> and <code>String</code> parameters are just 44 * different representations of the same name, then the overloaded 45 * versions of the same methods behave the same. 46 * In the method descriptions below, only one version is documented. 47 * The second version instead has a link to the first: the same 48 * documentation applies to both. 49 * <p> 50 * See {@code Context} for a discussion on the interpretation of the 51 * name argument to the {@code Context} methods. These same rules 52 * apply to the name argument to the {@code DirContext} methods. 53 * 54 * <h2>Attribute Models</h2> 55 * There are two basic models of what attributes should be 56 * associated with. First, attributes may be directly associated with a 57 * DirContext object. 58 * In this model, an attribute operation on the named object is 59 * roughly equivalent 60 * to a lookup on the name (which returns the DirContext object), 61 * followed by the attribute operation invoked on the DirContext object 62 * in which the caller supplies an empty name. The attributes can be viewed 63 * as being stored along with the object (note that this does not imply that 64 * the implementation must do so). 65 * <p> 66 * The second model is that attributes are associated with a 67 * name (typically an atomic name) in a DirContext. 68 * In this model, an attribute operation on the named object is 69 * roughly equivalent to a lookup on the name of the parent DirContext of the 70 * named object, followed by the attribute operation invoked on the parent 71 * in which the caller supplies the terminal atomic name. 72 * The attributes can be viewed as being stored in the parent DirContext 73 * (again, this does not imply that the implementation must do so). 74 * Objects that are not DirContexts can have attributes, as long as 75 * their parents are DirContexts. 76 * <p> 77 * JNDI support both of these models. 78 * It is up to the individual service providers to decide where to 79 * "store" attributes. 80 * JNDI clients are safest when they do not make assumptions about 81 * whether an object's attributes are stored as part of the object, or stored 82 * within the parent object and associated with the object's name. 83 * 84 * <h2>Attribute Type Names</h2> 85 * In the {@code getAttributes()} and {@code search()} methods, 86 * you can supply the attributes to return by supplying a list of 87 * attribute names (strings). 88 * The attributes that you get back might not have the same names as the 89 * attribute names you have specified. This is because some directories 90 * support features that cause them to return other attributes. Such 91 * features include attribute subclassing, attribute name synonyms, and 92 * attribute language codes. 93 * <p> 94 * In attribute subclassing, attributes are defined in a class hierarchy. 95 * In some directories, for example, the "name" attribute might be the 96 * superclass of all name-related attributes, including "commonName" and 97 * "surName". Asking for the "name" attribute might return both the 98 * "commonName" and "surName" attributes. 99 * <p> 100 * With attribute type synonyms, a directory can assign multiple names to 101 * the same attribute. For example, "cn" and "commonName" might both 102 * refer to the same attribute. Asking for "cn" might return the 103 * "commonName" attribute. 104 * <p> 105 * Some directories support the language codes for attributes. 106 * Asking such a directory for the "description" attribute, for example, 107 * might return all of the following attributes: 108 * <ul> 109 * <li>description 110 * <li>description;lang-en 111 * <li>description;lang-de 112 * <li>description;lang-fr 113 * </ul> 114 * 115 * 116 *<h2>Operational Attributes</h2> 117 *<p> 118 * Some directories have the notion of "operational attributes" which are 119 * attributes associated with a directory object for administrative 120 * purposes. An example of operational attributes is the access control 121 * list for an object. 122 * <p> 123 * In the {@code getAttributes()} and {@code search()} methods, 124 * you can specify that all attributes associated with the requested objects 125 * be returned by supply {@code null} as the list of attributes to return. 126 * The attributes returned do <em>not</em> include operational attributes. 127 * In order to retrieve operational attributes, you must name them explicitly. 128 * 129 * 130 * <h2>Named Context</h2> 131 * <p> 132 * There are certain methods in which the name must resolve to a context 133 * (for example, when searching a single level context). The documentation 134 * of such methods 135 * use the term <em>named context</em> to describe their name parameter. 136 * For these methods, if the named object is not a DirContext, 137 * <code>NotContextException</code> is thrown. 138 * Aside from these methods, there is no requirement that the 139 * <em>named object</em> be a DirContext. 140 * 141 *<h2>Parameters</h2> 142 *<p> 143 * An {@code Attributes}, {@code SearchControls}, or array object 144 * passed as a parameter to any method will not be modified by the 145 * service provider. The service provider may keep a reference to it 146 * for the duration of the operation, including any enumeration of the 147 * method's results and the processing of any referrals generated. 148 * The caller should not modify the object during this time. 149 * An {@code Attributes} object returned by any method is owned by 150 * the caller. The caller may subsequently modify it; the service 151 * provider will not. 152 * 153 *<h2>Exceptions</h2> 154 *<p> 155 * All the methods in this interface can throw a NamingException or 156 * any of its subclasses. See NamingException and their subclasses 157 * for details on each exception. 158 * 159 * @author Rosanna Lee 160 * @author Scott Seligman 161 * @author R. Vasudevan 162 * 163 * @see javax.naming.Context 164 * @since 1.3 165 */ 166 167 public interface DirContext extends Context { 168 169 /** 170 * Retrieves all of the attributes associated with a named object. 171 * See the class description regarding attribute models, attribute 172 * type names, and operational attributes. 173 * |