001: /*
002: * Copyright 1999,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.naming;
018:
019: import java.util.Hashtable;
020: import javax.naming.Context;
021: import javax.naming.Name;
022: import javax.naming.NameParser;
023: import javax.naming.NamingEnumeration;
024: import javax.naming.NamingException;
025:
026: /**
027: * Catalina JNDI Context implementation.
028: *
029: * @author Remy Maucherat
030: * @version $Revision: 1.2 $ $Date: 2004/02/27 14:58:53 $
031: */
032:
033: public class SelectorContext implements Context {
034:
035: // -------------------------------------------------------------- Constants
036:
037: /**
038: * Namespace URL.
039: */
040: public static final String prefix = "java:";
041:
042: /**
043: * Namespace URL length.
044: */
045: public static final int prefixLength = prefix.length();
046:
047: /**
048: * Initial context prefix.
049: */
050: public static final String IC_PREFIX = "IC_";
051:
052: // ----------------------------------------------------------- Constructors
053:
054: /**
055: * Builds a Catalina selector context using the given environment.
056: */
057: public SelectorContext(Hashtable env) {
058: this .env = env;
059: }
060:
061: /**
062: * Builds a Catalina selector context using the given environment.
063: */
064: public SelectorContext(Hashtable env, boolean initialContext) {
065: this (env);
066: this .initialContext = initialContext;
067: }
068:
069: // ----------------------------------------------------- Instance Variables
070:
071: /**
072: * Environment.
073: */
074: protected Hashtable env;
075:
076: /**
077: * The string manager for this package.
078: */
079: protected StringManager sm = StringManager
080: .getManager(Constants.Package);
081:
082: /**
083: * Request for an initial context.
084: */
085: protected boolean initialContext = false;
086:
087: // --------------------------------------------------------- Public Methods
088:
089: // -------------------------------------------------------- Context Methods
090:
091: /**
092: * Retrieves the named object. If name is empty, returns a new instance
093: * of this context (which represents the same naming context as this
094: * context, but its environment may be modified independently and it may
095: * be accessed concurrently).
096: *
097: * @param name the name of the object to look up
098: * @return the object bound to name
099: * @exception NamingException if a naming exception is encountered
100: */
101: public Object lookup(Name name) throws NamingException {
102: // Strip the URL header
103: // Find the appropriate NamingContext according to the current bindings
104: // Execute the lookup on that context
105: return getBoundContext().lookup(parseName(name));
106: }
107:
108: /**
109: * Retrieves the named object.
110: *
111: * @param name the name of the object to look up
112: * @return the object bound to name
113: * @exception NamingException if a naming exception is encountered
114: */
115: public Object lookup(String name) throws NamingException {
116: // Strip the URL header
117: // Find the appropriate NamingContext according to the current bindings
118: // Execute the lookup on that context
119: return getBoundContext().lookup(parseName(name));
120: }
121:
122: /**
123: * Binds a name to an object. All intermediate contexts and the target
124: * context (that named by all but terminal atomic component of the name)
125: * must already exist.
126: *
127: * @param name the name to bind; may not be empty
128: * @param obj the object to bind; possibly null
129: * @exception NameAlreadyBoundException if name is already bound
130: * @exception InvalidAttributesException if object did not supply all
131: * mandatory attributes
132: * @exception NamingException if a naming exception is encountered
133: */
134: public void bind(Name name, Object obj) throws NamingException {
135: getBoundContext().bind(parseName(name), obj);
136: }
137:
138: /**
139: * Binds a name to an object.
140: *
141: * @param name the name to bind; may not be empty
142: * @param obj the object to bind; possibly null
143: * @exception NameAlreadyBoundException if name is already bound
144: * @exception InvalidAttributesException if object did not supply all
145: * mandatory attributes
146: * @exception NamingException if a naming exception is encountered
147: */
148: public void bind(String name, Object obj) throws NamingException {
149: getBoundContext().bind(parseName(name), obj);
150: }
151:
152: /**
153: * Binds a name to an object, overwriting any existing binding. All
154: * intermediate contexts and the target context (that named by all but
155: * terminal atomic component of the name) must already exist.
156: * <p>
157: * If the object is a DirContext, any existing attributes associated with
158: * the name are replaced with those of the object. Otherwise, any
159: * existing attributes associated with the name remain unchanged.
160: *
161: * @param name the name to bind; may not be empty
162: * @param obj the object to bind; possibly null
163: * @exception InvalidAttributesException if object did not supply all
164: * mandatory attributes
165: * @exception NamingException if a naming exception is encountered
166: */
167: public void rebind(Name name, Object obj) throws NamingException {
168: getBoundContext().rebind(parseName(name), obj);
169: }
170:
171: /**
172: * Binds a name to an object, overwriting any existing binding.
173: *
174: * @param name the name to bind; may not be empty
175: * @param obj the object to bind; possibly null
176: * @exception InvalidAttributesException if object did not supply all
177: * mandatory attributes
178: * @exception NamingException if a naming exception is encountered
179: */
180: public void rebind(String name, Object obj) throws NamingException {
181: getBoundContext().rebind(parseName(name), obj);
182: }
183:
184: /**
185: * Unbinds the named object. Removes the terminal atomic name in name
186: * from the target context--that named by all but the terminal atomic
187: * part of name.
188: * <p>
189: * This method is idempotent. It succeeds even if the terminal atomic
190: * name is not bound in the target context, but throws
191: * NameNotFoundException if any of the intermediate contexts do not exist.
192: *
193: * @param name the name to bind; may not be empty
194: * @exception NameNotFoundException if an intermediate context does not
195: * exist
196: * @exception NamingException if a naming exception is encountered
197: */
198: public void unbind(Name name) throws NamingException {
199: getBoundContext().unbind(parseName(name));
200: }
201:
202: /**
203: * Unbinds the named object.
204: *
205: * @param name the name to bind; may not be empty
206: * @exception NameNotFoundException if an intermediate context does not
207: * exist
208: * @exception NamingException if a naming exception is encountered
209: */
210: public void unbind(String name) throws NamingException {
211: getBoundContext().unbind(parseName(name));
212: }
213:
214: /**
215: * Binds a new name to the object bound to an old name, and unbinds the
216: * old name. Both names are relative to this context. Any attributes
217: * associated with the old name become associated with the new name.
218: * Intermediate contexts of the old name are not changed.
219: *
220: * @param oldName the name of the existing binding; may not be empty
221: * @param newName the name of the new binding; may not be empty
222: * @exception NameAlreadyBoundException if newName is already bound
223: * @exception NamingException if a naming exception is encountered
224: */
225: public void rename(Name oldName, Name newName)
226: throws NamingException {
227: getBoundContext()
228: .rename(parseName(oldName), parseName(newName));
229: }
230:
231: /**
232: * Binds a new name to the object bound to an old name, and unbinds the
233: * old name.
234: *
235: * @param oldName the name of the existing binding; may not be empty
236: * @param newName the name of the new binding; may not be empty
237: * @exception NameAlreadyBoundException if newName is already bound
238: * @exception NamingException if a naming exception is encountered
239: */
240: public void rename(String oldName, String newName)
241: throws NamingException {
242: getBoundContext()
243: .rename(parseName(oldName), parseName(newName));
244: }
245:
246: /**
247: * Enumerates the names bound in the named context, along with the class
248: * names of objects bound to them. The contents of any subcontexts are
249: * not included.
250: * <p>
251: * If a binding is added to or removed from this context, its effect on
252: * an enumeration previously returned is undefined.
253: *
254: * @param name the name of the context to list
255: * @return an enumeration of the names and class names of the bindings in
256: * this context. Each element of the enumeration is of type NameClassPair.
257: * @exception NamingException if a naming exception is encountered
258: */
259: public NamingEnumeration list(Name name) throws NamingException {
260: return getBoundContext().list(parseName(name));
261: }
262:
263: /**
264: * Enumerates the names bound in the named context, along with the class
265: * names of objects bound to them.
266: *
267: * @param name the name of the context to list
268: * @return an enumeration of the names and class names of the bindings in
269: * this context. Each element of the enumeration is of type NameClassPair.
270: * @exception NamingException if a naming exception is encountered
271: */
272: public NamingEnumeration list(String name) throws NamingException {
273: return getBoundContext().list(parseName(name));
274: }
275:
276: /**
277: * Enumerates the names bound in the named context, along with the
278: * objects bound to them. The contents of any subcontexts are not
279: * included.
280: * <p>
281: * If a binding is added to or removed from this context, its effect on
282: * an enumeration previously returned is undefined.
283: *
284: * @param name the name of the context to list
285: * @return an enumeration of the bindings in this context.
286: * Each element of the enumeration is of type Binding.
287: * @exception NamingException if a naming exception is encountered
288: */
289: public NamingEnumeration listBindings(Name name)
290: throws NamingException {
291: return getBoundContext().listBindings(parseName(name));
292: }
293:
294: /**
295: * Enumerates the names bound in the named context, along with the
296: * objects bound to them.
297: *
298: * @param name the name of the context to list
299: * @return an enumeration of the bindings in this context.
300: * Each element of the enumeration is of type Binding.
301: * @exception NamingException if a naming exception is encountered
302: */
303: public NamingEnumeration listBindings(String name)
304: throws NamingException {
305: return getBoundContext().listBindings(parseName(name));
306: }
307:
308: /**
309: * Destroys the named context and removes it from the namespace. Any
310: * attributes associated with the name are also removed. Intermediate
311: * contexts are not destroyed.
312: * <p>
313: * This method is idempotent. It succeeds even if the terminal atomic
314: * name is not bound in the target context, but throws
315: * NameNotFoundException if any of the intermediate contexts do not exist.
316: *
317: * In a federated naming system, a context from one naming system may be
318: * bound to a name in another. One can subsequently look up and perform
319: * operations on the foreign context using a composite name. However, an
320: * attempt destroy the context using this composite name will fail with
321: * NotContextException, because the foreign context is not a "subcontext"
322: * of the context in which it is bound. Instead, use unbind() to remove
323: * the binding of the foreign context. Destroying the foreign context
324: * requires that the destroySubcontext() be performed on a context from
325: * the foreign context's "native" naming system.
326: *
327: * @param name the name of the context to be destroyed; may not be empty
328: * @exception NameNotFoundException if an intermediate context does not
329: * exist
330: * @exception NotContextException if the name is bound but does not name
331: * a context, or does not name a context of the appropriate type
332: */
333: public void destroySubcontext(Name name) throws NamingException {
334: getBoundContext().destroySubcontext(parseName(name));
335: }
336:
337: /**
338: * Destroys the named context and removes it from the namespace.
339: *
340: * @param name the name of the context to be destroyed; may not be empty
341: * @exception NameNotFoundException if an intermediate context does not
342: * exist
343: * @exception NotContextException if the name is bound but does not name
344: * a context, or does not name a context of the appropriate type
345: */
346: public void destroySubcontext(String name) throws NamingException {
347: getBoundContext().destroySubcontext(parseName(name));
348: }
349:
350: /**
351: * Creates and binds a new context. Creates a new context with the given
352: * name and binds it in the target context (that named by all but
353: * terminal atomic component of the name). All intermediate contexts and
354: * the target context must already exist.
355: *
356: * @param name the name of the context to create; may not be empty
357: * @return the newly created context
358: * @exception NameAlreadyBoundException if name is already bound
359: * @exception InvalidAttributesException if creation of the subcontext
360: * requires specification of mandatory attributes
361: * @exception NamingException if a naming exception is encountered
362: */
363: public Context createSubcontext(Name name) throws NamingException {
364: return getBoundContext().createSubcontext(parseName(name));
365: }
366:
367: /**
368: * Creates and binds a new context.
369: *
370: * @param name the name of the context to create; may not be empty
371: * @return the newly created context
372: * @exception NameAlreadyBoundException if name is already bound
373: * @exception InvalidAttributesException if creation of the subcontext
374: * requires specification of mandatory attributes
375: * @exception NamingException if a naming exception is encountered
376: */
377: public Context createSubcontext(String name) throws NamingException {
378: return getBoundContext().createSubcontext(parseName(name));
379: }
380:
381: /**
382: * Retrieves the named object, following links except for the terminal
383: * atomic component of the name. If the object bound to name is not a
384: * link, returns the object itself.
385: *
386: * @param name the name of the object to look up
387: * @return the object bound to name, not following the terminal link
388: * (if any).
389: * @exception NamingException if a naming exception is encountered
390: */
391: public Object lookupLink(Name name) throws NamingException {
392: return getBoundContext().lookupLink(parseName(name));
393: }
394:
395: /**
396: * Retrieves the named object, following links except for the terminal
397: * atomic component of the name.
398: *
399: * @param name the name of the object to look up
400: * @return the object bound to name, not following the terminal link
401: * (if any).
402: * @exception NamingException if a naming exception is encountered
403: */
404: public Object lookupLink(String name) throws NamingException {
405: return getBoundContext().lookupLink(parseName(name));
406: }
407:
408: /**
409: * Retrieves the parser associated with the named context. In a
410: * federation of namespaces, different naming systems will parse names
411: * differently. This method allows an application to get a parser for
412: * parsing names into their atomic components using the naming convention
413: * of a particular naming system. Within any single naming system,
414: * NameParser objects returned by this method must be equal (using the
415: * equals() test).
416: *
417: * @param name the name of the context from which to get the parser
418: * @return a name parser that can parse compound names into their atomic
419: * components
420: * @exception NamingException if a naming exception is encountered
421: */
422: public NameParser getNameParser(Name name) throws NamingException {
423: return getBoundContext().getNameParser(parseName(name));
424: }
425:
426: /**
427: * Retrieves the parser associated with the named context.
428: *
429: * @param name the name of the context from which to get the parser
430: * @return a name parser that can parse compound names into their atomic
431: * components
432: * @exception NamingException if a naming exception is encountered
433: */
434: public NameParser getNameParser(String name) throws NamingException {
435: return getBoundContext().getNameParser(parseName(name));
436: }
437:
438: /**
439: * Composes the name of this context with a name relative to this context.
440: * <p>
441: * Given a name (name) relative to this context, and the name (prefix)
442: * of this context relative to one of its ancestors, this method returns
443: * the composition of the two names using the syntax appropriate for the
444: * naming system(s) involved. That is, if name names an object relative
445: * to this context, the result is the name of the same object, but
446: * relative to the ancestor context. None of the names may be null.
447: *
448: * @param name a name relative to this context
449: * @param prefix the name of this context relative to one of its ancestors
450: * @return the composition of prefix and name
451: * @exception NamingException if a naming exception is encountered
452: */
453: public Name composeName(Name name, Name prefix)
454: throws NamingException {
455: prefix = (Name) name.clone();
456: return prefix.addAll(name);
457: }
458:
459: /**
460: * Composes the name of this context with a name relative to this context.
461: *
462: * @param name a name relative to this context
463: * @param prefix the name of this context relative to one of its ancestors
464: * @return the composition of prefix and name
465: * @exception NamingException if a naming exception is encountered
466: */
467: public String composeName(String name, String prefix)
468: throws NamingException {
469: return prefix + "/" + name;
470: }
471:
472: /**
473: * Adds a new environment property to the environment of this context. If
474: * the property already exists, its value is overwritten.
475: *
476: * @param propName the name of the environment property to add; may not
477: * be null
478: * @param propVal the value of the property to add; may not be null
479: * @exception NamingException if a naming exception is encountered
480: */
481: public Object addToEnvironment(String propName, Object propVal)
482: throws NamingException {
483: return getBoundContext().addToEnvironment(propName, propVal);
484: }
485:
486: /**
487: * Removes an environment property from the environment of this context.
488: *
489: * @param propName the name of the environment property to remove;
490: * may not be null
491: * @exception NamingException if a naming exception is encountered
492: */
493: public Object removeFromEnvironment(String propName)
494: throws NamingException {
495: return getBoundContext().removeFromEnvironment(propName);
496: }
497:
498: /**
499: * Retrieves the environment in effect for this context. See class
500: * description for more details on environment properties.
501: * The caller should not make any changes to the object returned: their
502: * effect on the context is undefined. The environment of this context
503: * may be changed using addToEnvironment() and removeFromEnvironment().
504: *
505: * @return the environment of this context; never null
506: * @exception NamingException if a naming exception is encountered
507: */
508: public Hashtable getEnvironment() throws NamingException {
509: return getBoundContext().getEnvironment();
510: }
511:
512: /**
513: * Closes this context. This method releases this context's resources
514: * immediately, instead of waiting for them to be released automatically
515: * by the garbage collector.
516: * This method is idempotent: invoking it on a context that has already
517: * been closed has no effect. Invoking any other method on a closed
518: * context is not allowed, and results in undefined behaviour.
519: *
520: * @exception NamingException if a naming exception is encountered
521: */
522: public void close() throws NamingException {
523: getBoundContext().close();
524: }
525:
526: /**
527: * Retrieves the full name of this context within its own namespace.
528: * <p>
529: * Many naming services have a notion of a "full name" for objects in
530: * their respective namespaces. For example, an LDAP entry has a
531: * distinguished name, and a DNS record has a fully qualified name. This
532: * method allows the client application to retrieve this name. The string
533: * returned by this method is not a JNDI composite name and should not be
534: * passed directly to context methods. In naming systems for which the
535: * notion of full name does not make sense,
536: * OperationNotSupportedException is thrown.
537: *
538: * @return this context's name in its own namespace; never null
539: * @exception OperationNotSupportedException if the naming system does
540: * not have the notion of a full name
541: * @exception NamingException if a naming exception is encountered
542: */
543: public String getNameInNamespace() throws NamingException {
544: return prefix;
545: }
546:
547: // ------------------------------------------------------ Protected Methods
548:
549: /**
550: * Get the bound context.
551: */
552: protected Context getBoundContext() throws NamingException {
553:
554: if (initialContext) {
555: String ICName = IC_PREFIX;
556: if (ContextBindings.isThreadBound()) {
557: ICName += ContextBindings.getThreadName();
558: } else if (ContextBindings.isClassLoaderBound()) {
559: ICName += ContextBindings.getClassLoaderName();
560: }
561: Context initialContext = ContextBindings.getContext(ICName);
562: if (initialContext == null) {
563: // Allocating a new context and binding it to the appropriate
564: // name
565: initialContext = new NamingContext(env, ICName);
566: ContextBindings.bindContext(ICName, initialContext);
567: }
568: return initialContext;
569: } else {
570: if (ContextBindings.isThreadBound()) {
571: return ContextBindings.getThread();
572: } else {
573: return ContextBindings.getClassLoader();
574: }
575: }
576:
577: }
578:
579: /**
580: * Strips the URL header.
581: *
582: * @return the parsed name
583: * @exception NamingException if there is no "java:" header or if no
584: * naming context has been bound to this thread
585: */
586: protected String parseName(String name) throws NamingException {
587:
588: if ((!initialContext) && (name.startsWith(prefix))) {
589: return (name.substring(prefixLength));
590: } else {
591: if (initialContext) {
592: return (name);
593: } else {
594: throw new NamingException(sm
595: .getString("selectorContext.noJavaUrl"));
596: }
597: }
598:
599: }
600:
601: /**
602: * Strips the URL header.
603: *
604: * @return the parsed name
605: * @exception NamingException if there is no "java:" header or if no
606: * naming context has been bound to this thread
607: */
608: protected Name parseName(Name name) throws NamingException {
609:
610: if ((!initialContext) && (!name.isEmpty())
611: && (name.get(0).equals(prefix))) {
612: return (name.getSuffix(1));
613: } else {
614: if (initialContext) {
615: return (name);
616: } else {
617: throw new NamingException(sm
618: .getString("selectorContext.noJavaUrl"));
619: }
620: }
621:
622: }
623:
624: }
|