1. /*
  2. * @(#)SearchControls.java 1.8 01/02/09
  3. *
  4. * Copyright 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package javax.naming.directory;
  11. /**
  12. * This class encapsulates
  13. * factors that determine scope of search and what gets returned
  14. * as a result of the search.
  15. *<p>
  16. * A SearchControls instance is not synchronized against concurrent
  17. * multithreaded access. Multiple threads trying to access and modify
  18. * a single SearchControls instance should lock the object.
  19. *
  20. * @author Rosanna Lee
  21. * @author Scott Seligman
  22. * @version 1.8 01/02/09
  23. * @since 1.3
  24. */
  25. public class SearchControls implements java.io.Serializable {
  26. /**
  27. * Search the named object.
  28. *<p>
  29. * The NamingEnumeration that results from search()
  30. * using OBJECT_SCOPE will contain one or zero element.
  31. * The enumeration contains one element if the named object satisfies
  32. * the search filter specified in search().
  33. * The element will have as its name the empty string because the names
  34. * of elements in the NamingEnumeration are relative to the
  35. * target context--in this case, the target context is the named object.
  36. * It contains zero element if the named object does not satisfy
  37. * the search filter specified in search().
  38. * <p>
  39. * The value of this constant is <tt>0</tt>.
  40. */
  41. public final static int OBJECT_SCOPE = 0;
  42. /**
  43. * Search one level of the named context.
  44. *<p>
  45. * The NamingEnumeration that results from search()
  46. * using ONELEVEL_SCOPE contains elements with
  47. * objects in the named context that satisfy
  48. * the search filter specified in search().
  49. * The names of elements in the NamingEnumeration are atomic names
  50. * relative to the named context.
  51. * <p>
  52. * The value of this constant is <tt>1</tt>.
  53. */
  54. public final static int ONELEVEL_SCOPE = 1;
  55. /**
  56. * Search the entire subtree rooted at the named object.
  57. *<p>
  58. * If the named object is not a DirContext, search only the object.
  59. * If the named object is a DirContext, search the subtree
  60. * rooted at the named object, including the named object itself.
  61. *<p>
  62. * The search will not cross naming system boundaries.
  63. *<p>
  64. * The NamingEnumeration that results from search()
  65. * using SUBTREE_SCOPE contains elements of objects
  66. * from the subtree (including the named context)
  67. * that satisfy the search filter specified in search().
  68. * The names of elements in the NamingEnumeration are either
  69. * relative to the named context or is a URL string.
  70. * If the named context satisfies the search filter, it is
  71. * included in the enumeration with the empty string as
  72. * its name.
  73. * <p>
  74. * The value of this constant is <tt>2</tt>.
  75. */
  76. public final static int SUBTREE_SCOPE = 2;
  77. /**
  78. * Contains the scope with which to apply the search. One of
  79. * <tt>ONELEVEL_SCOPE</tt>, <tt>OBJECT_SCOPE</tt>, or
  80. * <tt>SUBTREE_SCOPE</tt>.
  81. * @serial
  82. */
  83. private int searchScope;
  84. /**
  85. * Contains the milliseconds to wait before returning
  86. * from search.
  87. * @serial
  88. */
  89. private int timeLimit;
  90. /**
  91. * Indicates whether JNDI links are dereferenced during
  92. * search.
  93. * @serial
  94. */
  95. private boolean derefLink;
  96. /**
  97. * Indicates whether object is returned in <tt>SearchResult</tt>.
  98. * @serial
  99. */
  100. private boolean returnObj;
  101. /**
  102. * Contains the maximum number of SearchResults to return.
  103. * @serial
  104. */
  105. private long countLimit;
  106. /**
  107. * Contains the list of attributes to be returned in
  108. * <tt>SearchResult</tt> for each matching entry of search. <tt>null</tt>
  109. * indicates that all attributes are to be returned.
  110. * @serial
  111. */
  112. private String[] attributesToReturn;
  113. /**
  114. * Constructs a search constraints using defaults.
  115. *<p>
  116. * The defaults are:
  117. * <ul>
  118. * <li>search one level
  119. * <li>no maximum return limit for search results
  120. * <li>no time limit for search
  121. * <li>return all attributes associated with objects that satisfy
  122. * the search filter.
  123. * <li>do not return named object (return only name and class)
  124. * <li>do not dereference links during search
  125. *</ul>
  126. */
  127. public SearchControls() {
  128. searchScope = ONELEVEL_SCOPE;
  129. timeLimit = 0; // no limit
  130. countLimit = 0; // no limit
  131. derefLink = false;
  132. returnObj = false;
  133. attributesToReturn = null; // return all
  134. }
  135. /**
  136. * Constructs a search constraints using arguments.
  137. * @param scope The search scope. One of:
  138. * OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
  139. * @param timelim The number of milliseconds to wait before returning.
  140. * If 0, wait indefinitely.
  141. * @param deref If true, dereference links during search.
  142. * @param countlim The maximum number of entries to return. If 0, return
  143. * all entries that satisfy filter.
  144. * @param retobj If true, return the object bound to the name of the
  145. * entry; if false, do not return object.
  146. * @param attrs The identifiers of the attributes to return along with
  147. * the entry. If null, return all attributes. If empty
  148. * return no attributes.
  149. */
  150. public SearchControls(int scope,
  151. long countlim,
  152. int timelim,
  153. String[] attrs,
  154. boolean retobj,
  155. boolean deref) {
  156. searchScope = scope;
  157. timeLimit = timelim; // no limit
  158. derefLink = deref;
  159. returnObj = retobj;
  160. countLimit = countlim; // no limit
  161. attributesToReturn = attrs; // return all
  162. }
  163. /**
  164. * Retrieves the search scope of these SearchControls.
  165. *<p>
  166. * One of OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
  167. *
  168. * @return The search scope of this SearchControls.
  169. * @see #setSearchScope
  170. */
  171. public int getSearchScope() {
  172. return searchScope;
  173. }
  174. /**
  175. * Retrieves the time limit of these SearchControls in milliseconds.
  176. *<p>
  177. * If the value is 0, this means to wait indefinitely.
  178. * @return The time limit of these SearchControls in milliseconds.
  179. * @see #setTimeLimit
  180. */
  181. public int getTimeLimit() {
  182. return timeLimit;
  183. }
  184. /**
  185. * Determines whether links will be dereferenced during the search.
  186. *
  187. * @return true if links will be dereferenced; false otherwise.
  188. * @see #setDerefLinkFlag
  189. */
  190. public boolean getDerefLinkFlag() {
  191. return derefLink;
  192. }
  193. /**
  194. * Determines whether objects will be returned as part of the result.
  195. *
  196. * @return true if objects will be returned; false otherwise.
  197. * @see #setReturningObjFlag
  198. */
  199. public boolean getReturningObjFlag() {
  200. return returnObj;
  201. }
  202. /**
  203. * Retrieves the maximum number of entries that will be returned
  204. * as a result of the search.
  205. *<p>
  206. * 0 indicates that all entries will be returned.
  207. * @return The maximum number of entries that will be returned.
  208. * @see #setCountLimit
  209. */
  210. public long getCountLimit() {
  211. return countLimit;
  212. }
  213. /**
  214. * Retrieves the attributes that will be returned as part of the search.
  215. *<p>
  216. * A value of null indicates that all attributes will be returned.
  217. * An empty array indicates that no attributes are to be returned.
  218. *
  219. * @return An array of attribute ids identifying the attributes that
  220. * will be returned. Can be null.
  221. * @see #setReturningAttributes
  222. */
  223. public String[] getReturningAttributes() {
  224. return attributesToReturn;
  225. }
  226. /**
  227. * Sets the search scope to one of:
  228. * OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
  229. * @param scope The search scope of this SearchControls.
  230. * @see #getSearchScope
  231. */
  232. public void setSearchScope(int scope) {
  233. searchScope = scope;
  234. }
  235. /**
  236. * Sets the time limit of these SearchControls in milliseconds.
  237. *<p>
  238. * If the value is 0, this means to wait indefinitely.
  239. * @param ms The time limit of these SearchControls in milliseconds.
  240. * @see #getTimeLimit
  241. */
  242. public void setTimeLimit(int ms) {
  243. timeLimit = ms;
  244. }
  245. /**
  246. * Enables/disables link dereferencing during the search.
  247. *
  248. * @param on if true links will be dereferenced; if false, not followed.
  249. * @see #getDerefLinkFlag
  250. */
  251. public void setDerefLinkFlag(boolean on) {
  252. derefLink = on;
  253. }
  254. /**
  255. * Enables/disables returning objects returned as part of the result.
  256. *<p>
  257. * If disabled, only the name and class of the object is returned.
  258. * If enabled, the object will be returned.
  259. *
  260. * @param on if true, objects will be returned; if false,
  261. * objects will not be returned.
  262. * @see #getReturningObjFlag
  263. */
  264. public void setReturningObjFlag(boolean on) {
  265. returnObj = on;
  266. }
  267. /**
  268. * Sets the maximum number of entries to be returned
  269. * as a result of the search.
  270. *<p>
  271. * 0 indicates no limit: all entries will be returned.
  272. *
  273. * @param limit The maximum number of entries that will be returned.
  274. * @see #getCountLimit
  275. */
  276. public void setCountLimit(long limit) {
  277. countLimit = limit;
  278. }
  279. /**
  280. * Specifies the attributes that will be returned as part of the search.
  281. *<p>
  282. * null indicates that all attributes will be returned.
  283. * An empty array indicates no attributes are returned.
  284. *
  285. * @param attrs An array of attribute ids identifying the attributes that
  286. * will be returned. Can be null.
  287. * @see #getReturningAttributes
  288. */
  289. public void setReturningAttributes(String[] attrs) {
  290. attributesToReturn = attrs;
  291. }
  292. /**
  293. * Use serialVersionUID from JNDI 1.1.1 for interoperability.
  294. */
  295. private static final long serialVersionUID = -2480540967773454797L;
  296. }