harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [10/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/c...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ClassLoader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ClassLoader.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ClassLoader.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ClassLoader.java Sun Apr 26 12:30:01 2009
@@ -25,22 +25,28 @@
 import java.util.Enumeration;
 
 /**
+ * Loads classes and resources from a repository. One or more class loaders are
+ * installed at runtime. These are consulted whenever the runtime system needs a
+ * specific class that is not yet available in-memory. Typically, class loaders
+ * are grouped into a tree where child class loaders delegate all requests to
+ * parent class loaders. Only if the parent class loader cannot satisfy the
+ * request, the child class loader itself tries to handle it.
  * <p>
- * A ClassLoader is used for loading classes.
+ * {@code ClassLoader} is an abstract class that implements the common
+ * infrastructure required by all class loaders.
  * </p>
- * 
- * <h4>VM Implementors Note</h4>
- * <p>
- * This class must be implemented by the VM. The documented methods and natives
- * must be implemented to support other provided class implementations in this
- * package.
- * </p>
- * 
- * @since 1.0
+ *
  * @see Class
+ * @since 1.0
  */
 public abstract class ClassLoader {
 
+    /*
+     * This class must be implemented by the VM. The documented methods and
+     * natives must be implemented to support other provided class
+     * implementations in this package.
+     */
+
     /**
      * The 'System' ClassLoader; also known as the bootstrap ClassLoader.
      * 
@@ -58,17 +64,16 @@
     }
 
     /**
-     * Returns the system class loader. This is the parent for new ClassLoader
-     * instances, and is typically the class loader used to start the
-     * application. If a security manager is present, and the caller's class
-     * loader is not null and the caller's class loader is not the same as or an
-     * ancestor of the system class loader, then this method calls the security
-     * manager's checkPermission method with a
-     * RuntimePermission("getClassLoader") permission to ensure it's ok to
-     * access the system class loader. If not, a SecurityException will be
-     * thrown.
-     * 
-     * @return The system classLoader.
+     * Returns the system class loader. This is the parent for new
+     * {@code ClassLoader} instances and is typically the class loader used to
+     * start the application. If a security manager is present and the caller's
+     * class loader is neither {@code null} nor the same as or an ancestor of
+     * the system class loader, then this method calls the security manager's
+     * checkPermission method with a RuntimePermission("getClassLoader")
+     * permission to ensure that it is ok to access the system class loader. If
+     * not, a {@code SecurityException} is thrown.
+     *
+     * @return the system class loader.
      * @throws SecurityException
      *             if a security manager exists and it does not allow access to
      *             the system class loader.
@@ -78,12 +83,13 @@
     }
 
     /**
-     * Answers an URL specifying a resource which can be found by looking up
-     * resName using the system class loader's resource lookup algorithm.
-     * 
-     * @return A URL specifying a system resource or null.
+     * Finds the URL of the resource with the specified name. The system class
+     * loader's resource lookup algorithm is used to find the resource.
+     *
+     * @return the {@code URL} object for the requested resource or {@code null}
+     *         if the resource can not be found.
      * @param resName
-     *            The name of the resource to find.
+     *            the name of the resource to find.
      * @see Class#getResource
      */
     public static URL getSystemResource(String resName) {
@@ -91,15 +97,16 @@
     }
 
     /**
-     * Answers an Enumeration of URLs containing all resources which can be
-     * found by looking up resName using the system class loader's resource
-     * lookup algorithm.
-     * 
-     * @return An Enumeration of URLs containing the system resources
+     * Returns an enumeration of URLs for the resource with the specified name.
+     * The system class loader's resource lookup algorithm is used to find the
+     * resource.
+     *
+     * @return an enumeration of {@code URL} objects containing the requested
+     *         resources.
      * @param resName
-     *            String the name of the resource to find.
+     *            the name of the resource to find.
      * @throws IOException
-     *             if an IO exception occurs
+     *             if an I/O error occurs.
      */
     public static Enumeration<URL> getSystemResources(String resName)
             throws IOException {
@@ -107,14 +114,14 @@
     }
 
     /**
-     * Answers a stream on a resource found by looking up resName using the
-     * system class loader's resource lookup algorithm. Basically, the contents
-     * of the java.class.path are searched in order, looking for a path which
-     * matches the specified resource.
-     * 
-     * @return A stream on the resource or null.
+     * Returns a stream for the resource with the specified name. The system
+     * class loader's resource lookup algorithm is used to find the resource.
+     * Basically, the contents of the java.class.path are searched in order,
+     * looking for a path which matches the specified resource.
+     *
+     * @return a stream for the resource or {@code null}.
      * @param resName
-     *            The name of the resource to find.
+     *            the name of the resource to find.
      * @see Class#getResourceAsStream
      */
     public static InputStream getSystemResourceAsStream(String resName) {
@@ -124,26 +131,25 @@
     /**
      * Constructs a new instance of this class with the system class loader as
      * its parent.
-     * 
+     *
      * @throws SecurityException
      *             if a security manager exists and it does not allow the
-     *             creation of new ClassLoaders.
+     *             creation of a new {@code ClassLoader}.
      */
     protected ClassLoader() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with the given class loader as
-     * its parent.
-     * 
+     * Constructs a new instance of this class with the specified class loader
+     * as its parent.
+     *
      * @param parentLoader
-     *            The ClassLoader to use as the new class loaders parent.
+     *            The {@code ClassLoader} to use as the new class loader's
+     *            parent.
      * @throws SecurityException
      *             if a security manager exists and it does not allow the
-     *             creation of new ClassLoaders.
-     * @throws NullPointerException
-     *             if the parent is null.
+     *             creation of new a new {@code ClassLoader}.
      */
     protected ClassLoader(ClassLoader parentLoader) {
         super();
@@ -152,14 +158,22 @@
     /**
      * Constructs a new class from an array of bytes containing a class
      * definition in class file format.
-     * 
+     *
      * @param classRep
-     *            A memory image of a class file.
+     *            the memory image of a class file.
      * @param offset
-     *            The offset into the classRep.
+     *            the offset into {@code classRep}.
      * @param length
-     *            The length of the class file.
-     * @deprecated Use defineClass(String, byte[], int, int)
+     *            the length of the class file.
+     * @return the {@code Class} object created from the specified subset of
+     *         data in {@code classRep}.
+     * @throws ClassFormatError
+     *             if {@code classRep} does not contain a valid class.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0}, {@code length < 0} or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code classRep}.
+     * @deprecated Use {@link #defineClass(String, byte[], int, int)}
      */
     @Deprecated
     protected final Class<?> defineClass(byte[] classRep, int offset, int length)
@@ -170,15 +184,24 @@
     /**
      * Constructs a new class from an array of bytes containing a class
      * definition in class file format.
-     * 
+     *
      * @param className
-     *            The name of the new class
+     *            the expected name of the new class, may be {@code null} if not
+     *            known.
      * @param classRep
-     *            A memory image of a class file
+     *            the memory image of a class file.
      * @param offset
-     *            The offset into the classRep
+     *            the offset into {@code classRep}.
      * @param length
-     *            The length of the class file
+     *            the length of the class file.
+     * @return the {@code Class} object created from the specified subset of
+     *         data in {@code classRep}.
+     * @throws ClassFormatError
+     *             if {@code classRep} does not contain a valid class.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0}, {@code length < 0} or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code classRep}.
      */
     protected final Class<?> defineClass(String className, byte[] classRep,
             int offset, int length) throws ClassFormatError {
@@ -187,19 +210,33 @@
 
     /**
      * Constructs a new class from an array of bytes containing a class
-     * definition in class file format and assigns the new class to the
-     * specified protection domain.
-     * 
+     * definition in class file format and assigns the specified protection
+     * domain to the new class. If the provided protection domain is
+     * {@code null} then a default protection domain is assigned to the class.
+     *
      * @param className
-     *            The name of the new class.
+     *            the expected name of the new class, may be {@code null} if not
+     *            known.
      * @param classRep
-     *            A memory image of a class file.
+     *            the memory image of a class file.
      * @param offset
-     *            The offset into the classRep.
+     *            the offset into {@code classRep}.
      * @param length
-     *            The length of the class file.
+     *            the length of the class file.
      * @param protectionDomain
-     *            The protection domain this class should belongs to.
+     *            the protection domain to assign to the loaded class, may be
+     *            {@code null}.
+     * @return the {@code Class} object created from the specified subset of
+     *         data in {@code classRep}.
+     * @throws ClassFormatError
+     *             if {@code classRep} does not contain a valid class.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0}, {@code length < 0} or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code classRep}.
+     * @throws NoClassDefFoundError
+     *             if {@code className} is not equal to the name of the class
+     *             contained in {@code classRep}.
      */
     protected final Class<?> defineClass(String className, byte[] classRep,
             int offset, int length, ProtectionDomain protectionDomain)
@@ -208,20 +245,25 @@
     }
 
     /**
-     * <p>
-     * Defines a new class for the name, bytecodes in the byte buffer and the
-     * protection domain.
-     * </p>
-     * 
+     * Defines a new class with the specified name, byte code from the byte
+     * buffer and the optional protection domain. If the provided protection
+     * domain is {@code null} then a default protection domain is assigned to
+     * the class.
+     *
      * @param name
-     *            The name of the class to define.
+     *            the expected name of the new class, may be {@code null} if not
+     *            known.
      * @param b
-     *            The byte buffer containing the bytecodes of the new class.
+     *            the byte buffer containing the byte code of the new class.
      * @param protectionDomain
-     *            The protection domain this class belongs to.
-     * @return The defined class.
+     *            the protection domain to assign to the loaded class, may be
+     *            {@code null}.
+     * @return the {@code Class} object created from the data in {@code b}.
      * @throws ClassFormatError
-     *             if an invalid class file is defined.
+     *             if {@code b} does not contain a valid class.
+     * @throws NoClassDefFoundError
+     *             if {@code className} is not equal to the name of the class
+     *             contained in {@code b}.
      * @since 1.5
      */
     protected final Class<?> defineClass(String name, ByteBuffer b,
@@ -232,13 +274,13 @@
     }
 
     /**
-     * Overridden by subclasses, by default throws ClassNotFoundException. This
-     * method is called by loadClass() after the parent ClassLoader has failed
-     * to find a loaded class of the same name.
-     * 
-     * @return The class or null.
+     * Overridden by subclasses, throws a {@code ClassNotFoundException} by
+     * default. This method is called by {@code loadClass} after the parent
+     * {@code ClassLoader} has failed to find a loaded class of the same name.
+     *
      * @param className
-     *            The name of the class to search for.
+     *            the name of the class to look for.
+     * @return the {@code Class} object that is found.
      * @throws ClassNotFoundException
      *             if the class cannot be found.
      */
@@ -248,27 +290,27 @@
     }
 
     /**
-     * Attempts to find and return a class which has already been loaded by the
-     * virtual machine. Note that the class may not have been linked and the
-     * caller should call resolveClass() on the result if necessary.
-     * 
-     * @return The class or null.
+     * Returns the class with the specified name if it has already been loaded
+     * by the virtual machine or {@code null} if it has not yet been loaded.
+     *
      * @param className
-     *            The name of the class to search for.
+     *            the name of the class to look for.
+     * @return the {@code Class} object or {@code null} if the requested class
+     *         has not been loaded.
      */
     protected final Class<?> findLoadedClass(String className) {
         return null;
     }
 
     /**
-     * Attempts to load a class using the system class loader. Note that the
-     * class has already been been linked.
-     * 
-     * @return The class which was loaded.
+     * Finds the class with the specified name, loading it using the system
+     * class loader if necessary.
+     *
      * @param className
-     *            The name of the class to search for.
+     *            the name of the class to look for.
+     * @return the {@code Class} object with the requested {@code className}.
      * @throws ClassNotFoundException
-     *             if the class cannot be found.
+     *             if the class can not be found.
      */
     protected final Class<?> findSystemClass(String className)
             throws ClassNotFoundException {
@@ -276,54 +318,58 @@
     }
 
     /**
-     * Returns the specified ClassLoader's parent.
-     * 
-     * @return The class or null.
+     * Returns this class loader's parent.
+     *
+     * @return this class loader's parent or {@code null}.
      * @throws SecurityException
-     *             if a security manager exists and it does not allow the parent
-     *             loader to be retrieved.
+     *             if a security manager exists and it does not allow to
+     *             retrieve the parent class loader.
      */
     public final ClassLoader getParent() {
         return null;
     }
 
     /**
-     * Answers an URL which can be used to access the resource described by
+     * Returns an URL which can be used to access the resource described by
      * resName, using the class loader's resource lookup algorithm. The default
      * behavior is just to return null.
-     * 
-     * @return The location of the resource.
+     *
      * @param resName
-     *            String the name of the resource to find.
-     * @see Class#getResource(String)
+     *            the name of the resource to find.
+     * @return the {@code URL} object for the requested resource or {@code null}
+     *         if either the resource can not be found or a security manager
+     *         does not allow to access the resource.
+     * @see Class#getResource
      */
     public URL getResource(String resName) {
         return null;
     }
 
     /**
-     * Answers an Enumeration of URL which can be used to access the resources
+     * Returns an Enumeration of URL which can be used to access the resources
      * described by resName, using the class loader's resource lookup algorithm.
      * The default behavior is just to return an empty Enumeration.
-     * 
-     * @return The location of the resources.
+     *
+     * @return an enumeration of {@code URL} objects for the requested resource.
      * @param resName
-     *            String the name of the resource to find.
+     *            the name of the resource to find.
      * @throws IOException
-     *             if an IO exception occurs
+     *             if an I/O error occurs.
      */
     public Enumeration<URL> getResources(String resName) throws IOException {
         return null;
     }
 
     /**
-     * Answers a stream on a resource found by looking up resName using the
+     * Returns a stream on a resource found by looking up resName using the
      * class loader's resource lookup algorithm. The default behavior is just to
      * return null.
-     * 
-     * @return A stream on the resource or null.
+     *
+     * @return a stream for the resource or {@code null} if either the resource
+     *         can not be found or a security manager does not allow to access
+     *         the resource.
      * @param resName
-     *            String the name of the resource to find.
+     *            the name of the resource to find.
      * @see Class#getResourceAsStream
      */
     public InputStream getResourceAsStream(String resName) {
@@ -331,34 +377,42 @@
     }
 
     /**
-     * Invoked by the Virtual Machine when resolving class references.
-     * Equivalent to loadClass(className, false);
-     * 
-     * @return The Class object.
+     * Loads the class with the specified name. Invoking this method is
+     * equivalent to calling {@code loadClass(className, false)}.
+     *
+     * @return the {@code Class} object.
      * @param className
-     *            The name of the class to search for.
+     *            the name of the class to look for.
      * @throws ClassNotFoundException
-     *             if the class could not be found.
+     *             if the class can not be found.
      */
     public Class<?> loadClass(String className) throws ClassNotFoundException {
         return null;
     }
 
     /**
-     * Loads the class with the specified name, optionally linking the class
-     * after load. Steps are: 1) Call findLoadedClass(className) to determine if
-     * class is loaded 2) Call loadClass(className, resolveClass) on the parent
-     * loader. 3) Call findClass(className) to find the class
-     * 
-     * @return The Class object.
+     * Loads the class with the specified name, optionally linking it after
+     * loading. The following steps are performed:
+     * <ol>
+     * <li> Call {@link #findLoadedClass(String)} to determine if the requested
+     * class has already been loaded.</li>
+     * <li>If the class has not yet been loaded: Invoke this method on the
+     * parent class loader.</li>
+     * <li>If the class has still not been loaded: Call
+     * {@link #findClass(String)} to find the class.</li>
+     * </ol>
+     *
+     * @return the {@code Class} object.
      * @param className
-     *            The name of the class to search for.
-     * @param resolveClass
-     *            Indicates if class should be resolved after loading.
+     *            the name of the class to look for.
+     * @param resolve
+     *            Indicates if the class should be resolved after loading. This
+     *            parameter is ignored on the Android reference implementation;
+     *            classes are not resolved.
      * @throws ClassNotFoundException
-     *             if the class could not be found.
+     *             if the class can not be found.
      */
-    protected Class<?> loadClass(String className, boolean resolveClass)
+    protected Class<?> loadClass(String className, boolean resolve)
             throws ClassNotFoundException {
         return null;
     }
@@ -366,30 +420,29 @@
     /**
      * Forces a class to be linked (initialized). If the class has already been
      * linked this operation has no effect.
-     * 
+     *
      * @param clazz
-     *            The Class to link.
-     * @throws NullPointerException
-     *             if clazz is null.
+     *            the class to link.
      */
     protected final void resolveClass(Class<?> clazz) {
         return;
     }
 
     /**
-     * This method must be provided by the VM vendor, as it is used by other
-     * provided class implementations in this package. A sample implementation
-     * of this method is provided by the reference implementation. This method
-     * is used by SecurityManager.classLoaderDepth(), currentClassLoader() and
-     * currentLoadedClass(). Answers true if the receiver is a system class
+     * Indicates whether this class loader is the system class loader. This
+     * method must be provided by the virtual machine vendor, as it is used by
+     * other provided class implementations in this package. A sample
+     * implementation of this method is provided by the reference
+     * implementation. This method is used by
+     * SecurityManager.classLoaderDepth(), currentClassLoader() and
+     * currentLoadedClass(). Returns true if the receiver is a system class
      * loader.
-     * 
+     * <p>
      * Note that this method has package visibility only. It is defined here to
      * avoid the security manager check in getSystemClassLoader, which would be
      * required to implement this method anywhere else.
      *
-     * 
-     * @return <code>true</code> if the receiver is a system class loader
+     * @return {@code true} if the receiver is a system class loader
      * @see Class#getClassLoaderImpl()
      */
     final boolean isSystemClassLoader() {
@@ -397,111 +450,112 @@
     }
 
     /**
-     * <p>
-     * Answers true if the receiver is ancestor of another class loader.
-     * </p>
+     * Returns true if the receiver is ancestor of another class loader. It also
+     * returns true if the two class loader are equal.
      * <p>
      * Note that this method has package visibility only. It is defined here to
      * avoid the security manager check in getParent, which would be required to
-     * implement this method anywhere else.
-     * </p>
-     * 
+     * implement this method anywhere else. The method is also required in other
+     * places where class loaders are accesses.
+     *
      * @param child
      *            A child candidate
-     * @return <code>true</code> if the receiver is ancestor of the parameter
+     * @return {@code true} if the receiver is ancestor of, or equal to,
+     *         the parameter
      */
     final boolean isAncestorOf(ClassLoader child) {
         return false;
     }
 
     /**
-     * Answers an URL which can be used to access the resource described by
-     * resName, using the class loader's resource lookup algorithm. The default
-     * behavior is just to return null. This should be implemented by a
-     * ClassLoader.
-     * 
-     * @return The location of the resource.
+     * Finds the URL of the resource with the specified name. This
+     * implementation just returns {@code null}; it should be overridden in
+     * subclasses.
+     *
      * @param resName
-     *            The name of the resource to find.
+     *            the name of the resource to find.
+     * @return the {@code URL} object for the requested resource.
      */
     protected URL findResource(String resName) {
         return null;
     }
 
     /**
-     * Answers an Enumeration of URL which can be used to access the resources
-     * described by resName, using the class loader's resource lookup algorithm.
-     * The default behavior is just to return an empty Enumeration.
-     * 
+     * Finds an enumeration of URLs for the resource with the specified name.
+     * This implementation just returns an empty {@code Enumeration}; it should
+     * be overridden in subclasses.
+     *
      * @param resName
-     *            The name of the resource to find.
-     * 
-     * @return The locations of the resources.
-     * 
+     *            the name of the resource to find.
+     * @return an enumeration of {@code URL} objects for the requested resource.
      * @throws IOException
-     *             when an error occurs
+     *             if an I/O error occurs.
      */
     protected Enumeration<URL> findResources(String resName) throws IOException {
         return null;
     }
 
     /**
-     * Answers the absolute path of the file containing the library associated
-     * with the given name, or null. If null is answered, the system searches
-     * the directories specified by the system property "java.library.path".
-     * 
-     * @return The library file name or null.
+     * Returns the absolute path of the file containing the library with the
+     * specified name, or {@code null}. If this method returns {@code null} then
+     * the virtual machine searches the directories specified by the system
+     * property "java.library.path".
+     *
      * @param libName
-     *            The name of the library to find.
+     *            the name of the library to find.
+     * @return the absolute path of the library.
      */
     protected String findLibrary(String libName) {
         return null;
     }
 
     /**
-     * Attempt to locate the requested package. If no package information can be
-     * located, null is returned.
-     * 
+     * Returns the package with the specified name. Package information is
+     * searched in this class loader.
+     *
      * @param name
-     *            The name of the package to find
-     * @return The package requested, or null
+     *            the name of the package to find.
+     * @return the package with the requested name; {@code null} if the package
+     *         can not be found.
      */
     protected Package getPackage(String name) {
         return null;
     }
 
     /**
-     * Return all the packages known to this class loader.
-     * 
-     * @return All the packages known to this classloader
+     * Returns all the packages known to this class loader.
+     *
+     * @return an array with all packages known to this class loader.
      */
     protected Package[] getPackages() {
         return null;
     }
 
     /**
-     * Define a new Package using the specified information.
-     * 
+     * Defines and returns a new {@code Package} using the specified
+     * information. If {@code sealBase} is {@code null}, the package is left
+     * unsealed. Otherwise, the package is sealed using this URL.
+     *
      * @param name
-     *            The name of the package
+     *            the name of the package.
      * @param specTitle
-     *            The title of the specification for the Package
+     *            the title of the specification.
      * @param specVersion
-     *            The version of the specification for the Package
+     *            the version of the specification.
      * @param specVendor
-     *            The vendor of the specification for the Package
+     *            the vendor of the specification.
      * @param implTitle
-     *            The implementation title of the Package
+     *            the implementation title.
      * @param implVersion
-     *            The implementation version of the Package
+     *            the implementation version.
      * @param implVendor
-     *            The specification vendor of the Package
+     *            the specification vendor.
      * @param sealBase
-     *            If sealBase is null, the package is left unsealed. Otherwise,
-     *            the the package is sealed using this URL.
-     * @return The Package created
+     *            the URL used to seal this package or {@code null} to leave the
+     *            package unsealed.
+     * @return the {@code Package} object that has been created.
      * @throws IllegalArgumentException
-     *             if the Package already exists
+     *             if a package with the specified name already exists.
      */
     protected Package definePackage(String name, String specTitle,
             String specVersion, String specVendor, String implTitle,
@@ -511,23 +565,23 @@
     }
 
     /**
-     * Gets the signers of a class.
-     * 
+     * Gets the signers of the specified class.
+     *
      * @param c
-     *            The Class object
-     * @return signers The signers for the class
+     *            the {@code Class} object for which to get the signers.
+     * @return signers the signers of {@code c}.
      */
     final Object[] getSigners(Class<?> c) {
         return null;
     }
 
     /**
-     * Sets the signers of a class.
-     * 
+     * Sets the signers of the specified class.
+     *
      * @param c
-     *            The Class object
+     *            the {@code Class} object for which to set the signers.
      * @param signers
-     *            The signers for the class
+     *            the signers for {@code c}.
      */
     protected final void setSigners(Class<?> c, Object[] signers) {
         return;
@@ -541,10 +595,10 @@
      * </p>
      * 
      * <pre>
-     *    		&lt; user code &amp;gt; &lt;- want this class
-     *    		Class.getDeclared*();
-     *    		Class.checkMemberAccess();
-     *    		SecurityManager.checkMemberAccess(); &lt;- current frame
+     *          &lt; user code &amp;gt; &lt;- want this class
+     *          Class.getDeclared*();
+     *          Class.checkMemberAccess();
+     *          SecurityManager.checkMemberAccess(); &lt;- current frame
      * </pre>
      * 
      * <p>
@@ -623,49 +677,49 @@
     }
 
     /**
-     * Sets the assertion status of a class.
-     * 
+     * Sets the assertion status of the class with the specified name.
+     *
      * @param cname
-     *            Class name
+     *            the name of the class for which to set the assertion status.
      * @param enable
-     *            Enable or disable assertion
+     *            the new assertion status.
      */
     public void setClassAssertionStatus(String cname, boolean enable) {
         return;
     }
 
     /**
-     * Sets the assertion status of a package.
-     * 
+     * Sets the assertion status of the package with the specified name.
+     *
      * @param pname
-     *            Package name
+     *            the name of the package for which to set the assertion status.
      * @param enable
-     *            Enable or disable assertion
+     *            the new assertion status.
      */
     public void setPackageAssertionStatus(String pname, boolean enable) {
         return;
     }
 
     /**
-     * Sets the default assertion status of a classloader
-     * 
+     * Sets the default assertion status for this class loader.
+     *
      * @param enable
-     *            Enable or disable assertion
+     *            the new assertion status.
      */
     public void setDefaultAssertionStatus(boolean enable) {
         return;
     }
 
     /**
-     * Clears the default, package and class assertion status of a classloader
-     * 
+     * Sets the default assertion status for this class loader to {@code false}
+     * and removes any package default and class assertion status settings.
      */
     public void clearAssertionStatus() {
         return;
     }
 
     /**
-     * Answers the assertion status of the named class Returns the assertion
+     * Returns the assertion status of the named class Returns the assertion
      * status of the class or nested class if it has been set. Otherwise returns
      * the assertion status of its package or superpackage if that has been set.
      * Otherwise returns the default assertion status. Returns 1 for enabled and
@@ -680,7 +734,7 @@
     }
 
     /**
-     * Answers the assertion status of the named package Returns the assertion
+     * Returns the assertion status of the named package Returns the assertion
      * status of the named package or superpackage if that has been set.
      * Otherwise returns the default assertion status. Returns 1 for enabled and
      * 0 for disabled.
@@ -694,9 +748,9 @@
     }
 
     /**
-     * Answers the default assertion status
+     * Returns the default assertion status
      * 
-     * @return boolean the default assertion status.
+     * @return the default assertion status.
      */
     boolean getDefaultAssertionStatus() {
         return false;

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Compiler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Compiler.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Compiler.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Compiler.java Sun Apr 26 12:30:01 2009
@@ -18,11 +18,9 @@
 package java.lang;
 
 /**
- * This class must be implemented by the VM vendor. This class is a placeholder
- * for environments which explicitly manage the action of a "Just In Time"
- * compiler.
- * 
- * @see Cloneable
+ * Placeholder class for environments which explicitly manage the action of a
+ * <em>Just In Time (JIT)</em> compiler. This class is usually implemented by
+ * the virtual machine vendor.
  */
 public final class Compiler {
 
@@ -34,51 +32,55 @@
     }
 
     /**
-     * Low level interface to the JIT compiler. Can return any object, or null
-     * if no JIT compiler is available.
-     * 
-     * @return Object result of executing command
-     * @param cmd Object a command for the JIT compiler
+     * Executes an operation according to the specified command object. This
+     * method is the low-level interface to the JIT compiler. It may return any
+     * object or {@code null} if no JIT compiler is available.
+     *
+     * @param cmd
+     *            the command object for the JIT compiler.
+     * @return the result of executing command or {@code null}.
      */
     public static Object command(Object cmd) {
         return null;
     }
 
     /**
-     * Compiles the class using the JIT compiler. Answers true if the
-     * compilation was successful, or false if it failed or there was no JIT
-     * compiler available.
-     * 
-     * @return boolean indicating compilation success
-     * @param classToCompile java.lang.Class the class to JIT compile
+     * Compiles the specified class using the JIT compiler and indicates if
+     * compilation has been successful.
+     *
+     * @param classToCompile
+     *            java.lang.Class the class to JIT compile
+     * @return {@code true} if the compilation has been successful;
+     *         {@code false} if it has failed or if there is no JIT compiler
+     *         available.
      */
     public static boolean compileClass(Class<?> classToCompile) {
         return false;
     }
 
     /**
-     * Compiles all classes whose name matches the argument using the JIT
-     * compiler. Answers true if the compilation was successful, or false if it
-     * failed or there was no JIT compiler available.
-     * 
-     * @return boolean indicating compilation success
-     * @param nameRoot String the string to match against class names
+     * Compiles all classes whose name matches the specified name using the JIT
+     * compiler and indicates if compilation has been successful.
+     *
+     * @param nameRoot
+     *            the string to match class names with.
+     * @return {@code true} if the compilation has been successful;
+     *         {@code false} if it has failed or if there is no JIT compiler
+     *         available.
      */
     public static boolean compileClasses(String nameRoot) {
         return false;
     }
 
     /**
-     * Disable the JIT compiler
-     * 
+     * Disables the JIT compiler.
      */
     public static void disable() {
         return;
     }
 
     /**
-     * Disable the JIT compiler
-     * 
+     * Enables the JIT compiler.
      */
     public static void enable() {
         return;

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Object.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Object.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Object.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Object.java Sun Apr 26 12:30:01 2009
@@ -18,44 +18,73 @@
 package java.lang;
 
 /**
- * This class must be implemented by the vm vendor. Object is the root of the
- * java class hierarchy. All non-base types respond to the messages defined in
- * this class.
- * 
+ * The root class of the Java class hierarchy. All non-primitive types
+ * (including arrays) inherit either directly or indirectly from this class.
+ * <p>
+ * {@code Object} provides some fundamental methods for accessing the
+ * {@link Class} of an object, getting its {@link #hashCode()}, or checking
+ * whether one object {@link #equals(Object)} another. The {@link #toString()}
+ * method can be used to convert an object reference into a printable string and
+ * is often overridden in subclasses.
+ * <p>
+ * The {@link #wait()} and {@link #notify()} methods provide a foundation for
+ * synchronization, acquiring and releasing an internal monitor associated with
+ * each {@code Object}.
  */
 public class Object {
 
+    /*
+     * This class must be implemented by the vm vendor. Object is the root of
+     * the java class hierarchy. All non-base types respond to the messages
+     * defined in this class.
+     */
+
     /**
-     * Constructs a new instance of this class.
-     * 
+     * Constructs a new instance of {@code Object}.
      */
     public Object() {
     }
 
     /**
-     * Answers a new instance of the same class as the receiver, whose slots
-     * have been filled in with the values in the slots of the receiver.
-     * <p>
-     * Classes which wish to support cloning must specify that they implement
-     * the Cloneable interface, since the implementation checks for this.
-     * 
-     * @return Object a shallow copy of this object.
-     * @throws CloneNotSupportedException if the receiver's class does not
-     *         implement the interface Cloneable.
+     * Creates and returns a copy of this {@code Object}. The default
+     * implementation returns a so-called "shallow" copy: It creates a new
+     * instance of the same class and then copies the field values (including
+     * object references) from this instance to the new instance. A "deep" copy,
+     * in contrast, would also recursively clone nested objects. A subclass that
+     * needs to implement this kind of cloning should call {@code super.clone()}
+     * to create the new instance and then create deep copies of the nested,
+     * mutable objects.
+     *
+     * @return a copy of this object.
+     * @throws CloneNotSupportedException
+     *             if this object's class does not implement the {@code
+     *             Cloneable} interface.
      */
     protected Object clone() throws CloneNotSupportedException {
         return null;
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison. The
-     * implementation in Object answers true only if the argument is the exact
-     * same object as the receiver (==).
-     * 
-     * @param o Object the object to compare with this object.
-     * @return boolean <code>true</code> if the object is the same as this
-     *         object <code>false</code> if it is different from this object.
+     * Compares this instance with the specified object and indicates if they
+     * are equal. In order to be equal, {@code o} must represent the same object
+     * as this instance using a class-specific comparison. The general contract
+     * is that this comparison should be both transitive and reflexive.
+     * <p>
+     * The implementation in {@code Object} returns {@code true} only if {@code
+     * o} is the exact same object as the receiver (using the == operator for
+     * comparison). Subclasses often implement {@code equals(Object)} so that
+     * it takes into account the two object's types and states.
+     * <p>
+     * The general contract for the {@code equals(Object)} and {@link
+     * #hashCode()} methods is that if {@code equals} returns {@code true} for
+     * any two objects, then {@code hashCode()} must return the same value for
+     * these objects. This means that subclasses of {@code Object} usually
+     * override either both methods or none of them.
+     *
+     * @param o
+     *            the object to compare this instance with.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         Object}; {@code false} otherwise.
      * @see #hashCode
      */
     public boolean equals(Object o) {
@@ -63,39 +92,60 @@
     }
 
     /**
-     * Called by the virtual machine when there are no longer any (non-weak)
-     * references to the receiver. Subclasses can use this facility to guarantee
-     * that any associated resources are cleaned up before the receiver is
-     * garbage collected. Uncaught exceptions which are thrown during the
-     * running of the method cause it to terminate immediately, but are
-     * otherwise ignored.
-     * <p>
-     * Note: The virtual machine assumes that the implementation in class Object
-     * is empty.
-     * 
-     * @throws Throwable The virtual machine ignores any exceptions which are
-     *         thrown during finalization.
+     * Is called before the object's memory is being reclaimed by the VM. This
+     * can only happen once the VM has detected, during a run of the garbage
+     * collector, that the object is no longer reachable by any thread of the
+     * running application.
+     * <p>
+     * The method can be used to free system resources or perform other cleanup
+     * before the object is garbage collected. The default implementation of the
+     * method is empty, which is also expected by the VM, but subclasses can
+     * override {@code finalize()} as required. Uncaught exceptions which are
+     * thrown during the execution of this method cause it to terminate
+     * immediately but are otherwise ignored.
+     * <p>
+     * Note that the VM does guarantee that {@code finalize()} is called at most
+     * once for any object, but it doesn't guarantee when (if at all) {@code
+     * finalize()} will be called. For example, object B's {@code finalize()}
+     * can delay the execution of object A's {@code finalize()} method and
+     * therefore it can delay the reclamation of A's memory. To be safe, use a
+     * {@link java.lang.ref.ReferenceQueue}, because it provides more control
+     * over the way the VM deals with references during garbage collection.
+     *
+     * @throws Throwable
+     *             any exception which is raised during finalization; these are
+     *             ignored by the virtual machine.
      */
-
     protected void finalize() throws Throwable {
     }
 
     /**
-     * Answers the unique instance of java.lang.Class which represents the class
-     * of the receiver.
-     * 
-     * @return Class the receiver's Class
+     * Returns the unique instance of {@link Class} which represents this
+     * object's class. Note that {@code getClass()} is a special case in that it
+     * actually returns {@code Class<? extends Foo>} where {@code Foo} is the
+     * erasure of the type of expression {@code getClass()} was called upon.
+     * <p>
+     * As an example, the following code actually compiles, although one might
+     * think it shouldn't:
+     * <p>
+     * <pre>
+     * List<Integer> l = new ArrayList<Integer>();
+     * Class<? extends List> c = l.getClass();
+     * </pre>
+     *
+     * @return this object's {@code Class} instance.
      */
     public final Class<? extends Object> getClass() {
         return null;
     }
 
     /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>.equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return int the receiver's hash.
+     * Returns an integer hash code for this object. By contract, any two
+     * objects for which {@code equals(Object)} returns {@code true} must return
+     * the same hash code value. This means that subclasses of {@code Object}
+     * usually override both methods or neither method.
+     *
+     * @return this object's hash code.
      * @see #equals
      */
     public int hashCode() {
@@ -103,11 +153,25 @@
     }
 
     /**
-     * Causes one thread which is <code>wait</code> ing on the receiver to be
-     * made ready to run. This does not guarantee that the thread will
-     * immediately run. The method can only be invoked by a thread which owns
-     * the receiver's monitor.
-     * 
+     * Causes a thread which is waiting on this object's monitor (by means of
+     * calling one of the {@code wait()} methods) to be woken up. If more than
+     * one thread is waiting, one of them is chosen at the discretion of the
+     * virtual machine. The chosen thread will not run immediately. The thread
+     * that called {@code notify()} has to release the object's monitor first.
+     * Also, the chosen thread still has to compete against other threads that
+     * try to synchronize on the same object.
+     * <p>
+     * This method can only be invoked by a thread which owns this object's
+     * monitor. A thread becomes owner of an object's monitor
+     * </p>
+     * <ul>
+     * <li>by executing a synchronized method of that object;</li>
+     * <li>by executing the body of a {@code synchronized} statement that
+     * synchronizes on the object;</li>
+     * <li>by executing a synchronized static method if the object is of type
+     * {@code Class}.</li>
+     * </ul>
+     *
      * @see #notifyAll
      * @see #wait()
      * @see #wait(long)
@@ -119,13 +183,26 @@
     }
 
     /**
-     * Causes all threads which are <code>wait</code> ing on the receiver to
-     * be made ready to run. The threads are scheduled according to their
-     * priorities as specified in class Thread. Between any two threads of the
-     * same priority the one which waited first will be the first thread that
-     * runs after being notified. The method can only be invoked by a thread
-     * which owns the receiver's monitor.
-     * 
+     * Causes all threads which are waiting on this object's monitor (by means
+     * of calling one of the {@code wait()} methods) to be woken up. The threads
+     * will not run immediately. The thread that called {@code notify()} has to
+     * release the object's monitor first. Also, the threads still have to
+     * compete against other threads that try to synchronize on the same object.
+     * <p>
+     * This method can only be invoked by a thread which owns this object's
+     * monitor. A thread becomes owner of an object's monitor
+     * </p>
+     * <ul>
+     * <li>by executing a synchronized method of that object;</li>
+     * <li>by executing the body of a {@code synchronized} statement that
+     * synchronizes on the object;</li>
+     * <li>by executing a synchronized static method if the object is of type
+     * {@code Class}.</li>
+     * </ul>
+     *
+     * @throws IllegalMonitorStateException
+     *             if the thread calling this method is not the owner of this
+     *             object's monitor.
      * @see #notify
      * @see #wait()
      * @see #wait(long)
@@ -137,30 +214,45 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return String a printable representation for the receiver.
+     * Returns a string containing a concise, human-readable description of this
+     * object. Subclasses are encouraged to override this method and provide an
+     * implementation that takes into account the object's type and data. The
+     * default implementation simply concatenates the class name, the '@' sign
+     * and a hexadecimal representation of the object's {@link #hashCode()},
+     * that is, it is equivalent to the following expression:
+     *
+     * <pre>
+     * getClass().getName() + '@' + Integer.toHexString(hashCode())
+     * </pre>
+     *
+     * @return a printable representation of this object.
      */
     public String toString() {
         return null;
     }
 
     /**
-     * Causes the thread which sent this message to be made not ready to run
-     * pending some change in the receiver (as indicated by <code>notify</code>
-     * or <code>notifyAll</code>). The method can only be invoked by a thread
-     * which owns the receiver's monitor. A waiting thread can be sent
-     * <code>interrupt()</code> to cause it to prematurely stop waiting, so
-     * senders of wait should check that the condition they were waiting for has
-     * been met.
-     * <p>
-     * When the thread waits, it gives up ownership of the receiver's monitor.
-     * When it is notified (or interrupted) it re-acquires the monitor before it
-     * starts running.
-     * 
-     * @throws InterruptedException to interrupt the wait.
-     * @see Thread#interrupt
+     * Causes the calling thread to wait until another thread calls the {@code
+     * notify()} or {@code notifyAll()} method of this object. This method can
+     * only be invoked by a thread which owns this object's monitor; see
+     * {@link #notify()} on how a thread can become the owner of a monitor.
+     * <p>
+     * A waiting thread can be sent {@code interrupt()} to cause it to
+     * prematurely stop waiting, so {@code wait} should be called in a loop to
+     * check that the condition that has been waited for has been met before
+     * continuing.
+     * </p>
+     * <p>
+     * While the thread waits, it gives up ownership of this object's monitor.
+     * When it is notified (or interrupted), it re-acquires the monitor before
+     * it starts running.
+     * </p>
+     *
+     * @throws IllegalMonitorStateException
+     *             if the thread calling this method is not the owner of this
+     *             object's monitor.
+     * @throws InterruptedException
+     *             if another thread interrupts this thread while it is waiting.
      * @see #notify
      * @see #notifyAll
      * @see #wait(long)
@@ -172,53 +264,80 @@
     }
 
     /**
-     * Causes the thread which sent this message to be made not ready to run
-     * either pending some change in the receiver (as indicated by
-     * <code>notify</code> or <code>notifyAll</code>) or the expiration of
-     * the timeout. The method can only be invoked by a thread which owns the
-     * receiver's monitor. A waiting thread can be sent <code>interrupt()</code>
-     * to cause it to prematurely stop waiting, so senders of wait should check
-     * that the condition they were waiting for has been met.
-     * <p>
-     * When the thread waits, it gives up ownership of the receiver's monitor.
-     * When it is notified (or interrupted) it re-acquires the monitor before it
-     * starts running.
-     * 
-     * @param time long The maximum time to wait in milliseconds.
-     * @throws InterruptedException to interrupt the wait.
+     * Causes the calling thread to wait until another thread calls the {@code
+     * notify()} or {@code notifyAll()} method of this object or until the
+     * specified timeout expires. This method can only be invoked by a thread
+     * which owns this object's monitor; see {@link #notify()} on how a thread
+     * can become the owner of a monitor.
+     * <p>
+     * A waiting thread can be sent {@code interrupt()} to cause it to
+     * prematurely stop waiting, so {@code wait} should be called in a loop to
+     * check that the condition that has been waited for has been met before
+     * continuing.
+     * </p>
+     * <p>
+     * While the thread waits, it gives up ownership of this object's monitor.
+     * When it is notified (or interrupted), it re-acquires the monitor before
+     * it starts running.
+     * </p>
+     *
+     * @param millis
+     *            the maximum time to wait in milliseconds.
+     * @throws IllegalArgumentException
+     *             if {@code millis < 0}.
+     * @throws IllegalMonitorStateException
+     *             if the thread calling this method is not the owner of this
+     *             object's monitor.
+     * @throws InterruptedException
+     *             if another thread interrupts this thread while it is waiting.
      * @see #notify
      * @see #notifyAll
      * @see #wait()
      * @see #wait(long,int)
      * @see java.lang.Thread
      */
-    public final void wait(long time) throws InterruptedException {
+    public final void wait(long millis) throws InterruptedException {
         return;
     }
 
     /**
-     * Causes the thread which sent this message to be made not ready to run
-     * either pending some change in the receiver (as indicated by
-     * <code>notify</code> or <code>notifyAll</code>) or the expiration of
-     * the timeout. The method can only be invoked by a thread which owns the
-     * receiver's monitor. A waiting thread can be sent <code>interrupt()</code>
-     * to cause it to prematurely stop waiting, so senders of wait should check
-     * that the condition they were waiting for has been met.
-     * <p>
-     * When the thread waits, it gives up ownership of the receiver's monitor.
-     * When it is notified (or interrupted) it re-acquires the monitor before it
-     * starts running.
-     * 
-     * @param time long The maximum time to wait in milliseconds.
-     * @param frac int The fraction of a mSec to wait, specified in nanoseconds.
-     * @throws InterruptedException to interrupt the wait.
+     * Causes the calling thread to wait until another thread calls the {@code
+     * notify()} or {@code notifyAll()} method of this object or until the
+     * specified timeout expires. This method can only be invoked by a thread
+     * that owns this object's monitor; see {@link #notify()} on how a thread
+     * can become the owner of a monitor.
+     * <p>
+     * A waiting thread can be sent {@code interrupt()} to cause it to
+     * prematurely stop waiting, so {@code wait} should be called in a loop to
+     * check that the condition that has been waited for has been met before
+     * continuing.
+     * </p>
+     * <p>
+     * While the thread waits, it gives up ownership of this object's monitor.
+     * When it is notified (or interrupted), it re-acquires the monitor before
+     * it starts running.
+     * </p>
+     *
+     * @param millis
+     *            the maximum time to wait in milliseconds.
+     * @param nanos
+     *            the fraction of a millisecond to wait, specified in
+     *            nanoseconds.
+     * @throws IllegalArgumentException
+     *             if {@code millis < 0}, {@code nanos < 0} or {@code nanos >
+     *             999999}.
+     * @throws IllegalMonitorStateException
+     *             if the thread calling this method is not the owner of this
+     *             object's monitor.
+     * @throws InterruptedException
+     *             if another thread interrupts this thread while it is waiting.
      * @see #notify
      * @see #notifyAll
      * @see #wait()
-     * @see #wait(long)
+     * @see #wait(long,int)
      * @see java.lang.Thread
      */
-    public final void wait(long time, int frac) throws InterruptedException {
+    public final void wait(long millis, int nanos) throws InterruptedException {
         return;
     }
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Package.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Package.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Package.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Package.java Sun Apr 26 12:30:01 2009
@@ -22,133 +22,137 @@
 import java.net.URL;
 
 /**
- * This class must be implemented by the VM vendor.
- * 
- * An instance of class Package contains information about a Java package. This
- * includes implementation and specification versions. Typically this
- * information is retrieved from the manifest.
+ * Contains information about a Java package. This includes implementation and
+ * specification versions. Typically this information is retrieved from the
+ * manifest.
  * <p>
  * Packages are managed by class loaders. All classes loaded by the same loader
- * from the same package share a Package instance.
- * 
- * 
+ * from the same package share a {@code Package} instance.
+ *
  * @see ClassLoader
  * @since 1.0
  */
 public class Package implements AnnotatedElement {
 
+    /*
+     * This class must be implemented by the VM vendor.
+     */
+
     /**
      * Prevent this class from being instantiated
      */
     private Package(){
         //do nothing
     }
-    
+
     /**
-     * Gets the annotation associated with the given annotation type and this
-     * package.
-     * 
-     * @return An instance of {@link Annotation} or <code>null</code>.
-     * @since 1.5
+     * Gets the annotation associated with the specified annotation type and
+     * this package, if present.
+     *
+     * @param annotationType
+     *            the annotation type to look for.
+     * @return an instance of {@link Annotation} or {@code null}.
      * @see java.lang.reflect.AnnotatedElement#getAnnotation(java.lang.Class)
+     * @since 1.5
      */
     public <T extends Annotation> T getAnnotation(Class<T> annotationType) {
         return null;
     }
 
     /**
-     * Gets all of the annotations associated with this package.
-     * 
-     * @return An array of {@link Annotation} instances, which may be empty.
-     * @since 1.5
+     * Gets all annotations associated with this package, if any.
+     *
+     * @return an array of {@link Annotation} instances, which may be empty.
      * @see java.lang.reflect.AnnotatedElement#getAnnotations()
+     * @since 1.5
      */
     public Annotation[] getAnnotations() {
         return new Annotation[0];
     }
 
     /**
-     * Gets all of the annotations directly declared on this element.
-     * 
-     * @return An array of {@link Annotation} instances, which may be empty.
-     * @since 1.5
+     * Gets all annotations directly declared on this package, if any.
+     *
+     * @return an array of {@link Annotation} instances, which may be empty.
      * @see java.lang.reflect.AnnotatedElement#getDeclaredAnnotations()
+     * @since 1.5
      */
     public Annotation[] getDeclaredAnnotations() {
         return new Annotation[0];
     }
 
     /**
-     * Indicates whether or not the given annotation is present.
-     * 
-     * @return A value of <code>true</code> if the annotation is present,
-     *         otherwise <code>false</code>.
-     * @since 1.5
+     * Indicates whether the specified annotation is present.
+     *
+     * @param annotationType
+     *            the annotation type to look for.
+     * @return {@code true} if the annotation is present; {@code false}
+     *         otherwise.
      * @see java.lang.reflect.AnnotatedElement#isAnnotationPresent(java.lang.Class)
+     * @since 1.5
      */
     public boolean isAnnotationPresent(Class<? extends Annotation> annotationType) {
         return false;
     }
 
     /**
-     * Return the title of the implementation of this package, or null if this
-     * is unknown. The format of this string is unspecified.
-     * 
-     * @return The implementation title, or null
+     * Returns the title of the implementation of this package, or {@code null}
+     * if this is unknown. The format of this string is unspecified.
+     *
+     * @return the implementation title, may be {@code null}.
      */
     public String getImplementationTitle() {
         return null;
     }
 
     /**
-     * Return the name of the vendor or organization that provided this
-     * implementation of the package, or null if this is unknown. The format of
-     * this string is unspecified.
-     * 
-     * @return The implementation vendor name, or null
+     * Returns the name of the vendor or organization that provides this
+     * implementation of the package, or {@code null} if this is unknown. The
+     * format of this string is unspecified.
+     *
+     * @return the implementation vendor name, may be {@code null}.
      */
     public String getImplementationVendor() {
         return null;
     }
 
     /**
-     * Return the version of the implementation of this package, or null if this
-     * is unknown. The format of this string is unspecified.
-     * 
-     * @return The implementation version, or null
+     * Returns the version of the implementation of this package, or {@code
+     * null} if this is unknown. The format of this string is unspecified.
+     *
+     * @return the implementation version, may be {@code null}.
      */
     public String getImplementationVersion() {
         return null;
     }
 
     /**
-     * Return the name of this package in the standard dot notation; for
+     * Returns the name of this package in the standard dot notation; for
      * example: "java.lang".
      * 
-     * @return The name of this package
+     * @return the name of this package.
      */
     public String getName() {
         return null;
     }
 
     /**
-     * Attempt to locate the requested package in the caller's class loader. If
-     * no package information can be located, null is returned.
-     * 
-     * @param packageName The name of the package to find
-     * @return The package requested, or null
+     * Attempts to locate the requested package in the caller's class loader. If
+     * no package information can be located, {@code null} is returned.
      * 
-     * @see ClassLoader#getPackage
+     * @param packageName
+     *            the name of the package to find.
+     * @return the requested package, or {@code null}.
+     * @see ClassLoader#getPackage(java.lang.String)
      */
     public static Package getPackage(String packageName) {
         return null;
     }
 
     /**
-     * Return all the packages known to the caller's class loader.
-     * 
-     * @return All the packages known to the caller's class loader
+     * Returns all the packages known to the caller's class loader.
      * 
+     * @return all the packages known to the caller's class loader.
      * @see ClassLoader#getPackages
      */
     public static Package[] getPackages() {
@@ -156,89 +160,81 @@
     }
 
     /**
-     * Return the title of the specification this package implements, or null if
-     * this is unknown.
+     * Returns the title of the specification this package implements, or
+     * {@code null} if this is unknown.
      * 
-     * @return The specification title, or null
+     * @return the specification title, may be {@code null}.
      */
     public String getSpecificationTitle() {
         return null;
     }
 
     /**
-     * Return the name of the vendor or organization that owns and maintains the
-     * specification this package implements, or null if this is unknown.
+     * Returns the name of the vendor or organization that owns and maintains
+     * the specification this package implements, or {@code null} if this is
+     * unknown.
      * 
-     * @return The specification vendor name, or null
+     * @return the specification vendor name, may be {@code null}.
      */
     public String getSpecificationVendor() {
         return null;
     }
 
     /**
-     * Return the version of the specification this package implements, or null
-     * if this is unknown. The version string is a sequence of non-negative
-     * integers separated by dots; for example: "1.2.3".
+     * Returns the version of the specification this package implements, or
+     * {@code null} if this is unknown. The version string is a sequence of
+     * non-negative integers separated by dots; for example: "1.2.3".
      * 
-     * @return The specification version string, or null
+     * @return the specification version string, may be {@code null}.
      */
     public String getSpecificationVersion() {
         return null;
     }
 
-    /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
-     */
     @Override
     public int hashCode() {
         return 0;
     }
 
     /**
-     * Return true if this package's specification version is compatible with
+     * Indicates whether this package's specification version is compatible with
      * the specified version string. Version strings are compared by comparing
      * each dot separated part of the version as an integer.
-     * 
-     * @param version The version string to compare against
-     * @return true if the package versions are compatible, false otherwise
-     * 
-     * @throws NumberFormatException if the package's version string or the one
-     *         provided is not in the correct format
+     *
+     * @param version
+     *            the version string to compare against.
+     * @return {@code true} if the package versions are compatible; {@code
+     *         false} otherwise.
+     * @throws NumberFormatException
+     *             if this package's version string or the one provided are not
+     *             in the correct format.
      */
     public boolean isCompatibleWith(String version) throws NumberFormatException {
         return false;
     }
 
     /**
-     * Return true if this package is sealed, false otherwise.
-     * 
-     * @return true if this package is sealed, false otherwise
+     * Indicates whether this package is sealed.
+     *
+     * @return {@code true} if this package is sealed; {@code false} otherwise.
      */
     public boolean isSealed() {
         return false;
     }
 
     /**
-     * Return true if this package is sealed with respect to the specified URL,
-     * false otherwise.
-     * 
-     * @param url the URL to test
-     * @return true if this package is sealed, false otherwise
+     * Indicates whether this package is sealed with respect to the specified
+     * URL.
+     *
+     * @param url
+     *            the URL to check.
+     * @return {@code true} if this package is sealed with {@code url}; {@code
+     *         false} otherwise
      */
     public boolean isSealed(URL url) {
         return false;
     }
 
-    /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return a printable representation for the receiver.
-     */
     @Override
     public String toString() {
         return null;



Mime
View raw message