KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.apache.naming.core;
18
19 import java.util.Hashtable;
20
21 import javax.naming.Name;
22 import javax.naming.NameAlreadyBoundException;
23 import javax.naming.NamingEnumeration;
24 import javax.naming.NamingException;
25 import javax.naming.OperationNotSupportedException;
26 import javax.naming.directory.Attribute;
27 import javax.naming.directory.Attributes;
28 import javax.naming.directory.DirContext;
29 import javax.naming.directory.ModificationItem;
30 import javax.naming.directory.SearchControls;
31
32
33 //import org.apache.naming.core.NameParserImpl;
34
35 // Based on a merge of various catalina naming contexts
36 // Name is used - it provide better oportunities for reuse and optimizations
37
38 /**
39  * Base Directory Context implementation. All j-t-c/naming contexts should
40  * extend it.
41  *
42  * Implements all JNDI methods - if you just extend it you'll get UnsuportedOperation.
43  * XXX Should it also act as introspector proxy or should we use a separate context ?
44  * The intention is to allow use 'introspection magic' and bean-like DirContexts.
45  *
46  * IMPORTANT: all contexts should use setters/getters for configuration, instead
47  * of the Hashtable. The default constructor will use introspection to configure
48  * and may provide ( via a hook ? ) JMX management on all contexts.
49  *
50  * You must extend and override few methods. Of course, you can also override any other
51  * method and provide a more optimal implementation, but in most cases you only
52  * need the minimal set.
53  *
54  * All methods use Name variant. They should expect an arbitrary implementation, but
55  * it's recommended to check if ServerName is used - and take advantage of the
56  * specific features ( MessageBytes, etc ).
57  *
58  * <ul>
59  * <li>
60  * </ul>
61  *
62  * @author Remy Maucherat
63  * @author Costin Manolache
64  */
65 public class BaseDirContext extends BaseContext implements DirContext {
66
67     public BaseDirContext()
68     {
69         super();
70     }
71
72     public BaseDirContext(Hashtable env)
73     {
74         super(env);
75     }
76
77
78     // ----------------------------------------------------- DirContext Methods
79
80     /**
81      * Retrieves all of the attributes associated with a named object.
82      *
83      * @return the set of attributes associated with name.
84      * Returns an empty attribute set if name has no attributes; never null.
85      * @param name the name of the object from which to retrieve attributes
86      * @exception javax.naming.NamingException if a naming exception is encountered
87      */
88     public Attributes getAttributes(Name name)
89             throws NamingException
90     {
91         return getAttributes(name, null);
92     }
93
94
95     /**
96      * Retrieves all of the attributes associated with a named object.
97      *
98      * @return the set of attributes associated with name
99      * @param name the name of the object from which to retrieve attributes
100      * @exception javax.naming.NamingException if a naming exception is encountered
101      */
102     public Attributes getAttributes(String name)
103             throws NamingException
104     {
105         return getAttributes(string2Name(name));
106     }
107
108     /**
109      * Retrieves selected attributes associated with a named object.
110      * See the class description regarding attribute models, attribute type
111      * names, and operational attributes.
112      *
113      * @return the requested attributes; never null
114      * @param name the name of the object from which to retrieve attributes
115      * @param attrIds the identifiers of the attributes to retrieve. null
116      * indicates that all attributes should be retrieved; an empty array
117      * indicates that none should be retrieved
118      * @exception javax.naming.NamingException if a naming exception is encountered
119      */
120     public Attributes getAttributes(String name, String[] attrIds)
121             throws NamingException
122     {
123         return getAttributes(string2Name(name), attrIds);
124     }
125
126     public Attributes getAttributes(Name name, String[] attrIds)
127             throws NamingException
128     {
129         if( attrIds==null ) {
130             attrIds= super.getAttributeNames(name);
131         }
132         Attributes res=new ServerAttributes();
133         if( attrIds==null ) return res;
134
135         for( int i=0; i<attrIds.length; i++ ) {
136             Object val=super.getAttribute(name, attrIds[i]);
137             res.put( attrIds[i], val );
138         }
139         return res;
140     }
141
142
143     /**
144      * Modifies the attributes associated with a named object. The order of
145      * the modifications is not specified. Where possible, the modifications
146      * are performed atomically.
147      *
148      * @param name the name of the object whose attributes will be updated
149      * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
150      * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
151      * @param attrs the attributes to be used for the modification; may not
152      * be null
153      * @exception AttributeModificationException if the modification cannot be
154      * completed successfully
155      * @exception javax.naming.NamingException if a naming exception is encountered
156      */
157     public void modifyAttributes(Name name, int mod_op, Attributes attrs)
158             throws NamingException
159     {
160         NamingEnumeration enum=attrs.getAll();
161         while( enum.hasMoreElements() ) {
162             Attribute att=(Attribute)enum.nextElement();
163             switch( mod_op ) {
164             case ADD_ATTRIBUTE:
165             case REPLACE_ATTRIBUTE:
166                 for( int i=0; i< att.size(); i++ ) {
167                     super.setAttribute(name, att.getID(), att.get(i));
168                 }
169                 break;
170             case REMOVE_ATTRIBUTE:
171                 break;
172             }
173         }
174     }
175
176     public void modifyAttributes(String name, int mod_op, Attributes attrs)
177             throws NamingException
178     {
179         modifyAttributes(string2Name(name), mod_op, attrs);
180     }
181
182
183     /**
184      * Modifies the attributes associated with a named object using an an
185      * ordered list of modifications. The modifications are performed in the
186      * order specified. Each modification specifies a modification operation
187      * code and an attribute on which to operate. Where possible, the
188      * modifications are performed atomically.
189      *
190      * @param name the name of the object whose attributes will be updated
191      * @param mods an ordered sequence of modifications to be performed; may
192      * not be null
193      * @exception AttributeModificationException if the modification cannot be
194      * completed successfully
195      * @exception javax.naming.NamingException if a naming exception is encountered
196      */
197     public void modifyAttributes(Name name, ModificationItem[] mods)
198             throws NamingException
199     {
200         if (mods==null) return;
201         for (int i=0; i<mods.length; i++) {
202
203             switch( mods[i].getModificationOp() ) {
204             case ADD_ATTRIBUTE:
205             case REPLACE_ATTRIBUTE:
206             case REMOVE_ATTRIBUTE:
207             };
208         }
209     }
210
211
212     public void modifyAttributes(String name, ModificationItem[] mods)
213             throws NamingException
214     {
215         modifyAttributes(string2Name(name), mods);
216     }
217
218
219     /**
220      * Binds a name to an object, along with associated attributes. If attrs
221      * is null, the resulting binding will have the attributes associated
222      * with obj if obj is a DirContext, and no attributes otherwise. If attrs
223      * is non-null, the resulting binding will have attrs as its attributes;
224      * any attributes associated with obj are ignored.
225      *
226      * @param name the name to bind; may not be empty
227      * @param obj the object to bind; possibly null
228      * @param attrs the attributes to associate with the binding
229      * @exception javax.naming.NameAlreadyBoundException if name is already bound
230      * @exception InvalidAttributesException if some "mandatory" attributes
231      * of the binding are not supplied
232      * @exception javax.naming.NamingException if a naming exception is encountered
233      */
234     public void bind(Name name, Object obj, Attributes attrs)
235             throws NamingException
236     {
237         super.bind( name, obj );
238
239         NamingEnumeration enum=attrs.getAll();
240         while( enum.hasMoreElements() ) {
241             Attribute att=(Attribute)enum.nextElement();
242
243             Object val=getAttribute(name, att.getID() );
244             if( val != null ) {
245                 throw new NameAlreadyBoundException(name.toString() + " : " +
246                         att.getID());
247             }
248
249             int size=att.size();
250             for( int i=0; i<size; i++ ) {
251                 // probably need some addAttribute
252 setAttribute( name, att.getID(), att.get(i));
253             }
254         }
255     }
256
257     public void bind( String name, Object obj, Attributes attrs )
258             throws NamingException
259     {
260         bind(string2Name(name), obj, attrs);
261     }
262
263
264     /**
265      * Binds a name to an object, along with associated attributes,
266      * overwriting any existing binding. If attrs is null and obj is a
267      * DirContext, the attributes from obj are used. If attrs is null and obj
268      * is not a DirContext, any existing attributes associated with the object
269      * already bound in the directory remain unchanged. If attrs is non-null,
270      * any existing attributes associated with the object already bound in
271      * the directory are removed and attrs is associated with the named
272      * object. If obj is a DirContext and attrs is non-null, the attributes
273      * of obj are ignored.
274      *
275      * @param name the name to bind; may not be empty
276      * @param obj the object to bind; possibly null
277      * @param attrs the attributes to associate with the binding
278      * @exception InvalidAttributesException if some "mandatory" attributes
279      * of the binding are not supplied
280      * @exception javax.naming.NamingException if a naming exception is encountered
281      */
282     public void rebind(Name name, Object obj, Attributes attrs)
283             throws NamingException
284     {
285         bind(name, obj, attrs, true);
286     }
287
288     public void rebind(String name, Object obj, Attributes attrs)
289             throws NamingException
290     {
291         bind(string2Name(name), obj, attrs, true);
292     }
293
294
295     /**
296      * Creates and binds a new context, along with associated attributes.
297      * This method creates a new subcontext with the given name, binds it in
298      * the target context (that named by all but terminal atomic component of
299      * the name), and associates the supplied attributes with the newly
300      * created object. All intermediate and target contexts must already
301      * exist. If attrs is null, this method is equivalent to
302      * Context.createSubcontext().
303      *
304      * @param name the name of the context to create; may not be empty
305      * @param attrs the attributes to associate with the newly created context
306      * @return the newly created context
307      * @exception javax.naming.NameAlreadyBoundException if the name is already bound
308      * @exception InvalidAttributesException if attrs does not contain all
309      * the mandatory attributes required for creation
310      * @exception javax.naming.NamingException if a naming exception is encountered
311      */
312     public DirContext createSubcontext(String name, Attributes attrs)
313             throws NamingException
314     {
315         return createSubcontext(string2Name(name), attrs);
316     }
317
318
319     /**
320      * Retrieves the schema associated with the named object. The schema
321      * describes rules regarding the structure of the namespace and the
322      * attributes stored within it. The schema specifies what types of
323      * objects can be added to the directory and where they can be added;
324      * what mandatory and optional attributes an object can have. The range
325      * of support for schemas is directory-specific.
326      *
327      * @param name the name of the object whose schema is to be retrieved
328      * @return the schema associated with the context; never null
329      * @exception javax.naming.OperationNotSupportedException if schema not supported
330      * @exception javax.naming.NamingException if a naming exception is encountered
331      */
332     public DirContext getSchema(Name name)
333             throws NamingException
334     {
335         return getSchema(name.toString());
336     }
337
338
339     /**
340      * Retrieves the schema associated with the named object.
341      *
342      * @param name the name of the object whose schema is to be retrieved
343      * @return the schema associated with the context; never null
344      * @exception javax.naming.OperationNotSupportedException if schema not supported
345      * @exception javax.naming.NamingException if a naming exception is encountered
346      */
347     public DirContext getSchema(String name)
348             throws NamingException
349     {
350         throw new OperationNotSupportedException();
351     }
352
353
354     /**
355      * Retrieves a context containing the schema objects of the named
356      * object's class definitions.
357      *
358      * @param name the name of the object whose object class definition is to
359      * be retrieved
360      * @return the DirContext containing the named object's class
361      * definitions; never null
362      * @exception javax.naming.OperationNotSupportedException if schema not supported
363      * @exception javax.naming.NamingException if a naming exception is encountered
364      */
365     public DirContext getSchemaClassDefinition(Name name)
366             throws NamingException
367     {
368         return getSchemaClassDefinition(name.toString());
369     }
370
371
372     /**
373      * Retrieves a context containing the schema objects of the named
374      * object's class definitions.
375      *
376      * @param name the name of the object whose object class definition is to
377      * be retrieved
378      * @return the DirContext containing the named object's class
379      * definitions; never null
380      * @exception javax.naming.OperationNotSupportedException if schema not supported
381      * @exception javax.naming.NamingException if a naming exception is encountered
382      */
383     public DirContext getSchemaClassDefinition(String name)
384             throws NamingException
385     {
386         throw new OperationNotSupportedException();
387     }
388
389
390     /**
391      * Searches in a single context for objects that contain a specified set
392      * of attributes, and retrieves selected attributes. The search is
393      * performed using the default SearchControls settings.
394      *
395      * @param name the name of the context to search
396      * @param matchingAttributes the attributes to search for. If empty or
397      * null, all objects in the target context are returned.
398      * @param attributesToReturn the attributes to return. null indicates
399      * that all attributes are to be returned; an empty array indicates that
400      * none are to be returned.
401      * @return a non-null enumeration of SearchResult objects. Each
402      * SearchResult contains the attributes identified by attributesToReturn
403      * and the name of the corresponding object, named relative to the
404      * context named by name.
405      * @exception javax.naming.NamingException if a naming exception is encountered
406      */
407     public NamingEnumeration search(Name name, Attributes matchingAttributes,
408                                     String[] attributesToReturn)
409             throws NamingException
410     {
411         return search(name.toString(), matchingAttributes, attributesToReturn);
412     }
413
414
415     /**
416      * Searches in a single context for objects that contain a specified set
417      * of attributes, and retrieves selected attributes.
418      *
419      * @param name the name of the context to search
420      * @param matchingAttributes the attributes to search for. If empty or
421      * null, all objects in the target context are returned.
422      * @param attributesToReturn the attributes to return. null indicates
423      * that all attributes are to be returned; an empty array indicates that
424      * none are to be returned.
425      * @return a non-null enumeration of SearchResult objects. Each
426      * SearchResult contains the attributes identified by attributesToReturn
427      * and the name of the corresponding object, named relative to the
428      * context named by name.
429      * @exception javax.naming.NamingException if a naming exception is encountered
430      */
431     public NamingEnumeration search(String name, Attributes matchingAttributes,
432                                     String[] attributesToReturn)
433             throws NamingException
434     {
435         throw new OperationNotSupportedException();
436     }
437
438
439     /**
440      * Searches in a single context for objects that contain a specified set
441      * of attributes. This method returns all the attributes of such objects.
442      * It is equivalent to supplying null as the atributesToReturn parameter
443      * to the method search(Name, Attributes, String[]).
444      *
445      * @param name the name of the context to search
446      * @param matchingAttributes the attributes to search for. If empty or
447      * null, all objects in the target context are returned.
448      * @return a non-null enumeration of SearchResult objects. Each
449      * SearchResult contains the attributes identified by attributesToReturn
450      * and the name of the corresponding object, named relative to the
451      * context named by name.
452      * @exception javax.naming.NamingException if a naming exception is encountered
453      */
454     public NamingEnumeration search(Name name, Attributes matchingAttributes)
455             throws NamingException
456     {
457         return search(name.toString(), matchingAttributes);
458     }
459
460
461     /**
462      * Searches in a single context for objects that contain a specified set
463      * of attributes.
464      *
465      * @param name the name of the context to search
466      * @param matchingAttributes the attributes to search for. If empty or
467      * null, all objects in the target context are returned.
468      * @return a non-null enumeration of SearchResult objects. Each
469      * SearchResult contains the attributes identified by attributesToReturn
470      * and the name of the corresponding object, named relative to the
471      * context named by name.
472      * @exception javax.naming.NamingException if a naming exception is encountered
473      */
474     public NamingEnumeration search(String name, Attributes matchingAttributes)
475             throws NamingException
476     {
477         throw new OperationNotSupportedException();
478     }
479
480     /**
481      * Searches in the named context or object for entries that satisfy the
482      * given search filter. Performs the search as specified by the search
483      * controls.
484      *
485      * @param name the name of the context or object to search
486      * @param filter the filter expression to use for the search; may not be
487      * null
488      * @param cons the search controls that control the search. If null,
489      * the default search controls are used (equivalent to
490      * (new SearchControls())).
491      * @return an enumeration of SearchResults of the objects that satisfy
492      * the filter; never null
493      * @exception InvalidSearchFilterException if the search filter specified
494      * is not supported or understood by the underlying directory
495      * @exception InvalidSearchControlsException if the search controls
496      * contain invalid settings
497      * @exception javax.naming.NamingException if a naming exception is encountered
498      */
499     public NamingEnumeration search(Name name, String filter,
500                                     SearchControls cons)
501             throws NamingException
502     {
503         return search(name.toString(), filter, cons);
504     }
505
506
507     /**
508      * Searches in the named context or object for entries that satisfy the
509      * given search filter. Performs the search as specified by the search
510      * controls.
511      *
512      * @param name the name of the context or object to search
513      * @param filter the filter expression to use for the search; may not be
514      * null
515      * @param cons the search controls that control the search. If null,
516      * the default search controls are used (equivalent to
517      * (new SearchControls())).
518      * @return an enumeration of SearchResults of the objects that satisfy
519      * the filter; never null
520      * @exception InvalidSearchFilterException if the search filter
521      * specified is not supported or understood by the underlying directory
522      * @exception InvalidSearchControlsException if the search controls
523      * contain invalid settings
524      * @exception javax.naming.NamingException if a naming exception is encountered
525      */
526     public NamingEnumeration search(String name, String filter,
527                                     SearchControls cons)
528             throws NamingException
529     {
530         throw new OperationNotSupportedException();
531     }
532
533
534     /**
535      * Searches in the named context or object for entries that satisfy the
536      * given search filter. Performs the search as specified by the search
537      * controls.
538      *
539      * @param name the name of the context or object to search
540      * @param filterExpr the filter expression to use for the search.
541      * The expression may contain variables of the form "{i}" where i is a
542      * nonnegative integer. May not be null.
543      * @param filterArgs the array of arguments to substitute for the
544      * variables in filterExpr. The value of filterArgs[i] will replace each
545      * occurrence of "{i}". If null, equivalent to an empty array.
546      * @param cons the search controls that control the search. If null, the
547      * default search controls are used (equivalent to (new SearchControls())).
548      * @return an enumeration of SearchResults of the objects that satisy the
549      * filter; never null
550      * @exception java.lang.ArrayIndexOutOfBoundsException if filterExpr contains {i}
551      * expressions where i is outside the bounds of the array filterArgs
552      * @exception InvalidSearchControlsException if cons contains invalid
553      * settings
554      * @exception InvalidSearchFilterException if filterExpr with filterArgs
555      * represents an invalid search filter
556      * @exception javax.naming.NamingException if a naming exception is encountered
557      */
558     public NamingEnumeration search(Name name, String filterExpr,
559                                     Object[] filterArgs, SearchControls cons)
560             throws NamingException
561     {
562         return search(name.toString(), filterExpr, filterArgs, cons);
563     }
564
565
566     /**
567      * Searches in the named context or object for entries that satisfy the
568      * given search filter. Performs the search as specified by the search
569      * controls.
570      *
571      * @param name the name of the context or object to search
572      * @param filterExpr the filter expression to use for the search.
573      * The expression may contain variables of the form "{i}" where i is a
574      * nonnegative integer. May not be null.
575      * @param filterArgs the array of arguments to substitute for the
576      * variables in filterExpr. The value of filterArgs[i] will replace each
577      * occurrence of "{i}". If null, equivalent to an empty array.
578      * @param cons the search controls that control the search. If null, the
579      * default search controls are used (equivalent to (new SearchControls())).
580      * @return an enumeration of SearchResults of the objects that satisy the
581      * filter; never null
582      * @exception java.lang.ArrayIndexOutOfBoundsException if filterExpr contains {i}
583      * expressions where i is outside the bounds of the array filterArgs
584      * @exception InvalidSearchControlsException if cons contains invalid
585      * settings
586      * @exception InvalidSearchFilterException if filterExpr with filterArgs
587      * represents an invalid search filter
588      * @exception javax.naming.NamingException if a naming exception is encountered
589      */
590     public NamingEnumeration search(String name, String filterExpr,
591                                     Object[] filterArgs,
592                                     SearchControls cons)
593             throws NamingException
594     {
595         throw new OperationNotSupportedException();
596     }
597
598 }
599
600
Popular Tags