2006-05-21 Audrius Meskauskas <[EMAIL PROTECTED]>
* javax/naming/Referenceable.java: Documented.
* javax/naming/spi/NamingManager.java: Documented.
Index: javax/naming/Referenceable.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/Referenceable.java,v
retrieving revision 1.3
diff -u -r1.3 Referenceable.java
--- javax/naming/Referenceable.java 2 Jul 2005 20:32:45 -0000 1.3
+++ javax/naming/Referenceable.java 21 May 2006 07:50:18 -0000
@@ -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 @@
package javax.naming;
+/**
+ * The object, implementing this interface, can provided the
+ * [EMAIL PROTECTED] 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;
}
Index: javax/naming/spi/NamingManager.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/spi/NamingManager.java,v
retrieving revision 1.11
diff -u -r1.11 NamingManager.java
--- javax/naming/spi/NamingManager.java 17 May 2006 10:58:45 -0000 1.11
+++ javax/naming/spi/NamingManager.java 21 May 2006 07:50:20 -0000
@@ -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.
@@ -55,9 +56,10 @@
import javax.naming.StringRefAddr;
/**
- * Contains methods for creating context objects and objects referred to by
+ * 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.
+ * certain naming or directory service. This class only contais static
+ * methods and cannot be instantiated.
*/
public class NamingManager
{
@@ -379,7 +381,58 @@
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
+ * [EMAIL PROTECTED] #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 [EMAIL PROTECTED] Reference} or [EMAIL PROTECTED] 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,
