1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.ldap.client.api;
21
22
23 import java.io.IOException;
24
25 import org.apache.directory.api.ldap.model.entry.Entry;
26 import org.apache.directory.api.ldap.model.exception.LdapException;
27 import org.apache.directory.api.ldap.model.message.AddRequest;
28 import org.apache.directory.api.ldap.model.message.BindRequest;
29 import org.apache.directory.api.ldap.model.message.CompareRequest;
30 import org.apache.directory.api.ldap.model.message.DeleteRequest;
31 import org.apache.directory.api.ldap.model.message.ExtendedRequest;
32 import org.apache.directory.api.ldap.model.message.ModifyDnRequest;
33 import org.apache.directory.api.ldap.model.message.ModifyRequest;
34 import org.apache.directory.api.ldap.model.message.SearchRequest;
35 import org.apache.directory.api.ldap.model.message.SearchScope;
36 import org.apache.directory.api.ldap.model.name.Dn;
37 import org.apache.directory.ldap.client.api.future.AddFuture;
38 import org.apache.directory.ldap.client.api.future.BindFuture;
39 import org.apache.directory.ldap.client.api.future.CompareFuture;
40 import org.apache.directory.ldap.client.api.future.DeleteFuture;
41 import org.apache.directory.ldap.client.api.future.ExtendedFuture;
42 import org.apache.directory.ldap.client.api.future.ModifyDnFuture;
43 import org.apache.directory.ldap.client.api.future.ModifyFuture;
44 import org.apache.directory.ldap.client.api.future.SearchFuture;
45
46
47 /**
48 * Root interface for all asynchronous LDAP connections.
49 *
50 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
51 */
52 public interface LdapAsyncConnection extends LdapConnection
53 {
54
55 /**
56 * Add an entry to the server asynchronously. This is a non blocking add :
57 * the user has to get for the response from the returned Future.
58 *
59 * @param entry The entry to add
60 * @return the add operation's future
61 * @throws LdapException if some error occurred
62 */
63 AddFuture addAsync( Entry entry ) throws LdapException;
64
65
66 /**
67 * Add an entry present in the AddRequest to the server.
68 *
69 * @param addRequest the request object containing an entry and controls(if any)
70 * @return the add operation's future
71 * @throws LdapException if some error occurred
72 */
73 AddFuture addAsync( AddRequest addRequest ) throws LdapException;
74
75
76 /**
77 * Asynchronous Bind on a server, using the LdapConnectionConfig informations.
78 *
79 * @return the bind operation's future
80 * @throws LdapException if some error occurred
81 * @throws IOException if some IO error occurred
82 */
83 BindFuture bindAsync() throws LdapException, IOException;
84
85
86 /**
87 * Anonymous asynchronous Bind on a server.
88 *
89 * @return the bind operation's future
90 * @throws LdapException if some error occurred
91 * @throws IOException if some IO error occurred
92 */
93 BindFuture anonymousBindAsync() throws LdapException, IOException;
94
95
96 /**
97 * Simple asynchronous Bind on a server.
98 *
99 * @param name The name we use to authenticate the user, it must be a valid Dn
100 * @param credentials The password, it can't be null
101 * @return the bind operation's future
102 * @throws LdapException if some error occurred
103 * @throws IOException if some IO error occurred
104 */
105 BindFuture bindAsync( String name, String credentials ) throws LdapException, IOException;
106
107
108 /**
109 * Simple asynchronous Bind on a server.
110 *
111 * @param name The name we use to authenticate the user, it must be a valid Dn
112 * @param credentials The password, it can't be null
113 * @return the bind operation's future
114 * @throws LdapException if some error occurred
115 * @throws IOException if some IO error occurred
116 */
117 BindFuture bindAsync( Dn name, String credentials ) throws LdapException, IOException;
118
119
120 /**
121 * Do an asynchronous bind, based on a BindRequest.
122 *
123 * @param bindRequest The BindRequest to send
124 * @return the bind operation's future
125 * @throws LdapException if some error occurred
126 * @throws IOException if some IO error occurred
127 */
128 BindFuture bindAsync( BindRequest bindRequest ) throws LdapException, IOException;
129
130
131 /**
132 * Do an asynchronous search, on the base object, using the given filter. The
133 * SearchRequest parameters default to :
134 * <pre>
135 * Scope : ONE
136 * DerefAlias : ALWAYS
137 * SizeLimit : none
138 * TimeLimit : none
139 * TypesOnly : false
140 * Attributes : all the user's attributes.
141 * This method is blocking.
142 * </pre>
143 *
144 * @param baseDn The base for the search, it must be a valid Dn, and can't be emtpy
145 * @param filter The filter to use for this search, it can't be empty
146 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE
147 * @param attributes The attributes for this search
148 * @return the search operation's future
149 * @throws org.apache.directory.api.ldap.model.exception.LdapException if some error occurred
150 */
151 SearchFuture searchAsync( String baseDn, String filter, SearchScope scope, String... attributes )
152 throws LdapException;
153
154
155 /**
156 * Do an asynchronous search, on the base object, using the given filter. The
157 * SearchRequest parameters default to :
158 * <pre>
159 * Scope : ONE
160 * DerefAlias : ALWAYS
161 * SizeLimit : none
162 * TimeLimit : none
163 * TypesOnly : false
164 * Attributes : all the user's attributes.
165 * This method is blocking.
166 * </pre>
167 *
168 * @param baseDn The base for the search, it must be a valid Dn, and can't be empty
169 * @param filter The filter to use for this search, it can't be empty
170 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE
171 * @param attributes The attributes for this search
172 * @return the search operation's future
173 * @throws LdapException if some error occurred
174 */
175 SearchFuture searchAsync( Dn baseDn, String filter, SearchScope scope, String... attributes )
176 throws LdapException;
177
178
179 /**
180 * Do a search, on the base object, using the given filter. The
181 * SearchRequest parameters default to :
182 * <pre>
183 * Scope : ONE
184 * DerefAlias : ALWAYS
185 * SizeLimit : none
186 * TimeLimit : none
187 * TypesOnly : false
188 * Attributes : all the user's attributes.
189 * This method is blocking.
190 * </pre>
191 *
192 * @param searchRequest The search request to send to the server
193 * @return the search operation's future
194 * @throws LdapException if some error occurred
195 */
196 SearchFuture searchAsync( SearchRequest searchRequest ) throws LdapException;
197
198
199 /**
200 * Performs an asynchronous modify operation based on the modifications present in
201 * the ModifyRequest.
202 *
203 * @param modRequest the request for modify operation
204 * @return the modify operation's future
205 * @throws LdapException in case of modify operation failure or timeout happens
206 */
207 ModifyFuture modifyAsync( ModifyRequest modRequest ) throws LdapException;
208
209
210 /**
211 * Performs the modifyDn operation based on the given ModifyDnRequest.
212 *
213 * @param modDnRequest the request
214 * @return modifyDn operation's future
215 * @throws LdapException if some error occurred
216 */
217 ModifyDnFuture modifyDnAsync( ModifyDnRequest modDnRequest ) throws LdapException;
218
219
220 /**
221 * Performs an asynchronous delete operation based on the delete request object.
222 *
223 * @param delRequest the delete operation's request
224 * @return delete operation's future
225 * @throws LdapException If the Dn is not valid or if the deletion failed
226 */
227 DeleteFuture deleteAsync( DeleteRequest delRequest ) throws LdapException;
228
229
230 /**
231 * Asynchronously compares an entry's attribute's value with that of the given value
232 *
233 * @param compareRequest the CompareRequest which contains the target Dn, attribute name and value
234 * @return compare operation's future
235 * @throws LdapException if some error occurred
236 */
237 CompareFuture compareAsync( CompareRequest compareRequest ) throws LdapException;
238
239
240 /**
241 * Asynchronously requests the server to perform an extended operation based on the given request.
242 *
243 * @param extendedRequest the object containing the details of the extended operation to be performed
244 * @return extended operation's Future
245 * @throws LdapException if some error occurred
246 */
247 ExtendedFuture extendedAsync( ExtendedRequest extendedRequest ) throws LdapException;
248
249
250 /**
251 * Configuration of LdapNetworkConnection
252 *
253 * @return the configuration of the LDAP connection
254 */
255 LdapConnectionConfig getConfig();
256 }