001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * https://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.directory.api.ldap.model.message; 021 022 023import java.util.List; 024 025import org.apache.directory.api.ldap.model.exception.LdapException; 026import org.apache.directory.api.ldap.model.filter.ExprNode; 027import org.apache.directory.api.ldap.model.name.Dn; 028import org.apache.directory.api.ldap.model.schema.SchemaManager; 029 030 031/** 032 * Search request protocol message interface. 033 * 034 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a> 035 */ 036public interface SearchRequest extends ManyReplyRequest, AbandonableRequest 037{ 038 /** 039 * Different response types that a search request may return. A search 040 * request unlike any other request type can generate four different kinds 041 * of responses. It is at most required to return a done response when it is 042 * complete however before then it can return search entry, search 043 * reference, and extended responses to the client. 044 * 045 * @see #getResponseTypes() 046 */ 047 MessageTypeEnum[] RESPONSE_TYPES = 048 { 049 MessageTypeEnum.SEARCH_RESULT_DONE, 050 MessageTypeEnum.SEARCH_RESULT_ENTRY, 051 MessageTypeEnum.SEARCH_RESULT_REFERENCE, 052 MessageTypeEnum.EXTENDED_RESPONSE 053 }; 054 055 056 /** 057 * Gets the different response types generated by a search request. 058 * 059 * @return the RESPONSE_TYPES array 060 * @see #RESPONSE_TYPES 061 */ 062 @Override 063 MessageTypeEnum[] getResponseTypes(); 064 065 066 /** 067 * Gets the search base as a distinguished name. 068 * 069 * @return the search base 070 */ 071 Dn getBase(); 072 073 074 /** 075 * Sets the search base as a distinguished name. 076 * 077 * @param baseDn the search base 078 * @return The SearchRequest instance 079 */ 080 SearchRequest setBase( Dn baseDn ); 081 082 083 /** 084 * Gets the search scope parameter enumeration. 085 * 086 * @return the scope enumeration parameter. 087 */ 088 SearchScope getScope(); 089 090 091 /** 092 * Sets the search scope parameter enumeration. 093 * 094 * @param scope the scope enumeration parameter. 095 * @return The SearchRequest instance 096 */ 097 SearchRequest setScope( SearchScope scope ); 098 099 100 /** 101 * Gets the alias handling parameter. 102 * 103 * @return the alias handling parameter enumeration. 104 */ 105 AliasDerefMode getDerefAliases(); 106 107 108 /** 109 * Sets the alias handling parameter. 110 * 111 * @param aliasDerefAliases the alias handling parameter enumeration. 112 * @return The SearchRequest instance 113 */ 114 SearchRequest setDerefAliases( AliasDerefMode aliasDerefAliases ); 115 116 117 /** 118 * A sizelimit that restricts the maximum number of entries to be returned 119 * as a result of the search. A value of 0 in this field indicates that no 120 * client-requested sizelimit restrictions are in effect for the search. 121 * Servers may enforce a maximum number of entries to return. 122 * 123 * @return search size limit. 124 */ 125 long getSizeLimit(); 126 127 128 /** 129 * Sets sizelimit that restricts the maximum number of entries to be 130 * returned as a result of the search. A value of 0 in this field indicates 131 * that no client-requested sizelimit restrictions are in effect for the 132 * search. Servers may enforce a maximum number of entries to return. 133 * 134 * @param entriesMax maximum search result entries to return. 135 * @return The SearchRequest instance 136 */ 137 SearchRequest setSizeLimit( long entriesMax ); 138 139 140 /** 141 * Gets the timelimit that restricts the maximum time (in seconds) allowed 142 * for a search. A value of 0 in this field indicates that no client- 143 * requested timelimit restrictions are in effect for the search. 144 * 145 * @return the search time limit in seconds. 146 */ 147 int getTimeLimit(); 148 149 150 /** 151 * Sets the timelimit that restricts the maximum time (in seconds) allowed 152 * for a search. A value of 0 in this field indicates that no client- 153 * requested timelimit restrictions are in effect for the search. 154 * 155 * @param secondsMax the search time limit in seconds. 156 * @return The SearchRequest instance 157 */ 158 SearchRequest setTimeLimit( int secondsMax ); 159 160 161 /** 162 * An indicator as to whether search results will contain both attribute 163 * types and values, or just attribute types. Setting this field to TRUE 164 * causes only attribute types (no values) to be returned. Setting this 165 * field to FALSE causes both attribute types and values to be returned. 166 * 167 * @return true for only types, false for types and values. 168 */ 169 boolean getTypesOnly(); 170 171 172 /** 173 * An indicator as to whether search results will contain both attribute 174 * types and values, or just attribute types. Setting this field to TRUE 175 * causes only attribute types (no values) to be returned. Setting this 176 * field to FALSE causes both attribute types and values to be returned. 177 * 178 * @param typesOnly true for only types, false for types and values. 179 * @return The SearchRequest instance 180 */ 181 SearchRequest setTypesOnly( boolean typesOnly ); 182 183 184 /** 185 * Gets the search filter associated with this search request. 186 * 187 * @return the expression node for the root of the filter expression tree. 188 */ 189 ExprNode getFilter(); 190 191 192 /** 193 * Sets the search filter associated with this search request. 194 * 195 * @param filter the expression node for the root of the filter expression tree. 196 * @return The SearchRequest instance 197 */ 198 SearchRequest setFilter( ExprNode filter ); 199 200 201 /** 202 * Sets the search filter associated with this search request. 203 * 204 * @param filter the expression node for the root of the filter expression tree. 205 * @return The SearchRequest instance 206 * @throws LdapException If the filter can't be added 207 */ 208 SearchRequest setFilter( String filter ) throws LdapException; 209 210 211 /** 212 * Sets the search filter associated with this search request. 213 * 214 * @param schemaManager the SchemaManager instance 215 * @param filter the expression node for the root of the filter expression tree. 216 * @return The SearchRequest instance 217 * @throws LdapException If the filter can't be added 218 */ 219 SearchRequest setFilter( SchemaManager schemaManager, String filter ) throws LdapException; 220 221 222 /** 223 * Gets a list of the attributes to be returned from each entry which 224 * matches the search filter. There are two special values which may be 225 * used: an empty list with no attributes, and the attribute description 226 * string "*". Both of these signify that all user attributes are to be 227 * returned. (The "*" allows the client to request all user attributes in 228 * addition to specific operational attributes). Attributes MUST be named at 229 * most once in the list, and are returned at most once in an entry. If 230 * there are attribute descriptions in the list which are not recognized, 231 * they are ignored by the server. If the client does not want any 232 * attributes returned, it can specify a list containing only the attribute 233 * with OID "1.1". This OID was chosen arbitrarily and does not correspond 234 * to any attribute in use. Client implementors should note that even if all 235 * user attributes are requested, some attributes of the entry may not be 236 * included in search results due to access control or other restrictions. 237 * Furthermore, servers will not return operational attributes, such as 238 * objectClasses or attributeTypes, unless they are listed by name, since 239 * there may be extremely large number of values for certain operational 240 * attributes. 241 * 242 * @return the attributes to return for this request 243 */ 244 List<String> getAttributes(); 245 246 247 /** 248 * Adds some attributes to the set of entry attributes to return. 249 * 250 * @param attributes the attributes description or identifier. 251 * @return The SearchRequest instance 252 */ 253 SearchRequest addAttributes( String... attributes ); 254 255 256 /** 257 * Removes an attribute to the set of entry attributes to return. 258 * 259 * @param attribute the attribute description or identifier. 260 * @return The SearchRequest instance 261 */ 262 SearchRequest removeAttribute( String attribute ); 263 264 265 /** 266 * {@inheritDoc} 267 */ 268 @Override 269 SearchRequest setMessageId( int messageId ); 270 271 272 /** 273 * {@inheritDoc} 274 */ 275 @Override 276 SearchRequest addControl( Control control ); 277 278 279 /** 280 * {@inheritDoc} 281 */ 282 @Override 283 SearchRequest addAllControls( Control[] controls ); 284 285 286 /** 287 * {@inheritDoc} 288 */ 289 @Override 290 SearchRequest removeControl( Control control ); 291 292 293 /** 294 * Tells the client if it should follow referrals instead of throwing exceptions 295 * @return true if we should follow the referrals 296 */ 297 boolean isFollowReferrals(); 298 299 300 /** 301 * Tells the client to follow referrals instead of throwing exceptions 302 * @return The SearchRequest instance 303 */ 304 SearchRequest followReferrals(); 305 306 307 /** 308 * Tells the client if it should ignore referrals instead of throwing exceptions 309 * @return true if we should ignore the referrals 310 */ 311 boolean isIgnoreReferrals(); 312 313 314 /** 315 * Tells the client to ignore referrals instead of throwing exceptions. The entry 316 * will contain the referral attributeType with the link. 317 * 318 * @return The SearchRequest instance 319 */ 320 SearchRequest ignoreReferrals(); 321}