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