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    }