1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package net.sf.ldaptemplate;
18
19 import java.util.List;
20
21 import javax.naming.Name;
22 import javax.naming.directory.Attributes;
23 import javax.naming.directory.ModificationItem;
24 import javax.naming.directory.SearchControls;
25
26 import org.springframework.dao.DataAccessException;
27 import org.springframework.dao.DataIntegrityViolationException;
28
29 /***
30 * Interface that specifies a basic set of LDAP operations. Implemented by
31 * LdapTemplate. Useful option to enhance testability.
32 *
33 * @author Mattias Arthursson
34 * @author Ulrik Sandberg
35 */
36 public interface LdapOperations {
37 /***
38 * Perform a search. Use this method only if especially needed - for the
39 * most cases there is an overloaded convenience method which calls this one
40 * with suitable argments. This method handles all the plumbing; getting a
41 * readonly context; looping through the NamingEnumeration and closing the
42 * context and enumeration. The actual search is delegated to the
43 * SearchExecutor and each SearchResult is passed to the CallbackHandler.
44 * Any encountered NamingException will be translated using the
45 * NamingExceptionTranslator.
46 *
47 * @param se
48 * the SearchExecutor to use for performing the actual search.
49 * @param handler
50 * the SearchResultCallbackHandler to which each found entry will
51 * be passed.
52 * @throws DataAccessException
53 * if any error occurs. Note that a NameNotFoundException will
54 * be ignored. Instead this is interpreted that no entries were
55 * found.
56 */
57 public void search(SearchExecutor se, SearchResultCallbackHandler handler)
58 throws DataAccessException;
59
60 /***
61 * Perform an operation (or series of operations) on a read-only context.
62 * This method handles the plumbing - getting a DirContext, translating any
63 * exceptions and closing the context afterwards. This method is not
64 * intended for searches; use
65 * {@link #search(SearchExecutor, SearchResultCallbackHandler)} or any of
66 * the overloaded search methods for this.
67 *
68 * @param ce
69 * the ContextExecutor to which the actual operation on the
70 * DirContext will be delegated.
71 * @return the result from the ContextExecutor's operation.
72 * @throws DataAccessException
73 * if the operation resulted in a NamingException.
74 */
75 public Object executeReadOnly(ContextExecutor ce)
76 throws DataAccessException;
77
78 /***
79 * Perform an operation (or series of operations) on a read-write context.
80 * This method handles the plumbing - getting a DirContext, translating any
81 * exceptions and closing the context afterwards.
82 *
83 * @param ce
84 * the ContextExecutor to which the actual operation on the
85 * DirContext will be delegated.
86 * @return the result from the ContextExecutor's operation.
87 * @throws DataAccessException
88 * if the operation resulted in a NamingException.
89 */
90 public Object executeReadWrite(ContextExecutor ce)
91 throws DataAccessException;
92
93 /***
94 * Search for all objects matching the supplied filter. Each SearchResult is
95 * supplied to the specified SearchResultCallbackHandler. Use the specified
96 * SearchControls in the search. Note that if you are using a ContextMapper,
97 * the returningObjFlag needs to be set to true.
98 *
99 * @param base
100 * The base DN where the search should begin.
101 * @param filter
102 * the filter to use in the search.
103 * @param controls
104 * the SearchControls to use in the search.
105 * @param handler
106 * the SearchResultCallbackHandler to supply the SearchResults
107 * to.
108 */
109 public void search(Name base, String filter, SearchControls controls,
110 SearchResultCallbackHandler handler);
111
112 /***
113 * Search for all objects matching the supplied filter. Each SearchResult is
114 * supplied to the specified SearchResultCallbackHandler. Use the specified
115 * SearchControls in the search. Note that if you are using a ContextMapper,
116 * the returningObjFlag needs to be set to true.
117 *
118 * @param base
119 * The base DN where the search should begin.
120 * @param filter
121 * the filter to use in the search.
122 * @param controls
123 * the SearchControls to use in the search.
124 * @param handler
125 * the SearchResultCallbackHandler to supply the SearchResults
126 * to.
127 */
128 public void search(String base, String filter, SearchControls controls,
129 SearchResultCallbackHandler handler);
130
131 /***
132 * Search for all objects matching the supplied filter. Each SearchResult is
133 * supplied to the specified SearchResultCallbackHandler. Use the specified
134 * search scope and return objects flag in search controls.
135 *
136 * @param base
137 * The base DN where the search should begin.
138 * @param filter
139 * the filter to use in the search.
140 * @param searchScope
141 * the search scope to set in SearchControls.
142 * @param returningObjFlag
143 * whether the bound object should be returned in search results.
144 * @param handler
145 * the SearchResultCallbackHandler to supply the SearchResults
146 * to.
147 * @throws DataAccessException
148 * if any error occurs. Note that a NameNotFoundException will
149 * be ignored. Instead this is interpreted that no entries were
150 * found.
151 */
152 public void search(Name base, String filter, int searchScope,
153 boolean returningObjFlag, SearchResultCallbackHandler handler)
154 throws DataAccessException;
155
156 /***
157 * Search for all objects matching the supplied filter. Each SearchResult is
158 * supplied to the specified SearchResultCallbackHandler. Use the specified
159 * search scope and return objects flag in search controls.
160 *
161 * @param base
162 * The base DN where the search should begin.
163 * @param filter
164 * the filter to use in the search.
165 * @param searchScope
166 * the search scope to set in SearchControls.
167 * @param returningObjFlag
168 * whether the bound object should be returned in search results.
169 * @param handler
170 * the SearchResultCallbackHandler to supply the SearchResults
171 * to.
172 * @throws DataAccessException
173 * if any error occurs. Note that a NameNotFoundException will
174 * be ignored. Instead this is interpreted that no entries were
175 * found.
176 */
177 public void search(String base, String filter, int searchScope,
178 boolean returningObjFlag, SearchResultCallbackHandler handler)
179 throws DataAccessException;
180
181 /***
182 * Search for all objects matching the supplied filter. Each SearchResult is
183 * supplied to the specified SearchResultCallbackHandler. The default Search
184 * scope (SearchControls.SUBTREE_SCOPE) will be used and the returnObjects
185 * flag will be set to false.
186 *
187 * @param base
188 * The base DN where the search should begin.
189 * @param filter
190 * the filter to use in the search.
191 * @param handler
192 * the SearchResultCallbackHandler to supply the SearchResults
193 * to.
194 * @throws DataAccessException
195 * if any error occurs. Note that a NameNotFoundException will
196 * be ignored. Instead this is interpreted that no entries were
197 * found.
198 */
199 public void search(Name base, String filter,
200 SearchResultCallbackHandler handler) throws DataAccessException;
201
202 /***
203 * Search for all objects matching the supplied filter. Each SearchResult is
204 * supplied to the specified SearchResultCallbackHandler. The default Search
205 * scope (SearchControls.SUBTREE_SCOPE) will be used and no the
206 * returnObjects will be set to false.
207 *
208 * @param base
209 * The base DN where the search should begin.
210 * @param filter
211 * the filter to use in the search.
212 * @param handler
213 * the SearchResultCallbackHandler to supply the SearchResults
214 * to.
215 * @throws DataAccessException
216 * if any error occurs. Note that a NameNotFoundException will
217 * be ignored. Instead this is interpreted that no entries were
218 * found.
219 */
220 public void search(String base, String filter,
221 SearchResultCallbackHandler handler) throws DataAccessException;
222
223 /***
224 * Search for all objects matching the supplied filter. The Attributes in
225 * each SearchResult is supplied to the specified AttributesMapper.
226 *
227 * @param base
228 * The base DN where the search should begin.
229 * @param filter
230 * the filter to use in the search.
231 * @param searchScope
232 * the search scope to set in SearchControls.
233 * @param mapper
234 * the AttributesMapper to use for translating each entry.
235 * @return a List containing all entries received from the AttributesMapper.
236 * @throws DataAccessException
237 * if any error occurs. Note that a NameNotFoundException will
238 * be ignored. Instead this is interpreted that no entries were
239 * found.
240 */
241 public List search(Name base, String filter, int searchScope,
242 AttributesMapper mapper) throws DataAccessException;
243
244 /***
245 * Search for all objects matching the supplied filter. The Attributes in
246 * each SearchResult is supplied to the specified AttributesMapper.
247 *
248 * @param base
249 * The base DN where the search should begin.
250 * @param filter
251 * the filter to use in the search.
252 * @param searchScope
253 * the search scope to set in SearchControls.
254 * @param mapper
255 * the AttributesMapper to use for translating each entry.
256 * @return a List containing all entries received from the AttributesMapper.
257 * @throws DataAccessException
258 * if any error occurs. Note that a NameNotFoundException will
259 * be ignored. Instead this is interpreted that no entries were
260 * found.
261 */
262 public List search(String base, String filter, int searchScope,
263 AttributesMapper mapper) throws DataAccessException;
264
265 /***
266 * Search for all objects matching the supplied filter. The Attributes in
267 * each SearchResult is supplied to the specified AttributesMapper. The
268 * default seach scope will be used.
269 *
270 * @param base
271 * The base DN where the search should begin.
272 * @param filter
273 * the filter to use in the search.
274 * @param mapper
275 * the AttributesMapper to use for translating each entry.
276 * @return a List containing all entries received from the AttributesMapper.
277 * @throws DataAccessException
278 * if any error occurs. Note that a NameNotFoundException will
279 * be ignored. Instead this is interpreted that no entries were
280 * found.
281 */
282 public List search(Name base, String filter, AttributesMapper mapper)
283 throws DataAccessException;
284
285 /***
286 * Search for all objects matching the supplied filter. The Attributes in
287 * each SearchResult is supplied to the specified AttributesMapper. The
288 * default seach scope will be used.
289 *
290 * @param base
291 * The base DN where the search should begin.
292 * @param filter
293 * the filter to use in the search.
294 * @param mapper
295 * the AttributesMapper to use for translating each entry.
296 * @return a List containing all entries received from the AttributesMapper.
297 * @throws DataAccessException
298 * if any error occurs. Note that a NameNotFoundException will
299 * be ignored. Instead this is interpreted that no entries were
300 * found.
301 */
302 public List search(String base, String filter, AttributesMapper mapper)
303 throws DataAccessException;
304
305 /***
306 * Search for all objects matching the supplied filter. The Object returned
307 * in each SearchResult is supplied to the specified ContextMapper.
308 *
309 * @param base
310 * The base DN where the search should begin.
311 * @param filter
312 * the filter to use in the search.
313 * @param searchScope
314 * the search scope to set in SearchControls.
315 * @param mapper
316 * the ContextMapper to use for translating each entry.
317 * @return a List containing all entries received from the ContextMapper.
318 * @throws DataAccessException
319 * if any error occurs. Note that a NameNotFoundException will
320 * be ignored. Instead this is interpreted that no entries were
321 * found.
322 */
323 public List search(Name base, String filter, int searchScope,
324 ContextMapper mapper) throws DataAccessException;
325
326 /***
327 * Search for all objects matching the supplied filter. The Object returned
328 * in each SearchResult is supplied to the specified ContextMapper. The
329 * default search scope (SearchControls.SUBTREE_SCOPE) will be used.
330 *
331 * @param base
332 * The base DN where the search should begin.
333 * @param filter
334 * the filter to use in the search.
335 * @param searchScope
336 * the search scope to set in SearchControls.
337 * @param mapper
338 * the ContextMapper to use for translating each entry.
339 * @return a List containing all entries received from the ContextMapper.
340 * @throws DataAccessException
341 * if any error occurs. Note that a NameNotFoundException will
342 * be ignored. Instead this is interpreted that no entries were
343 * found.
344 */
345 public List search(String base, String filter, int searchScope,
346 ContextMapper mapper) throws DataAccessException;
347
348 /***
349 * Search for all objects matching the supplied filter. The Object returned
350 * in each SearchResult is supplied to the specified ContextMapper. The
351 * default search scope (SearchControls.SUBTREE_SCOPE) will be used.
352 *
353 * @param base
354 * The base DN where the search should begin.
355 * @param filter
356 * the filter to use in the search.
357 * @param mapper
358 * the ContextMapper to use for translating each entry.
359 * @return a List containing all entries received from the ContextMapper.
360 * @throws DataAccessException
361 * if any error occurs. Note that a NameNotFoundException will
362 * be ignored. Instead this is interpreted that no entries were
363 * found.
364 */
365 public List search(Name base, String filter, ContextMapper mapper)
366 throws DataAccessException;
367
368 /***
369 * Search for all objects matching the supplied filter. The Object returned
370 * in each SearchResult is supplied to the specified ContextMapper. The
371 * default search scope (SearchControls.SUBTREE_SCOPE) will be used.
372 *
373 * @param base
374 * The base DN where the search should begin.
375 * @param filter
376 * the filter to use in the search.
377 * @param mapper
378 * the ContextMapper to use for translating each entry.
379 * @return a List containing all entries received from the ContextMapper.
380 * @throws DataAccessException
381 * if any error occurs. Note that a NameNotFoundException will
382 * be ignored. Instead this is interpreted that no entries were
383 * found.
384 */
385 public List search(String base, String filter, ContextMapper mapper)
386 throws DataAccessException;
387
388 /***
389 * Search for all objects matching the supplied filter. The Object returned
390 * in each SearchResult is supplied to the specified ContextMapper.
391 *
392 * @param base
393 * The base DN where the search should begin.
394 * @param filter
395 * the filter to use in the search.
396 * @param controls
397 * the SearchControls to use in the search. If the returnObjFlag
398 * is not set in the SearchControls, this method will set it
399 * automatically, as this is required for the ContextMapper to
400 * work.
401 * @param mapper
402 * the ContextMapper to use for translating each entry.
403 * @return a List containing all entries received from the ContextMapper.
404 * @throws DataAccessException
405 * if any error occurs. Note that a NameNotFoundException will
406 * be ignored. Instead this is interpreted that no entries were
407 * found.
408 */
409 public List search(String base, String filter, SearchControls controls,
410 ContextMapper mapper);
411
412 /***
413 * Search for all objects matching the supplied filter. The Object returned
414 * in each SearchResult is supplied to the specified ContextMapper.
415 *
416 * @param base
417 * The base DN where the search should begin.
418 * @param filter
419 * the filter to use in the search.
420 * @param controls
421 * the SearchControls to use in the search. If the returnObjFlag
422 * is not set in the SearchControls, this method will set it
423 * automatically, as this is required for the ContextMapper to
424 * work.
425 * @param mapper
426 * the ContextMapper to use for translating each entry.
427 * @return a List containing all entries received from the ContextMapper.
428 * @throws DataAccessException
429 * if any error occurs. Note that a NameNotFoundException will
430 * be ignored. Instead this is interpreted that no entries were
431 * found.
432 */
433 public List search(Name base, String filter, SearchControls controls,
434 ContextMapper mapper);
435
436 /***
437 * Search for all objects matching the supplied filter. The Object returned
438 * in each SearchResult is supplied to the specified AttributesMapper.
439 *
440 * @param base
441 * The base DN where the search should begin.
442 * @param filter
443 * the filter to use in the search.
444 * @param controls
445 * the SearchControls to use in the search.
446 * @param mapper
447 * the AttributesMapper to use for translating each entry.
448 * @return a List containing all entries received from the ContextMapper.
449 * @throws DataAccessException
450 * if any error occurs. Note that a NameNotFoundException will
451 * be ignored. Instead this is interpreted that no entries were
452 * found.
453 */
454 public List search(String base, String filter, SearchControls controls,
455 AttributesMapper mapper);
456
457 /***
458 * Search for all objects matching the supplied filter. The Object returned
459 * in each SearchResult is supplied to the specified AttributesMapper.
460 *
461 * @param base
462 * The base DN where the search should begin.
463 * @param filter
464 * the filter to use in the search.
465 * @param controls
466 * the SearchControls to use in the search. If the returnObjFlag
467 * is not set in the SearchControls, this method will set it
468 * automatically, as this is required for the ContextMapper to
469 * work.
470 * @param mapper
471 * the AttributesMapper to use for translating each entry.
472 * @return a List containing all entries received from the ContextMapper.
473 * @throws DataAccessException
474 * if any error occurs. Note that a NameNotFoundException will
475 * be ignored. Instead this is interpreted that no entries were
476 * found.
477 */
478 public List search(Name base, String filter, SearchControls controls,
479 AttributesMapper mapper);
480
481 /***
482 * Lookup the supplied DN and return the found object. <b>WARNING</b>: This
483 * method should only be used if a DirObjectFactory has been specified on
484 * the ContextFactory. If this is not the case, you will get a new instance
485 * of the actual DirContext, which is probably not what you want. If,
486 * however this <b>is</b> what you want, be careful to close the context
487 * after you finished working with it.
488 *
489 * @param dn
490 * the distinguished name of the object to find.
491 * @return the found object.
492 * @throws DataAccessException
493 * if any error occurs.
494 */
495 public Object lookup(Name dn) throws DataAccessException;
496
497 /***
498 * Lookup the supplied DN and return the found object. <b>WARNING</b>: This
499 * method should only be used if a DirObjectFactory has been specified on
500 * the ContextFactory. If this is not the case, you will get a new instance
501 * of the actual DirContext, which is probably not what you want. If,
502 * however this <b>is</b> what you want, be careful to close the context
503 * after you finished working with it.
504 *
505 * @param dn
506 * the distinguished name of the object to find.
507 * @return the found object.
508 * @throws DataAccessException
509 * if any error occurs.
510 */
511 public Object lookup(String dn) throws DataAccessException;
512
513 /***
514 * Convenience method to get the attributes of a specified DN and
515 * automatically pass them to an AttributesMapper.
516 *
517 * @param dn
518 * the distinguished name to find.
519 * @param mapper
520 * the AttributesMapper to use for mapping the found object.
521 * @return the object returned from the mapper.
522 * @throws DataAccessException
523 * if any error occurs.
524 */
525 public Object lookup(Name dn, AttributesMapper mapper)
526 throws DataAccessException;
527
528 /***
529 * Convenience method to get the attributes of a specified DN and
530 * automatically pass them to an AttributesMapper.
531 *
532 * @param dn
533 * the distinguished name to find.
534 * @param mapper
535 * the AttributesMapper to use for mapping the found object.
536 * @return the object returned from the mapper.
537 * @throws DataAccessException
538 * if any error occurs.
539 */
540 public Object lookup(String dn, AttributesMapper mapper)
541 throws DataAccessException;
542
543 /***
544 * Convenience method to lookup a specified DN and automatically pass the
545 * found objectt to a ContextMapper.
546 *
547 * @param dn
548 * the distinguished name to find.
549 * @param mapper
550 * the ContextMapper to use for mapping the found object.
551 * @return the object returned from the mapper.
552 * @throws DataAccessException
553 * if any error occurs.
554 */
555 public Object lookup(Name dn, ContextMapper mapper)
556 throws DataAccessException;
557
558 /***
559 * Convenience method to lookup a specified DN and automatically pass the
560 * found objectt to a ContextMapper.
561 *
562 * @param dn
563 * the distinguished name to find.
564 * @param mapper
565 * the ContextMapper to use for mapping the found object.
566 * @return the object returned from the mapper.
567 * @throws DataAccessException
568 * if any error occurs.
569 */
570 public Object lookup(String dn, ContextMapper mapper)
571 throws DataAccessException;
572
573 /***
574 * Modify the distinguished name dn with the supplied ModificationItems.
575 *
576 * @param dn
577 * The distinguished name of the node to modify.
578 * @param mods
579 * the modifications to perform.
580 * @throws DataAccessException
581 * if any error occurs.
582 */
583 public void modifyAttributes(Name dn, ModificationItem[] mods)
584 throws DataAccessException;
585
586 /***
587 * Modify the distinguished name dn with the supplied ModificationItems.
588 *
589 * @param dn
590 * The distinguished name of the node to modify.
591 * @param mods
592 * the modifications to perform.
593 * @throws DataAccessException
594 * if any error occurs.
595 */
596 public void modifyAttributes(String dn, ModificationItem[] mods)
597 throws DataAccessException;
598
599 /***
600 * Bind the supplied object together with the attributes to the specified
601 * dn.
602 *
603 * @param dn
604 * the distinguished name to bind the object and attributes to.
605 * @param obj
606 * the object to bind, may be null.
607 * @param attributes
608 * the attributes to bind.
609 * @throws DataAccessException
610 * if any error occurs.
611 */
612 public void bind(Name dn, Object obj, Attributes attributes)
613 throws DataAccessException;
614
615 /***
616 * Bind the supplied object together with the attributes to the specified
617 * dn.
618 *
619 * @param dn
620 * the distinguished name to bind the object and attributes to.
621 * @param obj
622 * the object to bind, may be null.
623 * @param attributes
624 * the attributes to bind.
625 * @throws DataAccessException
626 * if any error occurs.
627 */
628 public void bind(String dn, Object obj, Attributes attributes)
629 throws DataAccessException;
630
631 /***
632 * Unbind the specified distinguished name.
633 *
634 * @param dn
635 * the distinguished name to unbind.
636 * @throws DataAccessException
637 * if any error occurs.
638 */
639 public void unbind(Name dn) throws DataAccessException;
640
641 /***
642 * Unbind the specified distinguished name.
643 *
644 * @param dn
645 * the distinguished name to unbind.
646 * @throws DataAccessException
647 * if any error occurs.
648 */
649 public void unbind(String dn) throws DataAccessException;
650
651 /***
652 * Unbind the specified distinguished name.
653 *
654 * @param dn
655 * the distinguished name to unbind.
656 * @param recursive
657 * whether to unbind all subcontexts as well.
658 * @throws DataAccessException
659 * if any error occurs.
660 */
661 public void unbind(Name dn, boolean recursive) throws DataAccessException;
662
663 /***
664 * Unbind the specified distinguished name.
665 *
666 * @param dn
667 * the distinguished name to unbind.
668 * @param recursive
669 * whether to unbind all subcontexts as well.
670 * @throws DataAccessException
671 * if any error occurs.
672 */
673 public void unbind(String dn, boolean recursive) throws DataAccessException;
674
675 /***
676 * Rebind the name to the object along with the specified attributes,
677 * overwriting any previous values. This method assumes that the specified
678 * context already exists.
679 *
680 * @param dn
681 * the distinguished name to rebind.
682 * @param obj
683 * the object to bind to the DN.
684 * @param attributes
685 * the attributes to bind.
686 */
687 public void rebind(Name dn, Object obj, Attributes attributes)
688 throws DataAccessException;
689
690 /***
691 * Rebind the name to the object along with the specified attributes,
692 * overwriting any previous values. This method assumes that the specified
693 * context already exists.
694 *
695 * @param dn
696 * the distinguished name to rebind.
697 * @param obj
698 * the object to bind to the DN.
699 * @param attributes
700 * the attributes to bind.
701 */
702 public void rebind(String dn, Object obj, Attributes attributes)
703 throws DataAccessException;
704
705 /***
706 * Binds a new name to the object bound to an old name, and unbinds the old
707 * name. Both names are relative to this context. Any attributes associated
708 * with the old name become associated with the new name. Intermediate
709 * contexts of the old name are not changed.
710 *
711 * @param oldDn the name of the existing binding; may not be empty
712 * @param newDn the name of the new binding; may not be empty
713 * @throws DataIntegrityViolationException if newDn is already bound
714 */
715 public void rename(final Name oldDn, final Name newDn)
716 throws DataAccessException;
717
718 /***
719 * Binds a new name to the object bound to an old name, and unbinds the old
720 * name. See {@link #rename(Name, Name)} for details.
721 *
722 * @param oldDn the name of the existing binding; may not be empty
723 * @param newDn the name of the new binding; may not be empty
724 * @throws DataIntegrityViolationException if newDn is already bound
725 */
726 public void rename(final String oldDn, final String newDn)
727 throws DataAccessException;
728 }