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