Closeable class represents a stream of
+ * data, which can be closed when it is no longer needed.
+ * Closing a stream allows the resources it uses to be
+ * freed for an alternate use.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
public interface Closeable
{
- void close() throws IOException;
+
+ /**
+ * Closes the stream represented by this class, thus freeing
+ * system resources. In that case that the stream is already
+ * in the closed state, this method has no effect.
+ *
+ * @throws IOException if an I/O error occurs in closing.
+ */
+ void close()
+ throws IOException;
+
}
Index: java/io/Flushable.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/io/Attic/Flushable.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 Flushable.java
--- java/io/Flushable.java 26 Aug 2004 21:21:10 -0000 1.1.2.1
+++ java/io/Flushable.java 20 Feb 2005 20:48:34 -0000
@@ -1,5 +1,5 @@
-/* Flushable.java -- flush()-able object
- Copyright (C) 2004 Free Software Foundation
+/* Flushable.java -- Flushable object
+ Copyright (C) 2004, 2005 Free Software Foundation
This file is part of GNU Classpath.
@@ -37,7 +37,26 @@ exception statement from your version. *
package java.io;
+/**
+ * A Flushable class represents a stream of
+ * data, for which internally buffered data can be `flushed'.
+ * Flushing such a stream causes the buffered data to be
+ * written to the stream.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
public interface Flushable
{
- void flush() throws IOException;
+
+ /**
+ * Flushes the stream represented by this class,
+ * so that any buffered data is written to the stream.
+ *
+ * @throws IOException if an I/O error occurs in flushing.
+ */
+ void flush()
+ throws IOException;
+
}
Index: java/lang/Appendable.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/Appendable.java,v
retrieving revision 1.1.2.4
diff -u -3 -p -u -r1.1.2.4 Appendable.java
--- java/lang/Appendable.java 1 Feb 2005 00:25:38 -0000 1.1.2.4
+++ java/lang/Appendable.java 20 Feb 2005 20:48:34 -0000
@@ -55,7 +55,8 @@ import java.io.IOException;
*
*
* Note: implementation of this interface is required for
- * any class that wishes to receive data from a Formatter instance.
+ * any class that wishes to receive data from a Formatter
+ * instance.
*
+ * Thrown when a type is accessed using a String-based
+ * representation, but no definition of the supplied type is found.
+ * This is effectively an unchecked equivalent of the existing
+ * ClassNotFound exception.
+ *
+ * It may occur due to an attempt to load a missing class, interface or + * annotation, or when an undefined type variable is accessed. + *
+ * + * @author Tom Tromey (address@hidden) + * @author Andrew John Hughes (address@hidden) + * @see ClassNotFoundException + * @since 1.5 + */ +public class TypeNotPresentException + extends RuntimeException { + + /** + * Constructs aTypeNotPresentException for
+ * the supplied type. The specified cause Throwable
+ * may be used to provide additional history, with regards to the
+ * root of the problem. It is perfectly valid for this to be null,
+ * if the cause of the problem is unknown.
+ *
+ * @param typeName the name of the missing type.
+ * @param cause the cause of this exception, or null if the cause
+ * is unknown.
+ */
public TypeNotPresentException(String typeName, Throwable cause)
{
super("type \"" + typeName + "\" not found", cause);
this.typeName = typeName;
}
+ /**
+ * Returns the name of the missing type.
+ *
+ * @return the missing type's name.
+ */
public String typeName()
{
return typeName;
}
+ /**
+ * The name of the missing type.
+ *
+ * @serial the missing type's name.
+ */
// Name fixed by serialization.
private String typeName;
+
}
Index: java/lang/annotation/AnnotationFormatError.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/annotation/Attic/AnnotationFormatError.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 AnnotationFormatError.java
--- java/lang/annotation/AnnotationFormatError.java 7 Aug 2004 19:01:27 -0000 1.1.2.1
+++ java/lang/annotation/AnnotationFormatError.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
-/* AnnotationFormatError.java - Thrown when annotation is malformed in class
- Copyright (C) 2004 Free Software Foundation
+/* AnnotationFormatError.java - Thrown when an binary annotation is malformed
+ Copyright (C) 2004, 2005 Free Software Foundation
This file is part of GNU Classpath.
@@ -38,22 +38,67 @@ exception statement from your version. *
package java.lang.annotation;
/**
+ * Thrown when an annotation found in a class file is
+ * malformed. When the runtime machine finds a class file
+ * containing annotations, it attempts to parse them.
+ * This error is thrown if this operation fails.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
* @since 1.5
*/
public class AnnotationFormatError extends Error
{
+
+ /**
+ * Constructs a new AnnotationFormatError
+ * using the specified message to give details of the error.
+ *
+ * @param message the message to use in the error output.
+ */
public AnnotationFormatError(String message)
{
super(message);
}
+ /**
+ *
+ * Constructs a new AnnotationFormatError
+ * using the specified message to give details of the error.
+ * The supplied cause Throwable is used to
+ * provide additional history, with regards to the root
+ * of the problem. It is perfectly valid for this to be null, if
+ * the cause is unknown.
+ *
+ * Note: if a cause is supplied, the error + * message from this cause is not automatically included in the + * error message given by this error. + *
+ * + * @param message the message to use in the error output + * @param cause the cause of this error, or null if the cause + * is unknown. + */ public AnnotationFormatError(String message, Throwable cause) { super(message, cause); } + /** + * Constructs a newAnnotationFormatError using
+ * the supplied cause Throwable to
+ * provide additional history, with regards to the root
+ * of the problem. It is perfectly valid for this to be null, if
+ * the cause is unknown. If the cause is not null, the error
+ * message from this cause will also be used as the message
+ * for this error.
+ *
+ * @param cause the cause of the error.
+ */
public AnnotationFormatError(Throwable cause)
{
super(cause);
}
+
}
Index: java/lang/annotation/AnnotationTypeMismatchException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/annotation/Attic/AnnotationTypeMismatchException.java,v
retrieving revision 1.1.2.2
diff -u -3 -p -u -r1.1.2.2 AnnotationTypeMismatchException.java
--- java/lang/annotation/AnnotationTypeMismatchException.java 7 Jan 2005 03:42:30 -0000 1.1.2.2
+++ java/lang/annotation/AnnotationTypeMismatchException.java 20 Feb 2005 20:48:35 -0000
@@ -40,29 +40,72 @@ package java.lang.annotation;
import java.lang.reflect.Method;
/**
+ * Thrown when accessing an element within an annotation for
+ * which the type has changed, since compilation or serialization
+ * took place. The mismatch between the compiled or serialized
+ * type and the current type causes this exception to be thrown.
+ *
* @author Tom Tromey (address@hidden)
* @author Andrew John Hughes (address@hidden)
* @since 1.5
*/
public class AnnotationTypeMismatchException extends RuntimeException
{
+
+ /**
+ * Constructs an AnnotationTypeMismatchException
+ * which is due to a mismatched type in the annotation
+ * element, m. The erroneous type used for the
+ * data in m is represented by the string,
+ * type. This string is of an undefined format,
+ * and may contain the value as well as the type.
+ *
+ * @param m the element from the annotation.
+ * @param type the name of the erroneous type found in m.
+ */
public AnnotationTypeMismatchException(Method m, String type)
{
this.element = m;
this.foundType = type;
}
+ /**
+ * Returns the element from the annotation, for which a
+ * mismatch occurred.
+ *
+ * @return the element with the mismatched type.
+ */
public Method element()
{
return element;
}
+ /**
+ * Returns the erroneous type used by the element,
+ * represented as a String. The format
+ * of this String is not explicitly specified,
+ * and may contain the value as well as the type.
+ *
+ * @return the type found in the element.
+ */
public String foundType()
{
return foundType;
}
// Names are chosen from serialization spec.
+ /**
+ * The element from the annotation.
+ *
+ * @serial the element with the mismatched type.
+ */
private Method element;
+
+ /**
+ * The erroneous type used by the element.
+ *
+ * @serial the type found in the element.
+ */
private String foundType;
+
}
Index: java/lang/reflect/GenericArrayType.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/reflect/Attic/GenericArrayType.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 GenericArrayType.java
--- java/lang/reflect/GenericArrayType.java 27 Aug 2004 00:05:03 -0000 1.1.2.1
+++ java/lang/reflect/GenericArrayType.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
-/* GenericArrayType.java - Represent an array type with generic componet
- Copyright (C) 2004 Free Software Foundation, Inc.
+/* GenericArrayType.java - Represent an array type with a generic component
+ Copyright (C) 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,7 +38,24 @@ exception statement from your version. *
package java.lang.reflect;
-public interface GenericArrayType extends Type
+/**
+ * Represents the type of an array's components, which may be
+ * either a parameterized type or a type variable.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
+public interface GenericArrayType
+ extends Type
{
+
+ /**
+ * Returns the Type of the components within the array.
+ *
+ * @return a Type instance representing the type of
+ * the array's components.
+ */
Type getGenericComponentType();
+
}
Index: java/lang/reflect/GenericSignatureFormatError.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/reflect/Attic/GenericSignatureFormatError.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 GenericSignatureFormatError.java
--- java/lang/reflect/GenericSignatureFormatError.java 27 Aug 2004 00:05:03 -0000 1.1.2.1
+++ java/lang/reflect/GenericSignatureFormatError.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
-/* GenericSignatureFormatError.java
- Copyright (C) 2004 Free Software Foundation, Inc.
+/* GenericSignatureFormatError.java - Thrown when a signature is malformed.
+ Copyright (C) 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,9 +38,25 @@ exception statement from your version. *
package java.lang.reflect;
-public class GenericSignatureFormatError extends ClassFormatError
+/**
+ * Thrown on encountering a syntactically malformed signature in
+ * a reflective method. During reflection, the generic type signature
+ * of a type, method or constructor may be interpreted by the virtual
+ * machine. This error is thrown if this operation fails.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
+public class GenericSignatureFormatError
+ extends ClassFormatError
{
+
+ /**
+ * Constructs a new GenericSignatureFormatError.
+ */
public GenericSignatureFormatError()
{
}
+
}
Index: java/lang/reflect/ParameterizedType.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/reflect/Attic/ParameterizedType.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 ParameterizedType.java
--- java/lang/reflect/ParameterizedType.java 27 Aug 2004 00:05:03 -0000 1.1.2.1
+++ java/lang/reflect/ParameterizedType.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
-/* ParameterizedType.java
- Copyright (C) 2004 Free Software Foundation, Inc.
+/* ParameterizedType.java -- Represents parameterized types e.g. List
+ * Represents a type which is parameterized over one or more other
+ * types. For example, List<Integer> is a parameterized
+ * type, with List parameterized over the type
+ * Integer.
+ *
+ * Instances of this classes are created as needed, during reflection.
+ * On creating a parameterized type, p, the
+ * GenericTypeDeclaration corresponding to p
+ * is created and resolved. Each type argument of p
+ * is then created recursively; details of this process are availble
+ * in the documentation of TypeVariable. This creation
+ * process only happens once; repetition has no effect.
+ *
+ * Implementors of this interface must implement an appropriate
+ * equals() method. This method should equate any
+ * two instances of the implementing class that have the same
+ * GenericTypeDeclaration and Type
+ * parameters.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @see GenericTypeDeclaration
+ * @see TypeVariable
+ * @since 1.5
+ */
+public interface ParameterizedType
+ extends Type
{
+
+ /**
+ *
+ * Returns an array of Type objects, which gives
+ * the parameters of this type.
+ *
+ * Note: the returned array may be empty. This
+ * occurs if the supposed ParameterizedType is simply
+ * a normal type wrapped inside a parameterized type.
+ *
Types, representing the arguments
+ * of this type.
+ * @throws TypeNotPresentException if any of the types referred to by
+ * the parameters of this type do not actually exist.
+ * @throws MalformedParameterizedTypeException if any of the types
+ * refer to a type which can not be instantiated.
+ */
Type[] getActualTypeArguments();
+
+ /**
+ * Returns the type of which this type is a member. For example,
+ * in Top<String>.Bottom<Integer>,
+ * Bottom<Integer> is a member of
+ * Top<String>, and so the latter is returned
+ * by this method. Calling this method on top-level types (such as
+ * Top<String>) returns null.
+ *
+ * @return the type which owns this type.
+ * @throws TypeNotPresentException if the owner type referred to by
+ * this type do not actually exist.
+ * @throws MalformedParameterizedTypeException if the owner type
+ * referred to by this type can not be instantiated.
+ */
Type getOwnerType();
+
+ /**
+ * Returns a version of this type without parameters, which corresponds
+ * to the class or interface which declared the type. For example,
+ * the raw type corresponding to List<Double>
+ * is List, which was declared by the List
+ * class.
+ *
+ * @return the raw variant of this type (i.e. the type without
+ * parameters).
+ */
Type getRawType();
+
}
Index: java/lang/reflect/Type.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/reflect/Attic/Type.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 Type.java
--- java/lang/reflect/Type.java 27 Aug 2004 00:05:03 -0000 1.1.2.1
+++ java/lang/reflect/Type.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
/* Type.java - Superinterface for all types.
- Copyright (C) 2004 Free Software Foundation, Inc.
+ Copyright (C) 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,6 +38,18 @@ exception statement from your version. *
package java.lang.reflect;
+/**
+ * Represents any Type within the Java programming
+ * language. This may be a primitive type (e.g. int,
+ * an array type (e.g. double[]>/code>), a raw type
+ * (e.g. Calendar), a parameterized type
+ * (e.g. List<Boolean>, or a type
+ * variable (e.g. T extends String).
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
public interface Type
{
}
Index: java/lang/reflect/WildcardType.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/reflect/Attic/WildcardType.java,v
retrieving revision 1.1.2.1
diff -u -3 -p -u -r1.1.2.1 WildcardType.java
--- java/lang/reflect/WildcardType.java 27 Aug 2004 00:05:03 -0000 1.1.2.1
+++ java/lang/reflect/WildcardType.java 20 Feb 2005 20:48:35 -0000
@@ -1,5 +1,5 @@
-/* WildcardType.java
- Copyright (C) 2004 Free Software Foundation, Inc.
+/* WildcardType.java -- A wildcard type expression e.g. ? extends String
+ Copyright (C) 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,8 +38,78 @@ exception statement from your version. *
package java.lang.reflect;
+/**
+ * Represents a wildcard type expression, where the type variable
+ * is unnamed. The simplest example of this is ?,
+ * which represents any unbounded type. Another example is
+ * ? extends Number, which specifies any type
+ * which is a subclass of Number (Number
+ * is the upper bound).
+ *
+ *
+ * ? super String gives the type a less common lower bound,
+ * which means that the type must be either a String or one
+ * of its superclasses. This can be useful in working with collections.
+ * You may want a method to add instances of a class to a collection
+ * with a more generic type (e.g. adding Strings to
+ * a list of Objects), but don't want to allow users
+ * to pass in a collection with a more specific type.
+ *
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @since 1.5
+ */
public interface WildcardType extends Type
{
+
+ /**
+ *
+ * Returns an array of Types, which specify the
+ * lower bounds of this type. The default lower bound is
+ * null, which causes this method to return an
+ * empty array.
+ *
+ *
+ * In generating the array of Types, each
+ * ParameterizedType or TypeVariable is
+ * created, (see the documentation for these classes for details of this
+ * process), if necessary, while all other types are simply
+ * resolved.
+ *
+ *
+ * @return an array of Type objects, representing
+ * the wildcard type's lower bounds.
+ * @throws TypeNotPresentException if any of the types referred to by
+ * the lower bounds of this type do not actually exist.
+ * @throws MalformedParameterizedTypeException if any of the types
+ * refer to a type which can not be instantiated.
+ */
Type[] getLowerBounds();
+
+ /**
+ *
+ * Returns an array of Types, which specify the
+ * upper bounds of this type. The default upper bound is
+ * Object, which causes this method to return an
+ * array, containing just the Type instance for
+ * Object.
+ *
+ *
+ * In generating the array of Types, each
+ * ParameterizedType or TypeVariable is
+ * created, (see the documentation for these classes for details of this
+ * process), if necessary, while all other types are simply
+ * resolved.
+ *
+ *
+ * @return an array of Type objects, representing
+ * the wildcard type's upper bounds.
+ * @throws TypeNotPresentException if any of the types referred to by
+ * the upper bounds of this type do not actually exist.
+ * @throws MalformedParameterizedTypeException if any of the types
+ * refer to a type which can not be instantiated.
+ */
Type[] getUpperBounds();
+
}