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: IdSearchControl.java,v 1.7 2008/07/06 05:48:30 arviranga Exp $
026 *
027 */
028
029/*
030 * Portions Copyrighted [2011] [ForgeRock AS]
031 */
032package com.sun.identity.idm;
033
034import java.util.HashSet;
035import java.util.HashMap;
036import java.util.Iterator;
037import java.util.Map;
038import java.util.Set;
039
040
041/**
042 * This is a helper class which is used in the <code> AMIdentityRepository
043 * </code>
044 * search method. It is used to to modify search controls for a given search
045 * operation. The specific controls that can be modified are: maximum time limit
046 * and size limit for the search, attributes that should be returned from the
047 * search, simple modifications to be made to the search filter used by each
048 * plugin by adding attribute-values which can be either OR'ed or AND'ed to the
049 * basic search.
050 * 
051 * @supported.all.api
052 */
053public final class IdSearchControl {
054    private Set returnAttributes = null;
055
056    // Disabled by default
057    private boolean getAllAttributesEnabled;
058
059    private int timeOut = 0;
060
061    private int maxResults = 0;
062
063    Map avPairs = null;
064
065    IdSearchOpModifier modifier = IdSearchOpModifier.OR;
066
067    boolean recursive = false;
068
069    /**
070     * Creates the <code>IdSearchControl</code> object
071     */
072    public IdSearchControl() {
073
074    }
075
076    /**
077     * Set the return attribute names, if attributes of the entries need to be
078     * obtained as part of the search.
079     * 
080     * NOTE: If the return attribute values are specified as part of
081     * <code>AMSearchControl</code>, there could be a significant performance
082     * overhead compared to when none are specified. When the return attributes
083     * are set, the return attributes can be obtained as a map with identity
084     * name as map-key and set of attribute values as map-value from
085     * <code>AMSearchResults</code> object.
086     * 
087     * @param attributeNames
088     *            Set of attribute names whose values need to be obtained as
089     *            part of the search.
090     * 
091     */
092    public void setReturnAttributes(Set attributeNames) {
093        if (attributeNames != null && !attributeNames.isEmpty()) {
094            returnAttributes = new HashSet(attributeNames);
095        }
096    }
097
098    /**
099     * Returns the list of attributes requested to be read when the search is
100     * performed.
101     * 
102     * @return Set of attributes requested to be read.
103     */
104    public Set getReturnAttributes() {
105        return returnAttributes;
106    }
107
108    /**
109     * Sets the specified boolean value to the variable. Boolean value is set to
110     * true, if all attributes of the entries need to be obtained as part of the
111     * search.
112     * 
113     * When the option for getting all attributes is set to true, the search
114     * results will return a Map, where the Key is the DN of the search results,
115     * and value is another Map of attribute names for keys and Sets for values
116     * of those attributes.
117     * 
118     * @param getAllAttributes
119     *            Boolean value set to true as part of the
120     *            <code>IdSearchControl</code> to obtain all attributes as
121     *            part of the search.
122     * 
123     * 
124     */
125    public void setAllReturnAttributes(boolean getAllAttributes) {
126        this.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     * Sets the maximum number of milliseconds to wait for any operation for the
140     * search.
141     * 
142     * @param timeOut
143     *            Max number of milliseconds
144     * 
145     */
146    public void setTimeOut(int timeOut) {
147        this.timeOut = timeOut;
148    }
149
150    /**
151     * Returns current time out setting.
152     * 
153     * @return current time out setting.
154     */
155    public int getTimeOut() {
156        return timeOut;
157    }
158
159    /**
160     * Sets the maximum number of search results to return; 0 means there is no
161     * limit.
162     * 
163     * @param maxNumber
164     *            Max number of results
165     */
166    public void setMaxResults(int maxNumber) {
167        maxResults = maxNumber;
168    }
169
170    /**
171     * Returns the maximum number of search results. return 0 means there is no
172     * limit.
173     * 
174     * @return the maximum number of search results.
175     */
176    public int getMaxResults() {
177        return maxResults;
178    }
179
180    /**
181     * Set the options for modifying the basic search filter in each plugin. By
182     * default, there are no modifications.
183     * 
184     * @param mod
185     *            One of the supported IdSearchOpModifiers
186     * @param avMap
187     *            Map of attribute-value pairs to be used to modify the search
188     *            operation.
189     */
190    public void setSearchModifiers(IdSearchOpModifier mod, Map avMap) {
191        modifier = mod;
192        if (avMap != null && !avMap.isEmpty()) {
193            this.avPairs = new HashMap();
194            Iterator it = avMap.keySet().iterator();
195            while (it.hasNext()) {
196                String attr = (String) it.next();
197                Set values = new HashSet((Set) avMap.get(attr));
198                this.avPairs.put(attr, values);
199            }
200        }
201    }
202
203    /**
204     * Returns the IdSearchOpModifier defined for this SearchControl
205     * 
206     * @return One of the supported IdSearchOpModifier
207     */
208    public IdSearchOpModifier getSearchModifier() {
209        return modifier;
210    }
211
212    /**
213     * Returns the map set to be used to modify the search filter in each
214     * plugin.
215     * 
216     * @return Map of attribute values pairs, if it is set. Null otherwise.
217     */
218    public Map getSearchModifierMap() {
219        return avPairs;
220    }
221
222    /**
223     * Sets the recursive flag to be true or false. It is false by default so
224     * plugin searches are not recursive.
225     *
226     * @deprecated This method is deprecated. The setting for recursive
227     * search should be configured via the data store.
228     *
229     * @param rec 
230     *        <code>true</code> if search is recursive; 
231     *        else <code>false</code>
232     */
233    public void setRecursive(boolean rec) {
234        recursive = rec;
235    }
236
237    /**
238     * Returns true if recursive is enabled, false otherwise
239     *
240     * @deprecated This method is deprecated. The setting for recursive
241     * search should be configured via the data store.
242     * 
243     * @return true if recursive search is on; else false.
244     */
245    public boolean isRecursive() {
246        return recursive;
247    }
248    
249    /**
250     * Return String representation of the <code>IdeSearchControl</code>
251     * object. It returns the search controls
252     *
253     * @return String representation of the <code>IdSearchControl</code>
254     * object.
255     */
256    public String toString() {
257       StringBuilder sb = new StringBuilder(100);
258       sb.append("IdSearchControl:");
259       sb.append("\n\tReturnAllAttributes: ").append(getAllAttributesEnabled);
260       sb.append("\n\tReturn Attributes: ").append(returnAttributes);
261       sb.append("\n\tTimeout=").append(timeOut);
262       sb.append("\n\tMaxResults=").append(maxResults);
263       sb.append("\n\tOperator: ").append(modifier);
264       sb.append("\n\tSearchAttrs: ").append(avPairs);
265       return (sb.toString());
266    }
267}