Java > Open Source Codes > org > apache > naming > resources > BaseDirContext


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
1210

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags