2006-05-22 Audrius Meskauskas <AudriusA@Bioinformatics.org>

	* javax/naming/spi/InitialContextFactory.java,
	javax/naming/spi/InitialContextFactoryBuilder.java,
	javax/naming/spi/NamingManager.java,
	javax/naming/spi/ObjectFactory.java,
	javax/naming/spi/ResolveResult.java,
	javax/naming/spi/Resolver.java,
	javax/naming/spi/StateFactory.java: Documented.

8 files changed, 196 insertions, 24 deletions

diff --git a/ChangeLog b/ChangeLog
index 88e839c0b..dbccd4065 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2006-05-22  Audrius Meskauskas  <AudriusA@Bioinformatics.org>
+
+	* javax/naming/spi/InitialContextFactory.java,
+	javax/naming/spi/InitialContextFactoryBuilder.java,
+	javax/naming/spi/NamingManager.java,
+	javax/naming/spi/ObjectFactory.java,
+	javax/naming/spi/ResolveResult.java,
+	javax/naming/spi/Resolver.java,
+	javax/naming/spi/StateFactory.java: Documented.
+
 2006-05-21  Tom Tromey  <tromey@redhat.com>
 
 	PR classpath/27688:
diff --git a/javax/naming/spi/InitialContextFactory.java b/javax/naming/spi/InitialContextFactory.java
index 7bfcf095e..d9b3336dc 100644
--- a/javax/naming/spi/InitialContextFactory.java
+++ b/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/javax/naming/spi/InitialContextFactoryBuilder.java b/javax/naming/spi/InitialContextFactoryBuilder.java
index 76564ab5e..4696cecb8 100644
--- a/javax/naming/spi/InitialContextFactoryBuilder.java
+++ b/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/javax/naming/spi/NamingManager.java b/javax/naming/spi/NamingManager.java
index 9e72cf29f..a36d519d7 100644
--- a/javax/naming/spi/NamingManager.java
+++ b/javax/naming/spi/NamingManager.java
@@ -573,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(),
@@ -592,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/javax/naming/spi/ObjectFactory.java b/javax/naming/spi/ObjectFactory.java
index c14674792..27771b6cb 100644
--- a/javax/naming/spi/ObjectFactory.java
+++ b/javax/naming/spi/ObjectFactory.java
@@ -44,8 +44,10 @@ import javax.naming.Context;
 import javax.naming.Name;
 
 /**
- * Represents a factory for creating the object. Classes, implementing this
- * interface, must be public and have public parameterless constructor.
+ * 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
 {
diff --git a/javax/naming/spi/ResolveResult.java b/javax/naming/spi/ResolveResult.java
index 07e2df3c0..d5051a5d4 100644
--- a/javax/naming/spi/ResolveResult.java
+++ b/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/javax/naming/spi/Resolver.java b/javax/naming/spi/Resolver.java
index d80fb6169..eb3eeb560 100644
--- a/javax/naming/spi/Resolver.java
+++ b/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/javax/naming/spi/StateFactory.java b/javax/naming/spi/StateFactory.java
index 1fbdeb1fa..5694f8a1a 100644
--- a/javax/naming/spi/StateFactory.java
+++ b/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;
 }