Imported GNU Classpath 0.92

2006-08-14  Mark Wielaard  <mark@klomp.org>

       Imported GNU Classpath 0.92
       * HACKING: Add more importing hints. Update automake version
       requirement.

       * configure.ac (gconf-peer): New enable AC argument.
       Add --disable-gconf-peer and --enable-default-preferences-peer
       to classpath configure when gconf is disabled.
       * scripts/makemake.tcl: Set gnu/java/util/prefs/gconf and
       gnu/java/awt/dnd/peer/gtk to bc. Classify
       gnu/java/security/Configuration.java as generated source file.

       * gnu/java/lang/management/VMGarbageCollectorMXBeanImpl.java,
       gnu/java/lang/management/VMMemoryPoolMXBeanImpl.java,
       gnu/java/lang/management/VMClassLoadingMXBeanImpl.java,
       gnu/java/lang/management/VMRuntimeMXBeanImpl.java,
       gnu/java/lang/management/VMMemoryManagerMXBeanImpl.java,
       gnu/java/lang/management/VMThreadMXBeanImpl.java,
       gnu/java/lang/management/VMMemoryMXBeanImpl.java,
       gnu/java/lang/management/VMCompilationMXBeanImpl.java: New VM stub
       classes.
       * java/lang/management/VMManagementFactory.java: Likewise.
       * java/net/VMURLConnection.java: Likewise.
       * gnu/java/nio/VMChannel.java: Likewise.

       * java/lang/Thread.java (getState): Add stub implementation.
       * java/lang/Class.java (isEnum): Likewise.
       * java/lang/Class.h (isEnum): Likewise.

       * gnu/awt/xlib/XToolkit.java (getClasspathTextLayoutPeer): Removed.

       * javax/naming/spi/NamingManager.java: New override for StackWalker
       functionality.

       * configure, sources.am, Makefile.in, gcj/Makefile.in,
       include/Makefile.in, testsuite/Makefile.in: Regenerated.

From-SVN: r116139

8 files changed, 539 insertions, 98 deletions

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;
 }