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: AMSearchControl.java,v 1.4 2008/06/25 05:41:22 qcheng Exp $
026 *
027 */
028
029package com.iplanet.am.sdk;
030
031import java.util.Set;
032
033import com.iplanet.ums.SearchControl;
034
035/**
036 * This class provides a way to customize Search behaviors. Common behaviors are
037 * time limit, result limit and Virtual list view. In future, we will provide
038 * ways for client to define different hierarchical tree through
039 * <code>AMSearchControl</code>.
040 *
041 * @deprecated  As of Sun Java System Access Manager 7.1.
042 * @supported.all.api
043 */
044public class AMSearchControl {
045
046    private SearchControl searchControl;
047
048    private Set returnAttributes = null;
049
050    // Disabled by default
051    private static boolean getAllAttributesEnabled = false;
052
053    /**
054     * Creates the <code>AMSearchControl</code> object
055     */
056    public AMSearchControl() {
057        searchControl = new SearchControl();
058    }
059
060    protected SearchControl getSearchControl() {
061        return searchControl;
062    }
063
064    /**
065     * Set the return attribute names, if attributes of the entries need to be
066     * obtained as part of the search.
067     * 
068     * NOTE: If the return attribute values are specified as part of
069     * <code>AMSearchControl</code>, there could be a significant performance
070     * overhead compared to when none are specified. When the return attributes
071     * are set, the return attributes can be obtained as a map with DN as
072     * map-key and set of attribute values as map-value from
073     * <code>AMSearchResults</code> object.
074     * 
075     * @param attributeNames
076     *            Set of attribute names whose values need to be obtained as
077     *            part of the search.
078     * 
079     */
080    public void setReturnAttributes(Set attributeNames) {
081        returnAttributes = attributeNames;
082    }
083
084    /**
085     * Returns the list of attributes requested to be read when the search is
086     * performed.
087     * 
088     * @return list of attributes requested to be read.
089     */
090    public String[] getReturnAttributes() {
091        String returnAttrs[] = null;
092        if (returnAttributes != null && !returnAttributes.isEmpty()) {
093            returnAttrs = (String[]) returnAttributes
094                    .toArray(new String[returnAttributes.size()]);
095
096        }
097        return returnAttrs;
098    }
099
100    /**
101     * Sets the specified boolean value to the variable. Boolean value is set to
102     * true, if all attributes of the entries need to be obtained as part of the
103     * search.
104     * 
105     * NOTE: If this <code>getAllReturnAttributes</code> boolean is set to
106     * true as part of <code>AMSearchControl</code>, it overrides any other
107     * <code>setReturnAttributes</code> set as part of the
108     * <code>AMSearchControl</code>. This is similar to using a wildcard '*'
109     * in search.
110     * 
111     * When the option for getting all attributes is set to true, the search
112     * results will return a Map, where the Key is the DN of the search results,
113     * and value is another Map of attribute names for keys and Sets for values
114     * of those attributes.
115     * 
116     * @param getAllAttributes
117     *            Boolean value set to true as part of the
118     *            <code>AMSearchControl</code> to obtain all attributes as
119     *            part of the search.
120     * 
121     * 
122     */
123    public void setAllReturnAttributes(boolean getAllAttributes) {
124        SearchControl sc = getSearchControl();
125        sc.setAllReturnAttributes(getAllAttributes);
126        getAllAttributesEnabled = getAllAttributes;
127    }
128
129    /**
130     * Returns true if the option for getting all attributes has been enabled.
131     * 
132     * @return true if the option for getting all attributes has been enabled.
133     */
134    public boolean isGetAllReturnAttributesEnabled() {
135        return getAllAttributesEnabled;
136    }
137
138    /**
139     * Set sort order based on attribute names.
140     * 
141     * @param attributeNames
142     *            array of attribute names to sort on
143     * 
144     */
145    public void setSortKeys(String[] attributeNames) {
146        searchControl.setSortKeys(attributeNames);
147    }
148
149    /**
150     * Set range for retrieving VLV data.
151     * 
152     * @param startIndex
153     *            starting position.
154     * @param beforeCount
155     *            Number of entries before the <code>startIndex</code>.
156     * @param afterCount
157     *            Number of entries after the <code>startIndex</code>.
158     */
159    protected void setVLVRange(int startIndex, int beforeCount, int afterCount) 
160    {
161        searchControl.setVLVRange(startIndex, beforeCount, afterCount);
162    }
163
164    /**
165     * Set range for retrieving VLV data.
166     * 
167     * @param jumpTo
168     *            Search expression defining the result set return.
169     * @param beforeCount
170     *            Number of entries before the <code>startIndex</code>.
171     * @param afterCount
172     *            Number of entries after the <code>startIndex</code>.
173     */
174    protected void setVLVRange(String jumpTo, int beforeCount, int afterCount) 
175    {
176        searchControl.setVLVRange(jumpTo, beforeCount, afterCount);
177    }
178
179    /**
180     * Get range for current VLV setting.
181     * 
182     * @return array of integers which contain <code>startIndex</code>,
183     *         <code>beforeCount</code> and <code>afterCount</code>.
184     */
185    protected int[] getVLVRange() {
186        return searchControl.getVLVRange();
187    }
188
189    /**
190     * Returns <code>jumpTo</code> value for VLV range.
191     * 
192     * @return <code>jumpTo</code> value.
193     * 
194     */
195    protected String getVLVJumpTo() {
196        return searchControl.getVLVJumpTo();
197    }
198
199    /**
200     * Sets the maximum number of milliseconds to wait for any operation for the
201     * search.
202     * 
203     * @param timeOut
204     *            Max number of milliseconds
205     * 
206     */
207    public void setTimeOut(int timeOut) {
208        searchControl.setTimeOut(timeOut);
209    }
210
211    /**
212     * Returns current time out setting.
213     * 
214     * @return current time out setting.
215     */
216    public int getTimeOut() {
217        return searchControl.getTimeOut();
218    }
219
220    /**
221     * Sets the maximum number of search results to return; 0 means there is no
222     * limit.
223     * 
224     * @param maxNumber
225     *            Max number of results
226     */
227    public void setMaxResults(int maxNumber) {
228        searchControl.setMaxResults(maxNumber);
229    }
230
231    /**
232     * Returns the maximum number of search results. return 0 means there is no
233     * limit.
234     * 
235     * @return the maximum number of search results.
236     */
237    public int getMaxResults() {
238        return searchControl.getMaxResults();
239    }
240
241    /**
242     * Sets the search scope in <code>AMSearchControl</code>.
243     * 
244     * @param scope
245     *            Search scope defined in the <code>AMSearchControl</code> to
246     *            be used with the search API
247     */
248    public void setSearchScope(int scope) {
249        searchControl.setSearchScope(scope);
250    }
251
252    /**
253     * Gets the search scope defined in the <code>AMSearchControl</code>.
254     * 
255     * @return search scope defined in the <code>AMSearchControl</code>. If
256     *         search scope is never defined in the
257     *         <code>AMSearchControl</code> <code>SCOPE_SUB</code> for
258     *         subtree type of search is assumed.
259     */
260    public int getSearchScope() {
261        return searchControl.getSearchScope();
262    }
263
264    /**
265     * Gets the search scope defined in the <code>AMSearchControl</code>.
266     * Allows a user to specify default search scope if nothing has been defined
267     * in the <code>AMSearchControl</code> yet.
268     * 
269     * @param defaultScope
270     *            Scope value to be used in case the
271     *            <code>AMSearchControl</code> is not set up with a search
272     *            scope
273     * 
274     * @return Search scope defined in the <code>AMSearchControl</code>.
275     *         Return <code>defaultScope</code> if scope is not defined in the
276     *         control.
277     */
278    public int getSearchScope(int defaultScope) {
279        return searchControl.getSearchScope(defaultScope);
280    }
281}