1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19 package org.apache.naming.resources;
20
21 import java.util.Hashtable;
22
23 import javax.naming.Context;
24 import javax.naming.Name;
25 import javax.naming.NameParser;
26 import javax.naming.NamingEnumeration;
27 import javax.naming.NamingException;
28 import javax.naming.directory.Attributes;
29 import javax.naming.directory.DirContext;
30 import javax.naming.directory.ModificationItem;
31 import javax.naming.directory.SearchControls;
32
33 import org.apache.naming.NameParserImpl;
34 import org.apache.naming.StringManager;
35
36 /**
37 * Directory Context implementation helper class.
38 *
39 * @author Remy Maucherat
40 * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
41 */
42
43 public abstract class BaseDirContext implements DirContext {
44
45
46 // -------------------------------------------------------------- Constants
47
48
49 // ----------------------------------------------------------- Constructors
50
51
52 /**
53 * Builds a base directory context.
54 */
55 public BaseDirContext() {
56 this.env = new Hashtable();
57 }
58
59
60 /**
61 * Builds a base directory context using the given environment.
62 */
63 public BaseDirContext(Hashtable env) {
64 this.env = env;
65 }
66
67
68 // ----------------------------------------------------- Instance Variables
69
70
71 /**
72 * The document base path.
73 */
74 protected String docBase = null;
75
76
77 /**
78 * Environment.
79 */
80 protected Hashtable env;
81
82
83 /**
84 * The string manager for this package.
85 */
86 protected StringManager sm = StringManager.getManager(Constants.Package);
87
88
89 /**
90 * Name parser for this context.
91 */
92 protected final NameParser nameParser = new NameParserImpl();
93
94
95 /**
96 * Cached.
97 */
98 protected boolean cached = true;
99
100
101 /**
102 * Cache TTL.
103 */
104 protected int cacheTTL = 5000; // 5s
105
106
107 /**
108 * Max size of resources which will have their content cached.
109 */
110 protected int cacheMaxSize = 10240; // 10 MB
111
112
113 // ------------------------------------------------------------- Properties
114
115
116 /**
117 * Return the document root for this component.
118 */
119 public String getDocBase() {
120 return (this.docBase);
121 }
122
123
124 /**
125 * Set the document root for this component.
126 *
127 * @param docBase The new document root
128 *
129 * @exception IllegalArgumentException if the specified value is not
130 * supported by this implementation
131 * @exception IllegalArgumentException if this would create a
132 * malformed URL
133 */
134 public void setDocBase(String docBase) {
135
136 // Validate the format of the proposed document root
137 if (docBase == null)
138 throw new IllegalArgumentException
139 (sm.getString("resources.null"));
140
141 // Change the document root property
142 this.docBase = docBase;
143
144 }
145
146
147 /**
148 * Set cached.
149 */
150 public void setCached(boolean cached) {
151 this.cached = cached;
152 }
153
154
155 /**
156 * Is cached ?
157 */
158 public boolean isCached() {
159 return cached;
160 }
161
162
163 /**
164 * Set cache TTL.
165 */
166 public void setCacheTTL(int cacheTTL) {
167 this.cacheTTL = cacheTTL;
168 }
169
170
171 /**
172 * Get cache TTL.
173 */
174 public int getCacheTTL() {
175 return cacheTTL;
176 }
177
178
179 /**
180 * Return the maximum size of the cache in KB.
181 */
182 public int getCacheMaxSize() {
183 return cacheMaxSize;
184 }
185
186
187 /**
188 * Set the maximum size of the cache in KB.
189 */
190 public void setCacheMaxSize(int cacheMaxSize) {
191 this.cacheMaxSize = cacheMaxSize;
192 }
193
194
195 // --------------------------------------------------------- Public Methods
196
197
198 /**
199 * Allocate resources for this directory context.
200 */
201 public void allocate() {
202 ; // No action taken by the default implementation
203 }
204
205
206 /**
207 * Release any resources allocated for this directory context.
208 */
209 public void release() {
210 ; // No action taken by the default implementation
211 }
212
213
214 // -------------------------------------------------------- Context Methods
215
216
217 /**
218 * Retrieves the named object. If name is empty, returns a new instance
219 * of this context (which represents the same naming context as this
220 * context, but its environment may be modified independently and it may
221 * be accessed concurrently).
222 *
223 * @param name the name of the object to look up
224 * @return the object bound to name
225 * @exception NamingException if a naming exception is encountered
226 */
227 public Object lookup(Name name)
228 throws NamingException {
229 return lookup(name.toString());
230 }
231
232
233 /**
234 * Retrieves the named object.
235 *
236 * @param name the name of the object to look up
237 * @return the object bound to name
238 * @exception NamingException if a naming exception is encountered
239 */
240 public abstract Object lookup(String name)
241 throws NamingException;
242
243
244 /**
245 * Binds a name to an object. All intermediate contexts and the target
246 * context (that named by all but terminal atomic component of the name)
247 * must already exist.
248 *
249 * @param name the name to bind; may not be empty
250 * @param obj the object to bind; possibly null
251 * @exception NameAlreadyBoundException if name is already bound
252 * @exception InvalidAttributesException if object did not supply all
253 * mandatory attributes
254 * @exception NamingException if a naming exception is encountered
255 */
256 public void bind(Name name, Object obj)
257 throws NamingException {
258 bind(name.toString(), obj);
259 }
260
261
262 /**
263 * Binds a name to an object.
264 *
265 * @param name the name to bind; may not be empty
266 * @param obj the object to bind; possibly null
267 * @exception NameAlreadyBoundException if name is already bound
268 * @exception InvalidAttributesException if object did not supply all
269 * mandatory attributes
270 * @exception NamingException if a naming exception is encountered
271 */
272 public void bind(String name, Object obj)
273 throws NamingException {
274 bind(name, obj, null);
275 }
276
277
278 /**
279 * Binds a name to an object, overwriting any existing binding. All
280 * intermediate contexts and the target context (that named by all but
281 * terminal atomic component of the name) must already exist.
282 * <p>
283 * If the object is a DirContext, any existing attributes associated with
284 * the name are replaced with those of the object. Otherwise, any
285 * existing attributes associated with the name remain unchanged.
286 *
287 * @param name the name to bind; may not be empty
288 * @param obj the object to bind; possibly null
289 * @exception InvalidAttributesException if object did not supply all
290 * mandatory attributes
291 * @exception NamingException if a naming exception is encountered
292 */
293 public void rebind(Name name, Object obj)
294 throws NamingException {
295 rebind(name.toString(), obj);
296 }
297
298
299 /**
300 * Binds a name to an object, overwriting any existing binding.
301 *
302 * @param name the name to bind; may not be empty
303 * @param obj the object to bind; possibly null
304 * @exception InvalidAttributesException if object did not supply all
305 * mandatory attributes
306 * @exception NamingException if a naming exception is encountered
307 */
308 public void rebind(String name, Object obj)
309 throws NamingException {
310 rebind(name, obj, null);
311 }
312
313
314 /**
315 * Unbinds the named object. Removes the terminal atomic name in name
316 * from the target context--that named by all but the terminal atomic
317 * part of name.
318 * <p>
319 * This method is idempotent. It succeeds even if the terminal atomic
320 * name is not bound in the target context, but throws
321 * NameNotFoundException if any of the intermediate contexts do not exist.
322 *
323 * @param name the name to bind; may not be empty
324 * @exception NameNotFoundException if an intermediate context does not
325 * exist
326 * @exception NamingException if a naming exception is encountered
327 */
328 public void unbind(Name name)
329 throws NamingException {
330 unbind(name.toString());
331 }
332
333
334 /**
335 * Unbinds the named object.
336 *
337 * @param name the name to bind; may not be empty
338 * @exception NameNotFoundException if an intermediate context does not
339 * exist
340 * @exception NamingException if a naming exception is encountered
341 */
342 public abstract void unbind(String name)
343 throws NamingException;
344
345
346 /**
347 * Binds a new name to the object bound to an old name, and unbinds the
348 * old name. Both names are relative to this context. Any attributes
349 * associated with the old name become associated with the new name.
350 * Intermediate contexts of the old name are not changed.
351 *
352 * @param oldName the name of the existing binding; may not be empty
353 * @param newName the name of the new binding; may not be empty
354 * @exception NameAlreadyBoundException if newName is already bound
355 * @exception NamingException if a naming exception is encountered
356 */
357 public void rename(Name oldName, Name newName)
358 throws NamingException {
359 rename(oldName.toString(), newName.toString());
360 }
361
362
363 /**
364 * Binds a new name to the object bound to an old name, and unbinds the
365 * old name.
366 *
367 * @param oldName the name of the existing binding; may not be empty
368 * @param newName the name of the new binding; may not be empty
369 * @exception NameAlreadyBoundException if newName is already bound
370 * @exception NamingException if a naming exception is encountered
371 */
372 public abstract void rename(String oldName, String newName)
373 throws NamingException;
374
375
376 /**
377 * Enumerates the names bound in the named context, along with the class
378 * names of objects bound to them. The contents of any subcontexts are
379 * not included.
380 * <p>
381 * If a binding is added to or removed from this context, its effect on
382 * an enumeration previously returned is undefined.
383 *
384 * @param name the name of the context to list
385 * @return an enumeration of the names and class names of the bindings in
386 * this context. Each element of the enumeration is of type NameClassPair.
387 * @exception NamingException if a naming exception is encountered
388 */
389 public NamingEnumeration list(Name name)
390 throws NamingException {
391 return list(name.toString());
392 }
393
394
395 /**
396 * Enumerates the names bound in the named context, along with the class
397 * names of objects bound to them.
398 *
399 * @param name the name of the context to list
400 * @return an enumeration of the names and class names of the bindings in
401 * this context. Each element of the enumeration is of type NameClassPair.
402 * @exception NamingException if a naming exception is encountered
403 */
404 public abstract NamingEnumeration list(String name)
405 throws NamingException;
406
407
408 /**
409 * Enumerates the names bound in the named context, along with the
410 * objects bound to them. The contents of any subcontexts are not
411 * included.
412 * <p>
413 * If a binding is added to or removed from this context, its effect on
414 * an enumeration previously returned is undefined.
415 *
416 * @param name the name of the context to list
417 * @return an enumeration of the bindings in this context.
418 * Each element of the enumeration is of type Binding.
419 * @exception NamingException if a naming exception is encountered
420 */
421 public NamingEnumeration listBindings(Name name)
422 throws NamingException {
423 return listBindings(name.toString());
424 }
425
426
427 /**
428 * Enumerates the names bound in the named context, along with the
429 * objects bound to them.
430 *
431 * @param name the name of the context to list
432 * @return an enumeration of the bindings in this context.
433 * Each element of the enumeration is of type Binding.
434 * @exception NamingException if a naming exception is encountered
435 */
436 public abstract NamingEnumeration listBindings(String name)
437 throws NamingException;
438
439
440 /**
441 * Destroys the named context and removes it from the namespace. Any
442 * attributes associated with the name are also removed. Intermediate
443 * contexts are not destroyed.
444 * <p>
445 * This method is idempotent. It succeeds even if the terminal atomic
446 * name is not bound in the target context, but throws
447 * NameNotFoundException if any of the intermediate contexts do not exist.
448 *
449 * In a federated naming system, a context from one naming system may be
450 * bound to a name in another. One can subsequently look up and perform
451 * operations on the foreign context using a composite name. However, an
452 * attempt destroy the context using this composite name will fail with
453 * NotContextException, because the foreign context is not a "subcontext"
454 * of the context in which it is bound. Instead, use unbind() to remove
455 * the binding of the foreign context. Destroying the foreign context
456 * requires that the destroySubcontext() be performed on a context from
457 * the foreign context's "native" naming system.
458 *
459 * @param name the name of the context to be destroyed; may not be empty
460 * @exception NameNotFoundException if an intermediate context does not
461 * exist
462 * @exception NotContextException if the name is bound but does not name
463 * a context, or does not name a context of the appropriate type
464 */
465 public void destroySubcontext(Name name)
466 throws NamingException {
467 destroySubcontext(name.toString());
468 }
469
470
471 /**
472 * Destroys the named context and removes it from the namespace.
473 *
474 * @param name the name of the context to be destroyed; may not be empty
475 * @exception NameNotFoundException if an intermediate context does not
476 * exist
477 * @exception NotContextException if the name is bound but does not name
478 * a context, or does not name a context of the appropriate type
479 */
480 public abstract void destroySubcontext(String name)
481 throws NamingException;
482
483
484 /**
485 * Creates and binds a new context. Creates a new context with the given
486 * name and binds it in the target context (that named by all but
487 * terminal atomic component of the name). All intermediate contexts and
488 * the target context must already exist.
489 *
490 * @param name the name of the context to create; may not be empty
491 * @return the newly created context
492 * @exception NameAlreadyBoundException if name is already bound
493 * @exception InvalidAttributesException if creation of the subcontext
494 * requires specification of mandatory attributes
495 * @exception NamingException if a naming exception is encountered
496 */
497 public Context createSubcontext(Name name)
498 throws NamingException {
499 return createSubcontext(name.toString());
500 }
501
502
503 /**
504 * Creates and binds a new context.
505 *
506 * @param name the name of the context to create; may not be empty
507 * @return the newly created context
508 * @exception NameAlreadyBoundException if name is already bound
509 * @exception InvalidAttributesException if creation of the subcontext
510 * requires specification of mandatory attributes
511 * @exception NamingException if a naming exception is encountered
512 */
513 public Context createSubcontext(String name)
514 throws NamingException {
515 return createSubcontext(name, null);
516 }
517
518
519 /**
520 * Retrieves the named object, following links except for the terminal
521 * atomic component of the name. If the object bound to name is not a
522 * link, returns the object itself.
523 *
524 * @param name the name of the object to look up
525 * @return the object bound to name, not following the terminal link
526 * (if any).
527 * @exception NamingException if a naming exception is encountered
528 */
529 public Object lookupLink(Name name)
530 throws NamingException {
531 return lookupLink(name.toString());
532 }
533
534
535 /**
536 * Retrieves the named object, following links except for the terminal
537 * atomic component of the name.
538 *
539 * @param name the name of the object to look up
540 * @return the object bound to name, not following the terminal link
541 * (if any).
542 * @exception NamingException if a naming exception is encountered
543 */
544 public abstract Object lookupLink(String name)
545 throws NamingException;
546
547
548 /**
549 * Retrieves the parser associated with the named context. In a
550 * federation of namespaces, different naming systems will parse names
551 * differently. This method allows an application to get a parser for
552 * parsing names into their atomic components using the naming convention
553 * of a particular naming system. Within any single naming system,
554 * NameParser objects returned by this method must be equal (using the
555 * equals() test).
556 *
557 * @param name the name of the context from which to get the parser
558 * @return a name parser that can parse compound names into their atomic
559 * components
560 * @exception NamingException if a naming exception is encountered
561 */
562 public NameParser getNameParser(Name name)
563 throws NamingException {
564 return new NameParserImpl();
565 }
566
567
568 /**
569 * Retrieves the parser associated with the named context.
570 *
571 * @param name the name of the context from which to get the parser
572 * @return a name parser that can parse compound names into their atomic
573 * components
574 * @exception NamingException if a naming exception is encountered
575 */
576 public NameParser getNameParser(String name)
577 throws NamingException {
578 return new NameParserImpl();
579 }
580
581
582 /**
583 * Composes the name of this context with a name relative to this context.
584 * <p>
585 * Given a name (name) relative to this context, and the name (prefix)
586 * of this context relative to one of its ancestors, this method returns
587 * the composition of the two names using the syntax appropriate for the
588 * naming system(s) involved. That is, if name names an object relative
589 * to this context, the result is the name of the same object, but
590 * relative to the ancestor context. None of the names may be null.
591 *
592 * @param name a name relative to this context
593 * @param prefix the name of this context relative to one of its ancestors
594 * @return the composition of prefix and name
595 * @exception NamingException if a naming exception is encountered
596 */
597 public Name composeName(Name name, Name prefix)
598 throws NamingException {
599 prefix = (Name) prefix.clone();
600 return prefix.addAll(name);
601 }
602
603
604 /**
605 * Composes the name of this context with a name relative to this context.
606 *
607 * @param name a name relative to this context
608 * @param prefix the name of this context relative to one of its ancestors
609 * @return the composition of prefix and name
610 * @exception NamingException if a naming exception is encountered
611 */
612 public String composeName(String name, String prefix)
613 throws NamingException {
614 return prefix + "/" + name;
615 }
616
617
618 /**
619 * Adds a new environment property to the environment of this context. If
620 * the property already exists, its value is overwritten.
621 *
622 * @param propName the name of the environment property to add; may not
623 * be null
624 * @param propVal the value of the property to add; may not be null
625 * @exception NamingException if a naming exception is encountered
626 */
627 public Object addToEnvironment(String propName, Object propVal)
628 throws NamingException {
629 return env.put(propName, propVal);
630 }
631
632
633 /**
634 * Removes an environment property from the environment of this context.
635 *
636 * @param propName the name of the environment property to remove;
637 * may not be null
638 * @exception NamingException if a naming exception is encountered
639 */
640 public Object removeFromEnvironment(String propName)
641 throws NamingException {
642 return env.remove(propName);
643 }
644
645
646 /**
647 * Retrieves the environment in effect for this context. See class
648 * description for more details on environment properties.
649 * The caller should not make any changes to the object returned: their
650 * effect on the context is undefined. The environment of this context
651 * may be changed using addToEnvironment() and removeFromEnvironment().
652 *
653 * @return the environment of this context; never null
654 * @exception NamingException if a naming exception is encountered
655 */
656 public Hashtable getEnvironment()
657 throws NamingException {
658 return env;
659 }
660
661
662 /**
663 * Closes this context. This method releases this context's resources
664 * immediately, instead of waiting for them to be released automatically
665 * by the garbage collector.
666 * This method is idempotent: invoking it on a context that has already
667 * been closed has no effect. Invoking any other method on a closed
668 * context is not allowed, and results in undefined behaviour.
669 *
670 * @exception NamingException if a naming exception is encountered
671 */
672 public void close()
673 throws NamingException {
674 env.clear();
675 }
676
677
678 /**
679 * Retrieves the full name of this context within its own namespace.
680 * <p>
681 * Many naming services have a notion of a "full name" for objects in
682 * their respective namespaces. For example, an LDAP entry has a
683 * distinguished name, and a DNS record has a fully qualified name. This
684 * method allows the client application to retrieve this name. The string
685 * returned by this method is not a JNDI composite name and should not be
686 * passed directly to context methods. In naming systems for which the
687 * notion of full name does not make sense,
688 * OperationNotSupportedException is thrown.
689 *
690 * @return this context's name in its own namespace; never null
691 * @exception OperationNotSupportedException if the naming system does
692 * not have the notion of a full name
693 * @exception NamingException if a naming exception is encountered
694 */
695 public abstract String getNameInNamespace()
696 throws NamingException;
697
698
699 // ----------------------------------------------------- DirContext Methods
700
701
702 /**
703 * Retrieves all of the attributes associated with a named object.
704 *
705 * @return the set of attributes associated with name.
706 * Returns an empty attribute set if name has no attributes; never null.
707 * @param name the name of the object from which to retrieve attributes
708 * @exception NamingException if a naming exception is encountered
709 */
710 public Attributes getAttributes(Name name)
711 throws NamingException {
712 return getAttributes(name.toString());
713 }
714
715
716 /**
717 * Retrieves all of the attributes associated with a named object.
718 *
719 * @return the set of attributes associated with name
720 * @param name the name of the object from which to retrieve attributes
721 * @exception NamingException if a naming exception is encountered
722 */
723 public Attributes getAttributes(String name)
724 throws NamingException {
725 return getAttributes(name, null);
726 }
727
728
729 /**
730 * Retrieves selected attributes associated with a named object.
731 * See the class description regarding attribute models, attribute type
732 * names, and operational attributes.
733 *
734 * @return the requested attributes; never null
735 * @param name the name of the object from which to retrieve attributes
736 * @param attrIds the identifiers of the attributes to retrieve. null
737 * indicates that all attributes should be retrieved; an empty array
738 * indicates that none should be retrieved
739 * @exception NamingException if a naming exception is encountered
740 */
741 public Attributes getAttributes(Name name, String[] attrIds)
742 throws NamingException {
743 return getAttributes(name.toString(), attrIds);
744 }
745
746
747 /**
748 * Retrieves selected attributes associated with a named object.
749 *
750 * @return the requested attributes; never null
751 * @param name the name of the object from which to retrieve attributes
752 * @param attrIds the identifiers of the attributes to retrieve. null
753 * indicates that all attributes should be retrieved; an empty array
754 * indicates that none should be retrieved
755 * @exception NamingException if a naming exception is encountered
756 */
757 public abstract Attributes getAttributes(String name, String[] attrIds)
758 throws NamingException;
759
760
761 /**
762 * Modifies the attributes associated with a named object. The order of
763 * the modifications is not specified. Where possible, the modifications
764 * are performed atomically.
765 *
766 * @param name the name of the object whose attributes will be updated
767 * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
768 * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
769 * @param attrs the attributes to be used for the modification; may not
770 * be null
771 * @exception AttributeModificationException if the modification cannot be
772 * completed successfully
773 * @exception NamingException if a naming exception is encountered
774 */
775 public void modifyAttributes(Name name, int mod_op, Attributes attrs)
776 throws NamingException {
777 modifyAttributes(name.toString(), mod_op, attrs);
778 }
779
780
781 /**
782 * Modifies the attributes associated with a named object.
783 *
784 * @param name the name of the object whose attributes will be updated
785 * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
786 * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
787 * @param attrs the attributes to be used for the modification; may not
788 * be null
789 * @exception AttributeModificationException if the modification cannot be
790 * completed successfully
791 * @exception NamingException if a naming exception is encountered
792 */
793 public abstract void modifyAttributes
794 (String name, int mod_op, Attributes attrs)
795 throws NamingException;
796
797
798 /**
799 * Modifies the attributes associated with a named object using an an
800 * ordered list of modifications. The modifications are performed in the
801 * order specified. Each modification specifies a modification operation
802 * code and an attribute on which to operate. Where possible, the
803 * modifications are performed atomically.
804 *
805 * @param name the name of the object whose attributes will be updated
806 * @param mods an ordered sequence of modifications to be performed; may
807 * not be null
808 * @exception AttributeModificationException if the modification cannot be
809 * completed successfully
810 * @exception NamingException if a naming exception is encountered
811 */
812 public void modifyAttributes(Name name, ModificationItem[] mods)
813 throws NamingException {
814 modifyAttributes(name.toString(), mods);
815 }
816
817
818 /**
819 * Modifies the attributes associated with a named object using an an
820 * ordered list of modifications.
821 *
822 * @param name the name of the object whose attributes will be updated
823 * @param mods an ordered sequence of modifications to be performed; may
824 * not be null
825 * @exception AttributeModificationException if the modification cannot be
826 * completed successfully
827 * @exception NamingException if a naming exception is encountered
828 */
829 public abstract void modifyAttributes(String name, ModificationItem[] mods)
830 throws NamingException;
831
832
833 /**
834 * Binds a name to an object, along with associated attributes. If attrs
835 * is null, the resulting binding will have the attributes associated
836 * with obj if obj is a DirContext, and no attributes otherwise. If attrs
837 * is non-null, the resulting binding will have attrs as its attributes;
838 * any attributes associated with obj are ignored.
839 *
840 * @param name the name to bind; may not be empty
841 * @param obj the object to bind; possibly null
842 * @param attrs the attributes to associate with the binding
843 * @exception NameAlreadyBoundException if name is already bound
844 * @exception InvalidAttributesException if some "mandatory" attributes
845 * of the binding are not supplied
846 * @exception NamingException if a naming exception is encountered
847 */
848 public void bind(Name name, Object obj, Attributes attrs)
849 throws NamingException {
850 bind(name.toString(), obj, attrs);
851 }
852
853
854 /**
855 * Binds a name to an object, along with associated attributes.
856 *
857 * @param name the name to bind; may not be empty
858 * @param obj the object to bind; possibly null
859 * @param attrs the attributes to associate with the binding
860 * @exception NameAlreadyBoundException if name is already bound
861 * @exception InvalidAttributesException if some "mandatory" attributes
862 * of the binding are not supplied
863 * @exception NamingException if a naming exception is encountered
864 */
865 public abstract void bind(String name, Object obj, Attributes attrs)
866 throws NamingException;
867
868
869 /**
870 * Binds a name to an object, along with associated attributes,
871 * overwriting any existing binding. If attrs is null and obj is a
872 * DirContext, the attributes from obj are used. If attrs is null and obj
873 * is not a DirContext, any existing attributes associated with the object
874 * already bound in the directory remain unchanged. If attrs is non-null,
875 * any existing attributes associated with the object already bound in
876 * the directory are removed and attrs is associated with the named
877 * object. If obj is a DirContext and attrs is non-null, the attributes
878 * of obj are ignored.
879 *
880 * @param name the name to bind; may not be empty
881 * @param obj the object to bind; possibly null
882 * @param attrs the attributes to associate with the binding
883 * @exception InvalidAttributesException if some "mandatory" attributes
884 * of the binding are not supplied
885 * @exception NamingException if a naming exception is encountered
886 */
887 public void rebind(Name name, Object obj, Attributes attrs)
888 throws NamingException {
889 rebind(name.toString(), obj, attrs);
890 }
891
892
893 /**
894 * Binds a name to an object, along with associated attributes,
895 * overwriting any existing binding.
896 *
897 * @param name the name to bind; may not be empty
898 * @param obj the object to bind; possibly null
899 * @param attrs the attributes to associate with the binding
900 * @exception InvalidAttributesException if some "mandatory" attributes
901 * of the binding are not supplied
902 * @exception NamingException if a naming exception is encountered
903 */
904 public abstract void rebind(String name, Object obj, Attributes attrs)
905 throws NamingException;
906
907
908 /**
909 * Creates and binds a new context, along with associated attributes.
910 * This method creates a new subcontext with the given name, binds it in
911 * the target context (that named by all but terminal atomic component of
912 * the name), and associates the supplied attributes with the newly
913 * created object. All intermediate and target contexts must already
914 * exist. If attrs is null, this method is equivalent to
915 * Context.createSubcontext().
916 *
917 * @param name the name of the context to create; may not be empty
918 * @param attrs the attributes to associate with the newly created context
919 * @return the newly created context
920 * @exception NameAlreadyBoundException if the name is already bound
921 * @exception InvalidAttributesException if attrs does not contain all
922 * the mandatory attributes required for creation
923 * @exception NamingException if a naming exception is encountered
924 */
925 public DirContext createSubcontext(Name name, Attributes attrs)
926 throws NamingException {
927 return createSubcontext(name.toString(), attrs);
928 }
929
930
931 /**
932 * Creates and binds a new context, along with associated attributes.
933 *
934 * @param name the name of the context to create; may not be empty
935 * @param attrs the attributes to associate with the newly created context
936 * @return the newly created context
937 * @exception NameAlreadyBoundException if the name is already bound
938 * @exception InvalidAttributesException if attrs does not contain all
939 * the mandatory attributes required for creation
940 * @exception NamingException if a naming exception is encountered
941 */
942 public abstract DirContext createSubcontext(String name, Attributes attrs)
943 throws NamingException;
944
945
946 /**
947 * Retrieves the schema associated with the named object. The schema
948 * describes rules regarding the structure of the namespace and the
949 * attributes stored within it. The schema specifies what types of
950 * objects can be added to the directory and where they can be added;
951 * what mandatory and optional attributes an object can have. The range
952 * of support for schemas is directory-specific.
953 *
954 * @param name the name of the object whose schema is to be retrieved
955 * @return the schema associated with the context; never null
956 * @exception OperationNotSupportedException if schema not supported
957 * @exception NamingException if a naming exception is encountered
958 */
959 public DirContext getSchema(Name name)
960 throws NamingException {
961 return getSchema(name.toString());
962 }
963
964
965 /**
966 * Retrieves the schema associated with the named object.
967 *
968 * @param name the name of the object whose schema is to be retrieved
969 * @return the schema associated with the context; never null
970 * @exception OperationNotSupportedException if schema not supported
971 * @exception NamingException if a naming exception is encountered
972 */
973 public abstract DirContext getSchema(String name)
974 throws NamingException;
975
976
977 /**
978 * Retrieves a context containing the schema objects of the named
979 * object's class definitions.
980 *
981 * @param name the name of the object whose object class definition is to
982 * be retrieved
983 * @return the DirContext containing the named object's class
984 * definitions; never null
985 * @exception OperationNotSupportedException if schema not supported
986 * @exception NamingException if a naming exception is encountered
987 */
988 public DirContext getSchemaClassDefinition(Name name)
989 throws NamingException {
990 return getSchemaClassDefinition(name.toString());
991 }
992
993
994 /**
995 * Retrieves a context containing the schema objects of the named
996 * object's class definitions.
997 *
998 * @param name the name of the object whose object class definition is to
999 * be retrieved
1000 * @return the DirContext containing the named object's class
1001 * definitions; never null
1002 * @exception OperationNotSupportedException if schema not supported
1003 * @exception NamingException if a naming exception is encountered
1004 */
1005 public abstract DirContext getSchemaClassDefinition(String name)
1006 throws NamingException;
1007
1008
1009 /**
1010 * Searches in a single context for objects that contain a specified set
1011 * of attributes, and retrieves selected attributes. The search is
1012 * performed using the default SearchControls settings.
1013 *
1014 * @param name the name of the context to search
1015 * @param matchingAttributes the attributes to search for. If empty or
1016 * null, all objects in the target context are returned.
1017 * @param attributesToReturn the attributes to return. null indicates
1018 * that all attributes are to be returned; an empty array indicates that
1019 * none are to be returned.
1020 * @return a non-null enumeration of SearchResult objects. Each
1021 * SearchResult contains the attributes identified by attributesToReturn
1022 * and the name of the corresponding object, named relative to the
1023 * context named by name.
1024 * @exception NamingException if a naming exception is encountered
1025 */
1026 public NamingEnumeration search(Name name, Attributes matchingAttributes,
1027 String[] attributesToReturn)
1028 throws NamingException {
1029 return search(name.toString(), matchingAttributes, attributesToReturn);
1030 }
1031
1032
1033 /**
1034 * Searches in a single context for objects that contain a specified set
1035 * of attributes, and retrieves selected attributes.
1036 *
1037 * @param name the name of the context to search
1038 * @param matchingAttributes the attributes to search for. If empty or
1039 * null, all objects in the target context are returned.
1040 * @param attributesToReturn the attributes to return. null indicates
1041 * that all attributes are to be returned; an empty array indicates that
1042 * none are to be returned.
1043 * @return a non-null enumeration of SearchResult objects. Each
1044 * SearchResult contains the attributes identified by attributesToReturn
1045 * and the name of the corresponding object, named relative to the
1046 * context named by name.
1047 * @exception NamingException if a naming exception is encountered
1048 */
1049 public abstract NamingEnumeration search
1050 (String name, Attributes matchingAttributes,
1051 String[] attributesToReturn)
1052 throws NamingException;
1053
1054
1055 /**
1056 * Searches in a single context for objects that contain a specified set
1057 * of attributes. This method returns all the attributes of such objects.
1058 * It is equivalent to supplying null as the atributesToReturn parameter
1059 * to the method search(Name, Attributes, String[]).
1060 *
1061 * @param name the name of the context to search
1062 * @param matchingAttributes the attributes to search for. If empty or
1063 * null, all objects in the target context are returned.
1064 * @return a non-null enumeration of SearchResult objects. Each
1065 * SearchResult contains the attributes identified by attributesToReturn
1066 * and the name of the corresponding object, named relative to the
1067 * context named by name.
1068 * @exception NamingException if a naming exception is encountered
1069 */
1070 public NamingEnumeration search(Name name, Attributes matchingAttributes)
1071 throws NamingException {
1072 return search(name.toString(), matchingAttributes);
1073 }
1074
1075
1076 /**
1077 * Searches in a single context for objects that contain a specified set
1078 * of attributes.
1079 *
1080 * @param name the name of the context to search
1081 * @param matchingAttributes the attributes to search for. If empty or
1082 * null, all objects in the target context are returned.
1083 * @return a non-null enumeration of SearchResult objects. Each
1084 * SearchResult contains the attributes identified by attributesToReturn
1085 * and the name of the corresponding object, named relative to the
1086 * context named by name.
1087 * @exception NamingException if a naming exception is encountered
1088 */
1089 public abstract NamingEnumeration search
1090 (String name, Attributes matchingAttributes)
1091 throws NamingException;
1092
1093
1094 /**
1095 * Searches in the named context or object for entries that satisfy the
1096 * given search filter. Performs the search as specified by the search
1097 * controls.
1098 *
1099 * @param name the name of the context or object to search
1100 * @param filter the filter expression to use for the search; may not be
1101 * null
1102 * @param cons the search controls that control the search. If null,
1103 * the default search controls are used (equivalent to
1104 * (new SearchControls())).
1105 * @return an enumeration of SearchResults of the objects that satisfy
1106 * the filter; never null
1107 * @exception InvalidSearchFilterException if the search filter specified
1108 * is not supported or understood by the underlying directory
1109 * @exception InvalidSearchControlsException if the search controls
1110 * contain invalid settings
1111 * @exception NamingException if a naming exception is encountered
1112 */
1113 public NamingEnumeration search
1114 (Name name, String filter, SearchControls cons)
1115 throws NamingException {
1116 return search(name.toString(), filter, cons);
1117 }
1118
1119
1120 /**
1121 * Searches in the named context or object for entries that satisfy the
1122 * given search filter. Performs the search as specified by the search
1123 * controls.
1124 *
1125 * @param name the name of the context or object to search
1126 * @param filter the filter expression to use for the search; may not be
1127 * null
1128 * @param cons the search controls that control the search. If null,
1129 * the default search controls are used (equivalent to
1130 * (new SearchControls())).
1131 * @return an enumeration of SearchResults of the objects that satisfy
1132 * the filter; never null
1133 * @exception InvalidSearchFilterException if the search filter
1134 * specified is not supported or understood by the underlying directory
1135 * @exception InvalidSearchControlsException if the search controls
1136 * contain invalid settings
1137 * @exception NamingException if a naming exception is encountered
1138 */
1139 public abstract NamingEnumeration search(String name, String filter,
1140 SearchControls cons)
1141 throws NamingException;
1142
1143
1144 /**
1145 * Searches in the named context or object for entries that satisfy the
1146 * given search filter. Performs the search as specified by the search
1147 * controls.
1148 *
1149 * @param name the name of the context or object to search
1150 * @param filterExpr the filter expression to use for the search.
1151 * The expression may contain variables of the form "{i}" where i is a
1152 * nonnegative integer. May not be null.
1153 * @param filterArgs the array of arguments to substitute for the
1154 * variables in filterExpr. The value of filterArgs[i] will replace each
1155 * occurrence of "{i}". If null, equivalent to an empty array.
1156 * @param cons the search controls that control the search. If null, the
1157 * default search controls are used (equivalent to (new SearchControls())).
1158 * @return an enumeration of SearchResults of the objects that satisy the
1159 * filter; never null
1160 * @exception ArrayIndexOutOfBoundsException if filterExpr contains {i}
1161 * expressions where i is outside the bounds of the array filterArgs
1162 * @exception InvalidSearchControlsException if cons contains invalid
1163 * settings
1164 * @exception InvalidSearchFilterException if filterExpr with filterArgs
1165 * represents an invalid search filter
1166 * @exception NamingException if a naming exception is encountered
1167 */
1168 public NamingEnumeration search(Name name, String filterExpr,
1169 Object[] filterArgs, SearchControls cons)
1170 throws NamingException {
1171 return search(name.toString(), filterExpr, filterArgs, cons);
1172 }
1173
1174
1175 /**
1176 * Searches in the named context or object for entries that satisfy the
1177 * given search filter. Performs the search as specified by the search
1178 * controls.
1179 *
1180 * @param name the name of the context or object to search
1181 * @param filterExpr the filter expression to use for the search.
1182 * The expression may contain variables of the form "{i}" where i is a
1183 * nonnegative integer. May not be null.
1184 * @param filterArgs the array of arguments to substitute for the
1185 * variables in filterExpr. The value of filterArgs[i] will replace each
1186 * occurrence of "{i}". If null, equivalent to an empty array.
1187 * @param cons the search controls that control the search. If null, the
1188 * default search controls are used (equivalent to (new SearchControls())).
1189 * @return an enumeration of SearchResults of the objects that satisy the
1190 * filter; never null
1191 * @exception ArrayIndexOutOfBoundsException if filterExpr contains {i}
1192 * expressions where i is outside the bounds of the array filterArgs
1193 * @exception InvalidSearchControlsException if cons contains invalid
1194 * settings
1195 * @exception InvalidSearchFilterException if filterExpr with filterArgs
1196 * represents an invalid search filter
1197 * @exception NamingException if a naming exception is encountered
1198 */
1199 public abstract NamingEnumeration search
1200 (String name, String filterExpr,
1201 Object[] filterArgs, SearchControls cons)
1202 throws NamingException;
1203
1204
1205 // ------------------------------------------------------ Protected Methods
1206
1207
1208 }
1209
Save This Page