2006-05-21 Audrius Meskauskas <[EMAIL PROTECTED]>
* javax/naming/NameParser.java,
javax/naming/NamingEnumeration.java,
javax/naming/PartialResultException.java,
javax/naming/SizeLimitExceededException.java,
javax/naming/spi/ObjectFactory.java,
javax/naming/spi/ObjectFactoryBuilder.java: Documented.
Index: javax/naming/NameParser.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/NameParser.java,v
retrieving revision 1.3
diff -u -r1.3 NameParser.java
--- javax/naming/NameParser.java 2 Jul 2005 20:32:45 -0000 1.3
+++ javax/naming/NameParser.java 21 May 2006 12:12:38 -0000
@@ -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 @@
package javax.naming;
+/**
+ * Parser the string representation of the given name into the [EMAIL PROTECTED] Name}
+ * representation.
+ *
+ * @see Context#getNameParser(String)
+ * @see Context#getNameParser(Name)
+ */
public interface NameParser
-{
+{
+ /**
+ * Parser the string name representation into the [EMAIL PROTECTED] Name} representation
+ *
+ * @param name the string representation of the name
+ * @return the [EMAIL PROTECTED] 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;
}
Index: javax/naming/NamingEnumeration.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/NamingEnumeration.java,v
retrieving revision 1.3
diff -u -r1.3 NamingEnumeration.java
--- javax/naming/NamingEnumeration.java 2 Jul 2005 20:32:45 -0000 1.3
+++ javax/naming/NamingEnumeration.java 21 May 2006 12:12:38 -0000
@@ -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 @@
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 [EMAIL PROTECTED] #next()} and [EMAIL PROTECTED] #hasMore()}. If the inherited
+ * [EMAIL PROTECTED] java.util.Enumeration#nextElement()} and
+ * [EMAIL PROTECTED] 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
+ * [EMAIL PROTECTED] 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;
+
}
Index: javax/naming/PartialResultException.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/PartialResultException.java,v
retrieving revision 1.4
diff -u -r1.4 PartialResultException.java
--- javax/naming/PartialResultException.java 3 Mar 2006 22:50:55 -0000 1.4
+++ javax/naming/PartialResultException.java 21 May 2006 12:12:38 -0000
@@ -38,7 +38,11 @@
package javax.naming;
-
+/**
+ * Thrown from the [EMAIL PROTECTED] 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;
Index: javax/naming/SizeLimitExceededException.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/SizeLimitExceededException.java,v
retrieving revision 1.4
diff -u -r1.4 SizeLimitExceededException.java
--- javax/naming/SizeLimitExceededException.java 3 Mar 2006 22:50:55 -0000 1.4
+++ javax/naming/SizeLimitExceededException.java 21 May 2006 12:12:38 -0000
@@ -38,7 +38,12 @@
package javax.naming;
-
+/**
+ * Thrown from the [EMAIL PROTECTED] 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;
Index: javax/naming/spi/ObjectFactory.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/spi/ObjectFactory.java,v
retrieving revision 1.4
diff -u -r1.4 ObjectFactory.java
--- javax/naming/spi/ObjectFactory.java 2 Jul 2005 20:32:45 -0000 1.4
+++ javax/naming/spi/ObjectFactory.java 21 May 2006 12:12:39 -0000
@@ -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,31 @@
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.
+ */
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;
}
Index: javax/naming/spi/ObjectFactoryBuilder.java
===================================================================
RCS file: /sources/classpath/classpath/javax/naming/spi/ObjectFactoryBuilder.java,v
retrieving revision 1.5
diff -u -r1.5 ObjectFactoryBuilder.java
--- javax/naming/spi/ObjectFactoryBuilder.java 2 Jul 2005 20:32:45 -0000 1.5
+++ javax/naming/spi/ObjectFactoryBuilder.java 21 May 2006 12:12:41 -0000
@@ -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 @@
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 ([EMAIL PROTECTED])
- * @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 [EMAIL PROTECTED] Reference} or [EMAIL PROTECTED] 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;
}
