001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: SearchControl.java,v 1.5 2009/01/28 05:34:51 ww203982 Exp $
026 *
027 * Portions Copyright 2015 ForgeRock AS.
028 */
029
030package com.iplanet.ums;
031
032import java.util.Hashtable;
033
034import org.forgerock.opendj.ldap.SearchScope;
035
036/**
037 * This class provides a way to customize Search behaviors. Common behaviors are
038 * time limit, result limit and Virtual list view. In future, we will provide
039 * ways for client to define different hierarchical tree through SearchControl.
040 *
041 * @supported.api
042 */
043public class SearchControl implements java.io.Serializable {
044
045    private static final long serialVersionUID = -8755868973524858945L;
046
047    static final String KeyVlvRange = "vlvRange";
048
049    static final String KeyVlvJumpTo = "vlvJumpTo";
050
051    static final String KeyTimeOut = "timeOut";
052
053    static final String KeySortKeys = "sortKeys";
054
055    static final String KeyMaxResults = "maxResults";
056
057    static final String KeySearchScope = "searchScope";
058
059    static final int DEFAULT_MAX_RESULTS = 0;
060
061    static final int DEFAULT_TIMEOUT = 0;
062
063    // Disabled by default
064    private static boolean getAllAttributesEnabled = false;
065
066    /**
067     * Search scope for one level. You use this search scope in getting
068     * immediate children of a container. This is the default search scope in
069     * getChildren method in search API. One can use
070     * SearchControl.setSearchScope to override the default search scope in
071     * getChildren.
072     * 
073     * @supported.api
074     */
075    public static final int SCOPE_ONE = SearchScope.SINGLE_LEVEL.intValue();
076
077    /**
078     * Search scope for subtree level. This scope is used as the default search
079     * scope in the search API. One can use SearchControl.setSearchScope to
080     * override the default search scope in search methods.
081     * 
082     * @supported.api
083     */
084    public static final int SCOPE_SUB = SearchScope.WHOLE_SUBTREE.intValue();
085
086    /**
087     * Search scope for just this object.
088     * 
089     * @supported.api
090     */
091    public static final int SCOPE_BASE = SearchScope.BASE_OBJECT.intValue();
092
093    /**
094     * Set sort order based on attribute names.
095     * 
096     * @param attributeNames
097     *            array of attribute names to sort on
098     * @supported.api
099     */
100    public void setSortKeys(String[] attributeNames) {
101        SortKey[] sortKeys;
102        if (attributeNames == null)
103            return;
104
105        sortKeys = new SortKey[attributeNames.length];
106        for (int i = 0; i < sortKeys.length; i++) {
107            sortKeys[i] = new SortKey();
108            sortKeys[i].attributeName = attributeNames[i];
109            sortKeys[i].reverse = false;
110        }
111
112        set(KeySortKeys, sortKeys);
113    }
114
115    /**
116     * Set sort order based on SortKey
117     * 
118     * @param sortKeys
119     *            array of SortKey.
120     * @supported.api
121     */
122    public void setSortKeys(SortKey[] sortKeys) {
123        set(KeySortKeys, sortKeys);
124    }
125
126    /**
127     * Get existing attribute names for sorting.
128     * @supported.api
129     */
130    public SortKey[] getSortKeys() {
131        return (SortKey[]) get(KeySortKeys);
132    }
133
134    /**
135     * Set range for retrieving VLV data.
136     * 
137     * @param startIndex
138     *            starting position
139     * @param beforeCount
140     *            Number of entries before the startIndex
141     * @param afterCount
142     *            Number of entries after the startIndex.
143     * @supported.api
144     */
145    public void setVLVRange(int startIndex, int beforeCount, int afterCount) {
146        int[] range = new int[3];
147        range[0] = startIndex;
148        range[1] = beforeCount;
149        range[2] = afterCount;
150
151        set(KeyVlvRange, range);
152    }
153
154    /**
155     * Set range for retrieving VLV data.
156     * 
157     * @param jumpTo
158     *            Search expression defining the result set return
159     * @param beforeCount
160     *            Number of entries before the startIndex
161     * @param afterCount
162     *            Number of entries after the startIndex.
163     * @supported.api
164     */
165    public void setVLVRange(String jumpTo, int beforeCount, int afterCount) {
166        int[] range = new int[3];
167
168        range[0] = 0;
169        range[1] = beforeCount;
170        range[2] = afterCount;
171
172        set(KeyVlvJumpTo, jumpTo);
173        set(KeyVlvRange, range);
174    }
175
176    /**
177     * Get range for current VLV setting.
178     * 
179     * @return array of int which contain startIndex, beforeCount and
180     *         afterCount.
181     * @supported.api
182     */
183    public int[] getVLVRange() {
184        return (int[]) get(KeyVlvRange);
185    }
186
187    /**
188     * Get jumpTo value for VLV range.
189     * 
190     * @return jumpTo value.
191     * @supported.api
192     */
193    public String getVLVJumpTo() {
194        return (String) get(KeyVlvJumpTo);
195    }
196
197    /**
198     * Sets the maximum number of milliseconds to wait for any operation for the
199     * search.
200     * 
201     * @param timeOut
202     *            Max number of milliseconds.
203     * @supported.api
204     */
205    public void setTimeOut(int timeOut) {
206        set(KeyTimeOut, new Integer(timeOut));
207    }
208
209    /**
210     * Get current time out setting.
211     * @supported.api
212     */
213    public int getTimeOut() {
214        Integer i = (Integer) get(KeyTimeOut);
215        if (i == null) {
216            return DEFAULT_TIMEOUT;
217        } else {
218            return i.intValue();
219        }
220    }
221
222    /**
223     * Sets the maximum number of search results to return; 0 means there is no
224     * limit.
225     * @supported.api
226     */
227    public void setMaxResults(int maxNumber) {
228        set(KeyMaxResults, new Integer(maxNumber));
229    }
230
231    /**
232     * Gets the maximum number of search results to return. return 0 means there
233     * is no limit.
234     * @supported.api
235     */
236    public int getMaxResults() {
237        Integer i = (Integer) get(KeyMaxResults);
238        if (i == null) {
239            return DEFAULT_MAX_RESULTS;
240        } else {
241            return i.intValue();
242        }
243    }
244
245    /**
246     * Sets the search scope in SearchControl.
247     * 
248     * @param scope
249     *            Search scope defined in the SearchControl to be used with the
250     *            search API.
251     * @supported.api
252     */
253    public void setSearchScope(int scope) {
254        set(KeySearchScope, new Integer(scope));
255    }
256
257    /**
258     * Gets the search scope defined in the SearchControl.
259     * 
260     * @return search scope defined in the SearchControl. If search scope is
261     *         never defined in the SearchControl SCOPE_SUB for subtree type of
262     *         search is assumed.
263     * @supported.api
264     */
265    public int getSearchScope() {
266        Integer scope = (Integer) get(KeySearchScope);
267        if (scope != null) {
268            return scope.intValue();
269        } else {
270            return SearchControl.SCOPE_SUB;
271        }
272    }
273
274    /**
275     * Gets the search scope defined in the SearchControl. Allow user to specify
276     * default search scope if nothing has been defined in the SearchControl
277     * yet.
278     * 
279     * @param defaultScope
280     *            Scope value to be used in case the SearchControl is not set up
281     *            with a search scope
282     * 
283     * @return Search scope defined in the SearchControl. Return defaultScope if
284     *         scope is not defined in the control.
285     * @supported.api
286     */
287    public int getSearchScope(int defaultScope) {
288        Integer scope = (Integer) get(KeySearchScope);
289        if (scope != null) {
290            return scope.intValue();
291        } else {
292            return defaultScope;
293        }
294    }
295
296    /**
297     * Sets internal attribute value in SearchControl
298     */
299    protected void set(String name, Object o) {
300        m_hashTable.put(name, o);
301    }
302
303    /**
304     * Gets internal attribute defined in SearchControl
305     * 
306     * @param name
307     *            Name of attribute to get
308     * @return Object representing the value of the attribute. Return null
309     *         object if the given attribute name is not found
310     */
311    protected Object get(String name) {
312        return m_hashTable.get(name);
313    }
314
315    /**
316     * Checks if an internal attribute is defined for the control
317     * 
318     * @param name
319     *            Name of internal attribute to check against
320     * @return <code>true</code> if internal attribute is defined in the
321     *         control and <code>false</code> otherwise
322     */
323    protected boolean contains(String name) {
324        return m_hashTable.containsKey(name);
325    }
326
327    /**
328     * Sets the specified boolean value to the variable. Boolean value is set to
329     * true, if all attributes of the entries need to be obtained as part of the
330     * search.
331     * 
332     * NOTE: If this getAllReturnAttributes boolean is set to true as part of
333     * AMSearchControl, it overrides any other setReturnAttributes set as part
334     * of the AMSearchControl. This is similar to using a wildcard '*' in
335     * search.
336     * 
337     * When all the return attributes are set, the return attributes can be
338     * obtained as a map with DN as map-key and set of attribute values as
339     * map-value from AMSearchResults object.
340     * 
341     * @param getAllAttributes
342     *            Boolean value set to true as part of the AMSearchControl to
343     *            obtain all attributes as part of the search.
344     * 
345     * 
346     */
347    public void setAllReturnAttributes(boolean getAllAttributes) {
348        getAllAttributesEnabled = getAllAttributes;
349    }
350
351    /**
352     * Method to check if the boolean getAllAttributesEnabled is enabled or
353     * disabled.
354     * 
355     * @return Returns the value of the boolean getAllAttributesEnabled. Returns
356     *         true or false.
357     */
358    public boolean isGetAllReturnAttributesEnabled() {
359        return getAllAttributesEnabled;
360    }
361
362    private Hashtable m_hashTable = new Hashtable();
363}