SearchControls


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