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;
021
022
023 import java.util.List;
024
025 import org.apache.directory.shared.ldap.filter.ExprNode;
026 import org.apache.directory.shared.ldap.filter.SearchScope;
027 import org.apache.directory.shared.ldap.name.LdapDN;
028
029
030 /**
031 * Search request protocol message interface.
032 *
033 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
034 * @version $Rev: 764131 $
035 */
036 public interface InternalSearchRequest extends ManyReplyRequest, InternalAbandonableRequest
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 { InternalSearchResponseDone.TYPE, InternalSearchResponseEntry.TYPE, InternalSearchResponseReference.TYPE, InternalExtendedResponse.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 LdapDN getBase();
066
067
068 /**
069 * Sets the search base as a distinguished name.
070 *
071 * @param baseDn the search base
072 */
073 void setBase( LdapDN baseDn );
074
075
076 /**
077 * Gets the search scope parameter enumeration.
078 *
079 * @return the scope enumeration parameter.
080 */
081 SearchScope getScope();
082
083
084 /**
085 * Sets the search scope parameter enumeration.
086 *
087 * @param scope the scope enumeration parameter.
088 */
089 void setScope( SearchScope scope );
090
091
092 /**
093 * Gets the alias handling parameter.
094 *
095 * @return the alias handling parameter enumeration.
096 */
097 AliasDerefMode getDerefAliases();
098
099
100 /**
101 * Sets the alias handling parameter.
102 *
103 * @param aliasDerefAliases
104 * the alias handling parameter enumeration.
105 */
106 void setDerefAliases( AliasDerefMode aliasDerefAliases );
107
108
109 /**
110 * A sizelimit that restricts the maximum number of entries to be returned
111 * as a result of the search. A value of 0 in this field indicates that no
112 * client-requested sizelimit restrictions are in effect for the search.
113 * Servers may enforce a maximum number of entries to return.
114 *
115 * @return search size limit.
116 */
117 int getSizeLimit();
118
119
120 /**
121 * Sets sizelimit that restricts the maximum number of entries to be
122 * returned as a result of the search. A value of 0 in this field indicates
123 * that no client-requested sizelimit restrictions are in effect for the
124 * search. Servers may enforce a maximum number of entries to return.
125 *
126 * @param entriesMax
127 * maximum search result entries to return.
128 */
129 void setSizeLimit( int entriesMax );
130
131
132 /**
133 * Gets the timelimit that restricts the maximum time (in seconds) allowed
134 * for a search. A value of 0 in this field indicates that no client-
135 * requested timelimit restrictions are in effect for the search.
136 *
137 * @return the search time limit in seconds.
138 */
139 int getTimeLimit();
140
141
142 /**
143 * Sets the timelimit that restricts the maximum time (in seconds) allowed
144 * for a search. A value of 0 in this field indicates that no client-
145 * requested timelimit restrictions are in effect for the search.
146 *
147 * @param secondsMax
148 * the search time limit in seconds.
149 */
150 void setTimeLimit( int secondsMax );
151
152
153 /**
154 * An indicator as to whether search results will contain both attribute
155 * types and values, or just attribute types. Setting this field to TRUE
156 * causes only attribute types (no values) to be returned. Setting this
157 * field to FALSE causes both attribute types and values to be returned.
158 *
159 * @return true for only types, false for types and values.
160 */
161 boolean getTypesOnly();
162
163
164 /**
165 * An indicator as to whether search results will contain both attribute
166 * types and values, or just attribute types. Setting this field to TRUE
167 * causes only attribute types (no values) to be returned. Setting this
168 * field to FALSE causes both attribute types and values to be returned.
169 *
170 * @param typesOnly
171 * true for only types, false for types and values.
172 */
173 void setTypesOnly( boolean typesOnly );
174
175
176 /**
177 * Gets the search filter associated with this search request.
178 *
179 * @return the expression node for the root of the filter expression tree.
180 */
181 ExprNode getFilter();
182
183
184 /**
185 * Sets the search filter associated with this search request.
186 *
187 * @param filter
188 * the expression node for the root of the filter expression
189 * tree.
190 */
191 void setFilter( ExprNode filter );
192
193
194 /**
195 * Gets a list of the attributes to be returned from each entry which
196 * matches the search filter. There are two special values which may be
197 * used: an empty list with no attributes, and the attribute description
198 * string "*". Both of these signify that all user attributes are to be
199 * returned. (The "*" allows the client to request all user attributes in
200 * addition to specific operational attributes). Attributes MUST be named at
201 * most once in the list, and are returned at most once in an entry. If
202 * there are attribute descriptions in the list which are not recognized,
203 * they are ignored by the server. If the client does not want any
204 * attributes returned, it can specify a list containing only the attribute
205 * with OID "1.1". This OID was chosen arbitrarily and does not correspond
206 * to any attribute in use. Client implementors should note that even if all
207 * user attributes are requested, some attributes of the entry may not be
208 * included in search results due to access control or other restrictions.
209 * Furthermore, servers will not return operational attributes, such as
210 * objectClasses or attributeTypes, unless they are listed by name, since
211 * there may be extremely large number of values for certain operational
212 * attributes.
213 *
214 * @return the attributes to return for this request
215 */
216 List<String> getAttributes();
217
218
219 /**
220 * Adds an attribute to the set of entry attributes to return.
221 *
222 * @param attribute
223 * the attribute description or identifier.
224 */
225 void addAttribute( String attribute );
226
227
228 /**
229 * Removes an attribute to the set of entry attributes to return.
230 *
231 * @param attribute
232 * the attribute description or identifier.
233 */
234 void removeAttribute( String attribute );
235 }