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 }