0001 /*
0002 * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package javax.naming.directory;
0027
0028 import javax.naming.*;
0029
0030 /**
0031 * The directory service interface, containing
0032 * methods for examining and updating attributes
0033 * associated with objects, and for searching the directory.
0034 * <p>
0035 * <h4>Names</h4>
0036 * Each name passed as an argument to a <tt>DirContext</tt> method is relative
0037 * to that context. The empty name is used to name the context itself.
0038 * The name parameter may never be null.
0039 * <p>
0040 * Most of the methods have overloaded versions with one taking a
0041 * <code>Name</code> parameter and one taking a <code>String</code>.
0042 * These overloaded versions are equivalent in that if
0043 * the <code>Name</code> and <code>String</code> parameters are just
0044 * different representations of the same name, then the overloaded
0045 * versions of the same methods behave the same.
0046 * In the method descriptions below, only one version is documented.
0047 * The second version instead has a link to the first: the same
0048 * documentation applies to both.
0049 * <p>
0050 * See <tt>Context</tt> for a discussion on the interpretation of the
0051 * name argument to the <tt>Context</tt> methods. These same rules
0052 * apply to the name argument to the <tt>DirContext</tt> methods.
0053 * <p>
0054 * <h4>Attribute Models</h4>
0055 * There are two basic models of what attributes should be
0056 * associated with. First, attributes may be directly associated with a
0057 * DirContext object.
0058 * In this model, an attribute operation on the named object is
0059 * roughly equivalent
0060 * to a lookup on the name (which returns the DirContext object),
0061 * followed by the attribute operation invoked on the DirContext object
0062 * in which the caller supplies an empty name. The attributes can be viewed
0063 * as being stored along with the object (note that this does not imply that
0064 * the implementation must do so).
0065 * <p>
0066 * The second model is that attributes are associated with a
0067 * name (typically an atomic name) in a DirContext.
0068 * In this model, an attribute operation on the named object is
0069 * roughly equivalent to a lookup on the name of the parent DirContext of the
0070 * named object, followed by the attribute operation invoked on the parent
0071 * in which the caller supplies the terminal atomic name.
0072 * The attributes can be viewed as being stored in the parent DirContext
0073 * (again, this does not imply that the implementation must do so).
0074 * Objects that are not DirContexts can have attributes, as long as
0075 * their parents are DirContexts.
0076 * <p>
0077 * JNDI support both of these models.
0078 * It is up to the individual service providers to decide where to
0079 * "store" attributes.
0080 * JNDI clients are safest when they do not make assumptions about
0081 * whether an object's attributes are stored as part of the object, or stored
0082 * within the parent object and associated with the object's name.
0083 * <p>
0084 * <h4>Attribute Type Names</h4>
0085 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
0086 * you can supply the attributes to return by supplying a list of
0087 * attribute names (strings).
0088 * The attributes that you get back might not have the same names as the
0089 * attribute names you have specified. This is because some directories
0090 * support features that cause them to return other attributes. Such
0091 * features include attribute subclassing, attribute name synonyms, and
0092 * attribute language codes.
0093 * <p>
0094 * In attribute subclassing, attributes are defined in a class hierarchy.
0095 * In some directories, for example, the "name" attribute might be the
0096 * superclass of all name-related attributes, including "commonName" and
0097 * "surName". Asking for the "name" attribute might return both the
0098 * "commonName" and "surName" attributes.
0099 * <p>
0100 * With attribute type synonyms, a directory can assign multiple names to
0101 * the same attribute. For example, "cn" and "commonName" might both
0102 * refer to the same attribute. Asking for "cn" might return the
0103 * "commonName" attribute.
0104 * <p>
0105 * Some directories support the language codes for attributes.
0106 * Asking such a directory for the "description" attribute, for example,
0107 * might return all of the following attributes:
0108 * <ul>
0109 * <li>description
0110 * <li>description;lang-en
0111 * <li>description;lang-de
0112 * <li>description;lang-fr
0113 * </ul>
0114 *
0115 * <p>
0116 *<h4>Operational Attributes</h4>
0117 *<p>
0118 * Some directories have the notion of "operational attributes" which are
0119 * attributes associated with a directory object for administrative
0120 * purposes. An example of operational attributes is the access control
0121 * list for an object.
0122 * <p>
0123 * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
0124 * you can specify that all attributes associated with the requested objects
0125 * be returned by supply <tt>null</tt> as the list of attributes to return.
0126 * The attributes returned do <em>not</em> include operational attributes.
0127 * In order to retrieve operational attributes, you must name them explicitly.
0128 *
0129 * <p>
0130 * <h4>Named Context</h4>
0131 * <p>
0132 * There are certain methods in which the name must resolve to a context
0133 * (for example, when searching a single level context). The documentation
0134 * of such methods
0135 * use the term <em>named context</em> to describe their name parameter.
0136 * For these methods, if the named object is not a DirContext,
0137 * <code>NotContextException</code> is thrown.
0138 * Aside from these methods, there is no requirement that the
0139 * <em>named object</em> be a DirContext.
0140 *<p>
0141 *<h4>Parameters</h4>
0142 *<p>
0143 * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
0144 * passed as a parameter to any method will not be modified by the
0145 * service provider. The service provider may keep a reference to it
0146 * for the duration of the operation, including any enumeration of the
0147 * method's results and the processing of any referrals generated.
0148 * The caller should not modify the object during this time.
0149 * An <tt>Attributes</tt> object returned by any method is owned by
0150 * the caller. The caller may subsequently modify it; the service
0151 * provider will not.
0152 *<p>
0153 *<h4>Exceptions</h4>
0154 *<p>
0155 * All the methods in this interface can throw a NamingException or
0156 * any of its subclasses. See NamingException and their subclasses
0157 * for details on each exception.
0158 *
0159 * @author Rosanna Lee
0160 * @author Scott Seligman
0161 * @author R. Vasudevan
0162 * @version 1.19 07/05/05
0163 *
0164 * @see javax.naming.Context
0165 * @since 1.3
0166 */
0167
0168 public interface DirContext extends Context {
0169
0170 /**
0171 * Retrieves all of the attributes associated with a named object.
0172 * See the class description regarding attribute models, attribute
0173 * type names, and operational attributes.
0174 *
0175 * @param name
0176 * the name of the object from which to retrieve attributes
0177 * @return the set of attributes associated with <code>name</code>.
0178 * Returns an empty attribute set if name has no attributes;
0179 * never null.
0180 * @throws NamingException if a naming exception is encountered
0181 *
0182 * @see #getAttributes(String)
0183 * @see #getAttributes(Name, String[])
0184 */
0185 public Attributes getAttributes(Name name) throws NamingException;
0186
0187 /**
0188 * Retrieves all of the attributes associated with a named object.
0189 * See {@link #getAttributes(Name)} for details.
0190 *
0191 * @param name
0192 * the name of the object from which to retrieve attributes
0193 * @return the set of attributes associated with <code>name</code>
0194 *
0195 * @throws NamingException if a naming exception is encountered
0196 */
0197 public Attributes getAttributes(String name) throws NamingException;
0198
0199 /**
0200 * Retrieves selected attributes associated with a named object.
0201 * See the class description regarding attribute models, attribute
0202 * type names, and operational attributes.
0203 *
0204 * <p> If the object does not have an attribute
0205 * specified, the directory will ignore the nonexistent attribute
0206 * and return those requested attributes that the object does have.
0207 *
0208 * <p> A directory might return more attributes than was requested
0209 * (see <strong>Attribute Type Names</strong> in the class description),
0210 * but is not allowed to return arbitrary, unrelated attributes.
0211 *
0212 * <p> See also <strong>Operational Attributes</strong> in the class
0213 * description.
0214 *
0215 * @param name
0216 * the name of the object from which to retrieve attributes
0217 * @param attrIds
0218 * the identifiers of the attributes to retrieve.
0219 * null indicates that all attributes should be retrieved;
0220 * an empty array indicates that none should be retrieved.
0221 * @return the requested attributes; never null
0222 *
0223 * @throws NamingException if a naming exception is encountered
0224 */
0225 public Attributes getAttributes(Name name, String[] attrIds)
0226 throws NamingException;
0227
0228 /**
0229 * Retrieves selected attributes associated with a named object.
0230 * See {@link #getAttributes(Name, String[])} for details.
0231 *
0232 * @param name
0233 * The name of the object from which to retrieve attributes
0234 * @param attrIds
0235 * the identifiers of the attributes to retrieve.
0236 * null indicates that all attributes should be retrieved;
0237 * an empty array indicates that none should be retrieved.
0238 * @return the requested attributes; never null
0239 *
0240 * @throws NamingException if a naming exception is encountered
0241 */
0242 public Attributes getAttributes(String name, String[] attrIds)
0243 throws NamingException;
0244
0245 /**
0246 * This constant specifies to add an attribute with the specified values.
0247 * <p>
0248 * If attribute does not exist,
0249 * create the attribute. The resulting attribute has a union of the
0250 * specified value set and the prior value set.
0251 * Adding an attribute with no value will throw
0252 * <code>InvalidAttributeValueException</code> if the attribute must have
0253 * at least one value. For a single-valued attribute where that attribute
0254 * already exists, throws <code>AttributeInUseException</code>.
0255 * If attempting to add more than one value to a single-valued attribute,
0256 * throws <code>InvalidAttributeValueException</code>.
0257 * <p>
0258 * The value of this constant is <tt>1</tt>.
0259 *
0260 * @see ModificationItem
0261 * @see #modifyAttributes
0262 */
0263 public final static int ADD_ATTRIBUTE = 1;
0264
0265 /**
0266 * This constant specifies to replace an attribute with specified values.
0267 *<p>
0268 * If attribute already exists,
0269 * replaces all existing values with new specified values. If the
0270 * attribute does not exist, creates it. If no value is specified,
0271 * deletes all the values of the attribute.
0272 * Removal of the last value will remove the attribute if the attribute
0273 * is required to have at least one value. If
0274 * attempting to add more than one value to a single-valued attribute,
0275 * throws <code>InvalidAttributeValueException</code>.
0276 * <p>
0277 * The value of this constant is <tt>2</tt>.
0278 *
0279 * @see ModificationItem
0280 * @see #modifyAttributes
0281 */
0282 public final static int REPLACE_ATTRIBUTE = 2;
0283
0284 /**
0285 * This constant specifies to delete
0286 * the specified attribute values from the attribute.
0287 *<p>
0288 * The resulting attribute has the set difference of its prior value set
0289 * and the specified value set.
0290 * If no values are specified, deletes the entire attribute.
0291 * If the attribute does not exist, or if some or all members of the
0292 * specified value set do not exist, this absence may be ignored
0293 * and the operation succeeds, or a NamingException may be thrown to
0294 * indicate the absence.
0295 * Removal of the last value will remove the attribute if the
0296 * attribute is required to have at least one value.
0297 * <p>
0298 * The value of this constant is <tt>3</tt>.
0299 *
0300 * @see ModificationItem
0301 * @see #modifyAttributes
0302 */
0303 public final static int REMOVE_ATTRIBUTE = 3;
0304
0305 /**
0306 * Modifies the attributes associated with a named object.
0307 * The order of the modifications is not specified. Where
0308 * possible, the modifications are performed atomically.
0309 *
0310 * @param name
0311 * the name of the object whose attributes will be updated
0312 * @param mod_op
0313 * the modification operation, one of:
0314 * <code>ADD_ATTRIBUTE</code>,
0315 * <code>REPLACE_ATTRIBUTE</code>,
0316 * <code>REMOVE_ATTRIBUTE</code>.
0317 * @param attrs
0318 * the attributes to be used for the modification; may not be null
0319 *
0320 * @throws AttributeModificationException if the modification cannot
0321 * be completed successfully
0322 * @throws NamingException if a naming exception is encountered
0323 *
0324 * @see #modifyAttributes(Name, ModificationItem[])
0325 */
0326 public void modifyAttributes(Name name, int mod_op, Attributes attrs)
0327 throws NamingException;
0328
0329 /**
0330 * Modifies the attributes associated with a named object.
0331 * See {@link #modifyAttributes(Name, int, Attributes)} for details.
0332 *
0333 * @param name
0334 * the name of the object whose attributes will be updated
0335 * @param mod_op
0336 * the modification operation, one of:
0337 * <code>ADD_ATTRIBUTE</code>,
0338 * <code>REPLACE_ATTRIBUTE</code>,
0339 * <code>REMOVE_ATTRIBUTE</code>.
0340 * @param attrs
0341 * the attributes to be used for the modification; may not be null
0342 *
0343 * @throws AttributeModificationException if the modification cannot
0344 * be completed successfully
0345 * @throws NamingException if a naming exception is encountered
0346 */
0347 public void modifyAttributes(String name, int mod_op,
0348 Attributes attrs) throws NamingException;
0349
0350 /**
0351 * Modifies the attributes associated with a named object using
0352 * an ordered list of modifications.
0353 * The modifications are performed
0354 * in the order specified. Each modification specifies a
0355 * modification operation code and an attribute on which to
0356 * operate. Where possible, the modifications are
0357 * performed atomically.
0358 *
0359 * @param name
0360 * the name of the object whose attributes will be updated
0361 * @param mods
0362 * an ordered sequence of modifications to be performed;
0363 * may not be null
0364 *
0365 * @throws AttributeModificationException if the modifications
0366 * cannot be completed successfully
0367 * @throws NamingException if a naming exception is encountered
0368 *
0369 * @see #modifyAttributes(Name, int, Attributes)
0370 * @see ModificationItem
0371 */
0372 public void modifyAttributes(Name name, ModificationItem[] mods)
0373 throws NamingException;
0374
0375 /**
0376 * Modifies the attributes associated with a named object using
0377 * an ordered list of modifications.
0378 * See {@link #modifyAttributes(Name, ModificationItem[])} for details.
0379 *
0380 * @param name
0381 * the name of the object whose attributes will be updated
0382 * @param mods
0383 * an ordered sequence of modifications to be performed;
0384 * may not be null
0385 *
0386 * @throws AttributeModificationException if the modifications
0387 * cannot be completed successfully
0388 * @throws NamingException if a naming exception is encountered
0389 */
0390 public void modifyAttributes(String name, ModificationItem[] mods)
0391 throws NamingException;
0392
0393 /**
0394 * Binds a name to an object, along with associated attributes.
0395 * If <tt>attrs</tt> is null, the resulting binding will have
0396 * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a
0397 * <tt>DirContext</tt>, and no attributes otherwise.
0398 * If <tt>attrs</tt> is non-null, the resulting binding will have
0399 * <tt>attrs</tt> as its attributes; any attributes associated with
0400 * <tt>obj</tt> are ignored.
0401 *
0402 * @param name
0403 * the name to bind; may not be empty
0404 * @param obj
0405 * the object to bind; possibly null
0406 * @param attrs
0407 * the attributes to associate with the binding
0408 *
0409 * @throws NameAlreadyBoundException if name is already bound
0410 * @throws InvalidAttributesException if some "mandatory" attributes
0411 * of the binding are not supplied
0412 * @throws NamingException if a naming exception is encountered
0413 *
0414 * @see Context#bind(Name, Object)
0415 * @see #rebind(Name, Object, Attributes)
0416 */
0417 public void bind(Name name, Object obj, Attributes attrs)
0418 throws NamingException;
0419
0420 /**
0421 * Binds a name to an object, along with associated attributes.
0422 * See {@link #bind(Name, Object, Attributes)} for details.
0423 *
0424 * @param name
0425 * the name to bind; may not be empty
0426 * @param obj
0427 * the object to bind; possibly null
0428 * @param attrs
0429 * the attributes to associate with the binding
0430 *
0431 * @throws NameAlreadyBoundException if name is already bound
0432 * @throws InvalidAttributesException if some "mandatory" attributes
0433 * of the binding are not supplied
0434 * @throws NamingException if a naming exception is encountered
0435 */
0436 public void bind(String name, Object obj, Attributes attrs)
0437 throws NamingException;
0438
0439 /**
0440 * Binds a name to an object, along with associated attributes,
0441 * overwriting any existing binding.
0442 * If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,
0443 * the attributes from <tt>obj</tt> are used.
0444 * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,
0445 * any existing attributes associated with the object already bound
0446 * in the directory remain unchanged.
0447 * If <tt>attrs</tt> is non-null, any existing attributes associated with
0448 * the object already bound in the directory are removed and <tt>attrs</tt>
0449 * is associated with the named object. If <tt>obj</tt> is a
0450 * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes
0451 * of <tt>obj</tt> are ignored.
0452 *
0453 * @param name
0454 * the name to bind; may not be empty
0455 * @param obj
0456 * the object to bind; possibly null
0457 * @param attrs
0458 * the attributes to associate with the binding
0459 *
0460 * @throws InvalidAttributesException if some "mandatory" attributes
0461 * of the binding are not supplied
0462 * @throws NamingException if a naming exception is encountered
0463 *
0464 * @see Context#bind(Name, Object)
0465 * @see #bind(Name, Object, Attributes)
0466 */
0467 public void rebind(Name name, Object obj, Attributes attrs)
0468 throws NamingException;
0469
0470 /**
0471 * Binds a name to an object, along with associated attributes,
0472 * overwriting any existing binding.
0473 * See {@link #rebind(Name, Object, Attributes)} for details.
0474 *
0475 * @param name
0476 * the name to bind; may not be empty
0477 * @param obj
0478 * the object to bind; possibly null
0479 * @param attrs
0480 * the attributes to associate with the binding
0481 *
0482 * @throws InvalidAttributesException if some "mandatory" attributes
0483 * of the binding are not supplied
0484 * @throws NamingException if a naming exception is encountered
0485 */
0486 public void rebind(String name, Object obj, Attributes attrs)
0487 throws NamingException;
0488
0489 /**
0490 * Creates and binds a new context, along with associated attributes.
0491 * This method creates a new subcontext with the given name, binds it in
0492 * the target context (that named by all but terminal atomic
0493 * component of the name), and associates the supplied attributes
0494 * with the newly created object.
0495 * All intermediate and target contexts must already exist.
0496 * If <tt>attrs</tt> is null, this method is equivalent to
0497 * <tt>Context.createSubcontext()</tt>.
0498 *
0499 * @param name
0500 * the name of the context to create; may not be empty
0501 * @param attrs
0502 * the attributes to associate with the newly created context
0503 * @return the newly created context
0504 *
0505 * @throws NameAlreadyBoundException if the name is already bound
0506 * @throws InvalidAttributesException if <code>attrs</code> does not
0507 * contain all the mandatory attributes required for creation
0508 * @throws NamingException if a naming exception is encountered
0509 *
0510 * @see Context#createSubcontext(Name)
0511 */
0512 public DirContext createSubcontext(Name name, Attributes attrs)
0513 throws NamingException;
0514
0515 /**
0516 * Creates and binds a new context, along with associated attributes.
0517 * See {@link #createSubcontext(Name, Attributes)} for details.
0518 *
0519 * @param name
0520 * the name of the context to create; may not be empty
0521 * @param attrs
0522 * the attributes to associate with the newly created context
0523 * @return the newly created context
0524 *
0525 * @throws NameAlreadyBoundException if the name is already bound
0526 * @throws InvalidAttributesException if <code>attrs</code> does not
0527 * contain all the mandatory attributes required for creation
0528 * @throws NamingException if a naming exception is encountered
0529 */
0530 public DirContext createSubcontext(String name, Attributes attrs)
0531 throws NamingException;
0532
0533 // -------------------- schema operations
0534
0535 /**
0536 * Retrieves the schema associated with the named object.
0537 * The schema describes rules regarding the structure of the namespace
0538 * and the attributes stored within it. The schema
0539 * specifies what types of objects can be added to the directory and where
0540 * they can be added; what mandatory and optional attributes an object
0541 * can have. The range of support for schemas is directory-specific.
0542 *
0543 * <p> This method returns the root of the schema information tree
0544 * that is applicable to the named object. Several named objects
0545 * (or even an entire directory) might share the same schema.
0546 *
0547 * <p> Issues such as structure and contents of the schema tree,
0548 * permission to modify to the contents of the schema
0549 * tree, and the effect of such modifications on the directory
0550 * are dependent on the underlying directory.
0551 *
0552 * @param name
0553 * the name of the object whose schema is to be retrieved
0554 * @return the schema associated with the context; never null
0555 * @throws OperationNotSupportedException if schema not supported
0556 * @throws NamingException if a naming exception is encountered
0557 */
0558 public DirContext getSchema(Name name) throws NamingException;
0559
0560 /**
0561 * Retrieves the schema associated with the named object.
0562 * See {@link #getSchema(Name)} for details.
0563 *
0564 * @param name
0565 * the name of the object whose schema is to be retrieved
0566 * @return the schema associated with the context; never null
0567 * @throws OperationNotSupportedException if schema not supported
0568 * @throws NamingException if a naming exception is encountered
0569 */
0570 public DirContext getSchema(String name) throws NamingException;
0571
0572 /**
0573 * Retrieves a context containing the schema objects of the
0574 * named object's class definitions.
0575 *<p>
0576 * One category of information found in directory schemas is
0577 * <em>class definitions</em>. An "object class" definition
0578 * specifies the object's <em>type</em> and what attributes (mandatory
0579 * and optional) the object must/can have. Note that the term
0580 * "object class" being referred to here is in the directory sense
0581 * rather than in the Java sense.
0582 * For example, if the named object is a directory object of
0583 * "Person" class, <tt>getSchemaClassDefinition()</tt> would return a
0584 * <tt>DirContext</tt> representing the (directory's) object class
0585 * definition of "Person".
0586 *<p>
0587 * The information that can be retrieved from an object class definition
0588 * is directory-dependent.
0589 *<p>
0590 * Prior to JNDI 1.2, this method
0591 * returned a single schema object representing the class definition of
0592 * the named object.
0593 * Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing
0594 * all of the named object's class definitions.
0595 *
0596 * @param name
0597 * the name of the object whose object class
0598 * definition is to be retrieved
0599 * @return the <tt>DirContext</tt> containing the named
0600 * object's class definitions; never null
0601 *
0602 * @throws OperationNotSupportedException if schema not supported
0603 * @throws NamingException if a naming exception is encountered
0604 */
0605 public DirContext getSchemaClassDefinition(Name name)
0606 throws NamingException;
0607
0608 /**
0609 * Retrieves a context containing the schema objects of the
0610 * named object's class definitions.
0611 * See {@link #getSchemaClassDefinition(Name)} for details.
0612 *
0613 * @param name
0614 * the name of the object whose object class
0615 * definition is to be retrieved
0616 * @return the <tt>DirContext</tt> containing the named
0617 * object's class definitions; never null
0618 *
0619 * @throws OperationNotSupportedException if schema not supported
0620 * @throws NamingException if a naming exception is encountered
0621 */
0622 public DirContext getSchemaClassDefinition(String name)
0623 throws NamingException;
0624
0625 // -------------------- search operations
0626
0627 /**
0628 * Searches in a single context for objects that contain a
0629 * specified set of attributes, and retrieves selected attributes.
0630 * The search is performed using the default
0631 * <code>SearchControls</code> settings.
0632 * <p>
0633 * For an object to be selected, each attribute in
0634 * <code>matchingAttributes</code> must match some attribute of the
0635 * object. If <code>matchingAttributes</code> is empty or
0636 * null, all objects in the target context are returned.
0637 *<p>
0638 * An attribute <em>A</em><sub>1</sub> in
0639 * <code>matchingAttributes</code> is considered to match an
0640 * attribute <em>A</em><sub>2</sub> of an object if
0641 * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same
0642 * identifier, and each value of <em>A</em><sub>1</sub> is equal
0643 * to some value of <em>A</em><sub>2</sub>. This implies that the
0644 * order of values is not significant, and that
0645 * <em>A</em><sub>2</sub> may contain "extra" values not found in
0646 * <em>A</em><sub>1</sub> without affecting the comparison. It
0647 * also implies that if <em>A</em><sub>1</sub> has no values, then
0648 * testing for a match is equivalent to testing for the presence
0649 * of an attribute <em>A</em><sub>2</sub> with the same
0650 * identifier.
0651 *<p>
0652 * The precise definition of "equality" used in comparing attribute values
0653 * is defined by the underlying directory service. It might use the
0654 * <code>Object.equals</code> method, for example, or might use a schema
0655 * to specify a different equality operation.
0656 * For matching based on operations other than equality (such as
0657 * substring comparison) use the version of the <code>search</code>
0658 * method that takes a filter argument.
0659 * <p>
0660 * When changes are made to this <tt>DirContext</tt>,
0661 * the effect on enumerations returned by prior calls to this method
0662 * is undefined.
0663 *<p>
0664 * If the object does not have the attribute
0665 * specified, the directory will ignore the nonexistent attribute
0666 * and return the requested attributes that the object does have.
0667 *<p>
0668 * A directory might return more attributes than was requested
0669 * (see <strong>Attribute Type Names</strong> in the class description),
0670 * but is not allowed to return arbitrary, unrelated attributes.
0671 *<p>
0672 * See also <strong>Operational Attributes</strong> in the class
0673 * description.
0674 *
0675 * @param name
0676 * the name of the context to search
0677 * @param matchingAttributes
0678 * the attributes to search for. If empty or null,
0679 * all objects in the target context are returned.
0680 * @param attributesToReturn
0681 * the attributes to return. null indicates that
0682 * all attributes are to be returned;
0683 * an empty array indicates that none are to be returned.
0684 * @return
0685 * a non-null enumeration of <tt>SearchResult</tt> objects.
0686 * Each <tt>SearchResult</tt> contains the attributes
0687 * identified by <code>attributesToReturn</code>
0688 * and the name of the corresponding object, named relative
0689 * to the context named by <code>name</code>.
0690 * @throws NamingException if a naming exception is encountered
0691 *
0692 * @see SearchControls
0693 * @see SearchResult
0694 * @see #search(Name, String, Object[], SearchControls)
0695 */
0696 public NamingEnumeration<SearchResult> search(Name name,
0697 Attributes matchingAttributes, String[] attributesToReturn)
0698 throws NamingException;
0699
0700 /**
0701 * Searches in a single context for objects that contain a
0702 * specified set of attributes, and retrieves selected attributes.
0703 * See {@link #search(Name, Attributes, String[])} for details.
0704 *
0705 * @param name
0706 * the name of the context to search
0707 * @param matchingAttributes
0708 * the attributes to search for
0709 * @param attributesToReturn
0710 * the attributes to return
0711 * @return a non-null enumeration of <tt>SearchResult</tt> objects
0712 * @throws NamingException if a naming exception is encountered
0713 */
0714 public NamingEnumeration<SearchResult> search(String name,
0715 Attributes matchingAttributes, String[] attributesToReturn)
0716 throws NamingException;
0717
0718 /**
0719 * Searches in a single context for objects that contain a
0720 * specified set of attributes.
0721 * This method returns all the attributes of such objects.
0722 * It is equivalent to supplying null as
0723 * the <tt>atributesToReturn</tt> parameter to the method
0724 * <code>search(Name, Attributes, String[])</code>.
0725 * <br>
0726 * See {@link #search(Name, Attributes, String[])} for a full description.
0727 *
0728 * @param name
0729 * the name of the context to search
0730 * @param matchingAttributes
0731 * the attributes to search for
0732 * @return an enumeration of <tt>SearchResult</tt> objects
0733 * @throws NamingException if a naming exception is encountered
0734 *
0735 * @see #search(Name, Attributes, String[])
0736 */
0737 public NamingEnumeration<SearchResult> search(Name name,
0738 Attributes matchingAttributes) throws NamingException;
0739
0740 /**
0741 * Searches in a single context for objects that contain a
0742 * specified set of attributes.
0743 * See {@link #search(Name, Attributes)} for details.
0744 *
0745 * @param name
0746 * the name of the context to search
0747 * @param matchingAttributes
0748 * the attributes to search for
0749 * @return an enumeration of <tt>SearchResult</tt> objects
0750 * @throws NamingException if a naming exception is encountered
0751 */
0752 public NamingEnumeration<SearchResult> search(String name,
0753 Attributes matchingAttributes) throws NamingException;
0754
0755 /**
0756 * Searches in the named context or object for entries that satisfy the
0757 * given search filter. Performs the search as specified by
0758 * the search controls.
0759 * <p>
0760 * The format and interpretation of <code>filter</code> follows RFC 2254
0761 * with the
0762 * following interpretations for <code>attr</code> and <code>value</code>
0763 * mentioned in the RFC.
0764 * <p>
0765 * <code>attr</code> is the attribute's identifier.
0766 * <p>
0767 * <code>value</code> is the string representation the attribute's value.
0768 * The translation of this string representation into the attribute's value
0769 * is directory-specific.
0770 * <p>
0771 * For the assertion "someCount=127", for example, <code>attr</code>
0772 * is "someCount" and <code>value</code> is "127".
0773 * The provider determines, based on the attribute ID ("someCount")
0774 * (and possibly its schema), that the attribute's value is an integer.
0775 * It then parses the string "127" appropriately.
0776 *<p>
0777 * Any non-ASCII characters in the filter string should be
0778 * represented by the appropriate Java (Unicode) characters, and
0779 * not encoded as UTF-8 octets. Alternately, the
0780 * "backslash-hexcode" notation described in RFC 2254 may be used.
0781 *<p>
0782 * If the directory does not support a string representation of
0783 * some or all of its attributes, the form of <code>search</code> that
0784 * accepts filter arguments in the form of Objects can be used instead.
0785 * The service provider for such a directory would then translate
0786 * the filter arguments to its service-specific representation
0787 * for filter evaluation.
0788 * See <code>search(Name, String, Object[], SearchControls)</code>.
0789 * <p>
0790 * RFC 2254 defines certain operators for the filter, including substring
0791 * matches, equality, approximate match, greater than, less than. These
0792 * operators are mapped to operators with corresponding semantics in the
0793 * underlying directory. For example, for the equals operator, suppose
0794 * the directory has a matching rule defining "equality" of the
0795 * attributes in the filter. This rule would be used for checking
0796 * equality of the attributes specified in the filter with the attributes
0797 * of objects in the directory. Similarly, if the directory has a
0798 * matching rule for ordering, this rule would be used for
0799 * making "greater than" and "less than" comparisons.
0800 *<p>
0801 * Not all of the operators defined in RFC 2254 are applicable to all
0802 * attributes. When an operator is not applicable, the exception
0803 * <code>InvalidSearchFilterException</code> is thrown.
0804 * <p>
0805 * The result is returned in an enumeration of <tt>SearchResult</tt>s.
0806 * Each <tt>SearchResult</tt> contains the name of the object
0807 * and other information about the object (see SearchResult).
0808 * The name is either relative to the target context of the search
0809 * (which is named by the <code>name</code> parameter), or
0810 * it is a URL string. If the target context is included in
0811 * the enumeration (as is possible when
0812 * <code>cons</code> specifies a search scope of
0813 * <code>SearchControls.OBJECT_SCOPE</code> or
0814 * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty
0815 * string. The <tt>SearchResult</tt> may also contain attributes of the
0816 * matching object if the <tt>cons</tt> argument specified that attributes
0817 * be returned.
0818 *<p>
0819 * If the object does not have a requested attribute, that
0820 * nonexistent attribute will be ignored. Those requested
0821 * attributes that the object does have will be returned.
0822 *<p>
0823 * A directory might return more attributes than were requested
0824 * (see <strong>Attribute Type Names</strong> in the class description)
0825 * but is not allowed to return arbitrary, unrelated attributes.
0826 *<p>
0827 * See also <strong>Operational Attributes</strong> in the class
0828 * description.
0829 *
0830 * @param name
0831 * the name of the context or object to search
0832 * @param filter
0833 * the filter expression to use for the search; may not be null
0834 * @param cons
0835 * the search controls that control the search. If null,
0836 * the default search controls are used (equivalent
0837 * to <tt>(new SearchControls())</tt>).
0838 * @return an enumeration of <tt>SearchResult</tt>s of
0839 * the objects that satisfy the filter; never null
0840 *
0841 * @throws InvalidSearchFilterException if the search filter specified is
0842 * not supported or understood by the underlying directory
0843 * @throws InvalidSearchControlsException if the search controls
0844 * contain invalid settings
0845 * @throws NamingException if a naming exception is encountered
0846 *
0847 * @see #search(Name, String, Object[], SearchControls)
0848 * @see SearchControls
0849 * @see SearchResult
0850 */
0851 public NamingEnumeration<SearchResult> search(Name name,
0852 String filter, SearchControls cons) throws NamingException;
0853
0854 /**
0855 * Searches in the named context or object for entries that satisfy the
0856 * given search filter. Performs the search as specified by
0857 * the search controls.
0858 * See {@link #search(Name, String, SearchControls)} for details.
0859 *
0860 * @param name
0861 * the name of the context or object to search
0862 * @param filter
0863 * the filter expression to use for the search; may not be null
0864 * @param cons
0865 * the search controls that control the search. If null,
0866 * the default search controls are used (equivalent
0867 * to <tt>(new SearchControls())</tt>).
0868 *
0869 * @return an enumeration of <tt>SearchResult</tt>s for
0870 * the objects that satisfy the filter.
0871 * @throws InvalidSearchFilterException if the search filter specified is
0872 * not supported or understood by the underlying directory
0873 * @throws InvalidSearchControlsException if the search controls
0874 * contain invalid settings
0875 * @throws NamingException if a naming exception is encountered
0876 */
0877 public NamingEnumeration<SearchResult> search(String name,
0878 String filter, SearchControls cons) throws NamingException;
0879
0880 /**
0881 * Searches in the named context or object for entries that satisfy the
0882 * given search filter. Performs the search as specified by
0883 * the search controls.
0884 *<p>
0885 * The interpretation of <code>filterExpr</code> is based on RFC
0886 * 2254. It may additionally contain variables of the form
0887 * <code>{i}</code> -- where <code>i</code> is an integer -- that
0888 * refer to objects in the <code>filterArgs</code> array. The
0889 * interpretation of <code>filterExpr</code> is otherwise
0890 * identical to that of the <code>filter</code> parameter of the
0891 * method <code>search(Name, String, SearchControls)</code>.
0892 *<p>
0893 * When a variable <code>{i}</code> appears in a search filter, it
0894 * indicates that the filter argument <code>filterArgs[i]</code>
0895 * is to be used in that place. Such variables may be used
0896 * wherever an <em>attr</em>, <em>value</em>, or
0897 * <em>matchingrule</em> production appears in the filter grammar
0898 * of RFC 2254, section 4. When a string-valued filter argument
0899 * is substituted for a variable, the filter is interpreted as if
0900 * the string were given in place of the variable, with any
0901 * characters having special significance within filters (such as
0902 * <code>'*'</code>) having been escaped according to the rules of
0903 * RFC 2254.
0904 *<p>
0905 * For directories that do not use a string representation for
0906 * some or all of their attributes, the filter argument
0907 * corresponding to an attribute value may be of a type other than
0908 * String. Directories that support unstructured binary-valued
0909 * attributes, for example, should accept byte arrays as filter
0910 * arguments. The interpretation (if any) of filter arguments of
0911 * any other type is determined by the service provider for that
0912 * directory, which maps the filter operations onto operations with
0913 * corresponding semantics in the underlying directory.
0914 *<p>
0915 * This method returns an enumeration of the results.
0916 * Each element in the enumeration contains the name of the object
0917 * and other information about the object (see <code>SearchResult</code>).
0918 * The name is either relative to the target context of the search
0919 * (which is named by the <code>name</code> parameter), or
0920 * it is a URL string. If the target context is included in
0921 * the enumeration (as is possible when
0922 * <code>cons</code> specifies a search scope of
0923 * <code>SearchControls.OBJECT_SCOPE</code> or
0924 * <code>SearchControls.SUBSTREE_SCOPE</code>),
0925 * its name is the empty string.
0926 *<p>
0927 * The <tt>SearchResult</tt> may also contain attributes of the matching
0928 * object if the <tt>cons</tt> argument specifies that attributes be
0929 * returned.
0930 *<p>
0931 * If the object does not have a requested attribute, that
0932 * nonexistent attribute will be ignored. Those requested
0933 * attributes that the object does have will be returned.
0934 *<p>
0935 * A directory might return more attributes than were requested
0936 * (see <strong>Attribute Type Names</strong> in the class description)
0937 * but is not allowed to return arbitrary, unrelated attributes.
0938 *<p>
0939 * If a search filter with invalid variable substitutions is provided
0940 * to this method, the result is undefined.
0941 * When changes are made to this DirContext,
0942 * the effect on enumerations returned by prior calls to this method
0943 * is undefined.
0944 *<p>
0945 * See also <strong>Operational Attributes</strong> in the class
0946 * description.
0947 *
0948 * @param name
0949 * the name of the context or object to search
0950 * @param filterExpr
0951 * the filter expression to use for the search.
0952 * The expression may contain variables of the
0953 * form "<code>{i}</code>" where <code>i</code>
0954 * is a nonnegative integer. May not be null.
0955 * @param filterArgs
0956 * the array of arguments to substitute for the variables
0957 * in <code>filterExpr</code>. The value of
0958 * <code>filterArgs[i]</code> will replace each
0959 * occurrence of "<code>{i}</code>".
0960 * If null, equivalent to an empty array.
0961 * @param cons
0962 * the search controls that control the search. If null,
0963 * the default search controls are used (equivalent
0964 * to <tt>(new SearchControls())</tt>).
0965 * @return an enumeration of <tt>SearchResult</tt>s of the objects
0966 * that satisfy the filter; never null
0967 *
0968 * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
0969 * <code>{i}</code> expressions where <code>i</code> is outside
0970 * the bounds of the array <code>filterArgs</code>
0971 * @throws InvalidSearchControlsException if <tt>cons</tt> contains
0972 * invalid settings
0973 * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
0974 * <tt>filterArgs</tt> represents an invalid search filter
0975 * @throws NamingException if a naming exception is encountered
0976 *
0977 * @see #search(Name, Attributes, String[])
0978 * @see java.text.MessageFormat
0979 */
0980 public NamingEnumeration<SearchResult> search(Name name,
0981 String filterExpr, Object[] filterArgs, SearchControls cons)
0982 throws NamingException;
0983
0984 /**
0985 * Searches in the named context or object for entries that satisfy the
0986 * given search filter. Performs the search as specified by
0987 * the search controls.
0988 * See {@link #search(Name, String, Object[], SearchControls)} for details.
0989 *
0990 * @param name
0991 * the name of the context or object to search
0992 * @param filterExpr
0993 * the filter expression to use for the search.
0994 * The expression may contain variables of the
0995 * form "<code>{i}</code>" where <code>i</code>
0996 * is a nonnegative integer. May not be null.
0997 * @param filterArgs
0998 * the array of arguments to substitute for the variables
0999 * in <code>filterExpr</code>. The value of
1000 * <code>filterArgs[i]</code> will replace each
1001 * occurrence of "<code>{i}</code>".
1002 * If null, equivalent to an empty array.
1003 * @param cons
1004 * the search controls that control the search. If null,
1005 * the default search controls are used (equivalent
1006 * to <tt>(new SearchControls())</tt>).
1007 * @return an enumeration of <tt>SearchResult</tt>s of the objects
1008 * that satisfy the filter; never null
1009 *
1010 * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
1011 * <code>{i}</code> expressions where <code>i</code> is outside
1012 * the bounds of the array <code>filterArgs</code>
1013 * @throws InvalidSearchControlsException if <tt>cons</tt> contains
1014 * invalid settings
1015 * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
1016 * <tt>filterArgs</tt> represents an invalid search filter
1017 * @throws NamingException if a naming exception is encountered
1018 */
1019 public NamingEnumeration<SearchResult> search(String name,
1020 String filterExpr, Object[] filterArgs, SearchControls cons)
1021 throws NamingException;
1022 }
|