You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by qi...@apache.org on 2009/04/26 14:30:06 UTC
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...
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>
- * < user code &gt; <- want this class
- * Class.getDeclared*();
- * Class.checkMemberAccess();
- * SecurityManager.checkMemberAccess(); <- current frame
+ * < user code &gt; <- want this class
+ * Class.getDeclared*();
+ * Class.checkMemberAccess();
+ * SecurityManager.checkMemberAccess(); <- 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;