29 |
29 |
30 /** |
30 /** |
31 * The directory service interface, containing |
31 * The directory service interface, containing |
32 * methods for examining and updating attributes |
32 * methods for examining and updating attributes |
33 * associated with objects, and for searching the directory. |
33 * associated with objects, and for searching the directory. |
34 * <p> |
34 * |
35 * <h1>Names</h1> |
35 * <h1>Names</h1> |
36 * Each name passed as an argument to a <tt>DirContext</tt> method is relative |
36 * Each name passed as an argument to a <tt>DirContext</tt> method is relative |
37 * to that context. The empty name is used to name the context itself. |
37 * to that context. The empty name is used to name the context itself. |
38 * The name parameter may never be null. |
38 * The name parameter may never be null. |
39 * <p> |
39 * <p> |
48 * documentation applies to both. |
48 * documentation applies to both. |
49 * <p> |
49 * <p> |
50 * See <tt>Context</tt> for a discussion on the interpretation of the |
50 * See <tt>Context</tt> for a discussion on the interpretation of the |
51 * name argument to the <tt>Context</tt> methods. These same rules |
51 * name argument to the <tt>Context</tt> methods. These same rules |
52 * apply to the name argument to the <tt>DirContext</tt> methods. |
52 * apply to the name argument to the <tt>DirContext</tt> methods. |
53 * <p> |
53 * |
54 * <h1>Attribute Models</h1> |
54 * <h1>Attribute Models</h1> |
55 * There are two basic models of what attributes should be |
55 * There are two basic models of what attributes should be |
56 * associated with. First, attributes may be directly associated with a |
56 * associated with. First, attributes may be directly associated with a |
57 * DirContext object. |
57 * DirContext object. |
58 * In this model, an attribute operation on the named object is |
58 * In this model, an attribute operation on the named object is |
78 * It is up to the individual service providers to decide where to |
78 * It is up to the individual service providers to decide where to |
79 * "store" attributes. |
79 * "store" attributes. |
80 * JNDI clients are safest when they do not make assumptions about |
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 |
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. |
82 * within the parent object and associated with the object's name. |
83 * <p> |
83 * |
84 * <h1>Attribute Type Names</h1> |
84 * <h1>Attribute Type Names</h1> |
85 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods, |
85 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods, |
86 * you can supply the attributes to return by supplying a list of |
86 * you can supply the attributes to return by supplying a list of |
87 * attribute names (strings). |
87 * attribute names (strings). |
88 * The attributes that you get back might not have the same names as the |
88 * The attributes that you get back might not have the same names as the |
110 * <li>description;lang-en |
110 * <li>description;lang-en |
111 * <li>description;lang-de |
111 * <li>description;lang-de |
112 * <li>description;lang-fr |
112 * <li>description;lang-fr |
113 * </ul> |
113 * </ul> |
114 * |
114 * |
115 * <p> |
115 * |
116 *<h1>Operational Attributes</h1> |
116 *<h1>Operational Attributes</h1> |
117 *<p> |
117 *<p> |
118 * Some directories have the notion of "operational attributes" which are |
118 * Some directories have the notion of "operational attributes" which are |
119 * attributes associated with a directory object for administrative |
119 * attributes associated with a directory object for administrative |
120 * purposes. An example of operational attributes is the access control |
120 * purposes. An example of operational attributes is the access control |
124 * you can specify that all attributes associated with the requested objects |
124 * you can specify that all attributes associated with the requested objects |
125 * be returned by supply <tt>null</tt> as the list of attributes to return. |
125 * be returned by supply <tt>null</tt> as the list of attributes to return. |
126 * The attributes returned do <em>not</em> include operational attributes. |
126 * The attributes returned do <em>not</em> include operational attributes. |
127 * In order to retrieve operational attributes, you must name them explicitly. |
127 * In order to retrieve operational attributes, you must name them explicitly. |
128 * |
128 * |
129 * <p> |
129 * |
130 * <h1>Named Context</h1> |
130 * <h1>Named Context</h1> |
131 * <p> |
131 * <p> |
132 * There are certain methods in which the name must resolve to a context |
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 |
133 * (for example, when searching a single level context). The documentation |
134 * of such methods |
134 * of such methods |
135 * use the term <em>named context</em> to describe their name parameter. |
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, |
136 * For these methods, if the named object is not a DirContext, |
137 * <code>NotContextException</code> is thrown. |
137 * <code>NotContextException</code> is thrown. |
138 * Aside from these methods, there is no requirement that the |
138 * Aside from these methods, there is no requirement that the |
139 * <em>named object</em> be a DirContext. |
139 * <em>named object</em> be a DirContext. |
140 *<p> |
140 * |
141 *<h1>Parameters</h1> |
141 *<h1>Parameters</h1> |
142 *<p> |
142 *<p> |
143 * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object |
143 * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object |
144 * passed as a parameter to any method will not be modified by the |
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 |
145 * service provider. The service provider may keep a reference to it |
147 * method's results and the processing of any referrals generated. |
147 * method's results and the processing of any referrals generated. |
148 * The caller should not modify the object during this time. |
148 * The caller should not modify the object during this time. |
149 * An <tt>Attributes</tt> object returned by any method is owned by |
149 * An <tt>Attributes</tt> object returned by any method is owned by |
150 * the caller. The caller may subsequently modify it; the service |
150 * the caller. The caller may subsequently modify it; the service |
151 * provider will not. |
151 * provider will not. |
152 *<p> |
152 * |
153 *<h1>Exceptions</h1> |
153 *<h1>Exceptions</h1> |
154 *<p> |
154 *<p> |
155 * All the methods in this interface can throw a NamingException or |
155 * All the methods in this interface can throw a NamingException or |
156 * any of its subclasses. See NamingException and their subclasses |
156 * any of its subclasses. See NamingException and their subclasses |
157 * for details on each exception. |
157 * for details on each exception. |