2006-04-06 Wolfgang Baer <WBaer@gmx.de>

	* javax/naming/Binding.java: Added API docs.
	* javax/naming/NameClassPair.java: Added API docs.
	(fullName): New field.
	(setNameInNamespace): New 1.5 method.
	(getNameInNamespace): Likewise.

2 files changed, 161 insertions, 2 deletions

diff --git a/javax/naming/Binding.java b/javax/naming/Binding.java
index 9d6608aba..a34f8b329 100644
--- a/javax/naming/Binding.java
+++ b/javax/naming/Binding.java
@@ -39,31 +39,73 @@ exception statement from your version. */
 package javax.naming;
 
 /**
+ * <code>Binding</code> represents the name-object mapping of a 
+ * binding in a context.
+ * <p>
+ * Bindings are mappings of a name to an object and this class is used to
+ * specify such mappings. The bindings of a context are retrieved by the
+ * <code>Context#listBindings()</code> methods.
+ * </p>
+ * 
  * @author Tom Tromey (tromey@redhat.com)
- * @date May 16, 2001
+ * @since 1.3
  */
 public class Binding extends NameClassPair
 {
   private static final long serialVersionUID = 8839217842691845890L;
 
+  /**
+   * Constructs an instance with the given name and object.
+   * 
+   * @param name the name of the binding relative to the target context
+   * (may not be <code>null</code>)
+   * @param obj the bound object
+   */
   public Binding (String name, Object obj)
   {
     super (name, null);
     boundObj = obj;
   }
 
+  /**
+   * Constructs an instance with the given name and object and a 
+   * flag indicating if the name is relative to the target context.
+   * 
+   * @param name the name of the binding relative to the target context
+   * (may not be <code>null</code>)
+   * @param obj the bound object
+   * @param isRelative flag indicating if the name is relative or not
+   */
   public Binding (String name, Object obj, boolean isRelative)
   {
     super (name, null, isRelative);
     boundObj = obj;
   }
 
+  /**
+   * Constructs an instance with the given name, classname and object.
+   * 
+   * @param name the name of the binding relative to the target context
+   * (may not be <code>null</code>)
+   * @param className the classname to set (maybe <code>null</code>)
+   * @param obj the bound object
+   */
   public Binding (String name, String className, Object obj)
   {
     super (name, className);
     boundObj = obj;
   }
 
+  /**
+   * Constructs an instance with the given name, classname, object and a 
+   * flag indicating if the name is relative to the target context.
+   * 
+   * @param name the name of the binding relative to the target context
+   * (may not be <code>null</code>)
+   * @param className the classname to set (maybe <code>null</code>)
+   * @param isRelative flag indicating if the name is relative or not
+   * @param obj the bound object
+   */
   public Binding (String name, String className, Object obj,
 		  boolean isRelative)
   {
@@ -71,6 +113,15 @@ public class Binding extends NameClassPair
     boundObj = obj;
   }
 
+  /**
+   * Returns the classname of the bound object.
+   * <p>
+   * Returns the classname if set explicitly. If not and the bound object is
+   * not <code>null</code> the classname of the bound object is used.
+   * </p>
+   * 
+   * @return The fully qualified classname (may be <code>null</code>).
+   */
   public String getClassName ()
   {
     String r = super.getClassName ();
@@ -79,16 +130,29 @@ public class Binding extends NameClassPair
     return boundObj == null ? null : boundObj.getClass ().getName ();
   }
 
+  /**
+   * Returns the bound object of this binding.
+   * @return The bound object (maybe <code>null</code>).
+   */
   public Object getObject ()
   {
     return boundObj;
   }
 
+  /**
+   * Sets the bound object of this binding.
+   * @param obj the bound object.
+   */
   public void setObject (Object obj)
   {
     boundObj = obj;
   }
 
+  /**
+   * Returns the string representation.
+   * @return The string as given by the NameClassPair superclass plus 
+   * the bound objects string representation seperated by a colon.
+   */
   public String toString ()
   {
     // Format specified by the documentation.
diff --git a/javax/naming/NameClassPair.java b/javax/naming/NameClassPair.java
index 127730af4..7925d45d8 100644
--- a/javax/naming/NameClassPair.java
+++ b/javax/naming/NameClassPair.java
@@ -41,18 +41,43 @@ package javax.naming;
 import java.io.Serializable;
 
 /**
+ * <code>NameClassPair</code> represents the name-classname mapping pair 
+ * of a binding in a context.
+ * <p>
+ * Bindings are mappings of a name to an object and this class is used to
+ * specify the mapping of the name to the class type of the bound object.
+ * As classname the fully qualified classname is used.
+ * </p>
+ * 
  * @author Tom Tromey (tromey@redhat.com)
- * @date May 16, 2001
+ * @since 1.3
  */
 public class NameClassPair implements Serializable
 {
   private static final long serialVersionUID = 5620776610160863339L;
 
+  /**
+   * Constructs an instance with the given name and classname.
+   * 
+   * @param name the name of the binding relative to the target context
+   * (may not be <code>null</code>)
+   * @param className the name of the class. If <code>null</code> the bound
+   * object is also <code>null</code>
+   */
   public NameClassPair (String name, String className)
   {
     this (name, className, true);
   }
 
+  /**
+   * Constructs an instance with the given name and classname and a 
+   * flag indicating if the name is relative to the target context.
+   * 
+   * @param name the name of the binding (may not be <code>null</code>)
+   * @param className the name of the class. If <code>null</code> the bound
+   * object is also <code>null</code>
+   * @param isRelative flag indicating if the name is relative or not
+   */
   public NameClassPair (String name, String className, boolean isRelative)
   {
     this.name = name;
@@ -60,36 +85,105 @@ public class NameClassPair implements Serializable
     this.isRel = isRelative;
   }
 
+  /**
+   * Returns the classname of the binding.
+   * @return The fully qualified classname or <code>null</code> if the 
+   * bound object is null.
+   */
   public String getClassName ()
   {
     return className;
   }
 
+  /**
+   * Returns the name of the binding.
+   * @return The name.
+   */
   public String getName ()
   {
     return name;
   }
 
+  /**
+   * Checks whether the name is relative to the target context or not.
+   * @return <code>true</code> if the name is relative, 
+   * <code>false</code> otherwise.
+   */
   public boolean isRelative ()
   {
     return isRel;
   }
 
+  /**
+   * Sets the classname of the bound object.
+   * @param name the classname to set (maybe <code>null</code>)
+   */
   public void setClassName (String name)
   {
     this.className = name;
   }
 
+  /**
+   * Sets the name of the binding.
+   * @param name the name to set
+   */
   public void setName (String name)
   {
     this.name = name;
   }
 
+  /**
+   * Sets if the name is relative to the target context.
+   * @param r <code>true</code> to mark as relative
+   */
   public void setRelative (boolean r)
   {
     this.isRel = r;
   }
+  
+  /**
+   * Sets the full name for this binding. Setting the full name by this 
+   * method is the only way to initialize full names of bindings if 
+   * supported by a specific naming system.
+   * 
+   * @param fullName the full name of this binding. If not set or set to 
+   * <code>null</code> the <code>getNameInNamespace()</code> method will
+   * throw an exception
+   * 
+   * @see #getNameInNamespace()
+   * 
+   * @since 1.5
+   */
+  public void setNameInNamespace(String fullName) 
+  {
+    this.fullName = fullName;
+  }
+  
+  /**
+   * Returns the full name for this binding. The full name of a binding is
+   * defined as the absolute name in its own namespace and is not valid 
+   * outside.
+   * 
+   * @return The full name in the bindings namespace.
+   * @throws UnsupportedOperationException if no full name is applicable in 
+   * the specific naming system.
+   * 
+   * @see Context#getNameInNamespace()
+   * 
+   * @since 1.5
+   */
+  public String getNameInNamespace()
+  {
+    if (this.fullName == null)
+      throw new UnsupportedOperationException();
+    
+    return this.fullName;
+  }
 
+  /**
+   * Returns the string representation.
+   * @return The string <code>getName() + ":" + getClassName()</code>.
+   */
   public String toString ()
   {
     // Specified by class documentation.
@@ -100,4 +194,5 @@ public class NameClassPair implements Serializable
   private String name;
   private String className;
   private boolean isRel;
+  private String fullName;
 }