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 */
020 package org.apache.directory.shared.ldap.message.internal;
021
022
023 import java.util.List;
024
025 import org.apache.directory.shared.ldap.codec.MessageTypeEnum;
026 import org.apache.directory.shared.ldap.filter.ExprNode;
027 import org.apache.directory.shared.ldap.filter.SearchScope;
028 import org.apache.directory.shared.ldap.message.AliasDerefMode;
029 import org.apache.directory.shared.ldap.message.ManyReplyRequest;
030 import org.apache.directory.shared.ldap.name.DN;
031
032
033 /**
034 * Search request protocol message interface.
035 *
036 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
037 * @version $Rev: 919009 $
038 */
039 public interface InternalSearchRequest extends ManyReplyRequest, InternalAbandonableRequest
040 {
041 /**
042 * Different response types that a search request may return. A search
043 * request unlike any other request type can generate four different kinds
044 * of responses. It is at most required to return a done response when it is
045 * complete however before then it can return search entry, search
046 * reference, and extended responses to the client.
047 *
048 * @see #getResponseTypes()
049 */
050 MessageTypeEnum[] RESPONSE_TYPES =
051 {
052 InternalSearchResponseDone.TYPE,
053 InternalSearchResponseEntry.TYPE,
054 InternalSearchResponseReference.TYPE,
055 InternalExtendedResponse.TYPE
056 };
057
058
059 /**
060 * Gets the different response types generated by a search request.
061 *
062 * @return the RESPONSE_TYPES array
063 * @see #RESPONSE_TYPES
064 */
065 MessageTypeEnum[] getResponseTypes();
066
067
068 /**
069 * Gets the search base as a distinguished name.
070 *
071 * @return the search base
072 */
073 DN getBase();
074
075
076 /**
077 * Sets the search base as a distinguished name.
078 *
079 * @param baseDn the search base
080 */
081 void setBase( DN baseDn );
082
083
084 /**
085 * Gets the search scope parameter enumeration.
086 *
087 * @return the scope enumeration parameter.
088 */
089 SearchScope getScope();
090
091
092 /**
093 * Sets the search scope parameter enumeration.
094 *
095 * @param scope the scope enumeration parameter.
096 */
097 void 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
112 * the alias handling parameter enumeration.
113 */
114 void 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
135 * maximum search result entries to return.
136 */
137 void 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
156 * the search time limit in seconds.
157 */
158 void 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
179 * true for only types, false for types and values.
180 */
181 void 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
196 * the expression node for the root of the filter expression
197 * tree.
198 */
199 void setFilter( ExprNode filter );
200
201
202 /**
203 * Gets a list of the attributes to be returned from each entry which
204 * matches the search filter. There are two special values which may be
205 * used: an empty list with no attributes, and the attribute description
206 * string "*". Both of these signify that all user attributes are to be
207 * returned. (The "*" allows the client to request all user attributes in
208 * addition to specific operational attributes). Attributes MUST be named at
209 * most once in the list, and are returned at most once in an entry. If
210 * there are attribute descriptions in the list which are not recognized,
211 * they are ignored by the server. If the client does not want any
212 * attributes returned, it can specify a list containing only the attribute
213 * with OID "1.1". This OID was chosen arbitrarily and does not correspond
214 * to any attribute in use. Client implementors should note that even if all
215 * user attributes are requested, some attributes of the entry may not be
216 * included in search results due to access control or other restrictions.
217 * Furthermore, servers will not return operational attributes, such as
218 * objectClasses or attributeTypes, unless they are listed by name, since
219 * there may be extremely large number of values for certain operational
220 * attributes.
221 *
222 * @return the attributes to return for this request
223 */
224 List<String> getAttributes();
225
226
227 /**
228 * Adds an attribute to the set of entry attributes to return.
229 *
230 * @param attribute
231 * the attribute description or identifier.
232 */
233 void addAttribute( String attribute );
234
235
236 /**
237 * Removes an attribute to the set of entry attributes to return.
238 *
239 * @param attribute
240 * the attribute description or identifier.
241 */
242 void removeAttribute( String attribute );
243 }