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.template;
21
22
23 import java.util.List;
24
25 import org.apache.directory.api.ldap.model.entry.Attribute;
26 import org.apache.directory.api.ldap.model.message.AddRequest;
27 import org.apache.directory.api.ldap.model.message.AddResponse;
28 import org.apache.directory.api.ldap.model.message.DeleteRequest;
29 import org.apache.directory.api.ldap.model.message.DeleteResponse;
30 import org.apache.directory.api.ldap.model.message.ModifyRequest;
31 import org.apache.directory.api.ldap.model.message.ModifyResponse;
32 import org.apache.directory.api.ldap.model.message.ResultResponse;
33 import org.apache.directory.api.ldap.model.message.SearchRequest;
34 import org.apache.directory.api.ldap.model.message.SearchScope;
35 import org.apache.directory.api.ldap.model.name.Dn;
36 import org.apache.directory.ldap.client.api.search.FilterBuilder;
37 import org.apache.directory.ldap.client.template.exception.PasswordException;
38
39
40 /**
41 * Specifies the set of operations available on
42 * {@link org.apache.directory.ldap.client.template.LdapConnectionTemplate
43 * LdapConnectionTemplate}. This interface can be useful for unit testing
44 * in order to stub out methods.
45 *
46 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
47 */
48 public interface LdapConnectionOperations
49 {
50
51 /**
52 * Adds an entry specified by an AddRequest to the LDAP server.
53 *
54 * @param addRequest The request
55 * @return An AddResponse
56 */
57 AddResponse add( AddRequest addRequest );
58
59
60 /**
61 * Adds an entry specified by a Dn and an array of Attribute's to the LDAP
62 * server.
63 *
64 * @param dn The distinguished name of the new entry
65 * @param attributes The attributes of the new entry
66 * @return An AddResponse
67 */
68 AddResponse add( Dn dn, Attribute... attributes );
69
70
71 /**
72 * Adds an entry specified by a Dn, to be filled out by a RequestBuilder,
73 * to the LDAP server.
74 *
75 * @param dn The distinguished name of the new entry
76 * @param requestBuilder The request builder
77 * @return An AddResponse
78 */
79 AddResponse add( Dn dn, RequestBuilder<AddRequest> requestBuilder );
80
81
82 /**
83 * Attempts to authenticate the supplied credentials against the first
84 * entry found matching the search criteria. If authentication fails,
85 * a PasswordException is thrown. If successful, the response is
86 * checked for warnings, and if present, a PasswordWarning is returned.
87 * Otherwise, null is returned.
88 *
89 * @param baseDn The base DN from which to start the search for the user to authenticate
90 * @param filter The filter selecting the entries
91 * @param scope The scope to look from
92 * @param password The password
93 * @return A PasswordWarning or null
94 * @throws PasswordException If the authentication failed
95 * @see #authenticate(Dn, char[])
96 * @see #searchFirst(String, String, SearchScope, EntryMapper)
97 */
98 PasswordWarning authenticate( String baseDn, String filter, SearchScope scope, char[] password )
99 throws PasswordException;
100
101
102 /**
103 * Attempts to authenticate the supplied credentials against the first
104 * entry found matching the search criteria. If authentication fails,
105 * a PasswordException is thrown. If successful, the response is
106 * checked for warnings, and if present, a PasswordWarning is returned.
107 * Otherwise, null is returned.
108 *
109 * @param baseDn The base DN from which to start the search for the user to authenticate
110 * @param filter The filter selecting the entries
111 * @param scope The scope to look from
112 * @param password The password
113 * @return A PasswordWarning or null
114 * @throws PasswordException If the authentication failed
115 * @see #authenticate(Dn, char[])
116 * @see #searchFirst(Dn, String, SearchScope, EntryMapper)
117 */
118 PasswordWarning authenticate( Dn baseDn, String filter, SearchScope scope, char[] password )
119 throws PasswordException;
120
121
122 /**
123 * Attempts to authenticate the supplied credentials against the first
124 * entry found matching the search criteria. If authentication fails,
125 * a PasswordException is thrown. If successful, the response is
126 * checked for warnings, and if present, a PasswordWarning is returned.
127 * Otherwise, null is returned.
128 *
129 * @param searchRequest The SearchRequst to use to find the user to authenticate
130 * @param password The password
131 * @return A PasswordWarning or null
132 * @throws PasswordException If the authentication failed
133 * @see #authenticate(Dn, char[])
134 * @see #searchFirst(SearchRequest, EntryMapper)
135 */
136 PasswordWarning authenticate( SearchRequest searchRequest, char[] password ) throws PasswordException;
137
138
139 /**
140 * Attempts to authenticate the supplied credentials. If authentication
141 * fails, a PasswordException is thrown. If successful, the response is
142 * checked for warnings, and if present, a PasswordWarning is returned.
143 * Otherwise, null is returned.
144 *
145 * @param userDn The distinguished name of the user
146 * @param password The password
147 * @return A PasswordWarning or null
148 * @throws PasswordException If authentication fails
149 */
150 PasswordWarning authenticate( Dn userDn, char[] password ) throws PasswordException;
151
152
153 /**
154 * Deletes an entry specified by a DeleteRequest from the LDAP server.
155 *
156 * @param deleteRequest The request
157 * @return A DeleteResponse
158 */
159 DeleteResponse delete( DeleteRequest deleteRequest );
160
161
162 /**
163 * Deletes an entry specified by Dn from the LDAP server.
164 *
165 * @param dn The distinguished name of the entry
166 * @return A DeleteResponse
167 */
168 DeleteResponse delete( Dn dn );
169
170
171 /**
172 * Deletes an entry specified by Dn, and whose request is configured
173 * by a RequestBuilder, from the LDAP server.
174 *
175 * @param dn The distinguished name of the entry
176 * @param requestBuilder The RequestBuilder
177 * @return A DeleteResponse
178 */
179 DeleteResponse delete( Dn dn, RequestBuilder<DeleteRequest> requestBuilder );
180
181
182 /**
183 * Executes the <code>connectionCallback</code>, supplying it a managed
184 * connection.
185 *
186 * @param connectionCallback The callback
187 * @param <T> The type of the mapped entry
188 * @return Whatever the callback returns
189 */
190 <T> T execute( ConnectionCallback<T> connectionCallback );
191
192
193 /**
194 * Performs a lookup, and supplies the matching entry to the
195 * <code>entryMapper</code>.
196 *
197 * @param dn The distinguished name of the entry
198 * @param entryMapper The mapper from entry to model object
199 * @param <T> The type of the mapped entry
200 * @return Whatever the <code>entryMapper</code> returns
201 */
202 <T> T lookup( Dn dn, EntryMapper<T> entryMapper );
203
204
205 /**
206 * Performs a lookup, requesting <code>attributes</code>, and supplies
207 * the matching entry to the <code>entryMapper</code>.
208 *
209 * @param dn The distinguished name of the entry
210 * @param attributes The attributes to be fetched
211 * @param entryMapper The mapper from entry to model object
212 * @param <T> The type of the mapped entry
213 * @return Whatever the <code>entryMapper</code> returns
214 */
215 <T> T lookup( Dn dn, String[] attributes, EntryMapper<T> entryMapper );
216
217
218 /**
219 * Modifies the password for <code>userDn</code> to
220 * <code>newPassword</code> using the admin account.
221 *
222 * @param userDn The DN of the entry we want to modify the pwassword for
223 * @param newPassword The new password
224 * @throws PasswordException If the password change failed
225 * @see #modifyPassword(Dn, char[], char[], boolean)
226 */
227 void modifyPassword( Dn userDn, char[] newPassword )
228 throws PasswordException;
229
230
231 /**
232 * Modifies the password for <code>userDn</code> from
233 * <code>oldPassword</code> to <code>newPassword</code>.
234 *
235 * @param userDn The DN of the entry we want to modify the pwassword for
236 * @param oldPassword The old password
237 * @param newPassword The new password
238 * @throws PasswordException If the password change failed
239 * @see #modifyPassword(Dn, char[], char[], boolean)
240 */
241 void modifyPassword( Dn userDn, char[] oldPassword,
242 char[] newPassword ) throws PasswordException;
243
244
245 /**
246 * Modifies the password for <code>userDn</code> from
247 * <code>oldPassword</code> to <code>newPassword</code>, optionally using
248 * an admin account. If <code>asAdmin</code> is true, then the operation
249 * is performed in admin context which means <code>oldPassword</code> is
250 * may be <code>null</code>.
251 *
252 * @param userDn The distinguished name of the user
253 * @param oldPassword The users old password (optional if asAdmin is true)
254 * @param newPassword The users new password
255 * @param asAdmin If true, execute in admin context
256 * @throws PasswordException If the password modification fails
257 */
258 void modifyPassword( Dn userDn, char[] oldPassword, char[] newPassword,
259 boolean asAdmin ) throws PasswordException;
260
261
262 /**
263 * Modifies an entry specified by a ModifyRequest on the LDAP server.
264 *
265 * @param modifyRequest The request
266 * @return A ModifyResponse
267 */
268 ModifyResponse modify( ModifyRequest modifyRequest );
269
270
271 /**
272 * Modifies an entry specified by Dn, and whose request is configured
273 * by a RequestBuilder, on the LDAP server.
274 *
275 * @param dn The distinguished name of the entry
276 * @param requestBuilder The RequestBuilder
277 * @return A ModifyResponse
278 */
279 ModifyResponse modify( Dn dn, RequestBuilder<ModifyRequest> requestBuilder );
280
281
282 /**
283 * Checks the supplied response for its result code, and if not
284 * ResultCodeEnum#SUCCESS, an exception is thrown. This method is
285 * intended to be used inline:
286 *
287 * <pre>
288 * template.responseOrException( template.delete( dn ) );
289 * </pre>
290 *
291 * @param response The response to check for success
292 * @param <T> The type of response
293 * @return The supplied <code>response</code>
294 */
295 <T extends ResultResponse> T responseOrException( T response );
296
297
298 /**
299 * Searches for the entries matching the supplied criteria, feeding the
300 * result into the <code>entryMapper</code>.
301 *
302 * @param baseDn The base DN from which to start the search
303 * @param filter The filter selecting the entries
304 * @param scope The scope to look from
305 * @param entryMapper The mapper
306 * @param <T> The type of the mapped entry
307 * @return The mapped entries
308 * @see #search(SearchRequest, EntryMapper)
309 */
310 <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope,
311 EntryMapper<T> entryMapper );
312
313
314 /**
315 * Searches for the entries matching the supplied criteria, feeding the
316 * result into the <code>entryMapper</code>.
317 *
318 * @param baseDn The base DN from which to start the search
319 * @param filter The filter selecting the entries
320 * @param scope The scope to look from
321 * @param entryMapper The mapper
322 * @param <T> The type of the mapped entry
323 * @return The mapped entries
324 * @see #search(SearchRequest, EntryMapper)
325 */
326 <T> List<T> search( String baseDn, String filter, SearchScope scope,
327 EntryMapper<T> entryMapper );
328
329
330 /**
331 * Searches for the entries matching the supplied criteria, feeding the
332 * result into the <code>entryMapper</code>.
333 *
334 * @param baseDn The base DN from which to start the search
335 * @param filter The filter selecting the entries
336 * @param scope The scope to look from
337 * @param entryMapper The mapper
338 * @param <T> The type of the mapped entry
339 * @return The mapped entries
340 * @see #search(SearchRequest, EntryMapper)
341 */
342 <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope,
343 EntryMapper<T> entryMapper );
344
345
346 /**
347 * Searches for the entries matching the supplied criteria, feeding the
348 * result into the <code>entryMapper</code>.
349 *
350 * @param baseDn The base DN from which to start the search
351 * @param filter The filter selecting the entries
352 * @param scope The scope to look from
353 * @param entryMapper The mapper
354 * @param <T> The type of the mapped entry
355 * @return The mapped entries
356 * @see #search(SearchRequest, EntryMapper)
357 */
358 <T> List<T> search( Dn baseDn, String filter, SearchScope scope,
359 EntryMapper<T> entryMapper );
360
361
362 /**
363 * Searches for the entries matching the supplied criteria, feeding the
364 * result into the <code>entryMapper</code>, querying only the requested
365 * attributes.
366 *
367 * @param baseDn The base DN from which to start the search
368 * @param filter The filter selecting the entries
369 * @param scope The scope to look from
370 * @param attributes The list of AttributeType to return
371 * @param entryMapper The mapper
372 * @param <T> The type of the mapped entry
373 * @return The mapped entries
374 * @see #search(SearchRequest, EntryMapper)
375 */
376 <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope,
377 String[] attributes, EntryMapper<T> entryMapper );
378
379
380 /**
381 * Searches for the entries matching the supplied criteria, feeding the
382 * result into the <code>entryMapper</code>, querying only the requested
383 * attributes.
384 *
385 * @param baseDn The base DN from which to start the search
386 * @param filter The filter selecting the entries
387 * @param scope The scope to look from
388 * @param attributes The list of AttributeType to return
389 * @param entryMapper The mapper
390 * @param <T> The type of the mapped entry
391 * @return The mapped entries
392 * @see #search(SearchRequest, EntryMapper)
393 */
394 <T> List<T> search( String baseDn, String filter, SearchScope scope,
395 String[] attributes, EntryMapper<T> entryMapper );
396
397
398 /**
399 * Searches for the entries matching the supplied criteria, feeding the
400 * result into the <code>entryMapper</code>, querying only the requested
401 * attributes.
402 *
403 * @param baseDn The base DN from which to start the search
404 * @param filter The filter selecting the entries
405 * @param scope The scope to look from
406 * @param attributes The list of AttributeType to return
407 * @param entryMapper The mapper
408 * @param <T> The type of the mapped entry
409 * @return The mapped entries
410 * @see #search(SearchRequest, EntryMapper)
411 */
412 <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope,
413 String[] attributes, EntryMapper<T> entryMapper );
414
415
416 /**
417 * Searches for the entries matching the supplied criteria, feeding the
418 * result into the <code>entryMapper</code>, querying only the requested
419 * attributes.
420 *
421 * @param baseDn The base DN from which to start the search
422 * @param filter The filter selecting the entries
423 * @param scope The scope to look from
424 * @param attributes The list of AttributeType to return
425 * @param entryMapper The mapper
426 * @param <T> The type of the mapped entry
427 * @return The mapped entries
428 * @see #search(SearchRequest, EntryMapper)
429 */
430 <T> List<T> search( Dn baseDn, String filter, SearchScope scope,
431 String[] attributes, EntryMapper<T> entryMapper );
432
433
434 /**
435 * Searches for the entries matching the supplied
436 * <code>searchRequest</code>, feeding the result into the
437 * <code>entryMapper</code>.
438 *
439 * @param searchRequest The search request
440 * @param entryMapper The mapper
441 * @param <T> The type of the mapped entry
442 * @return The mapped entries
443 */
444 <T> List<T> search( SearchRequest searchRequest,
445 EntryMapper<T> entryMapper );
446
447
448 /**
449 * Searches for the first entry matching the supplied criteria, feeding the
450 * result into the <code>entryMapper</code>.
451 *
452 * @param baseDn The base DN from which to start the search
453 * @param filter The filter selecting the entries
454 * @param scope The scope to look from
455 * @param entryMapper The mapper
456 * @param <T> The type of the mapped entry
457 * @return The mapped entries
458 * @see #searchFirst(SearchRequest, EntryMapper)
459 */
460 <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope,
461 EntryMapper<T> entryMapper );
462
463
464 /**
465 * Searches for the first entry matching the supplied criteria, feeding the
466 * result into the <code>entryMapper</code>.
467 *
468 * @param baseDn The base DN from which to start the search
469 * @param filter The filter selecting the entries
470 * @param scope The scope to look from
471 * @param entryMapper The mapper
472 * @param <T> The type of the mapped entry
473 * @return The mapped entries
474 * @see #searchFirst(SearchRequest, EntryMapper)
475 */
476 <T> T searchFirst( String baseDn, String filter, SearchScope scope,
477 EntryMapper<T> entryMapper );
478
479
480 /**
481 * Searches for the first entry matching the supplied criteria, feeding the
482 * result into the <code>entryMapper</code>.
483 *
484 * @param baseDn The base DN from which to start the search
485 * @param filter The filter selecting the entries
486 * @param scope The scope to look from
487 * @param entryMapper The mapper
488 * @param <T> The type of the mapped entry
489 * @return The mapped entries
490 * @see #searchFirst(SearchRequest, EntryMapper)
491 */
492 <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope,
493 EntryMapper<T> entryMapper );
494
495
496 /**
497 * Searches for the first entry matching the supplied criteria, feeding the
498 * result into the <code>entryMapper</code>.
499 *
500 * @param baseDn The base DN from which to start the search
501 * @param filter The filter selecting the entries
502 * @param scope The scope to look from
503 * @param entryMapper The mapper
504 * @param <T> The type of the mapped entry
505 * @return The mapped entries
506 * @see #searchFirst(SearchRequest, EntryMapper)
507 */
508 <T> T searchFirst( Dn baseDn, String filter, SearchScope scope,
509 EntryMapper<T> entryMapper );
510
511
512 /**
513 * Searches for the first entry matching the supplied criteria, feeding the
514 * result into the <code>entryMapper</code>, querying only the requested
515 * attributes.
516 *
517 * @param baseDn The base DN from which to start the search
518 * @param filter The filter selecting the entries
519 * @param scope The scope to look from
520 * @param attributes The list of AttributeType to return
521 * @param entryMapper The mapper
522 * @param <T> The type of the mapped entry
523 * @return The mapped entries
524 * @see #searchFirst(SearchRequest, EntryMapper)
525 */
526 <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope,
527 String[] attributes, EntryMapper<T> entryMapper );
528
529
530 /**
531 * Searches for the first entry matching the supplied criteria, feeding the
532 * result into the <code>entryMapper</code>, querying only the requested
533 * attributes.
534 *
535 * @param baseDn The base DN from which to start the search
536 * @param filter The filter selecting the entries
537 * @param scope The scope to look from
538 * @param attributes The list of AttributeType to return
539 * @param entryMapper The mapper
540 * @param <T> The type of the mapped entry
541 * @return The mapped entries
542 * @see #searchFirst(SearchRequest, EntryMapper)
543 */
544 <T> T searchFirst( String baseDn, String filter, SearchScope scope,
545 String[] attributes, EntryMapper<T> entryMapper );
546
547
548 /**
549 * Searches for the first entry matching the supplied criteria, feeding the
550 * result into the <code>entryMapper</code>, querying only the requested
551 * attributes.
552 *
553 * @param baseDn The base DN from which to start the search
554 * @param filter The filter selecting the entries
555 * @param scope The scope to look from
556 * @param attributes The list of AttributeType to return
557 * @param entryMapper The mapper
558 * @param <T> The type of the mapped entry
559 * @return The mapped entries
560 * @see #searchFirst(SearchRequest, EntryMapper)
561 */
562 <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope,
563 String[] attributes, EntryMapper<T> entryMapper );
564
565
566 /**
567 * Searches for the first entry matching the supplied criteria, feeding the
568 * result into the <code>entryMapper</code>, querying only the requested
569 * attributes.
570 *
571 * @param baseDn The base DN from which to start the search
572 * @param filter The filter selecting the entries
573 * @param scope The scope to look from
574 * @param attributes The list of AttributeType to return
575 * @param entryMapper The mapper
576 * @param <T> The type of the mapped entry
577 * @return The mapped entries
578 * @see #searchFirst(SearchRequest, EntryMapper)
579 */
580 <T> T searchFirst( Dn baseDn, String filter, SearchScope scope,
581 String[] attributes, EntryMapper<T> entryMapper );
582
583
584 /**
585 * Searches for the first entry matching the supplied
586 * <code>searchRequest</code>, feeding the result into the
587 * <code>entryMapper</code>. This is basically the same as
588 * {@link #search(SearchRequest, EntryMapper)}, but is optimized by
589 * modifying the <code>searchRequest</code> to set its size limit to 1.
590 * The <code>searchRequest</code> is returned to its original size limit
591 * before this method returns (or throws an exception).
592 *
593 * @param searchRequest The search request
594 * @param entryMapper The mapper
595 * @param <T> The type of the mapped entry
596 * @return The mapped entry
597 */
598 <T> T searchFirst( SearchRequest searchRequest,
599 EntryMapper<T> entryMapper );
600
601 }