diff options
Diffstat (limited to 'libjava/classpath/javax/naming')
19 files changed, 1512 insertions, 383 deletions
diff --git a/libjava/classpath/javax/naming/CompositeName.java b/libjava/classpath/javax/naming/CompositeName.java index 6f3466c..322f632 100644 --- a/libjava/classpath/javax/naming/CompositeName.java +++ b/libjava/classpath/javax/naming/CompositeName.java @@ -47,11 +47,18 @@ import java.util.NoSuchElementException; import java.util.Vector; /** + * Represents names that may span over several namespaces. For instance, + * the composite name http://www.gnu.org/software/classpath/index.html spans + * over three namespaces (the protocol http, the web server location + * (www.gnu.org) and the index.html location on the server). + * * @author Tom Tromey (tromey@redhat.com) */ public class CompositeName implements Name, Cloneable, Serializable { private static final long serialVersionUID = 1667768148915813118L; + + private transient Vector elts; public CompositeName () { @@ -331,6 +338,4 @@ public class CompositeName implements Name, Cloneable, Serializable for (int i = 0; i < elts.size(); i++) s.writeObject(elts.get(i)); } - - private transient Vector elts; } diff --git a/libjava/classpath/javax/naming/CompoundName.java b/libjava/classpath/javax/naming/CompoundName.java index b23736f..556edfc 100644 --- a/libjava/classpath/javax/naming/CompoundName.java +++ b/libjava/classpath/javax/naming/CompoundName.java @@ -48,6 +48,10 @@ import java.util.Properties; import java.util.Vector; /** + * Represents hierarchical names from the single namespace. For instance, + * the path /home/audriusa/classpath/file.txt is the compound name, using + * the filesystem namespace. + * * @author Tom Tromey (tromey@redhat.com) * @date May 16, 2001 * diff --git a/libjava/classpath/javax/naming/Context.java b/libjava/classpath/javax/naming/Context.java index 9df82c68..46b5403 100644 --- a/libjava/classpath/javax/naming/Context.java +++ b/libjava/classpath/javax/naming/Context.java @@ -1,5 +1,5 @@ -/* Context.java -- - Copyright (C) 2000 Free Software Foundation, Inc. +/* Context.java -- A naming context + Copyright (C) 2000, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -40,121 +40,453 @@ package javax.naming; import java.util.Hashtable; +import javax.naming.directory.InvalidAttributesException; + public interface Context { - // Property with name of the inital context factory to use - String INITIAL_CONTEXT_FACTORY - = "java.naming.factory.initial"; - - // Property with colon-separated list of object factories to use. - String OBJECT_FACTORIES - = "java.naming.factory.object"; - - // Property with colon-separated list of state factories to use. - String STATE_FACTORIES - = "java.naming.factory.state"; - - // Property with colon-separated list of package prefixes to use. - String URL_PKG_PREFIXES - = "java.naming.factory.url.pkgs"; - - // Property with URL specifying configuration for the service - // provider to use. - String PROVIDER_URL - = "java.naming.provider.url"; + /** + * Property with name of the inital context factory to use + */ + String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"; + + /** + * Property with colon-separated list of object factories to use. + */ + String OBJECT_FACTORIES = "java.naming.factory.object"; + + /** + * Property with colon-separated list of state factories to use. + */ + String STATE_FACTORIES = "java.naming.factory.state"; + + /** + * Property with colon-separated list of package prefixes to use. + */ + String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs"; + + /** + * Property with URL specifying configuration for the service provider to use. + */ + String PROVIDER_URL = "java.naming.provider.url"; + + /** + * Property with the DNS host and domain names to use. + */ + String DNS_URL = "java.naming.dns.url"; + + /** + * Property with the authoritativeness of the service requested. + */ + String AUTHORITATIVE = "java.naming.authoritative"; + + /** + * Property with the batch size to use when returning data via the service's + * protocol. + */ + String BATCHSIZE = "java.naming.batchsize"; + + /** + * Property defining how referrals encountered by the service provider are to + * be processed. + */ + String REFERRAL = "java.naming.referral"; + + /** + * Property specifying the security protocol to use. + */ + String SECURITY_PROTOCOL = "java.naming.security.protocol"; + + /** + * Property specifying the security level to use. + */ + String SECURITY_AUTHENTICATION = "java.naming.security.authentication"; + + /** + * Property for the identity of the principal for authenticating the caller to + * the service. + */ + String SECURITY_PRINCIPAL = "java.naming.security.principal"; + + /** + * Property specifying the credentials of the principal for authenticating the + * caller to the service. + */ + String SECURITY_CREDENTIALS = "java.naming.security.credentials"; + + /** + * Property for specifying the preferred language to use with the service. + */ + String LANGUAGE = "java.naming.language"; + + /** + * Property for the initial context constructor to use when searching for + * other properties. + */ + String APPLET = "java.naming.applet"; + + /** + * Give the specified name for the specified object. The passed name must not + * be already bound to some other object. + * + * @param name the name that will be given to the object (in the scope of this + * context). + * @param obj the object being named. + * @throws NameAlreadyBoundException if this name is already used to name some + * object. + * @throws InvalidAttributesException if the object does not supply all + * required attributes. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void bind(Name name, Object obj) throws NamingException; + + /** + * Give the specified name for the specified object. The passed name must not + * be already bound to some other object. + * + * @param name the name that will be given to the object (in the scope of this + * context). + * @param obj the object being named. + * @throws NameAlreadyBoundException if this name is already used to name some + * object. + * @throws InvalidAttributesException if the object does not supply all + * required attributes. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void bind(String name, Object obj) throws NamingException; + + /** + * Gets the previously named object by name. If the passed name is empty, the + * method should return a cloned instance of this naming context. + * + * @param name the name of the object being searched in this context + * @return the named object + * @throws NamingException if the naming fails. + */ + Object lookup(Name name) throws NamingException; + + /** + * Gets the previously named object by name. If the passed name is empty, the + * method should return a cloned instance of this naming context. + * + * @param name the name of the object being searched in this context + * @return the named object + * @throws NamingException if the naming fails. + */ + Object lookup(String name) throws NamingException; + + /** + * Give the specified name for the specified object. Unlike bind, this method + * silently replaces the existing binding for this name, if one exists. + * + * @param name the name that will be given to the object (in the scope of this + * context). + * @param obj the object being named. + * @throws InvalidAttributesException if the object does not supply all + * required attributes. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void rebind(Name name, Object obj) throws NamingException; + + /** + * Give the specified name for the specified object. Unlike bind, this method + * silently replaces the existing binding for this name, if one exists. + * + * @param name the name that will be given to the object (in the scope of this + * context). + * @param obj the object being named. + * @throws InvalidAttributesException if the object does not supply all + * required attributes. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void rebind(String name, Object obj) throws NamingException; + + /** + * Removes the name - object mapping from the current context. This method + * returns without action if the name is not bound to an object in the + * terminal context, but throws {@link NameNotFoundException} if one of the + * intermadiate contexts does not exist. + * + * @param name the name to be removed + * @throws NameNotFoundException if one of the intermediate naming contexts + * does not exist. Will not be thrown if just the terminal binding + * is missing. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void unbind(Name name) throws NamingException; + + /** + * Removes the name - object mapping from the current context. This method + * returns without action if the name is not bound to an object in the + * terminal context, but throws {@link NameNotFoundException} if one of the + * intermadiate contexts does not exist. + * + * @param name the name to be removed + * @throws NameNotFoundException if one of the intermediate naming contexts + * does not exist. Will not be thrown if just the terminal binding + * is missing. + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void unbind(String name) throws NamingException; + + /** + * Renames the existing binding, removing the existing and giving the new name + * for the same object. + * + * @param oldName the existing name of the known object + * @param newName the new name of the same object + * @throws NameNotFoundException if the oldName is unknown for this context + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void rename(Name oldName, Name newName) throws NamingException; + + /** + * Renames the existing binding, removing the existing and giving the new name + * for the same object. + * + * @param oldName the existing name of the known object + * @param newName the new name of the same object + * @throws NameNotFoundException if the oldName is unknown for this context + * @throws NamingException if the naming operation has failed due other + * reasons. + */ + void rename(String oldName, String newName) throws NamingException; + + /** + * Creates and returns the enumeration over the name bindings that are present + * the given subcontext. The enumeration elements have the type of + * {@link NameClassPair}, providing also information about the class of the + * bound object. The behaviour in the case if the bindings are added or + * removed later is not defined. The contents of the subcontexts are not + * included. + * + * @param name the name of the subcontext + * @return the enumeration over the names, known for the given subcontext. + * @throws NamingException + */ + NamingEnumeration list(Name name) throws NamingException; + + /** + * Creates and returns the enumeration over the name bindings that are present + * the given subcontext. The enumeration elements have the type of + * {@link NameClassPair}, providing also information about the class of the + * bound object. The behaviour in the case if the bindings are added or + * removed later is not defined. The contents of the subcontexts are not + * included. + * + * @param name the name of the subcontext + * @return the enumeration over the names, known for the given subcontext. + * @throws NamingException + */ + NamingEnumeration list(String name) throws NamingException; + + /** + * Creates and returns the enumeration over the name - object bindings that + * are present the given subcontext. The enumeration elements have the type of + * {@link Binding}, providing also information about the class of the bound + * object. The behaviour in the case if the bindings are added or removed + * later is not defined. The contents of the subcontexts are not included. + * + * @param name the name of the subcontext + * @return the enumeration over the names, known for the given subcontext. + * @throws NamingException + */ + NamingEnumeration listBindings(Name name) throws NamingException; + + /** + * Creates and returns the enumeration over the name - object bindings that + * are present the given subcontext. The enumeration elements have the type of + * {@link Binding}, providing also information about the class of the bound + * object. The behaviour in the case if the bindings are added or removed + * later is not defined. The contents of the subcontexts are not included. + * + * @param name the name of the subcontext + * @return the enumeration over the names, known for the given subcontext. + * @throws NamingException + */ + NamingEnumeration listBindings(String name) throws NamingException; + + /** + * Creates the new naming subcontext and binds it to the current (this) + * context. + * + * @param name the name of the new context being created + * @return the newly created context, bound to the instance of the context on + * that the method has been called + * @throws NameAlreadyBoundException if this name is already bound + * @throws InvalidAttributesException if the creation of the new context + * requires the missing mandatory attributes + * @throws NamingException + */ + Context createSubcontext(Name name) throws NamingException; + + /** + * Creates the new naming subcontext and binds it to the current (this) + * context. + * + * @param name the name of the new context being created + * @return the newly created context, bound to the instance of the context on + * that the method has been called + * @throws NameAlreadyBoundException if this name is already bound + * @throws InvalidAttributesException if the creation of the new context + * requires the missing mandatory attributes + * @throws NamingException + */ + Context createSubcontext(String name) throws NamingException; + + /** + * Removes the naming subcontext from this naming context. Returns without + * action if such subcontext does not exist. The context being destroyed must + * be empty. + * + * @param name the name of the subcontext beig removed. + * @throws ContextNotEmptyException if the named context is not empty. + * @throws NamingException + */ + void destroySubcontext(Name name) throws NamingException; + + /** + * Removes the naming subcontext from this naming context. Returns without + * action if such subcontext does not exist. The context being destroyed must + * be empty. + * + * @param name the name of the subcontext beig removed. + * @throws ContextNotEmptyException if the named context is not empty. + * @throws NamingException + */ + void destroySubcontext(String name) throws NamingException; + + /** + * Retrieves the named object, not following the link of the terminal atomic + * component of the name. If the object, named by the passed name, is not a + * link, returns that object itself. The intermediate links, if present, are + * followed. + * + * @param name the name of the object that may be a link, leading to another + * object. + * @return the named object, not following the terminal link (if present). + * @throws NamingException + */ + Object lookupLink(Name name) throws NamingException; + + /** + * Retrieves the named object, not following the link of the terminal atomic + * component of the name. If the object, named by the passed name, is not a + * link, returns that object itself. The intermediate links, if present, are + * followed. + * + * @param name the name of the object that may be a link, leading to another + * object. + * @return the named object, not following the terminal link (if present). + * @throws NamingException + */ + Object lookupLink(String name) throws NamingException; - // Property with the DNS host and domain names to use. - String DNS_URL - = "java.naming.dns.url"; + /** + * Obtains the name parser for parsing the names of the given naming + * subcontext. + * + * @param name the name of the subcontext for that the parser must be obtained + * @return the parser to parse the names of that context + * @throws NamingException + */ + NameParser getNameParser(Name name) throws NamingException; + + /** + * Obtains the name parser for parsing the names of the given naming + * subcontext. + * + * @param name the name of the subcontext for that the parser must be obtained + * @return the parser to parse the names of that context + * @throws NamingException + */ + NameParser getNameParser(String name) throws NamingException; - // Property with the authoritativeness of the service requested. - String AUTHORITATIVE - = "java.naming.authoritative"; + /** + * Composes the name of this context together with another name, related to + * this context. + * + * @param name a name, defined in the scope of this context + * @param prefix a name of this context itself, defined in the scope of some + * ancestor + * @return the name of the same object as named by the first parameter, but + * related to the context of the specified ancestor. + * @throws NamingException + */ + Name composeName(Name name, Name prefix) throws NamingException; + + /** + * Composes the name of this context together with another name, related to + * this context. + * + * @param name a name, defined in the scope of this context + * @param prefix a name of this context itself, defined in the scope of some + * ancestor + * @return the name of the same object as named by the first parameter, but + * related to the context of the specified ancestor. + * @throws NamingException + */ + String composeName(String name, String prefix) throws NamingException; - // Property with the batch size to use when returning data via the - // service's protocol. - String BATCHSIZE - = "java.naming.batchsize"; + /** + * Add new environment property to the environment of this context. Both name + * and value of the new property must not be null. If the property is already + * defined, is current value is replaced by the propVal. + * + * @param propName the name of the new property + * @param propVal the value of the new property + * @return the previous value of this property or null if the property has not + * been previously defined + * @throws NamingException + */ + Object addToEnvironment(String propName, Object propVal) + throws NamingException; - // Property defining how referrals encountered by the service - // provider are to be processed. - String REFERRAL - = "java.naming.referral"; - - // Property specifying the security protocol to use. - String SECURITY_PROTOCOL - = "java.naming.security.protocol"; - - // Property specifying the security level to use. - String SECURITY_AUTHENTICATION - = "java.naming.security.authentication"; - - // Property for the identity of the principal for authenticating - // the caller to the service. - String SECURITY_PRINCIPAL - = "java.naming.security.principal"; - - // Property specifying the credentials of the principal for - // authenticating the caller to the service. - String SECURITY_CREDENTIALS - = "java.naming.security.credentials"; - - // Property for specifying the preferred language to use with the - // service. - String LANGUAGE - = "java.naming.language"; - - // Property for the initial context constructor to use when searching - // for other properties. - String APPLET - = "java.naming.applet"; - - void bind (Name name, Object obj) throws NamingException; - void bind (String name, Object obj) throws NamingException; - - Object lookup (Name name) throws NamingException; - Object lookup (String name) throws NamingException; - - void rebind (Name name, Object obj) throws NamingException; - void rebind (String name, Object obj) throws NamingException; - - void unbind (Name name) throws NamingException; - void unbind (String name) throws NamingException; - - void rename (Name oldName, Name newName) throws NamingException; - void rename (String oldName, String newName) throws NamingException; - - NamingEnumeration list (Name name) throws NamingException; - NamingEnumeration list (String name) throws NamingException; - - NamingEnumeration listBindings (Name name) throws NamingException; - NamingEnumeration listBindings (String name) throws NamingException; - - void destroySubcontext (Name name) throws NamingException; - void destroySubcontext (String name) throws NamingException; - - Context createSubcontext (Name name) throws NamingException; - Context createSubcontext (String name) throws NamingException; - - Object lookupLink (Name name) throws NamingException; - Object lookupLink (String name) throws NamingException; - - NameParser getNameParser (Name name) throws NamingException; - NameParser getNameParser (String name) throws NamingException; - - Name composeName (Name name, Name prefix) throws NamingException; - String composeName (String name, - String prefix) throws NamingException; - - Object addToEnvironment (String propName, - Object propVal) throws NamingException; - - Object removeFromEnvironment (String propName) throws NamingException; - - Hashtable getEnvironment () throws NamingException; - - void close () throws NamingException; - - String getNameInNamespace () throws NamingException; + /** + * Removes the property with the given name from the environment. Returns + * without action if this property is not defined. + * + * @param propName the name of the property being removed. + * @return the value of the property that has been removed or null if the + * property was not defined. + * @throws NamingException + */ + Object removeFromEnvironment(String propName) throws NamingException; + + /** + * Returns the environment, associated with this naming context. The returned + * table should never be modified by the caller. Use {@link #addToEnvironment} + * and {@link #removeFromEnvironment} to modify the environement, if needed. + * + * @return the table, representing the environment of this context + * @throws NamingException + */ + Hashtable getEnvironment() throws NamingException; + + /** + * Releases all resources, associated with this context. The close() method + * can be called several times, but after it has been once invoked, it is not + * allowed to call any other method of this context, + * + * @throws NamingException + */ + void close() throws NamingException; + + /** + * Returs the full name of this naming context. The returned string is not a + * JNDI composite name and should not be passed directly to the methods of the + * naming context. + * + * @return the full name of this naming context, in its own namespace. + * @throws OperationNotSupportedException if the naming system, represented by + * this context, does not support the notation of the full name. + * @throws NamingException + */ + String getNameInNamespace() throws NamingException; } - diff --git a/libjava/classpath/javax/naming/ContextNotEmptyException.java b/libjava/classpath/javax/naming/ContextNotEmptyException.java index acbd46b..e856341 100644 --- a/libjava/classpath/javax/naming/ContextNotEmptyException.java +++ b/libjava/classpath/javax/naming/ContextNotEmptyException.java @@ -38,7 +38,12 @@ exception statement from your version. */ package javax.naming; - +/** + * This exception is thrown in response to the attempt to destroy the non + * empty context. Only empty contexts (without bindings) can be destroyed. + * + * @see Context#destroySubcontext + */ public class ContextNotEmptyException extends NamingException { private static final long serialVersionUID = 1090963683348219877L; diff --git a/libjava/classpath/javax/naming/InitialContext.java b/libjava/classpath/javax/naming/InitialContext.java index 1a9ee5a..d4a9587 100644 --- a/libjava/classpath/javax/naming/InitialContext.java +++ b/libjava/classpath/javax/naming/InitialContext.java @@ -1,5 +1,5 @@ -/* InitialContext.java -- - Copyright (C) 2000, 2002, 2003, 2004 Free Software Foundation, Inc. +/* InitialContext.java -- Initial naming context. + Copyright (C) 2000, 2002, 2003, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -43,170 +43,291 @@ import java.io.IOException; import java.io.InputStream; import java.net.URL; import java.util.Enumeration; +import java.util.HashSet; import java.util.Hashtable; import java.util.Properties; import javax.naming.spi.NamingManager; +/** + * The starting context for performing naming operations. All naming operations + * are performed in the scope of some context. The initial context is the + * starting point for the name resolution. + */ public class InitialContext implements Context { + /** + * Contains the default initial context. This value is returned by + * {@link NamingManager#getInitialContext}. It is set by this method + * when calling it first time. The subsequent calls return the value of + * this field. + */ protected Context defaultInitCtx; + + /** + * Indicates if the initial context was obtained by calling + * {@link NamingManager#getInitialContext}. + */ protected boolean gotDefault = false; + + /** + * The environment, associated with this initial context. + */ protected Hashtable myProps; - public InitialContext (Hashtable environment) - throws NamingException + /** + * The list of the properties, to that the second alternative value must + * be appended after the colon to the first possible value. Used in + * {@link #merge(Hashtable, Hashtable)} + */ + static final HashSet colon_list; + static + { + colon_list = new HashSet(); + colon_list.add(Context.OBJECT_FACTORIES); + colon_list.add(Context.URL_PKG_PREFIXES); + colon_list.add(Context.STATE_FACTORIES); + }; + + /** + * The properties that are searched in the agreed places in the + * {@link #init(Hashtable)} method. + */ + static final String[] use_properties = + { + Context.DNS_URL, + Context.INITIAL_CONTEXT_FACTORY, + Context.OBJECT_FACTORIES, + Context.PROVIDER_URL, + Context.STATE_FACTORIES, + Context.URL_PKG_PREFIXES, + }; + + + /** + * Creates the new initial context with the given properties. + * + * @param environment the properties, used by the initial context being + * created. + * @throws NamingException + */ + public InitialContext(Hashtable environment) throws NamingException { - init (environment); + init(environment); } - protected InitialContext (boolean lazy) - throws NamingException + /** + * Creates the initial context with the possibility to delay its + * initialisation. + * + * @param lazy specified if the initialization should not be performed by this + * constructor (true). If the valueis false, it works the same way as + * the parameterless constructor. + * @throws NamingException + */ + protected InitialContext(boolean lazy) throws NamingException { if (! lazy) - init (null); + init(null); } - public InitialContext () - throws NamingException + /** + * Creates teh new initial context with no properties. Same as + * InitialContext(null). + * + * @throws NamingException + */ + public InitialContext() throws NamingException { - init (null); + init(null); } - /** @since 1.3 */ - protected void init (Hashtable environment) - throws NamingException - { - // FIXME: Is this enough? - final String[] properties = { - Context.DNS_URL, - Context.INITIAL_CONTEXT_FACTORY, - Context.OBJECT_FACTORIES, - Context.PROVIDER_URL, - Context.STATE_FACTORIES, - Context.URL_PKG_PREFIXES, - }; - - // Create myProps, cloning environment if needed. + /** + * <p> + * Initialises the context, using the properties, specified in the passed + * table. + * </p> + * The missing properties are additionally obtained (in order) from the + * following locations: + * <ul> + * <li>If the passed parameter contains the key Context.APPLET, its value + * must be the instance of the {@link Applet}. Then the properties are + * requested via {@link Applet#getParameter(String)}.</li> + * <li>The value of the system property is used.</li> + * <li>The resource "jndi.properties" is requested from the context class + * loader of the current thread</li> + * <li>The property file "jndi.properties" is read from the location, + * specified by the system property "gnu.classpath.home.url". + * </ul> + * </p> + * + * @param environment the table of the properties, may be null. The method + * modifies the table and stores the reference to it. The caller must + * not later reuse this structure for other purposes. + * @since 1.3 + */ + protected void init(Hashtable environment) throws NamingException + { + // If is documented that the caller should not modify the environment. if (environment != null) - myProps = (Hashtable) environment.clone (); + myProps = environment; else - myProps = new Hashtable (); - - Applet napplet = (Applet) myProps.get (Context.APPLET); - - for (int i = properties.length - 1; i >= 0; i--) + myProps = new Hashtable(); + + Applet napplet = (Applet) myProps.get(Context.APPLET); + + Properties pApplet = null; + if (napplet != null) + pApplet = new Properties(); + Properties pSystem = new Properties(); + Object value; + + for (int i = use_properties.length - 1; i >= 0; i--) { - Object o = myProps.get (properties[i]); - - if (o == null) - { - if (napplet != null) - o = napplet.getParameter (properties[i]); - if (o == null) - o = System.getProperty (properties[i]); - if (o != null) - myProps.put (properties[i], o); - } + String key = use_properties[i]; + if (napplet != null) + { + value = napplet.getParameter(key); + if (value != null) + pApplet.put(key, value); + } + + value = System.getProperty(key); + if (value != null) + pSystem.put(key, value); } + + merge(myProps, pSystem); + if (pApplet != null) + merge(myProps, pApplet); try { - Enumeration ep = Thread.currentThread().getContextClassLoader().getResources("jndi.naming"); - while (ep.hasMoreElements ()) - { - URL url = (URL) ep.nextElement (); - Properties p = new Properties (); - - try - { - InputStream is = url.openStream (); - p.load (is); - is.close (); - } - catch (IOException e) - { - } - - merge (myProps, p); - } + Enumeration ep = Thread.currentThread(). + getContextClassLoader().getResources("jndi.properties"); + while (ep.hasMoreElements()) + { + URL url = (URL) ep.nextElement(); + Properties p = new Properties(); + + try + { + InputStream is = url.openStream(); + p.load(is); + is.close(); + } + catch (IOException e) + { + // Ignore. + } + + merge(myProps, p); + } } catch (IOException e) { + // Ignore. } String home = System.getProperty("gnu.classpath.home.url"); if (home != null) { - String url = home + "/jndi.properties"; - Properties p = new Properties (); - - try - { - InputStream is = new URL(url).openStream(); - p.load (is); - is.close (); - } - catch (IOException e) - { - // Ignore. - } - - merge (myProps, p); + String url = home + "/jndi.properties"; + Properties p = new Properties(); + + try + { + InputStream is = new URL(url).openStream(); + p.load(is); + is.close(); + } + catch (IOException e) + { + // Ignore. + } + + merge(myProps, p); } } - - // FIXME: Is this enough? - private static final String[] colon_list = - { - Context.OBJECT_FACTORIES, - Context.URL_PKG_PREFIXES, - Context.STATE_FACTORIES - }; - - private static void merge (Hashtable h1, Hashtable h2) - { - Enumeration e2 = h2.keys(); + + /** + * Merge the content of the two tables. If the second table contains the key + * that is missing in the first table, this key - value pair is copied to the + * first table. If both first and second tables contain the same key AND the + * {@link #colon_list} set also contains this key, the value from the second + * table is appended to the value from the first table after semicolon, and + * the resulted value replaces the value in the first table. + * + * @param primary the first table to merge. The merged result is also stored + * in this table. + * @param additional the second table, from where additional values are taken + */ + static void merge (Hashtable primary, Hashtable additional) + { + Enumeration en = additional.keys(); - while (e2.hasMoreElements()) + while (en.hasMoreElements()) { - String key2 = (String) e2.nextElement(); - Object value1 = h1.get(key2); - if (value1 == null) - h1.put(key2, h2.get(key2)); - else if (key2.compareTo(colon_list[0]) == 0 - || key2.compareTo(colon_list[1]) == 0 - || key2.compareTo(colon_list[2]) == 0 - || key2.compareTo(colon_list[3]) == 0) - { - String value2 = (String) h2.get(key2); - h1.put(key2, (String) value1 + ":" + value2); - } + String key2 = (String) en.nextElement(); + Object value1 = primary.get(key2); + if (value1 == null) + primary.put(key2, additional.get(key2)); + else if (colon_list.contains(key2)) + { + String value2 = (String) additional.get(key2); + primary.put(key2, (String) value1 + ":" + value2); + } } } - - protected Context getDefaultInitCtx () throws NamingException + + /** + * Get the default initial context. If {@link #gotDefault} == false, this + * method obtains the initial context from the naming manager and sets + * gotDefault to true. Otherwise the cached value ({@link #defaultInitCtx} is + * returned. + * + * @return the default initial context + * @throws NamingException + */ + protected Context getDefaultInitCtx() throws NamingException { if (! gotDefault) { - defaultInitCtx = NamingManager.getInitialContext (myProps); - gotDefault = true; + defaultInitCtx = NamingManager.getInitialContext(myProps); + gotDefault = true; } return defaultInitCtx; } - - protected Context getURLOrDefaultInitCtx (Name name) - throws NamingException - { - if (name.size () > 0) - return getURLOrDefaultInitCtx (name.get (0)); + /** + * Obtains the context for resolving the given name. If the first component of + * the name is the URL string, this method tries to find the corressponding + * URL naming context. If it is not an URL string, or the URL context is not + * found, the default initial context is returned. + * + * @param name the name, for that it is required to obtain the context. + * @return the context for resolving the name. + * @throws NamingException + */ + protected Context getURLOrDefaultInitCtx(Name name) throws NamingException + { + if (name.size() > 0) + return getURLOrDefaultInitCtx(name.get(0)); else - return getDefaultInitCtx (); + return getDefaultInitCtx(); } - protected Context getURLOrDefaultInitCtx (String name) - throws NamingException + /** + * Obtains the context for resolving the given name. If the first component of + * the name is the URL string, this method tries to find the corressponding + * URL naming context. If it is not an URL string, or the URL context is not + * found, the default initial context is returned. + * + * @param name the name, for that it is required to obtain the context. + * @return the context for resolving the name. + * @throws NamingException + */ + protected Context getURLOrDefaultInitCtx(String name) throws NamingException { String scheme = null; @@ -214,178 +335,211 @@ public class InitialContext implements Context return getDefaultInitCtx(); int colon = name.indexOf(':'); int slash = name.indexOf('/'); - if (colon > 0 && (slash == -1 || colon < slash)) + if (colon > 0 && (slash == - 1 || colon < slash)) scheme = name.substring(0, colon); - if (scheme != null) + if (scheme != null) { - Context context = - NamingManager.getURLContext(scheme, myProps); - if (context != null) - return context; + Context context = NamingManager.getURLContext(scheme, myProps); + if (context != null) + return context; } - + return getDefaultInitCtx(); } + /** @inheritDoc */ public void bind (Name name, Object obj) throws NamingException { getURLOrDefaultInitCtx (name).bind (name, obj); } + /** @inheritDoc */ public void bind (String name, Object obj) throws NamingException { getURLOrDefaultInitCtx (name).bind (name, obj); } + /** @inheritDoc */ public Object lookup (Name name) throws NamingException { try { - return getURLOrDefaultInitCtx (name).lookup (name); + return getURLOrDefaultInitCtx (name).lookup (name); } catch (CannotProceedException cpe) { - Context ctx = NamingManager.getContinuationContext (cpe); - return ctx.lookup (cpe.getRemainingName()); + Context ctx = NamingManager.getContinuationContext (cpe); + return ctx.lookup (cpe.getRemainingName()); } } + /** @inheritDoc */ public Object lookup (String name) throws NamingException { try - { - return getURLOrDefaultInitCtx (name).lookup (name); - } + { + return getURLOrDefaultInitCtx (name).lookup (name); + } catch (CannotProceedException cpe) - { - Context ctx = NamingManager.getContinuationContext (cpe); - return ctx.lookup (cpe.getRemainingName()); - } + { + Context ctx = NamingManager.getContinuationContext (cpe); + return ctx.lookup (cpe.getRemainingName()); + } } + /** @inheritDoc */ public void rebind (Name name, Object obj) throws NamingException { getURLOrDefaultInitCtx (name).rebind (name, obj); } - + + /** @inheritDoc */ public void rebind (String name, Object obj) throws NamingException { getURLOrDefaultInitCtx (name).rebind (name, obj); } + /** @inheritDoc */ public void unbind (Name name) throws NamingException { getURLOrDefaultInitCtx (name).unbind (name); } + /** @inheritDoc */ public void unbind (String name) throws NamingException { getURLOrDefaultInitCtx (name).unbind (name); } + /** @inheritDoc */ public void rename (Name oldName, Name newName) throws NamingException { getURLOrDefaultInitCtx (oldName).rename (oldName, newName); } + /** @inheritDoc */ public void rename (String oldName, String newName) throws NamingException { getURLOrDefaultInitCtx (oldName).rename (oldName, newName); } + /** @inheritDoc */ public NamingEnumeration list (Name name) throws NamingException { return getURLOrDefaultInitCtx (name).list (name); } + /** @inheritDoc */ public NamingEnumeration list (String name) throws NamingException { return getURLOrDefaultInitCtx (name).list (name); } + /** @inheritDoc */ public NamingEnumeration listBindings (Name name) throws NamingException { return getURLOrDefaultInitCtx (name).listBindings (name); } + /** @inheritDoc */ public NamingEnumeration listBindings (String name) throws NamingException { return getURLOrDefaultInitCtx (name).listBindings (name); } + /** @inheritDoc */ public void destroySubcontext (Name name) throws NamingException { getURLOrDefaultInitCtx (name).destroySubcontext (name); } + /** @inheritDoc */ public void destroySubcontext (String name) throws NamingException { getURLOrDefaultInitCtx (name).destroySubcontext (name); } + /** @inheritDoc */ public Context createSubcontext (Name name) throws NamingException { return getURLOrDefaultInitCtx (name).createSubcontext (name); } + /** @inheritDoc */ public Context createSubcontext (String name) throws NamingException { return getURLOrDefaultInitCtx (name).createSubcontext (name); } + /** @inheritDoc */ public Object lookupLink (Name name) throws NamingException { return getURLOrDefaultInitCtx (name).lookupLink (name); } + /** @inheritDoc */ public Object lookupLink (String name) throws NamingException { return getURLOrDefaultInitCtx (name).lookupLink (name); } + /** @inheritDoc */ public NameParser getNameParser (Name name) throws NamingException { return getURLOrDefaultInitCtx (name).getNameParser (name); } + /** @inheritDoc */ public NameParser getNameParser (String name) throws NamingException { return getURLOrDefaultInitCtx (name).getNameParser (name); } + /** @inheritDoc */ public Name composeName (Name name, Name prefix) throws NamingException { return getURLOrDefaultInitCtx (name).composeName (name, prefix); } + /** @inheritDoc */ public String composeName (String name, - String prefix) throws NamingException + String prefix) throws NamingException { return getURLOrDefaultInitCtx (name).composeName (name, prefix); } - + + /** @inheritDoc */ public Object addToEnvironment (String propName, - Object propVal) throws NamingException + Object propVal) throws NamingException { return myProps.put (propName, propVal); } + /** @inheritDoc */ public Object removeFromEnvironment (String propName) throws NamingException { return myProps.remove (propName); } + /** @inheritDoc */ public Hashtable getEnvironment () throws NamingException { return myProps; } + /** @inheritDoc */ public void close () throws NamingException { myProps = null; defaultInitCtx = null; } + /** + * This operation is not supported for the initial naming context. + * + * @throws OperationNotSupportedException always, unless the method is + * overridden in the derived class. + */ public String getNameInNamespace () throws NamingException { throw new OperationNotSupportedException (); diff --git a/libjava/classpath/javax/naming/NameParser.java b/libjava/classpath/javax/naming/NameParser.java index 1aeaf36..004b406 100644 --- a/libjava/classpath/javax/naming/NameParser.java +++ b/libjava/classpath/javax/naming/NameParser.java @@ -1,5 +1,5 @@ -/* NameParser.java -- - Copyright (C) 2000 Free Software Foundation, Inc. +/* NameParser.java -- JNDI name parser interface + Copyright (C) 2000, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,8 +38,24 @@ exception statement from your version. */ package javax.naming; +/** + * Parser the string representation of the given name into the {@link Name} + * representation. + * + * @see Context#getNameParser(String) + * @see Context#getNameParser(Name) + */ public interface NameParser -{ +{ + /** + * Parser the string name representation into the {@link Name} representation + * + * @param name the string representation of the name + * @return the {@link Name} representation of the name. + * @throws InvalidNameException if the name violates the syntax, expected by + * this parser + * @throws NamingException if some other naming exception occurs + */ Name parse (String name) throws NamingException; } diff --git a/libjava/classpath/javax/naming/NamingEnumeration.java b/libjava/classpath/javax/naming/NamingEnumeration.java index 3c9ee2d..86b1dfb 100644 --- a/libjava/classpath/javax/naming/NamingEnumeration.java +++ b/libjava/classpath/javax/naming/NamingEnumeration.java @@ -1,5 +1,5 @@ -/* NamingEnumeration.java -- - Copyright (C) 2000 Free Software Foundation, Inc. +/* NamingEnumeration.java -- The JNDI enumeration + Copyright (C) 2000, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -40,9 +40,50 @@ package javax.naming; import java.util.Enumeration; +/** + * <p>The specific type of enumeration that supports throwing various exceptions by + * the hasMore method. The exceptions are only thrown if the enumeration is + * scanned using {@link #next()} and {@link #hasMore()}. If the inherited + * {@link java.util.Enumeration#nextElement()} and + * {@link Enumeration#hasMoreElements()} are used instead, the exceptions are + * not throwed, and the enumeration is just iterated over available elements. + * </p> + * <p>This enumeration becomes invalid after throwing the exception. If the + * exception has been thrown, not other method should be called of that + * enumeration.</p> + */ public interface NamingEnumeration extends Enumeration { - void close() throws NamingException; - boolean hasMore() throws NamingException; + /** + * Returns the next element in this enumeration. The naming - specific + * exceptions are only throws after returning all still available elements of + * the enumeration. + * + * @return the next element of this enumeration + * @throws NamingException + */ Object next() throws NamingException; + + /** + * Checks if there are more unvisited elements in the enumeration, throwing + * exceptions if there are some unvisited, but not available elements. + * + * @return true if there are some unvisited elements, false otherwise. + * @throws PartialResultException if the enumeration, returned by the + * {@link Context#list(Name)} or other similar method contains only + * partial answer. + * @throws SizeLimitExceededException if remaining elements are not available + * because of the previously specified size limit. + * @throws NamingException + */ + boolean hasMore() throws NamingException; + + /** + * Immediately frees all resources, owned by this enumeration. If invoked, it + * must be the last method called for that enumeration. + * + * @throws NamingException + */ + void close() throws NamingException; + } diff --git a/libjava/classpath/javax/naming/PartialResultException.java b/libjava/classpath/javax/naming/PartialResultException.java index 6166078..28f0467 100644 --- a/libjava/classpath/javax/naming/PartialResultException.java +++ b/libjava/classpath/javax/naming/PartialResultException.java @@ -38,7 +38,11 @@ exception statement from your version. */ package javax.naming; - +/** + * Thrown from the {@link javax.naming.NamingEnumeration}, this exception + * indicates that the enumeration represents only part of the existing + * elements that would be an answer to the specified request. + */ public class PartialResultException extends NamingException { private static final long serialVersionUID = 2572144970049426786L; diff --git a/libjava/classpath/javax/naming/Reference.java b/libjava/classpath/javax/naming/Reference.java index 5b9883a..0fdecc1 100644 --- a/libjava/classpath/javax/naming/Reference.java +++ b/libjava/classpath/javax/naming/Reference.java @@ -43,54 +43,118 @@ import java.util.Enumeration; import java.util.Vector; /** + * This class represents a reference to an object that is located outside of the + * naming/directory system. + * + * @see Referenceable + * * @author Tom Tromey (tromey@redhat.com) - * @date May 16, 2001 */ public class Reference implements Cloneable, Serializable { private static final long serialVersionUID = - 1673475790065791735L; - + + /** + * The list of addresses, stored in this reference. The object may be + * have by several different addresses. + */ + protected Vector addrs; + + /** + * The name of the class factory to create an instance of the object, + * referenced by this reference. + */ + protected String classFactory; + + /** + * The location, from where the class factory should be loaded. + */ + protected String classFactoryLocation; + + /** + * The name of the class of the object, to that this reference refers. + */ + protected String className; + + /** + * Create a new reference that is referencting to the object of the + * specified class. + */ public Reference (String className) { this.className = className; addrs = new Vector (); } - + + /** + * Create a new reference that is referencing to the object of the + * specified class with the given address. + */ public Reference (String className, RefAddr addr) { this.className = className; addrs = new Vector (); addrs.add (addr); } - - public Reference (String className, String factory, String factoryLocation) + + /** + * Create a new reference that is referencing to the object of the + * specified class, specifying the class and location of the factory that + * produces these objects. + * + * @param className the object class name + * @param factoryClassName the object factory class name + * @param factoryLocation the object factory location + */ + public Reference (String className, String factoryClassName, + String factoryLocation) { this.className = className; - this.classFactory = factory; + this.classFactory = factoryClassName; this.classFactoryLocation = factoryLocation; addrs = new Vector (); } + /** + * Create a new reference that is referencing to the object of the + * specified class, specifying the class and location of the factory that + * produces these objects and also the address of this object. + * + * @param className the object class name + * @param addr the address of the object + * @param factoryClassName the object factory class name + * @param factoryLocation the object factory location + */ public Reference (String className, RefAddr addr, - String factory, String factoryLocation) + String factoryClassName, String factoryLocation) { this.className = className; - this.classFactory = factory; + this.classFactory = factoryClassName; this.classFactoryLocation = factoryLocation; addrs = new Vector (); addrs.add (addr); } + /** + * Add the new address for this object at the given position of the + * address list. + */ public void add (int posn, RefAddr addr) { addrs.add (posn, addr); } - + + /** + * Appends the new object address to the end of the address list. + */ public void add (RefAddr addr) { addrs.add (addr); } - + + /** + * Removes all defined addresses of the object. + */ public void clear () { addrs.clear (); @@ -109,7 +173,10 @@ public class Reference implements Cloneable, Serializable { return (a == null) ? (b == null) : a.equals (b); } - + + /** + * Compares two addresses for equality, by value. + */ public boolean equals (Object obj) { if (! (obj instanceof Reference)) @@ -120,12 +187,23 @@ public class Reference implements Cloneable, Serializable && equals (className, r.className) && addrs.equals (r.addrs)); } - + + /** + * Get the address of this object at the given position. + */ public RefAddr get (int posn) { return (RefAddr) addrs.get (posn); } - + + /** + * Get the given type of address for this object. + * + * @param addrType the needed type of address + * + * @return the address of this object, having the specified type. If there + * is no address of such type, null is returned. + */ public RefAddr get (String addrType) { for (int i = 0; i < addrs.size (); ++i) @@ -136,27 +214,50 @@ public class Reference implements Cloneable, Serializable } return null; } - + + /** + * Get the enumeration over all defined addresses of the object. + */ public Enumeration getAll () { return addrs.elements (); } - + + /** + * Get the name of the class of the referenced object. + * + * @see #className + */ public String getClassName () { return className; } - + + /** + * Get the location of the factory class of the referenced object. + * + * @see #classFactoryLocation + */ public String getFactoryClassLocation () { return classFactoryLocation; } + /** + * Get the name of the factory class of the referenced object + * + * @see #classFactory + */ public String getFactoryClassName () { return classFactory; } - + + /** + * Get the hashcode of this reference. + * + * @return the sum of the hash codes of the addresses. + */ public int hashCode () { // The spec says the hash code is the sum of the hash codes of the @@ -166,17 +267,30 @@ public class Reference implements Cloneable, Serializable h += addrs.get (i).hashCode (); return h; } - + + /** + * Remove the address at the given position. + * + * @param posn the position of the address to remove + * + * @return the removed address + */ public Object remove (int posn) { return addrs.remove (posn); } - + + /** + * Return the number of the defined addresses. + */ public int size () { return addrs.size (); } - + + /** + * Return the string representation. + */ public String toString () { String x = getClass ().toString () + "["; @@ -189,8 +303,4 @@ public class Reference implements Cloneable, Serializable return x + "]"; } - protected Vector addrs; - protected String classFactory; - protected String classFactoryLocation; - protected String className; } diff --git a/libjava/classpath/javax/naming/Referenceable.java b/libjava/classpath/javax/naming/Referenceable.java index cf1100a..21c5238 100644 --- a/libjava/classpath/javax/naming/Referenceable.java +++ b/libjava/classpath/javax/naming/Referenceable.java @@ -1,5 +1,5 @@ /* Referenceable.java -- - Copyright (C) 2000 Free Software Foundation, Inc. + Copyright (C) 2000, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,7 +38,19 @@ exception statement from your version. */ package javax.naming; +/** + * The object, implementing this interface, can provided the + * {@link Reference} about itself. + */ public interface Referenceable { + /** + * Get the reference about this object. + * + * @return the reference about this object, cannot be null. + * + * @throws NamingException if the naming exception has been raised while + * retrieving the reference. + */ Reference getReference() throws NamingException; } diff --git a/libjava/classpath/javax/naming/SizeLimitExceededException.java b/libjava/classpath/javax/naming/SizeLimitExceededException.java index 3ca9a23..caffa70 100644 --- a/libjava/classpath/javax/naming/SizeLimitExceededException.java +++ b/libjava/classpath/javax/naming/SizeLimitExceededException.java @@ -38,7 +38,12 @@ exception statement from your version. */ package javax.naming; - +/** + * Thrown from the {@link javax.naming.NamingEnumeration}, this exception + * indicates that there are more elements than the previously specified + * size limit. Hence the enumeration represents only part of the existing + * elements that would be an answer to the specified request. + */ public class SizeLimitExceededException extends LimitExceededException { private static final long serialVersionUID = 7129289564879168579L; diff --git a/libjava/classpath/javax/naming/spi/InitialContextFactory.java b/libjava/classpath/javax/naming/spi/InitialContextFactory.java index 7bfcf09..d9b3336 100644 --- a/libjava/classpath/javax/naming/spi/InitialContextFactory.java +++ b/libjava/classpath/javax/naming/spi/InitialContextFactory.java @@ -43,7 +43,28 @@ import java.util.Hashtable; import javax.naming.Context; import javax.naming.NamingException; +/** + * <p> + * Defines a factory that creates the initial context for the beginning of the + * name resolution. JNDI allows to specify different implementations of the + * initial context at runtime. + * </p> + * <p> + * The class, implementing this interface, must be public and have a public + * parameterless constructor + * </p> + */ public interface InitialContextFactory { - Context getInitialContext (Hashtable environment) throws NamingException; + /** + * Create a new initial context + * + * @param environment the properties, used when creating the context. The + * implementing class will not modify the table nor keep the + * reference to it. After the method returns, the caller can safely + * reuse the table for other purposes. + * @return the new initial context + * @throws NamingException if the naming exception has occured + */ + Context getInitialContext(Hashtable environment) throws NamingException; } diff --git a/libjava/classpath/javax/naming/spi/InitialContextFactoryBuilder.java b/libjava/classpath/javax/naming/spi/InitialContextFactoryBuilder.java index 76564ab..4696cec 100644 --- a/libjava/classpath/javax/naming/spi/InitialContextFactoryBuilder.java +++ b/libjava/classpath/javax/naming/spi/InitialContextFactoryBuilder.java @@ -42,8 +42,25 @@ import java.util.Hashtable; import javax.naming.NamingException; +/** + * Represents the builder that creates instances of the factories that produce + * initial naming contexts. JNDI allows to specifiy different initial contexts + * at runtime. The user program can install its own initial context factory + * builder. + * + * @see NamingManager#setInitialContextFactoryBuilder + */ public interface InitialContextFactoryBuilder { + /** + * Create the new inital context factory + * + * @param environment the properties, used for creation of the initial context + * factory. The parameter is owned by the caller: it is safe to reuse + * the table for other purposes after the method returns. + * @return the created initial context factory, never null. + * @throws NamingException on failure + */ InitialContextFactory createInitialContextFactory (Hashtable environment) throws NamingException; } diff --git a/libjava/classpath/javax/naming/spi/NamingManager.java b/libjava/classpath/javax/naming/spi/NamingManager.java index cfc9dbd..a36d519 100644 --- a/libjava/classpath/javax/naming/spi/NamingManager.java +++ b/libjava/classpath/javax/naming/spi/NamingManager.java @@ -1,5 +1,6 @@ -/* NamingManager.java -- - Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +/* NamingManager.java -- Creates contexts and objects + Copyright (C) 2000, 2001, 2002, 2003, 2004, + 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,6 +39,8 @@ exception statement from your version. */ package javax.naming.spi; +import gnu.classpath.VMStackWalker; + import java.util.Enumeration; import java.util.Hashtable; import java.util.StringTokenizer; @@ -52,8 +55,19 @@ import javax.naming.Reference; import javax.naming.Referenceable; import javax.naming.StringRefAddr; +/** + * Contains methods for creating contexts and objects referred to by + * location information. The location is specified in the scope of the + * certain naming or directory service. This class only contais static + * methods and cannot be instantiated. + */ public class NamingManager { + /** + * The environment property into which getContinuationContext() stores the + * value of the CannotProceedException parameter. The value of this field + * is <i>java.naming.spi.CannotProceedException<i>. + */ public static final String CPE = "java.naming.spi.CannotProceedException"; private static InitialContextFactoryBuilder icfb; @@ -65,12 +79,37 @@ public class NamingManager NamingManager () { } - + + /** + * Checks if the initial context factory builder has been set. + * + * @return true if the builder has been set + * + * @see #setInitialContextFactoryBuilder(InitialContextFactoryBuilder) + */ public static boolean hasInitialContextFactoryBuilder () { return icfb != null; } + /** + * Creates the initial context. If the initial object factory builder has + * been set with {@link #setObjectFactoryBuilder(ObjectFactoryBuilder)}, + * the work is delegated to this builder. Otherwise, the method searches + * for the property Context.INITIAL_CONTEXT_FACTORY first in the passed + * table and then in the system properties. The value of this property is + * uses as a class name to install the context factory. The corresponding + * class must exist, be public and have the public parameterless constructor. + * + * @param environment the properties, used to create the context. + * + * @return the created context + * + * @throws NoInitialContextException if the initial builder is not set, + * the property Context.INITIAL_CONTEXT_FACTORY is missing of the + * class, named by this property, cannot be instantiated. + * @throws NamingException if throws by the context factory + */ public static Context getInitialContext (Hashtable environment) throws NamingException { @@ -112,77 +151,191 @@ public class NamingManager return icf.getInitialContext (environment); } - - static Context getURLContext (Object refInfo, - Name name, - Context nameCtx, - String scheme, - Hashtable environment) - throws NamingException + + /** + * <p> + * Creates the URL context for the given URL scheme id. + * </p> + * <p> + * The class name of the factory that creates the context has the naming + * pattern scheme-idURLContextFactory. For instance, the factory for the "ftp" + * sheme should be named "ftpURLContextFactory". + * </p> + * <p> + * The Context.URL_PKG_PREFIXES environment property contains the + * colon-separated list of the possible package prefixes. The package name is + * constructed concatenating the package prefix with the scheme id. This + * property is searched in the passed <i>environment</i> parameter and later + * in the system properties. + * </p> + * <p> + * If the factory class cannot be found in the specified packages, system will + * try to use the default internal factory for the given scheme. + * </p> + * <p> + * After the factory is instantiated, its method + * {@link ObjectFactory#getObjectInstance(Object, Name, Context, Hashtable)} + * is called to create and return the object instance. + * + * @param refInfo passed to the factory + * @param name passed to the factory + * @param nameCtx passed to the factory + * @param scheme the url scheme that must be supported by the given context + * @param environment the properties for creating the factory and context (may + * be null) + * @return the created context + * @throws NamingException if thrown by the factory when creating the context. + */ + static Context getURLContext(Object refInfo, Name name, Context nameCtx, + String scheme, Hashtable environment) + throws NamingException { - String prefixes = null; + // Specified as the default in the docs. Unclear if this is + // right for us. + String defaultPrefix = "com.sun.jndi.url"; + + StringBuffer allPrefixes = new StringBuffer(); + + String prefixes; if (environment != null) - prefixes = (String) environment.get (Context.URL_PKG_PREFIXES); - if (prefixes == null) - prefixes = System.getProperty (Context.URL_PKG_PREFIXES); - if (prefixes == null) { - // Specified as the default in the docs. Unclear if this is - // right for us. - prefixes = "com.sun.jndi.url"; + prefixes = (String) environment.get(Context.URL_PKG_PREFIXES); + if (prefixes != null) + allPrefixes.append(prefixes); + } + + prefixes = System.getProperty(Context.URL_PKG_PREFIXES); + if (prefixes != null) + { + if (allPrefixes.length() > 0) + allPrefixes.append(':'); + allPrefixes.append(prefixes); } + if (allPrefixes.length() > 0) + allPrefixes.append(':'); + allPrefixes.append(defaultPrefix); + scheme = scheme + "." + scheme + "URLContextFactory"; - StringTokenizer tokens = new StringTokenizer (prefixes, ":"); - while (tokens.hasMoreTokens ()) + StringTokenizer tokens = new StringTokenizer(allPrefixes.toString(), ":"); + while (tokens.hasMoreTokens()) { - String aTry = tokens.nextToken (); - try - { - Class factoryClass = Class.forName (aTry + "." + scheme, - true, - Thread.currentThread().getContextClassLoader()); - ObjectFactory factory = - (ObjectFactory) factoryClass.newInstance (); - Object obj = factory.getObjectInstance (refInfo, name, - nameCtx, environment); - Context ctx = (Context) obj; - if (ctx != null) - return ctx; - } - catch (ClassNotFoundException _1) - { - // Ignore it. - } - catch (ClassCastException _2) - { - // This means that the class we found was not an - // ObjectFactory or that the factory returned something - // which was not a Context. - } - catch (InstantiationException _3) - { - // If we couldn't instantiate the factory we might get - // this. - } - catch (IllegalAccessException _4) - { - // Another possibility when instantiating. - } - catch (NamingException _5) - { - throw _5; - } - catch (Exception _6) - { - // Anything from getObjectInstance. - } + String aTry = tokens.nextToken(); + try + { + String tryClass = aTry + "." + scheme; + Class factoryClass = forName(tryClass); + if (factoryClass != null) + { + ObjectFactory factory = (ObjectFactory) factoryClass.newInstance(); + Object obj = factory.getObjectInstance(refInfo, name, nameCtx, + environment); + Context ctx = (Context) obj; + if (ctx != null) + return ctx; + } + } + catch (ClassNotFoundException _1) + { + // Ignore it. + } + catch (ClassCastException _2) + { + // This means that the class we found was not an + // ObjectFactory or that the factory returned something + // which was not a Context. + } + catch (InstantiationException _3) + { + // If we couldn't instantiate the factory we might get + // this. + } + catch (IllegalAccessException _4) + { + // Another possibility when instantiating. + } + catch (NamingException _5) + { + throw _5; + } + catch (Exception _6) + { + // Anything from getObjectInstance. + } } return null; } - + + /** + * Load the class with the given name. This method tries to use the context + * class loader first. If this fails, it searches for the suitable class + * loader in the caller stack trace. This method is a central point where all + * requests to find a class by name are delegated. + */ + static Class forName(String className) + { + try + { + return Class.forName(className, true, + Thread.currentThread().getContextClassLoader()); + } + catch (ClassNotFoundException nex) + { + /** + * Returns the first user defined class loader on the call stack, or + * null when no non-null class loader was found. + */ + Class[] ctx = VMStackWalker.getClassContext(); + for (int i = 0; i < ctx.length; i++) + { + // Since we live in a class loaded by the bootstrap + // class loader, getClassLoader is safe to call without + // needing to be wrapped in a privileged action. + ClassLoader cl = ctx[i].getClassLoader(); + try + { + if (cl != null) + return Class.forName(className, true, cl); + } + catch (ClassNotFoundException nex2) + { + // Try next. + } + } + } + return null; + } + + + /** + * <p> + * Creates the URL context for the given URL scheme id. + * </p> + * <p> + * The class name of the factory that creates the context has the naming + * pattern scheme-idURLContextFactory. For instance, the factory for the "ftp" + * sheme should be named "ftpURLContextFactory". The Context.URL_PKG_PREFIXES + * environment property contains the colon-separated list of the possible + * package prefixes. The package name is constructed concatenating the package + * prefix with the scheme id. + * </p> + * <p> + * If the factory class cannot be found in the specified packages, system will + * try to use the default internal factory for the given scheme. + * </p> + * <p> + * After the factory is instantiated, its method + * {@link ObjectFactory#getObjectInstance(Object, Name, Context, Hashtable)} + * is called to create and return the object instance. + * + * @param scheme the url scheme that must be supported by the given context + * @param environment the properties for creating the factory and context (may + * be null) + * @return the created context + * @throws NamingException if thrown by the factory when creating the context. + */ public static Context getURLContext (String scheme, Hashtable environment) throws NamingException @@ -190,6 +343,17 @@ public class NamingManager return getURLContext (null, null, null, scheme, environment); } + /** + * Sets the initial object factory builder. + * + * @param builder the builder to set + * + * @throws SecurityException if the builder cannot be installed due + * security restrictions. + * @throws NamingException if the builder cannot be installed due other + * reasons + * @throws IllegalStateException if setting the builder repeatedly + */ public static void setObjectFactoryBuilder (ObjectFactoryBuilder builder) throws NamingException { @@ -198,7 +362,7 @@ public class NamingManager sm.checkSetFactory (); // Once the builder is installed it cannot be replaced. if (ofb != null) - throw new IllegalStateException ("builder already installed"); + throw new IllegalStateException ("object factory builder already installed"); if (builder != null) ofb = builder; } @@ -217,7 +381,58 @@ public class NamingManager path += ":" + path2; return new StringTokenizer (path != null ? path : "", ":"); } - + + /** + * <p>Creates an object for the specified name context, environment and + * referencing context object.</p> + * <p> + * If the builder factory is set by + * {@link #setObjectFactoryBuilder(ObjectFactoryBuilder)}, the call is + * delegated to that factory. Otherwise, the object is created using the + * following rules: + * <ul> + * <li>If the referencing object (refInfo) contains the factory class name, + * the object is created by this factory. If the creation fails, + * the parameter refInfo is returned as the method return value.</li> + * <li>If the referencing object has no factory class name, and the addresses + * are StringRefAddrs having the address type "URL", the object is + * created by the URL context factory. The used factory corresponds the + * the naming schema of the each URL. If the attempt to create + * the object this way is not successful, the subsequent rule is + * tried.</li> + * <li> If the refInfo is not an instance of Reference or Referencable + * (for example, null), the object is created by the factories, + * specified in the Context.OBJECT_FACTORIES property of the + * environment and the provider resource file, associated with the + * nameCtx. The value of this property is the colon separated list + * of the possible factories. If none of the factories can be + * loaded, the refInfo is returned. + * </ul> + * </p> + * <p>The object factory must be public and have the public parameterless + * constructor.</p> + * + * @param refInfo the referencing object, for which the new object must be + * created (can be null). If not null, it is usually an instance of + * the {@link Reference} or {@link Referenceable}. + * @param name the name of the object. The name is relative to + * the nameCtx naming context. The value of this parameter can be + * null if the name is not specified. + * @param nameCtx the naming context, in which scope the name of the new + * object is specified. If this parameter is null, the name is + * specified in the scope of the initial context. + * @param environment contains additional information for creating the object. + * This paramter can be null if there is no need to provide any + * additional information. + * + * @return the created object. If the creation fails, in some cases + * the parameter refInfo may be returned. + * + * @throws NamingException if the attempt to name the new object has failed + * @throws Exception if the object factory throws it. The object factory + * only throws an exception if it does not want other factories + * to be used to create the object. + */ public static Object getObjectInstance (Object refInfo, Name name, Context nameCtx, @@ -312,7 +527,21 @@ public class NamingManager return obj == null ? refInfo : obj; } - public static void setInitialContextFactoryBuilder (InitialContextFactoryBuilder builder) + /** + * Sets the initial context factory builder. + * + * @param builder the builder to set + * + * @throws SecurityException if the builder cannot be installed due + * security restrictions. + * @throws NamingException if the builder cannot be installed due other + * reasons + * @throws IllegalStateException if setting the builder repeatedly + * + * @see #hasInitialContextFactoryBuilder() + */ + public static void setInitialContextFactoryBuilder + (InitialContextFactoryBuilder builder) throws NamingException { SecurityManager sm = System.getSecurityManager (); @@ -320,11 +549,23 @@ public class NamingManager sm.checkSetFactory (); // Once the builder is installed it cannot be replaced. if (icfb != null) - throw new IllegalStateException ("builder already installed"); + throw new IllegalStateException ("ctx factory builder already installed"); if (builder != null) icfb = builder; } - + + /** + * Creates a context in which the context operation must be continued. + * This method is used by operations on names that span multiple namespaces. + * + * @param cpe the exception that triggered this continuation. This method + * obtains the environment ({@link CannotProceedException#getEnvironment()} + * and sets the environment property {@link #CPE} = cpe. + * + * @return a non null context for continuing the operation + * + * @throws NamingException if the naming problems have occured + */ public static Context getContinuationContext (CannotProceedException cpe) throws NamingException { @@ -332,7 +573,7 @@ public class NamingManager if (env != null) env.put (CPE, cpe); - // It is really unclear to me if this is right. + // TODO: Check if this implementation matches the API specification try { Object obj = getObjectInstance (cpe.getResolvedObj(), @@ -351,7 +592,22 @@ public class NamingManager throw cpe; } - + + /** + * Get the object state for binding. + * + * @param obj the object, for that the binding state must be retrieved. Cannot + * be null. + * @param name the name of this object, related to the nameCtx. Can be null if + * not specified. + * @param nameCtx the naming context, to that the object name is related. Can + * be null if the name is related to the initial default context. + * @param environment the properties for creating the object state. Can be + * null if no properties are provided. + * @return the object state for binding, may be null if no changes are + * returned by the factory + * @throws NamingException + */ public static Object getStateToBind (Object obj, Name name, Context nameCtx, Hashtable environment) throws NamingException diff --git a/libjava/classpath/javax/naming/spi/ObjectFactory.java b/libjava/classpath/javax/naming/spi/ObjectFactory.java index 81648d9..27771b6 100644 --- a/libjava/classpath/javax/naming/spi/ObjectFactory.java +++ b/libjava/classpath/javax/naming/spi/ObjectFactory.java @@ -1,5 +1,5 @@ /* ObjectFactory.java -- - Copyright (C) 2001, 2004 Free Software Foundation, Inc. + Copyright (C) 2001, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -43,9 +43,33 @@ import java.util.Hashtable; import javax.naming.Context; import javax.naming.Name; +/** + * Represents a factory for creating the object. ObjectFactory performs the + * operation, that is the opposite to the operation, performed by the + * {@link StateFactory}. Classes, implementing this interface, must be public + * and have public parameterless constructor. + */ public interface ObjectFactory { - Object getObjectInstance (Object obj, Name name, Context nameCtx, - Hashtable environment) - throws Exception; + /** + * Creates the object, using the specified name and location information. The + * call of this method must be thread safe. + * + * @param refObj may provide the reference and location information. Can be null. + * @param name the name of the new object in the scope of the specified naming + * context. Can be null if the name is not specified. + * @param nameCtx the context, in which the object name is specified. Can be + * null if the name is specified in the scope of the default initial + * context. + * @param environment the properties, providing additional information on how + * to create an object. Can be null if not additional information is + * provided. + * @return the newly created object or null if the object cannot be created + * @throws Exception if this factory suggest not to try creating of this + * object by other alternative factories + * + * @see NamingManager#getObjectInstance(Object, Name, Context, Hashtable) + */ + Object getObjectInstance(Object refObj, Name name, Context nameCtx, + Hashtable environment) throws Exception; } diff --git a/libjava/classpath/javax/naming/spi/ObjectFactoryBuilder.java b/libjava/classpath/javax/naming/spi/ObjectFactoryBuilder.java index a761393..cb20c66 100644 --- a/libjava/classpath/javax/naming/spi/ObjectFactoryBuilder.java +++ b/libjava/classpath/javax/naming/spi/ObjectFactoryBuilder.java @@ -1,5 +1,5 @@ -/* ObjectFactoryBuilder.java -- - Copyright (C) 2001, 2004 Free Software Foundation, Inc. +/* ObjectFactoryBuilder.java -- the builder that creates the object factories. + Copyright (C) 2001, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -41,14 +41,30 @@ package javax.naming.spi; import java.util.Hashtable; import javax.naming.NamingException; +import javax.naming.Reference; +import javax.naming.Referenceable; /** + * Represents the builder that creates the object factories. + * + * @see NamingManager#setObjectFactoryBuilder(ObjectFactoryBuilder) + * * @author Warren Levy (warrenl@redhat.com) - * @date June 1, 2001 */ public interface ObjectFactoryBuilder -{ - ObjectFactory createObjectFactory(Object obj, +{ + /** + * Create a new object using the supplied environment. + * + * @param refInfo the referencing object, for which the new object must be + * created (can be null). If not null, it is usually an instance of + * the {@link Reference} or {@link Referenceable}. + * @param environment contains the additional information about the factory + * being created. Can be null. + * @return the created object factory. The null is never returned. + * @throws NamingException + */ + ObjectFactory createObjectFactory(Object refInfo, Hashtable environment) throws NamingException; } diff --git a/libjava/classpath/javax/naming/spi/ResolveResult.java b/libjava/classpath/javax/naming/spi/ResolveResult.java index 07e2df3..d5051a5 100644 --- a/libjava/classpath/javax/naming/spi/ResolveResult.java +++ b/libjava/classpath/javax/naming/spi/ResolveResult.java @@ -45,8 +45,11 @@ import javax.naming.InvalidNameException; import javax.naming.Name; /** + * Stores the partial resolution of the name. This class contains the + * object to which part of the name has been resolved and the remaining, + * unresolved part of this name. + * * @author Warren Levy (warrenl@redhat.com) - * @date June 5, 2001 */ public class ResolveResult implements Serializable @@ -54,51 +57,92 @@ public class ResolveResult implements Serializable private static final long serialVersionUID = - 4552108072002407559L; // Serialized fields. + /** + * The object, to that part of the name has been resolved. + */ protected Object resolvedObj; + + /** + * The remaining, unresolved part of the name. + */ protected Name remainingName; - + + /** + * Create the unitialised instance with both parts being null. + */ protected ResolveResult() { - resolvedObj = null; - remainingName = null; } - - public ResolveResult(Object robj, String rcomp) + + /** + * Create the initialised instance + * + * @param resolved the object, to that the name is partially resolved + * @param remaining the remaining unresolved part of the name. + */ + public ResolveResult(Object resolved, String remaining) { - if (robj == null || rcomp == null) + if (resolved == null || remaining == null) throw new IllegalArgumentException (); - resolvedObj = robj; + resolvedObj = resolved; remainingName = new CompositeName (); try { - remainingName.add (rcomp); + remainingName.add (remaining); } catch (InvalidNameException _) { } } - public ResolveResult(Object robj, Name rname) + /** + * Create the initialised instance + * + * @param resolved the object, to that the name is partially resolved + * @param remaining the remaining unresolved part of the name. + */ + public ResolveResult(Object resolved, Name remaining) { - resolvedObj = robj; - remainingName = rname; + resolvedObj = resolved; + remainingName = remaining; } + /** + * Get the remaining unresolved part of the name + * + * @return the remaining unresolved part of the name. + */ public Name getRemainingName() { return remainingName; } + /** + * Get the object to that the name was partially resolved + * + * @return the object, to that the name is partially resolved + */ public Object getResolvedObj() { return resolvedObj; } - + + /** + * Set the remaining unresolved name. + * + * @param name the name being set. The passed parameter is cloned, so the + * caller can reuse or modify it after the method returns. + */ public void setRemainingName(Name name) { remainingName = (Name) name.clone(); } - + + /** + * Append the name to the end of the resolved name. + * + * @param name the name to append + */ public void appendRemainingName(Name name) { try @@ -110,6 +154,11 @@ public class ResolveResult implements Serializable } } + /** + * Append the name to the end of the resolved name. + * + * @param name the name to append + */ public void appendRemainingComponent(String name) { try @@ -121,6 +170,11 @@ public class ResolveResult implements Serializable } } + /** + * Set the object to that the part of the name has been resolved. + * + * @param obj the object, to that the name has been partially resolved. + */ public void setResolvedObj(Object obj) { resolvedObj = obj; diff --git a/libjava/classpath/javax/naming/spi/Resolver.java b/libjava/classpath/javax/naming/spi/Resolver.java index d80fb61..eb3eeb5 100644 --- a/libjava/classpath/javax/naming/spi/Resolver.java +++ b/libjava/classpath/javax/naming/spi/Resolver.java @@ -1,5 +1,5 @@ /* Resolver.java -- - Copyright (C) 2001, 2005 Free Software Foundation, Inc. + Copyright (C) 2001, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,18 +38,47 @@ exception statement from your version. */ package javax.naming.spi; +import javax.naming.Context; import javax.naming.Name; import javax.naming.NamingException; +import javax.naming.NotContextException; /** + * <p>Represents the object, capable for the at least partial name resolution. + * The object is not necessay capable for the complete name resolution and + * need not implement the {@link Context}.</p> + * <p> + * Both passed parameters and returned results are owned by the caller.</p> + * * @author Warren Levy (warrenl@redhat.com) - * @date June 1, 2001 */ - public interface Resolver { + /** + * Partially resolve the name, stopping at the first instance of the context + * that is an instance of the contextType + * + * @param name the name to resolve + * @param contextType the class of the context, on that the resolution should + * be terminated + * @return the complete or partial name resolution + * @throws NotContextException if the context of the contextType is not found + * @throws NamingException on other failure + */ ResolveResult resolveToClass(Name name, Class contextType) throws NamingException; + + /** + * Partially resolve the name, stopping at the first instance of the context + * that is an instance of the contextType + * + * @param name the name to resolve + * @param contextType the class of the context, on that the resolution should + * be terminated + * @return the complete or partial name resolution + * @throws NotContextException if the context of the contextType is not found + * @throws NamingException on other failure + */ ResolveResult resolveToClass(String name, Class contextType) throws NamingException; } diff --git a/libjava/classpath/javax/naming/spi/StateFactory.java b/libjava/classpath/javax/naming/spi/StateFactory.java index 1fbdeb1..5694f8a 100644 --- a/libjava/classpath/javax/naming/spi/StateFactory.java +++ b/libjava/classpath/javax/naming/spi/StateFactory.java @@ -1,5 +1,5 @@ /* StateFactory.java -- - Copyright (C) 2001, 2004 Free Software Foundation, Inc. + Copyright (C) 2001, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -45,11 +45,35 @@ import javax.naming.Name; import javax.naming.NamingException; /** + * Represents a factory, producing the object states for binding. The operation, + * performed by this factory, is the reverse operation with related to the + * operation, performed by the {@link ObjectFactory}. Classes, implementing + * this interface, must be public and have public parameterless constructor. + * + * @see DirStateFactory + * @see ObjectFactory * @author Warren Levy (warrenl@redhat.com) - * @date June 1, 2001 */ public interface StateFactory { + /** + * Get the object state for binding. + * + * @param obj the object, for that the binding state must be retrieved. Cannot + * be null. + * @param name the name of this object, related to the nameCtx. Can be null if + * not specified. + * @param nameCtx the naming context, to that the object name is related. Can + * be null if the name is related to the initial default context. + * @param environment the properties for creating the object state. Can be + * null if no properties are provided. + * @return the object state for binding, may be null if no changes are + * returned by the factory + * @throws NamingException + * + * @see NamingManager#getStateToBind + * @see DirectoryManager#getStateToBind + */ Object getStateToBind(Object obj, Name name, Context nameCtx, Hashtable environment) throws NamingException; } |