001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2009-2010 Sun Microsystems, Inc. 025 * Portions copyright 2012-2013 ForgeRock AS. 026 */ 027 028package org.forgerock.opendj.ldap.requests; 029 030import java.util.List; 031 032import org.forgerock.i18n.LocalizedIllegalArgumentException; 033import org.forgerock.opendj.ldap.DN; 034import org.forgerock.opendj.ldap.DecodeException; 035import org.forgerock.opendj.ldap.DecodeOptions; 036import org.forgerock.opendj.ldap.DereferenceAliasesPolicy; 037import org.forgerock.opendj.ldap.Filter; 038import org.forgerock.opendj.ldap.SearchScope; 039import org.forgerock.opendj.ldap.controls.Control; 040import org.forgerock.opendj.ldap.controls.ControlDecoder; 041 042/** 043 * The Search operation is used to request a server to return, subject to access 044 * controls and other restrictions, a set of entries matching a complex search 045 * criterion. This can be used to read attributes from a single entry, from 046 * entries immediately subordinate to a particular entry, or from a whole 047 * subtree of entries. 048 * <p> 049 * Use {@link Requests#newSearchRequest(DN, SearchScope, Filter, String...)} or 050 * {@link Requests#newSearchRequest(String, SearchScope, String, String...)} to 051 * create a new search request. 052 * 053 * <pre> 054 * SearchRequest request = Requests.newSearchRequest("dc=example,dc=com", SearchScope.WHOLE_SUBTREE, 055 * "(sn=Jensen)", "cn"); 056 * </pre> 057 * 058 * Alternatively, use the 059 * {@link org.forgerock.opendj.ldap.Connection#search(String, SearchScope, String, String...) 060 * Connection.search()} method to specify the arguments directly. 061 * 062 * <pre> 063 * Connection connection = ...; 064 * ConnectionEntryReader reader = connection.search( 065 * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn"); 066 * </pre> 067 */ 068public interface SearchRequest extends Request { 069 /** 070 * Adds the provided attribute name(s) to the list of attributes to be 071 * included with each entry that matches the search criteria. Attributes 072 * that are sub-types of listed attributes are implicitly included. 073 * 074 * @param attributeDescriptions 075 * The name(s) of the attribute to be included with each entry. 076 * @return This search request. 077 * @throws UnsupportedOperationException 078 * If this search request does not permit attribute names to be 079 * added. 080 * @throws NullPointerException 081 * If {@code attributeDescriptions} was {@code null}. 082 */ 083 SearchRequest addAttribute(String... attributeDescriptions); 084 085 @Override 086 SearchRequest addControl(Control control); 087 088 /** 089 * Returns a {@code List} containing the list of attributes to be included 090 * with each entry that matches the search criteria. Attributes that are 091 * sub-types of listed attributes are implicitly included. The returned 092 * {@code List} may be modified if permitted by this search request. 093 * 094 * @return A {@code List} containing the list of attributes. 095 */ 096 List<String> getAttributes(); 097 098 @Override 099 <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) 100 throws DecodeException; 101 102 @Override 103 List<Control> getControls(); 104 105 /** 106 * Returns an indication as to whether or not alias entries are to be 107 * dereferenced during the search. 108 * 109 * @return The alias dereferencing policy. 110 */ 111 DereferenceAliasesPolicy getDereferenceAliasesPolicy(); 112 113 /** 114 * Returns the filter that defines the conditions that must be fulfilled in 115 * order for an entry to be returned. 116 * 117 * @return The search filter. 118 */ 119 Filter getFilter(); 120 121 /** 122 * Returns the distinguished name of the base entry relative to which the 123 * search is to be performed. 124 * 125 * @return The distinguished name of the base entry. 126 */ 127 DN getName(); 128 129 /** 130 * Returns the scope of the search. 131 * 132 * @return The search scope. 133 */ 134 SearchScope getScope(); 135 136 /** 137 * Returns the size limit that should be used in order to restrict the 138 * maximum number of entries returned by the search. 139 * <p> 140 * A value of zero (the default) in this field indicates that no 141 * client-requested size limit restrictions are in effect. Servers may also 142 * enforce a maximum number of entries to return. 143 * 144 * @return The size limit that should be used in order to restrict the 145 * maximum number of entries returned by the search. 146 */ 147 int getSizeLimit(); 148 149 /** 150 * Indicates whether search result is expected to be limited to a single entry. 151 * <p> 152 * It is the case if size limit is equal to 1 or if scope is equal to <code>SearchScope.BASE_OBJECT</code>. 153 * <p> 154 * If search results contain more than one entry, the search operation will throw 155 * a <code>MultipleEntriesFoundException</code>. 156 * 157 * @return {@code true} if the search is limited to a single entry result, 158 * or {@code false} (the default) otherwise. 159 */ 160 boolean isSingleEntrySearch(); 161 162 /** 163 * Returns the time limit that should be used in order to restrict the 164 * maximum time (in seconds) allowed for the search. 165 * <p> 166 * A value of zero (the default) in this field indicates that no 167 * client-requested time limit restrictions are in effect for the search. 168 * Servers may also enforce a maximum time limit for the search. 169 * 170 * @return The time limit that should be used in order to restrict the 171 * maximum time (in seconds) allowed for the search. 172 */ 173 int getTimeLimit(); 174 175 /** 176 * Indicates whether search results are to contain both attribute 177 * descriptions and values, or just attribute descriptions. 178 * 179 * @return {@code true} if only attribute descriptions (and not values) are 180 * to be returned, or {@code false} (the default) if both attribute 181 * descriptions and values are to be returned. 182 */ 183 boolean isTypesOnly(); 184 185 /** 186 * Sets the alias dereferencing policy to be used during the search. 187 * 188 * @param policy 189 * The alias dereferencing policy to be used during the search. 190 * @return This search request. 191 * @throws UnsupportedOperationException 192 * If this search request does not permit the alias 193 * dereferencing policy to be set. 194 * @throws NullPointerException 195 * If {@code policy} was {@code null}. 196 */ 197 SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy); 198 199 /** 200 * Sets the filter that defines the conditions that must be fulfilled in 201 * order for an entry to be returned. 202 * 203 * @param filter 204 * The filter that defines the conditions that must be fulfilled 205 * in order for an entry to be returned. 206 * @return This search request. 207 * @throws UnsupportedOperationException 208 * If this search request does not permit the filter to be set. 209 * @throws NullPointerException 210 * If {@code filter} was {@code null}. 211 */ 212 SearchRequest setFilter(Filter filter); 213 214 /** 215 * Sets the filter that defines the conditions that must be fulfilled in 216 * order for an entry to be returned. 217 * 218 * @param filter 219 * The filter that defines the conditions that must be fulfilled 220 * in order for an entry to be returned. 221 * @return This search request. 222 * @throws UnsupportedOperationException 223 * If this search request does not permit the filter to be set. 224 * @throws LocalizedIllegalArgumentException 225 * If {@code filter} is not a valid LDAP string representation 226 * of a filter. 227 * @throws NullPointerException 228 * If {@code filter} was {@code null}. 229 */ 230 SearchRequest setFilter(String filter); 231 232 /** 233 * Sets the distinguished name of the base entry relative to which the 234 * search is to be performed. 235 * 236 * @param dn 237 * The distinguished name of the base entry relative to which the 238 * search is to be performed. 239 * @return This search request. 240 * @throws UnsupportedOperationException 241 * If this search request does not permit the distinguished name 242 * to be set. 243 * @throws NullPointerException 244 * If {@code dn} was {@code null}. 245 */ 246 SearchRequest setName(DN dn); 247 248 /** 249 * Sets the distinguished name of the base entry relative to which the 250 * search is to be performed. 251 * 252 * @param dn 253 * The distinguished name of the base entry relative to which the 254 * search is to be performed. 255 * @return This search request. 256 * @throws LocalizedIllegalArgumentException 257 * If {@code dn} could not be decoded using the default schema. 258 * @throws UnsupportedOperationException 259 * If this search request does not permit the distinguished name 260 * to be set. 261 * @throws NullPointerException 262 * If {@code dn} was {@code null}. 263 */ 264 SearchRequest setName(String dn); 265 266 /** 267 * Sets the scope of the search. 268 * 269 * @param scope 270 * The scope of the search. 271 * @return This search request. 272 * @throws UnsupportedOperationException 273 * If this search request does not permit the scope to be set. 274 * @throws NullPointerException 275 * If {@code scope} was {@code null}. 276 */ 277 SearchRequest setScope(SearchScope scope); 278 279 /** 280 * Sets the size limit that should be used in order to restrict the maximum 281 * number of entries returned by the search. 282 * <p> 283 * A value of zero (the default) in this field indicates that no 284 * client-requested size limit restrictions are in effect. Servers may also 285 * enforce a maximum number of entries to return. 286 * 287 * @param limit 288 * The size limit that should be used in order to restrict the 289 * maximum number of entries returned by the search. 290 * @return This search request. 291 * @throws UnsupportedOperationException 292 * If this search request does not permit the size limit to be 293 * set. 294 * @throws LocalizedIllegalArgumentException 295 * If {@code limit} was negative. 296 */ 297 SearchRequest setSizeLimit(int limit); 298 299 /** 300 * Sets the time limit that should be used in order to restrict the maximum 301 * time (in seconds) allowed for the search. 302 * <p> 303 * A value of zero (the default) in this field indicates that no 304 * client-requested time limit restrictions are in effect for the search. 305 * Servers may also enforce a maximum time limit for the search. 306 * 307 * @param limit 308 * The time limit that should be used in order to restrict the 309 * maximum time (in seconds) allowed for the search. 310 * @return This search request. 311 * @throws UnsupportedOperationException 312 * If this search request does not permit the time limit to be 313 * set. 314 * @throws LocalizedIllegalArgumentException 315 * If {@code limit} was negative. 316 */ 317 SearchRequest setTimeLimit(int limit); 318 319 /** 320 * Specifies whether search results are to contain both attribute 321 * descriptions and values, or just attribute descriptions. 322 * 323 * @param typesOnly 324 * {@code true} if only attribute descriptions (and not values) 325 * are to be returned, or {@code false} (the default) if both 326 * attribute descriptions and values are to be returned. 327 * @return This search request. 328 * @throws UnsupportedOperationException 329 * If this search request does not permit the types-only 330 * parameter to be set. 331 */ 332 SearchRequest setTypesOnly(boolean typesOnly); 333 334}