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 * http://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.shared.ldap.model.message; 021 022 023import java.util.List; 024 025import org.apache.directory.shared.ldap.model.exception.LdapException; 026import org.apache.directory.shared.ldap.model.exception.MessageException; 027import org.apache.directory.shared.ldap.model.filter.ExprNode; 028import org.apache.directory.shared.ldap.model.name.Dn; 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<SearchResultDone>, 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 { SearchResultDone.TYPE, SearchResultEntry.TYPE, SearchResultReference.TYPE, ExtendedResponse.TYPE }; 049 050 051 /** 052 * Gets the different response types generated by a search request. 053 * 054 * @return the RESPONSE_TYPES array 055 * @see #RESPONSE_TYPES 056 */ 057 MessageTypeEnum[] getResponseTypes(); 058 059 060 /** 061 * Gets the search base as a distinguished name. 062 * 063 * @return the search base 064 */ 065 Dn getBase(); 066 067 068 /** 069 * Sets the search base as a distinguished name. 070 * 071 * @param baseDn the search base 072 * @return The SearchRequest instance 073 */ 074 SearchRequest setBase( Dn baseDn ); 075 076 077 /** 078 * Gets the search scope parameter enumeration. 079 * 080 * @return the scope enumeration parameter. 081 */ 082 SearchScope getScope(); 083 084 085 /** 086 * Sets the search scope parameter enumeration. 087 * 088 * @param scope the scope enumeration parameter. 089 * @return The SearchRequest instance 090 */ 091 SearchRequest setScope( SearchScope scope ); 092 093 094 /** 095 * Gets the alias handling parameter. 096 * 097 * @return the alias handling parameter enumeration. 098 */ 099 AliasDerefMode getDerefAliases(); 100 101 102 /** 103 * Sets the alias handling parameter. 104 * 105 * @param aliasDerefAliases the alias handling parameter enumeration. 106 * @return The SearchRequest instance 107 */ 108 SearchRequest setDerefAliases( AliasDerefMode aliasDerefAliases ); 109 110 111 /** 112 * A sizelimit that restricts the maximum number of entries to be returned 113 * as a result of the search. A value of 0 in this field indicates that no 114 * client-requested sizelimit restrictions are in effect for the search. 115 * Servers may enforce a maximum number of entries to return. 116 * 117 * @return search size limit. 118 */ 119 long getSizeLimit(); 120 121 122 /** 123 * Sets sizelimit that restricts the maximum number of entries to be 124 * returned as a result of the search. A value of 0 in this field indicates 125 * that no client-requested sizelimit restrictions are in effect for the 126 * search. Servers may enforce a maximum number of entries to return. 127 * 128 * @param entriesMax maximum search result entries to return. 129 * @return The SearchRequest instance 130 */ 131 SearchRequest setSizeLimit( long entriesMax ); 132 133 134 /** 135 * Gets the timelimit that restricts the maximum time (in seconds) allowed 136 * for a search. A value of 0 in this field indicates that no client- 137 * requested timelimit restrictions are in effect for the search. 138 * 139 * @return the search time limit in seconds. 140 */ 141 int getTimeLimit(); 142 143 144 /** 145 * Sets the timelimit that restricts the maximum time (in seconds) allowed 146 * for a search. A value of 0 in this field indicates that no client- 147 * requested timelimit restrictions are in effect for the search. 148 * 149 * @param secondsMax the search time limit in seconds. 150 * @return The SearchRequest instance 151 */ 152 SearchRequest setTimeLimit( int secondsMax ); 153 154 155 /** 156 * An indicator as to whether search results will contain both attribute 157 * types and values, or just attribute types. Setting this field to TRUE 158 * causes only attribute types (no values) to be returned. Setting this 159 * field to FALSE causes both attribute types and values to be returned. 160 * 161 * @return true for only types, false for types and values. 162 */ 163 boolean getTypesOnly(); 164 165 166 /** 167 * An indicator as to whether search results will contain both attribute 168 * types and values, or just attribute types. Setting this field to TRUE 169 * causes only attribute types (no values) to be returned. Setting this 170 * field to FALSE causes both attribute types and values to be returned. 171 * 172 * @param typesOnly true for only types, false for types and values. 173 * @return The SearchRequest instance 174 */ 175 SearchRequest setTypesOnly( boolean typesOnly ); 176 177 178 /** 179 * Gets the search filter associated with this search request. 180 * 181 * @return the expression node for the root of the filter expression tree. 182 */ 183 ExprNode getFilter(); 184 185 186 /** 187 * Sets the search filter associated with this search request. 188 * 189 * @param filter the expression node for the root of the filter expression tree. 190 * @return The SearchRequest instance 191 */ 192 SearchRequest setFilter( ExprNode filter ); 193 194 195 /** 196 * Sets the search filter associated with this search request. 197 * 198 * @param filter the expression node for the root of the filter expression tree. 199 * @return The SearchRequest instance 200 */ 201 SearchRequest setFilter( String filter ) throws LdapException; 202 203 204 /** 205 * Gets a list of the attributes to be returned from each entry which 206 * matches the search filter. There are two special values which may be 207 * used: an empty list with no attributes, and the attribute description 208 * string "*". Both of these signify that all user attributes are to be 209 * returned. (The "*" allows the client to request all user attributes in 210 * addition to specific operational attributes). Attributes MUST be named at 211 * most once in the list, and are returned at most once in an entry. If 212 * there are attribute descriptions in the list which are not recognized, 213 * they are ignored by the server. If the client does not want any 214 * attributes returned, it can specify a list containing only the attribute 215 * with OID "1.1". This OID was chosen arbitrarily and does not correspond 216 * to any attribute in use. Client implementors should note that even if all 217 * user attributes are requested, some attributes of the entry may not be 218 * included in search results due to access control or other restrictions. 219 * Furthermore, servers will not return operational attributes, such as 220 * objectClasses or attributeTypes, unless they are listed by name, since 221 * there may be extremely large number of values for certain operational 222 * attributes. 223 * 224 * @return the attributes to return for this request 225 */ 226 List<String> getAttributes(); 227 228 229 /** 230 * Adds some attributes to the set of entry attributes to return. 231 * 232 * @param attributes the attributes description or identifier. 233 * @return The SearchRequest instance 234 */ 235 SearchRequest addAttributes( String... attributes ); 236 237 238 /** 239 * Removes an attribute to the set of entry attributes to return. 240 * 241 * @param attribute the attribute description or identifier. 242 * @return The SearchRequest instance 243 */ 244 SearchRequest removeAttribute( String attribute ); 245 246 247 /** 248 * {@inheritDoc} 249 */ 250 SearchRequest setMessageId( int messageId ); 251 252 253 /** 254 * {@inheritDoc} 255 */ 256 SearchRequest addControl( Control control ) throws MessageException; 257 258 259 /** 260 * {@inheritDoc} 261 */ 262 SearchRequest addAllControls( Control[] controls ) throws MessageException; 263 264 265 /** 266 * {@inheritDoc} 267 */ 268 SearchRequest removeControl( Control control ) throws MessageException; 269}