1. /*
  2. * @(#)DirContext.java 1.9 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.naming.directory;
  8. import javax.naming.*;
  9. /**
  10. * The directory service interface, containing
  11. * methods for examining and updating attributes
  12. * associated with objects, and for searching the directory.
  13. * <p>
  14. * <h4>Names</h4>
  15. * Each name passed as an argument to a <tt>DirContext</tt> method is relative
  16. * to that context. The empty name is used to name the context itself.
  17. * The name parameter may never be null.
  18. * <p>
  19. * Most of the methods have overloaded versions with one taking a
  20. * <code>Name</code> parameter and one taking a <code>String</code>.
  21. * These overloaded versions are equivalent in that if
  22. * the <code>Name</code> and <code>String</code> parameters are just
  23. * different representations of the same name, then the overloaded
  24. * versions of the same methods behave the same.
  25. * In the method descriptions below, only one version is documented.
  26. * The second version instead has a link to the first: the same
  27. * documentation applies to both.
  28. * <p>
  29. * See <tt>Context</tt> for a discussion on the interpretation of the
  30. * name argument to the <tt>Context</tt> methods. These same rules
  31. * apply to the name argument to the <tt>DirContext</tt> methods.
  32. * <p>
  33. * <h4>Attribute Models</h4>
  34. * There are two basic models of what attributes should be
  35. * associated with. First, attributes may be directly associated with a
  36. * DirContext object.
  37. * In this model, an attribute operation on the named object is
  38. * roughly equivalent
  39. * to a lookup on the name (which returns the DirContext object),
  40. * followed by the attribute operation invoked on the DirContext object
  41. * in which the caller supplies an empty name. The attributes can be viewed
  42. * as being stored along with the object (note that this does not imply that
  43. * the implementation must do so).
  44. * <p>
  45. * The second model is that attributes are associated with a
  46. * name (typically an atomic name) in a DirContext.
  47. * In this model, an attribute operation on the named object is
  48. * roughly equivalent to a lookup on the name of the parent DirContext of the
  49. * named object, followed by the attribute operation invoked on the parent
  50. * in which the caller supplies the terminal atomic name.
  51. * The attributes can be viewed as being stored in the parent DirContext
  52. * (again, this does not imply that the implementation must do so).
  53. * Objects that are not DirContexts can have attributes, as long as
  54. * their parents are DirContexts.
  55. * <p>
  56. * JNDI support both of these models.
  57. * It is up to the individual service providers to decide where to
  58. * "store" attributes.
  59. * JNDI clients are safest when they do not make assumptions about
  60. * whether an object's attributes are stored as part of the object, or stored
  61. * within the parent object and associated with the object's name.
  62. * <p>
  63. * <h4>Attribute Type Names</h4>
  64. * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
  65. * you can supply the attributes to return by supplying a list of
  66. * attribute names (strings).
  67. * The attributes that you get back might not have the same names as the
  68. * attribute names you have specified. This is because some directories
  69. * support features that cause them to return other attributes. Such
  70. * features include attribute subclassing, attribute name synonyms, and
  71. * attribute language codes.
  72. * <p>
  73. * In attribute subclassing, attributes are defined in a class hierarchy.
  74. * In some directories, for example, the "name" attribute might be the
  75. * superclass of all name-related attributes, including "commonName" and
  76. * "surName". Asking for the "name" attribute might return both the
  77. * "commonName" and "surName" attributes.
  78. * <p>
  79. * With attribute type synonyms, a directory can assign multiple names to
  80. * the same attribute. For example, "cn" and "commonName" might both
  81. * refer to the same attribute. Asking for "cn" might return the
  82. * "commonName" attribute.
  83. * <p>
  84. * Some directories support the language codes for attributes.
  85. * Asking such a directory for the "description" attribute, for example,
  86. * might return all of the following attributes:
  87. * <ul>
  88. * <li>description
  89. * <li>description;lang-en
  90. * <li>description;lang-de
  91. * <li>description;lang-fr
  92. * </ul>
  93. *
  94. * <p>
  95. *<h4>Operational Attributes</h4>
  96. *<p>
  97. * Some directories have the notion of "operational attributes" which are
  98. * attributes associated with a directory object for administrative
  99. * purposes. An example of operational attributes is the access control
  100. * list for an object.
  101. * <p>
  102. * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
  103. * you can specify that all attributes associated with the requested objects
  104. * be returned by supply <tt>null</tt> as the list of attributes to return.
  105. * The attributes returned do <em>not</em> include operational attributes.
  106. * In order to retrieve operational attributes, you must name them explicitly.
  107. *
  108. * <p>
  109. * <h4>Named Context</h4>
  110. * <p>
  111. * There are certain methods in which the name must resolve to a context
  112. * (for example, when searching a single level context). The documentation
  113. * of such methods
  114. * use the term <em>named context</em> to describe their name parameter.
  115. * For these methods, if the named object is not a DirContext,
  116. * <code>NotContextException</code> is thrown.
  117. * Aside from these methods, there is no requirement that the
  118. * <em>named object</em> be a DirContext.
  119. *<p>
  120. *<h4>Parameters</h4>
  121. *<p>
  122. * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
  123. * passed as a parameter to any method will not be modified by the
  124. * service provider. The service provider may keep a reference to it
  125. * for the duration of the operation, including any enumeration of the
  126. * method's results and the processing of any referrals generated.
  127. * The caller should not modify the object during this time.
  128. * An <tt>Attributes</tt> object returned by any method is owned by
  129. * the caller. The caller may subsequently modify it; the service
  130. * provider will not.
  131. *<p>
  132. *<h4>Exceptions</h4>
  133. *<p>
  134. * All the methods in this interface can throw a NamingException or
  135. * any of its subclasses. See NamingException and their subclasses
  136. * for details on each exception.
  137. *
  138. * @author Rosanna Lee
  139. * @author Scott Seligman
  140. * @author R. Vasudevan
  141. * @version 1.9 03/01/23
  142. *
  143. * @see javax.naming.Context
  144. * @since 1.3
  145. */
  146. public interface DirContext extends Context {
  147. /**
  148. * Retrieves all of the attributes associated with a named object.
  149. * See the class description regarding attribute models, attribute
  150. * type names, and operational attributes.
  151. *
  152. * @param name
  153. * the name of the object from which to retrieve attributes
  154. * @return the set of attributes associated with <code>name</code>.
  155. * Returns an empty attribute set if name has no attributes;
  156. * never null.
  157. * @throws NamingException if a naming exception is encountered
  158. *
  159. * @see #getAttributes(String)
  160. * @see #getAttributes(Name, String[])
  161. */
  162. public Attributes getAttributes(Name name) throws NamingException;
  163. /**
  164. * Retrieves all of the attributes associated with a named object.
  165. * See {@link #getAttributes(Name)} for details.
  166. *
  167. * @param name
  168. * the name of the object from which to retrieve attributes
  169. * @return the set of attributes associated with <code>name</code>
  170. *
  171. * @throws NamingException if a naming exception is encountered
  172. */
  173. public Attributes getAttributes(String name) throws NamingException;
  174. /**
  175. * Retrieves selected attributes associated with a named object.
  176. * See the class description regarding attribute models, attribute
  177. * type names, and operational attributes.
  178. *
  179. * <p> If the object does not have an attribute
  180. * specified, the directory will ignore the nonexistent attribute
  181. * and return those requested attributes that the object does have.
  182. *
  183. * <p> A directory might return more attributes than was requested
  184. * (see <strong>Attribute Type Names</strong> in the class description),
  185. * but is not allowed to return arbitrary, unrelated attributes.
  186. *
  187. * <p> See also <strong>Operational Attributes</strong> in the class
  188. * description.
  189. *
  190. * @param name
  191. * the name of the object from which to retrieve attributes
  192. * @param attrIds
  193. * the identifiers of the attributes to retrieve.
  194. * null indicates that all attributes should be retrieved;
  195. * an empty array indicates that none should be retrieved.
  196. * @return the requested attributes; never null
  197. *
  198. * @throws NamingException if a naming exception is encountered
  199. */
  200. public Attributes getAttributes(Name name, String[] attrIds)
  201. throws NamingException;
  202. /**
  203. * Retrieves selected attributes associated with a named object.
  204. * See {@link #getAttributes(Name, String[])} for details.
  205. *
  206. * @param name
  207. * The name of the object from which to retrieve attributes
  208. * @param attrIds
  209. * the identifiers of the attributes to retrieve.
  210. * null indicates that all attributes should be retrieved;
  211. * an empty array indicates that none should be retrieved.
  212. * @return the requested attributes; never null
  213. *
  214. * @throws NamingException if a naming exception is encountered
  215. */
  216. public Attributes getAttributes(String name, String[] attrIds)
  217. throws NamingException;
  218. /**
  219. * This constant specifies to add an attribute with the specified values.
  220. * <p>
  221. * If attribute does not exist,
  222. * create the attribute. The resulting attribute has a union of the
  223. * specified value set and the prior value set.
  224. * Adding an attribute with no value will throw
  225. * <code>InvalidAttributeValueException</code> if the attribute must have
  226. * at least one value. For a single-valued attribute where that attribute
  227. * already exists, throws <code>AttributeInUseException</code>.
  228. * If attempting to add more than one value to a single-valued attribute,
  229. * throws <code>InvalidAttributeValueException</code>.
  230. * <p>
  231. * The value of this constant is <tt>1</tt>.
  232. *
  233. * @see ModificationItem
  234. * @see #modifyAttributes
  235. */
  236. public final static int ADD_ATTRIBUTE = 1;
  237. /**
  238. * This constant specifies to replace an attribute with specified values.
  239. *<p>
  240. * If attribute already exists,
  241. * replaces all existing values with new specified values. If the
  242. * attribute does not exist, creates it. If no value is specified,
  243. * deletes all the values of the attribute.
  244. * Removal of the last value will remove the attribute if the attribute
  245. * is required to have at least one value. If
  246. * attempting to add more than one value to a single-valued attribute,
  247. * throws <code>InvalidAttributeValueException</code>.
  248. * <p>
  249. * The value of this constant is <tt>2</tt>.
  250. *
  251. * @see ModificationItem
  252. * @see #modifyAttributes
  253. */
  254. public final static int REPLACE_ATTRIBUTE = 2;
  255. /**
  256. * This constant specifies to delete
  257. * the specified attribute values from the attribute.
  258. *<p>
  259. * The resulting attribute has the set difference of its prior value set
  260. * and the specified value set.
  261. * If no values are specified, deletes the entire attribute.
  262. * If the attribute does not exist, or if some or all members of the
  263. * specified value set do not exist, this absence may be ignored
  264. * and the operation succeeds, or a NamingException may be thrown to
  265. * indicate the absence.
  266. * Removal of the last value will remove the attribute if the
  267. * attribute is required to have at least one value.
  268. * <p>
  269. * The value of this constant is <tt>3</tt>.
  270. *
  271. * @see ModificationItem
  272. * @see #modifyAttributes
  273. */
  274. public final static int REMOVE_ATTRIBUTE = 3;
  275. /**
  276. * Modifies the attributes associated with a named object.
  277. * The order of the modifications is not specified. Where
  278. * possible, the modifications are performed atomically.
  279. *
  280. * @param name
  281. * the name of the object whose attributes will be updated
  282. * @param mod_op
  283. * the modification operation, one of:
  284. * <code>ADD_ATTRIBUTE</code>,
  285. * <code>REPLACE_ATTRIBUTE</code>,
  286. * <code>REMOVE_ATTRIBUTE</code>.
  287. * @param attrs
  288. * the attributes to be used for the modification; may not be null
  289. *
  290. * @throws AttributeModificationException if the modification cannot
  291. * be completed successfully
  292. * @throws NamingException if a naming exception is encountered
  293. *
  294. * @see #modifyAttributes(Name, ModificationItem[])
  295. */
  296. public void modifyAttributes(Name name, int mod_op, Attributes attrs)
  297. throws NamingException;
  298. /**
  299. * Modifies the attributes associated with a named object.
  300. * See {@link #modifyAttributes(Name, int, Attributes)} for details.
  301. *
  302. * @param name
  303. * the name of the object whose attributes will be updated
  304. * @param mod_op
  305. * the modification operation, one of:
  306. * <code>ADD_ATTRIBUTE</code>,
  307. * <code>REPLACE_ATTRIBUTE</code>,
  308. * <code>REMOVE_ATTRIBUTE</code>.
  309. * @param attrs
  310. * the attributes to be used for the modification; map not be null
  311. *
  312. * @throws AttributeModificationException if the modification cannot
  313. * be completed successfully
  314. * @throws NamingException if a naming exception is encountered
  315. */
  316. public void modifyAttributes(String name, int mod_op, Attributes attrs)
  317. throws NamingException;
  318. /**
  319. * Modifies the attributes associated with a named object using
  320. * an ordered list of modifications.
  321. * The modifications are performed
  322. * in the order specified. Each modification specifies a
  323. * modification operation code and an attribute on which to
  324. * operate. Where possible, the modifications are
  325. * performed atomically.
  326. *
  327. * @param name
  328. * the name of the object whose attributes will be updated
  329. * @param mods
  330. * an ordered sequence of modifications to be performed;
  331. * may not be null
  332. *
  333. * @throws AttributeModificationException if the modifications
  334. * cannot be completed successfully
  335. * @throws NamingException if a naming exception is encountered
  336. *
  337. * @see #modifyAttributes(Name, int, Attributes)
  338. * @see ModificationItem
  339. */
  340. public void modifyAttributes(Name name, ModificationItem[] mods)
  341. throws NamingException;
  342. /**
  343. * Modifies the attributes associated with a named object using
  344. * an ordered list of modifications.
  345. * See {@link #modifyAttributes(Name, ModificationItem[])} for details.
  346. *
  347. * @param name
  348. * the name of the object whose attributes will be updated
  349. * @param mods
  350. * an ordered sequence of modifications to be performed;
  351. * may not be null
  352. *
  353. * @throws AttributeModificationException if the modifications
  354. * cannot be completed successfully
  355. * @throws NamingException if a naming exception is encountered
  356. */
  357. public void modifyAttributes(String name, ModificationItem[] mods)
  358. throws NamingException;
  359. /**
  360. * Binds a name to an object, along with associated attributes.
  361. * If <tt>attrs</tt> is null, the resulting binding will have
  362. * the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a
  363. * <tt>DirContext</tt>, and no attributes otherwise.
  364. * If <tt>attrs</tt> is non-null, the resulting binding will have
  365. * <tt>attrs</tt> as its attributes; any attributes associated with
  366. * <tt>obj</tt> are ignored.
  367. *
  368. * @param name
  369. * the name to bind; may not be empty
  370. * @param obj
  371. * the object to bind; possibly null
  372. * @param attrs
  373. * the attributes to associate with the binding
  374. *
  375. * @throws NameAlreadyBoundException if name is already bound
  376. * @throws InvalidAttributesException if some "mandatory" attributes
  377. * of the binding are not supplied
  378. * @throws NamingException if a naming exception is encountered
  379. *
  380. * @see Context#bind(Name, Object)
  381. * @see #rebind(Name, Object, Attributes)
  382. */
  383. public void bind(Name name, Object obj, Attributes attrs)
  384. throws NamingException;
  385. /**
  386. * Binds a name to an object, along with associated attributes.
  387. * See {@link #bind(Name, Object, Attributes)} for details.
  388. *
  389. * @param name
  390. * the name to bind; may not be empty
  391. * @param obj
  392. * the object to bind; possibly null
  393. * @param attrs
  394. * the attributes to associate with the binding
  395. *
  396. * @throws NameAlreadyBoundException if name is already bound
  397. * @throws InvalidAttributesException if some "mandatory" attributes
  398. * of the binding are not supplied
  399. * @throws NamingException if a naming exception is encountered
  400. */
  401. public void bind(String name, Object obj, Attributes attrs)
  402. throws NamingException;
  403. /**
  404. * Binds a name to an object, along with associated attributes,
  405. * overwriting any existing binding.
  406. * If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,
  407. * the attributes from <tt>obj</tt> are used.
  408. * If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,
  409. * any existing attributes associated with the object already bound
  410. * in the directory remain unchanged.
  411. * If <tt>attrs</tt> is non-null, any existing attributes associated with
  412. * the object already bound in the directory are removed and <tt>attrs</tt>
  413. * is associated with the named object. If <tt>obj</tt> is a
  414. * <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes
  415. * of <tt>obj</tt> are ignored.
  416. *
  417. * @param name
  418. * the name to bind; may not be empty
  419. * @param obj
  420. * the object to bind; possibly null
  421. * @param attrs
  422. * the attributes to associate with the binding
  423. *
  424. * @throws InvalidAttributesException if some "mandatory" attributes
  425. * of the binding are not supplied
  426. * @throws NamingException if a naming exception is encountered
  427. *
  428. * @see Context#bind(Name, Object)
  429. * @see #bind(Name, Object, Attributes)
  430. */
  431. public void rebind(Name name, Object obj, Attributes attrs)
  432. throws NamingException;
  433. /**
  434. * Binds a name to an object, along with associated attributes,
  435. * overwriting any existing binding.
  436. * See {@link #rebind(Name, Object, Attributes)} for details.
  437. *
  438. * @param name
  439. * the name to bind; may not be empty
  440. * @param obj
  441. * the object to bind; possibly null
  442. * @param attrs
  443. * the attributes to associate with the binding
  444. *
  445. * @throws InvalidAttributesException if some "mandatory" attributes
  446. * of the binding are not supplied
  447. * @throws NamingException if a naming exception is encountered
  448. */
  449. public void rebind(String name, Object obj, Attributes attrs)
  450. throws NamingException;
  451. /**
  452. * Creates and binds a new context, along with associated attributes.
  453. * This method creates a new subcontext with the given name, binds it in
  454. * the target context (that named by all but terminal atomic
  455. * component of the name), and associates the supplied attributes
  456. * with the newly created object.
  457. * All intermediate and target contexts must already exist.
  458. * If <tt>attrs</tt> is null, this method is equivalent to
  459. * <tt>Context.createSubcontext()</tt>.
  460. *
  461. * @param name
  462. * the name of the context to create; may not be empty
  463. * @param attrs
  464. * the attributes to associate with the newly created context
  465. * @return the newly created context
  466. *
  467. * @throws NameAlreadyBoundException if the name is already bound
  468. * @throws InvalidAttributesException if <code>attrs</code> does not
  469. * contain all the mandatory attributes required for creation
  470. * @throws NamingException if a naming exception is encountered
  471. *
  472. * @see Context#createSubcontext(Name)
  473. */
  474. public DirContext createSubcontext(Name name, Attributes attrs)
  475. throws NamingException;
  476. /**
  477. * Creates and binds a new context, along with associated attributes.
  478. * See {@link #createSubcontext(Name, Attributes)} for details.
  479. *
  480. * @param name
  481. * the name of the context to create; may not be empty
  482. * @param attrs
  483. * the attributes to associate with the newly created context
  484. * @return the newly created context
  485. *
  486. * @throws NameAlreadyBoundException if the name is already bound
  487. * @throws InvalidAttributesException if <code>attrs</code> does not
  488. * contain all the mandatory attributes required for creation
  489. * @throws NamingException if a naming exception is encountered
  490. */
  491. public DirContext createSubcontext(String name, Attributes attrs)
  492. throws NamingException;
  493. // -------------------- schema operations
  494. /**
  495. * Retrieves the schema associated with the named object.
  496. * The schema describes rules regarding the structure of the namespace
  497. * and the attributes stored within it. The schema
  498. * specifies what types of objects can be added to the directory and where
  499. * they can be added; what mandatory and optional attributes an object
  500. * can have. The range of support for schemas is directory-specific.
  501. *
  502. * <p> This method returns the root of the schema information tree
  503. * that is applicable to the named object. Several named objects
  504. * (or even an entire directory) might share the same schema.
  505. *
  506. * <p> Issues such as structure and contents of the schema tree,
  507. * permission to modify to the contents of the schema
  508. * tree, and the effect of such modifications on the directory
  509. * are dependent on the underlying directory.
  510. *
  511. * @param name
  512. * the name of the object whose schema is to be retrieved
  513. * @return the schema associated with the context; never null
  514. * @throws OperationNotSupportedException if schema not supported
  515. * @throws NamingException if a naming exception is encountered
  516. */
  517. public DirContext getSchema(Name name) throws NamingException;
  518. /**
  519. * Retrieves the schema associated with the named object.
  520. * See {@link #getSchema(Name)} for details.
  521. *
  522. * @param name
  523. * the name of the object whose schema is to be retrieved
  524. * @return the schema associated with the context; never null
  525. * @throws OperationNotSupportedException if schema not supported
  526. * @throws NamingException if a naming exception is encountered
  527. */
  528. public DirContext getSchema(String name) throws NamingException;
  529. /**
  530. * Retrieves a context containing the schema objects of the
  531. * named object's class definitions.
  532. *<p>
  533. * One category of information found in directory schemas is
  534. * <em>class definitions</em>. An "object class" definition
  535. * specifies the object's <em>type</em> and what attributes (mandatory
  536. * and optional) the object must/can have. Note that the term
  537. * "object class" being referred to here is in the directory sense
  538. * rather than in the Java sense.
  539. * For example, if the named object is a directory object of
  540. * "Person" class, <tt>getSchemaClassDefinition()</tt> would return a
  541. * <tt>DirContext</tt> representing the (directory's) object class
  542. * definition of "Person".
  543. *<p>
  544. * The information that can be retrieved from an object class definition
  545. * is directory-dependent.
  546. *<p>
  547. * Prior to JNDI 1.2, this method
  548. * returned a single schema object representing the class definition of
  549. * the named object.
  550. * Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing
  551. * all of the named object's class definitions.
  552. *
  553. * @param name
  554. * the name of the object whose object class
  555. * definition is to be retrieved
  556. * @return the <tt>DirContext</tt> containing the named
  557. * object's class definitions; never null
  558. *
  559. * @throws OperationNotSupportedException if schema not supported
  560. * @throws NamingException if a naming exception is encountered
  561. */
  562. public DirContext getSchemaClassDefinition(Name name)
  563. throws NamingException;
  564. /**
  565. * Retrieves a context containing the schema objects of the
  566. * named object's class definitions.
  567. * See {@link #getSchemaClassDefinition(Name)} for details.
  568. *
  569. * @param name
  570. * the name of the object whose object class
  571. * definition is to be retrieved
  572. * @return the <tt>DirContext</tt> containing the named
  573. * object's class definitions; never null
  574. *
  575. * @throws OperationNotSupportedException if schema not supported
  576. * @throws NamingException if a naming exception is encountered
  577. */
  578. public DirContext getSchemaClassDefinition(String name)
  579. throws NamingException;
  580. // -------------------- search operations
  581. /**
  582. * Searches in a single context for objects that contain a
  583. * specified set of attributes, and retrieves selected attributes.
  584. * The search is performed using the default
  585. * <code>SearchControls</code> settings.
  586. * <p>
  587. * For an object to be selected, each attribute in
  588. * <code>matchingAttributes</code> must match some attribute of the
  589. * object. If <code>matchingAttributes</code> is empty or
  590. * null, all objects in the target context are returned.
  591. *<p>
  592. * An attribute <em>A</em><sub>1</sub> in
  593. * <code>matchingAttributes</code> is considered to match an
  594. * attribute <em>A</em><sub>2</sub> of an object if
  595. * <em>A</em><sub>1</sub> and <em>A</em><sub>2</sub> have the same
  596. * identifier, and each value of <em>A</em><sub>1</sub> is equal
  597. * to some value of <em>A</em><sub>2</sub>. This implies that the
  598. * order of values is not significant, and that
  599. * <em>A</em><sub>2</sub> may contain "extra" values not found in
  600. * <em>A</em><sub>1</sub> without affecting the comparison. It
  601. * also implies that if <em>A</em><sub>1</sub> has no values, then
  602. * testing for a match is equivalent to testing for the presence
  603. * of an attribute <em>A</em><sub>2</sub> with the same
  604. * identifier.
  605. *<p>
  606. * The precise definition of "equality" used in comparing attribute values
  607. * is defined by the underlying directory service. It might use the
  608. * <code>Object.equals</code> method, for example, or might use a schema
  609. * to specify a different equality operation.
  610. * For matching based on operations other than equality (such as
  611. * substring comparison) use the version of the <code>search</code>
  612. * method that takes a filter argument.
  613. * <p>
  614. * When changes are made to this <tt>DirContext</tt>,
  615. * the effect on enumerations returned by prior calls to this method
  616. * is undefined.
  617. *<p>
  618. * If the object does not have the attribute
  619. * specified, the directory will ignore the nonexistent attribute
  620. * and return the requested attributes that the object does have.
  621. *<p>
  622. * A directory might return more attributes than was requested
  623. * (see <strong>Attribute Type Names</strong> in the class description),
  624. * but is not allowed to return arbitrary, unrelated attributes.
  625. *<p>
  626. * See also <strong>Operational Attributes</strong> in the class
  627. * description.
  628. *
  629. * @param name
  630. * the name of the context to search
  631. * @param matchingAttributes
  632. * the attributes to search for. If empty or null,
  633. * all objects in the target context are returned.
  634. * @param attributesToReturn
  635. * the attributes to return. null indicates that
  636. * all attributes are to be returned;
  637. * an empty array indicates that none are to be returned.
  638. * @return
  639. * a non-null enumeration of <tt>SearchResult</tt> objects.
  640. * Each <tt>SearchResult</tt> contains the attributes
  641. * identified by <code>attributesToReturn</code>
  642. * and the name of the corresponding object, named relative
  643. * to the context named by <code>name</code>.
  644. * @throws NamingException if a naming exception is encountered
  645. *
  646. * @see SearchControls
  647. * @see SearchResult
  648. * @see #search(Name, String, Object[], SearchControls)
  649. */
  650. public NamingEnumeration search(Name name,
  651. Attributes matchingAttributes,
  652. String[] attributesToReturn)
  653. throws NamingException;
  654. /**
  655. * Searches in a single context for objects that contain a
  656. * specified set of attributes, and retrieves selected attributes.
  657. * See {@link #search(Name, Attributes, String[])} for details.
  658. *
  659. * @param name
  660. * the name of the context to search
  661. * @param matchingAttributes
  662. * the attributes to search for
  663. * @param attributesToReturn
  664. * the attributes to return
  665. * @return a non-null enumeration of <tt>SearchResult</tt> objects
  666. * @throws NamingException if a naming exception is encountered
  667. */
  668. public NamingEnumeration search(String name,
  669. Attributes matchingAttributes,
  670. String[] attributesToReturn)
  671. throws NamingException;
  672. /**
  673. * Searches in a single context for objects that contain a
  674. * specified set of attributes.
  675. * This method returns all the attributes of such objects.
  676. * It is equivalent to supplying null as
  677. * the <tt>atributesToReturn</tt> parameter to the method
  678. * <code>search(Name, Attributes, String[])</code>.
  679. * <br>
  680. * See {@link #search(Name, Attributes, String[])} for a full description.
  681. *
  682. * @param name
  683. * the name of the context to search
  684. * @param matchingAttributes
  685. * the attributes to search for
  686. * @return an enumeration of <tt>SearchResult</tt> objects
  687. * @throws NamingException if a naming exception is encountered
  688. *
  689. * @see #search(Name, Attributes, String[])
  690. */
  691. public NamingEnumeration search(Name name,
  692. Attributes matchingAttributes)
  693. throws NamingException;
  694. /**
  695. * Searches in a single context for objects that contain a
  696. * specified set of attributes.
  697. * See {@link #search(Name, Attributes)} for details.
  698. *
  699. * @param name
  700. * the name of the context to search
  701. * @param matchingAttributes
  702. * the attributes to search for
  703. * @return an enumeration of <tt>SearchResult</tt> objects
  704. * @throws NamingException if a naming exception is encountered
  705. */
  706. public NamingEnumeration search(String name,
  707. Attributes matchingAttributes)
  708. throws NamingException;
  709. /**
  710. * Searches in the named context or object for entries that satisfy the
  711. * given search filter. Performs the search as specified by
  712. * the search controls.
  713. * <p>
  714. * The format and interpretation of <code>filter</code> follows RFC 2254
  715. * with the
  716. * following interpretations for <code>attr</code> and <code>value</code>
  717. * mentioned in the RFC.
  718. * <p>
  719. * <code>attr</code> is the attribute's identifier.
  720. * <p>
  721. * <code>value</code> is the string representation the attribute's value.
  722. * The translation of this string representation into the attribute's value
  723. * is directory-specific.
  724. * <p>
  725. * For the assertion "someCount=127", for example, <code>attr</code>
  726. * is "someCount" and <code>value</code> is "127".
  727. * The provider determines, based on the attribute ID ("someCount")
  728. * (and possibly its schema), that the attribute's value is an integer.
  729. * It then parses the string "127" appropriately.
  730. *<p>
  731. * Any non-ASCII characters in the filter string should be
  732. * represented by the appropriate Java (Unicode) characters, and
  733. * not encoded as UTF-8 octets. Alternately, the
  734. * "backslash-hexcode" notation described in RFC 2254 may be used.
  735. *<p>
  736. * If the directory does not support a string representation of
  737. * some or all of its attributes, the form of <code>search</code> that
  738. * accepts filter arguments in the form of Objects can be used instead.
  739. * The service provider for such a directory would then translate
  740. * the filter arguments to its service-specific representation
  741. * for filter evaluation.
  742. * See <code>search(Name, String, Object[], SearchControls)</code>.
  743. * <p>
  744. * RFC 2254 defines certain operators for the filter, including substring
  745. * matches, equality, approximate match, greater than, less than. These
  746. * operators are mapped to operators with corresponding semantics in the
  747. * underlying directory. For example, for the equals operator, suppose
  748. * the directory has a matching rule defining "equality" of the
  749. * attributes in the filter. This rule would be used for checking
  750. * equality of the attributes specified in the filter with the attributes
  751. * of objects in the directory. Similarly, if the directory has a
  752. * matching rule for ordering, this rule would be used for
  753. * making "greater than" and "less than" comparisons.
  754. *<p>
  755. * Not all of the operators defined in RFC 2254 are applicable to all
  756. * attributes. When an operator is not applicable, the exception
  757. * <code>InvalidSearchFilterException</code> is thrown.
  758. * <p>
  759. * The result is returned in an enumeration of <tt>SearchResult</tt>s.
  760. * Each <tt>SearchResult</tt> contains the name of the object
  761. * and other information about the object (see SearchResult).
  762. * The name is either relative to the target context of the search
  763. * (which is named by the <code>name</code> parameter), or
  764. * it is a URL string. If the target context is included in
  765. * the enumeration (as is possible when
  766. * <code>cons</code> specifies a search scope of
  767. * <code>SearchControls.OBJECT_SCOPE</code> or
  768. * <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty
  769. * string. The <tt>SearchResult</tt> may also contain attributes of the
  770. * matching object if the <tt>cons</tt> argument specified that attributes
  771. * be returned.
  772. *<p>
  773. * If the object does not have a requested attribute, that
  774. * nonexistent attribute will be ignored. Those requested
  775. * attributes that the object does have will be returned.
  776. *<p>
  777. * A directory might return more attributes than were requested
  778. * (see <strong>Attribute Type Names</strong> in the class description)
  779. * but is not allowed to return arbitrary, unrelated attributes.
  780. *<p>
  781. * See also <strong>Operational Attributes</strong> in the class
  782. * description.
  783. *
  784. * @param name
  785. * the name of the context or object to search
  786. * @param filter
  787. * the filter expression to use for the search; may not be null
  788. * @param cons
  789. * the search controls that control the search. If null,
  790. * the default search controls are used (equivalent
  791. * to <tt>(new SearchControls())</tt>).
  792. * @return an enumeration of <tt>SearchResult</tt>s of
  793. * the objects that satisfy the filter; never null
  794. *
  795. * @throws InvalidSearchFilterException if the search filter specified is
  796. * not supported or understood by the underlying directory
  797. * @throws InvalidSearchControlsException if the search controls
  798. * contain invalid settings
  799. * @throws NamingException if a naming exception is encountered
  800. *
  801. * @see #search(Name, String, Object[], SearchControls)
  802. * @see SearchControls
  803. * @see SearchResult
  804. */
  805. public NamingEnumeration search(Name name,
  806. String filter,
  807. SearchControls cons)
  808. throws NamingException;
  809. /**
  810. * Searches in the named context or object for entries that satisfy the
  811. * given search filter. Performs the search as specified by
  812. * the search controls.
  813. * See {@link #search(Name, String, SearchControls)} for details.
  814. *
  815. * @param name
  816. * the name of the context or object to search
  817. * @param filter
  818. * the filter expression to use for the search; may not be null
  819. * @param cons
  820. * the search controls that control the search. If null,
  821. * the default search controls are used (equivalent
  822. * to <tt>(new SearchControls())</tt>).
  823. *
  824. * @return an enumeration of <tt>SearchResult</tt>s for
  825. * the objects that satisfy the filter.
  826. * @throws InvalidSearchFilterException if the search filter specified is
  827. * not supported or understood by the underlying directory
  828. * @throws InvalidSearchControlsException if the search controls
  829. * contain invalid settings
  830. * @throws NamingException if a naming exception is encountered
  831. */
  832. public NamingEnumeration search(String name,
  833. String filter,
  834. SearchControls cons)
  835. throws NamingException;
  836. /**
  837. * Searches in the named context or object for entries that satisfy the
  838. * given search filter. Performs the search as specified by
  839. * the search controls.
  840. *<p>
  841. * The interpretation of <code>filterExpr</code> is based on RFC
  842. * 2254. It may additionally contain variables of the form
  843. * <code>{i}</code> -- where <code>i</code> is an integer -- that
  844. * refer to objects in the <code>filterArgs</code> array. The
  845. * interpretation of <code>filterExpr</code> is otherwise
  846. * identical to that of the <code>filter</code> parameter of the
  847. * method <code>search(Name, String, SearchControls)</code>.
  848. *<p>
  849. * When a variable <code>{i}</code> appears in a search filter, it
  850. * indicates that the filter argument <code>filterArgs[i]</code>
  851. * is to be used in that place. Such variables may be used
  852. * wherever an <em>attr</em>, <em>value</em>, or
  853. * <em>matchingrule</em> production appears in the filter grammar
  854. * of RFC 2254, section 4. When a string-valued filter argument
  855. * is substituted for a variable, the filter is interpreted as if
  856. * the string were given in place of the variable, with any
  857. * characters having special significance within filters (such as
  858. * <code>'*'</code>) having been escaped according to the rules of
  859. * RFC 2254.
  860. *<p>
  861. * For directories that do not use a string representation for
  862. * some or all of their attributes, the filter argument
  863. * corresponding to an attribute value may be of a type other than
  864. * String. Directories that support unstructured binary-valued
  865. * attributes, for example, should accept byte arrays as filter
  866. * arguments. The interpretation (if any) of filter arguments of
  867. * any other type is determined by the service provider for that
  868. * directory, which maps the filter operations onto operations with
  869. * corresponding semantics in the underlying directory.
  870. *<p>
  871. * This method returns an enumeration of the results.
  872. * Each element in the enumeration contains the name of the object
  873. * and other information about the object (see <code>SearchResult</code>).
  874. * The name is either relative to the target context of the search
  875. * (which is named by the <code>name</code> parameter), or
  876. * it is a URL string. If the target context is included in
  877. * the enumeration (as is possible when
  878. * <code>cons</code> specifies a search scope of
  879. * <code>SearchControls.OBJECT_SCOPE</code> or
  880. * <code>SearchControls.SUBSTREE_SCOPE</code>),
  881. * its name is the empty string.
  882. *<p>
  883. * The <tt>SearchResult</tt> may also contain attributes of the matching
  884. * object if the <tt>cons</tt> argument specifies that attributes be
  885. * returned.
  886. *<p>
  887. * If the object does not have a requested attribute, that
  888. * nonexistent attribute will be ignored. Those requested
  889. * attributes that the object does have will be returned.
  890. *<p>
  891. * A directory might return more attributes than were requested
  892. * (see <strong>Attribute Type Names</strong> in the class description)
  893. * but is not allowed to return arbitrary, unrelated attributes.
  894. *<p>
  895. * If a search filter with invalid variable substitutions is provided
  896. * to this method, the result is undefined.
  897. * When changes are made to this DirContext,
  898. * the effect on enumerations returned by prior calls to this method
  899. * is undefined.
  900. *<p>
  901. * See also <strong>Operational Attributes</strong> in the class
  902. * description.
  903. *
  904. * @param name
  905. * the name of the context or object to search
  906. * @param filterExpr
  907. * the filter expression to use for the search.
  908. * The expression may contain variables of the
  909. * form "<code>{i}</code>" where <code>i</code>
  910. * is a nonnegative integer. May not be null.
  911. * @param filterArgs
  912. * the array of arguments to substitute for the variables
  913. * in <code>filterExpr</code>. The value of
  914. * <code>filterArgs[i]</code> will replace each
  915. * occurrence of "<code>{i}</code>".
  916. * If null, equivalent to an empty array.
  917. * @param cons
  918. * the search controls that control the search. If null,
  919. * the default search controls are used (equivalent
  920. * to <tt>(new SearchControls())</tt>).
  921. * @return an enumeration of <tt>SearchResult</tt>s of the objects
  922. * that satisfy the filter; never null
  923. *
  924. * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
  925. * <code>{i}</code> expressions where <code>i</code> is outside
  926. * the bounds of the array <code>filterArgs</code>
  927. * @throws InvalidSearchControlsException if <tt>cons</tt> contains
  928. * invalid settings
  929. * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
  930. * <tt>filterArgs</tt> represents an invalid search filter
  931. * @throws NamingException if a naming exception is encountered
  932. *
  933. * @see #search(Name, Attributes, String[])
  934. * @see java.text.MessageFormat
  935. */
  936. public NamingEnumeration search(Name name,
  937. String filterExpr,
  938. Object[] filterArgs,
  939. SearchControls cons)
  940. throws NamingException;
  941. /**
  942. * Searches in the named context or object for entries that satisfy the
  943. * given search filter. Performs the search as specified by
  944. * the search controls.
  945. * See {@link #search(Name, String, Object[], SearchControls)} for details.
  946. *
  947. * @param name
  948. * the name of the context or object to search
  949. * @param filterExpr
  950. * the filter expression to use for the search.
  951. * The expression may contain variables of the
  952. * form "<code>{i}</code>" where <code>i</code>
  953. * is a nonnegative integer. May not be null.
  954. * @param filterArgs
  955. * the array of arguments to substitute for the variables
  956. * in <code>filterExpr</code>. The value of
  957. * <code>filterArgs[i]</code> will replace each
  958. * occurrence of "<code>{i}</code>".
  959. * If null, equivalent to an empty array.
  960. * @param cons
  961. * the search controls that control the search. If null,
  962. * the default search controls are used (equivalent
  963. * to <tt>(new SearchControls())</tt>).
  964. * @return an enumeration of <tt>SearchResult</tt>s of the objects
  965. * that satisfy the filter; never null
  966. *
  967. * @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
  968. * <code>{i}</code> expressions where <code>i</code> is outside
  969. * the bounds of the array <code>filterArgs</code>
  970. * @throws InvalidSearchControlsException if <tt>cons</tt> contains
  971. * invalid settings
  972. * @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
  973. * <tt>filterArgs</tt> represents an invalid search filter
  974. * @throws NamingException if a naming exception is encountered
  975. */
  976. public NamingEnumeration search(String name,
  977. String filterExpr,
  978. Object[] filterArgs,
  979. SearchControls cons)
  980. throws NamingException;
  981. }