001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.directory;
019:
020: import java.io.Serializable;
021:
022: /**
023: * This class represents the scope of a search, and the list of attributes that
024: * the search encompasses.
025: * <p>
026: * The various scopes are defined by class constants representing Object,
027: * Single-depth, and Full-depth searches of the directory.
028: * </p>
029: * <p>
030: * This class is not thread-safe.
031: * </p>
032: */
033: public class SearchControls implements Serializable {
034:
035: /*
036: * This constant is used during deserialization to check the version which
037: * created the serialized object
038: */
039: private static final long serialVersionUID = 0xdd935921dd0f3e33L;
040:
041: /**
042: * Bounds the search to the object scope only.
043: * <p>
044: * The search takes place over the given object. The resulting enumeration
045: * will therefore only contain either zero or one (the given) object
046: * depending upon whether the object matches the search criteria.
047: * </p>
048: * <p>
049: * If the object does match, its name in the enumeration will be empty since
050: * names are specified relative to the root of the search.
051: * </p>
052: */
053: public static final int OBJECT_SCOPE = 0;
054:
055: /**
056: * Bounds the search to a single level of the naming context rooted at the
057: * given object.
058: * <p>
059: * The search will take place over the object, or if the object is a context
060: * then the object and all objects that are one level removed from the given
061: * context.
062: * </p>
063: * <p>
064: * Matches are named by a relative name to the given root, so will have
065: * atomic (single level valid) names.
066: * </p>
067: */
068: public static final int ONELEVEL_SCOPE = 1;
069:
070: /**
071: * Bounds the search to the subtree rooted at the given object or naming
072: * context.
073: * <p>
074: * The search will take place over the object, or if the object is a context
075: * then the object and all objects that are reachable from he given context.
076: * </p>
077: * <p>
078: * The names that are returned in the enumeration are defined to be either
079: * relative names to the given root, or full URIs of the matching objects.
080: * </p>
081: * <p>
082: * The search is defined to no cross naming system boundaries.
083: * </p>
084: */
085: public static final int SUBTREE_SCOPE = 2;
086:
087: /**
088: * The scope of the search.
089: * <p>
090: * Constrained to be one of ONELEVEL_SCOPE, OBJECT_SCOPE, or SUBTREE_SCOPE.
091: * </p>
092: *
093: * @serial
094: */
095: private int searchScope;
096:
097: /**
098: * search time limitation.
099: * <p>
100: * Maximum number of milliseconds to wait for the search to complete.
101: * </p>
102: *
103: * @serial
104: */
105: private int timeLimit;
106:
107: /**
108: * Flag showing whether searches should dereference JNDI links.
109: *
110: * @serial
111: */
112: private boolean derefLink;
113:
114: /**
115: * Flag showing whether an Object is returned in the search results.
116: *
117: * @serial
118: */
119: private boolean returnObj;
120:
121: /**
122: * Maximum number of search results that will be returned.
123: *
124: * @serial
125: */
126: private long countLimit;
127:
128: /**
129: * Lists attributes to match.
130: * <p>
131: * Contains a single entry for each attribute that is to be matches -- or it
132: * is null if all attributes are to be matched.
133: * </p>
134: *
135: * @serial
136: */
137: private String attributesToReturn[];
138:
139: /**
140: * Default constructor.
141: * <p>
142: * Equivalent to:
143: * <code>SearchControls (ONELEVEL_SCOPE, 0, 0, null, false, false)</code>.
144: * </p>
145: */
146: public SearchControls() {
147: this (ONELEVEL_SCOPE, 0, 0, null, false, false);
148: }
149:
150: /**
151: * Constructs a search control instance with all parameters.
152: *
153: * @param searchScope
154: * the search scope, chosen from OBJECT_SCOPE, ONELEVEL_SCOPE or
155: * SUBTREE_SCOPE.
156: * @param countLimit
157: * the maximum number of search results. If is zero, then the
158: * number of search results returned is unlimited.
159: * @param timeLimit
160: * the maximum number of search time in milliseconds, for the
161: * search. If is zero, then there is no time limit for the
162: * search.
163: * @param attributesToReturn
164: * an array of identifiers of attributes to return for each
165: * result. If is null, then all attributes are returned for each
166: * result.
167: * @param returnObj
168: * an flag. If true then search results contain an object,
169: * otherwise they contain only a name and class pair.
170: * @param derefLink
171: * an flag. If true then <code>LinkRef</code> references are
172: * followed in the search, otherwise they are not.
173: *
174: */
175: public SearchControls(int searchScope, long countLimit,
176: int timeLimit, String attributesToReturn[],
177: boolean returnObj, boolean derefLink) {
178:
179: this .searchScope = searchScope;
180: this .countLimit = countLimit;
181: this .timeLimit = timeLimit;
182: this .attributesToReturn = attributesToReturn;
183: this .derefLink = derefLink;
184: this .returnObj = returnObj;
185: }
186:
187: /**
188: * Gets the maximum number of search results.
189: *
190: * @return the maximum number of search results to return.
191: */
192: public long getCountLimit() {
193: return countLimit;
194: }
195:
196: /**
197: * Gets the flag indicates whether search will follow LinkRef references.
198: *
199: * @return flag indicates whether searches will follow <code>LinkRef</code>
200: * references. If true then <code>LinkRef</code> references are
201: * followed in the search, otherwise they are not.
202: */
203: public boolean getDerefLinkFlag() {
204: return derefLink;
205: }
206:
207: /**
208: * Gets identifiers of attributes to return for each result.
209: *
210: * @return an array of identifiers of attributes to return for each result.
211: * If is null, then all attributes are returned for each result.
212: */
213: public String[] getReturningAttributes() {
214: return attributesToReturn;
215: }
216:
217: /**
218: * Gets the flag whether search results will include the object (true) or
219: * not (false).
220: *
221: * @return if true then search results contain an object, otherwise they
222: * contain only a name and class pair.
223: */
224: public boolean getReturningObjFlag() {
225: return returnObj;
226: }
227:
228: /**
229: * Gets the search scope.
230: *
231: * @return the search scope, chosen from OBJECT_SCOPE, ONELEVEL_SCOPE or
232: * SUBTREE_SCOPE.
233: */
234: public int getSearchScope() {
235: return searchScope;
236: }
237:
238: /**
239: * Gets the the maximum number of search time.
240: *
241: * @return the maximum number of search time in milliseconds, for the
242: * search. If is zero, then there is no time limit for the search.
243: */
244: public int getTimeLimit() {
245: return timeLimit;
246: }
247:
248: /**
249: * Sets the maximum number of search results.
250: *
251: * @param l
252: * the maximum number of search results. If is zero, then the
253: * number of search results returned is unlimited.
254: */
255: public void setCountLimit(long l) {
256: countLimit = l;
257: }
258:
259: /**
260: * Sets the flag indicates whether search will follow <code>LinkRef</code>
261: * references.
262: *
263: * @param flag
264: * flag indicates whether searches will follow
265: * <code>LinkRef</code> references. If true then
266: * <code>LinkRef</code> references are followed in the search,
267: * otherwise they are not.
268: */
269: public void setDerefLinkFlag(boolean flag) {
270: derefLink = flag;
271: }
272:
273: /**
274: * Sets identifiers of attributes to return for each result.
275: *
276: * @param as
277: * an array of identifiers of attributes to return for each
278: * result. If is null, then all attributes are returned for each
279: * result.
280: */
281: public void setReturningAttributes(String as[]) {
282: attributesToReturn = as;
283: }
284:
285: /**
286: * Sets the flag whether search results will include the object (true) or
287: * not (false).
288: *
289: * @param flag
290: * if true then search results contain an object, otherwise they
291: * contain only a name and class pair.
292: */
293: public void setReturningObjFlag(boolean flag) {
294: returnObj = flag;
295: }
296:
297: /**
298: * Sets the search scope.
299: *
300: * @param i
301: * the search scope, chosen from OBJECT_SCOPE, ONELEVEL_SCOPE or
302: * SUBTREE_SCOPE.
303: */
304: public void setSearchScope(int i) {
305: searchScope = i;
306: }
307:
308: /**
309: * Sets the the maximum number of search time.
310: *
311: * @param i
312: * the maximum number of search time in milliseconds, for the
313: * search. If is zero, then there is no time limit for the
314: * search.
315: */
316: public void setTimeLimit(int i) {
317: timeLimit = i;
318: }
319:
320: }
|