harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r767477 [3/5] - in /harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang: ./ ref/ reflect/
Date Wed, 22 Apr 2009 12:04:11 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Runtime.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Runtime.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Runtime.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Runtime.java Wed Apr 22 12:04:10 2009
@@ -22,29 +22,43 @@
 import java.io.OutputStream;
 
 /**
- * This class, with the exception of the exec() APIs, must be implemented by the
- * VM vendor. The exec() APIs must first do any required security checks, and
- * then call org.apache.harmony.luni.internal.process.SystemProcess.create().
- * The Runtime interface.
+ * Allows Java applications to interface with the environment in which they are
+ * running. Applications can not create an instance of this class, but they can
+ * get a singleton instance by invoking {@link #getRuntime()}.
+ *
+ * @see System
  */
 public class Runtime {
-    
+
+    /*
+    * This class, with the exception of the exec() APIs, must be implemented by the
+    * VM vendor. The exec() APIs must first do any required security checks, and
+    * then call org.apache.harmony.luni.internal.process.SystemProcess.create().
+    * The Runtime interface.
+    */
+
     /**
      * Prevent this class from being instantiated
      */
     private Runtime(){
         //do nothing
     }
-    
+
     /**
-     * Execute progArray[0] in a separate platform process The new process
-     * inherits the environment of the caller.
-     * 
-     * @param progArray the array containing the program to execute as well as
-     *        any arguments to the program.
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified command and its arguments in a separate platform
+     * process. The new process inherits the environment of the caller. Calling
+     * this method is equivalent to calling {@code exec(progArray, null, null)}.
+     *
+     * @param progArray
+     *            the array containing the program to execute as well as any
+     *            arguments to the program.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String[] progArray) throws java.io.IOException {
@@ -52,16 +66,24 @@
     }
 
     /**
-     * Execute progArray[0] in a separate platform process The new process uses
-     * the environment provided in envp
-     * 
-     * @param progArray the array containing the program to execute a well as
-     *        any arguments to the program.
-     * @param envp the array containing the environment to start the new process
-     *        in.
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified command and its arguments in a separate platform
+     * process. The new process uses the environment provided in {@code envp}.
+     * Calling this method is equivalent to calling
+     * {@code exec(progArray, envp, null)}.
+     *
+     * @param progArray
+     *            the array containing the program to execute as well as any
+     *            arguments to the program.
+     * @param envp
+     *            the array containing the environment to start the new process
+     *            in.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String[] progArray, String[] envp) throws java.io.IOException {
@@ -69,18 +91,26 @@
     }
 
     /**
-     * Execute progArray[0] in a separate platform process. The new process uses
-     * the environment provided in envp
-     * 
-     * @param progArray the array containing the program to execute a well as
-     *        any arguments to the program.
-     * @param envp the array containing the environment to start the new process
-     *        in.
-     * @param directory the directory in which to execute progArray[0]. If null,
-     *        execute in same directory as parent process.
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified command and its arguments in a separate platform
+     * process. The new process uses the environment provided in {@code envp}
+     * and the working directory specified by {@code directory}.
+     *
+     * @param progArray
+     *            the array containing the program to execute as well as any
+     *            arguments to the program.
+     * @param envp
+     *            the array containing the environment to start the new process
+     *            in.
+     * @param directory
+     *            the directory in which to execute the program. If {@code null},
+     *            execute if in the same directory as the parent process.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String[] progArray, String[] envp, File directory)
@@ -89,13 +119,19 @@
     }
 
     /**
-     * Execute program in a separate platform process The new process inherits
-     * the environment of the caller.
-     * 
-     * @param prog the name of the program to execute
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified program in a separate platform process. The new
+     * process inherits the environment of the caller. Calling this method is
+     * equivalent to calling {@code exec(prog, null, null)}.
+     *
+     * @param prog
+     *            the name of the program to execute.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String prog) throws java.io.IOException {
@@ -103,15 +139,22 @@
     }
 
     /**
-     * Execute prog in a separate platform process The new process uses the
-     * environment provided in envp
-     * 
-     * @param prog the name of the program to execute
-     * @param envp the array containing the environment to start the new process
-     *        in.
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified program in a separate platform process. The new
+     * process uses the environment provided in {@code envp}. Calling this
+     * method is equivalent to calling {@code exec(prog, envp, null)}.
+     *
+     * @param prog
+     *            the name of the program to execute.
+     * @param envp
+     *            the array containing the environment to start the new process
+     *            in.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String prog, String[] envp) throws java.io.IOException {
@@ -119,17 +162,25 @@
     }
 
     /**
-     * Execute prog in a separate platform process The new process uses the
-     * environment provided in envp
-     * 
-     * @param prog the name of the program to execute
-     * @param envp the array containing the environment to start the new process
-     *        in.
-     * @param directory the initial directory for the subprocess, or null to use
-     *        the directory of the current process
-     * @throws java.io.IOException if the program cannot be executed
-     * @throws SecurityException if the current SecurityManager disallows
-     *         program execution
+     * Executes the specified program in a separate platform process. The new
+     * process uses the environment provided in {@code envp} and the working
+     * directory specified by {@code directory}.
+     *
+     * @param prog
+     *            the name of the program to execute.
+     * @param envp
+     *            the array containing the environment to start the new process
+     *            in.
+     * @param directory
+     *            the directory in which to execute the program. If {@code null},
+     *            execute if in the same directory as the parent process.
+     * @return the new {@code Process} object that represents the platform
+     *         process.
+     * @throws java.io.IOException
+     *             if the requested program can not be executed.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} disallows program
+     *             execution.
      * @see SecurityManager#checkExec
      */
     public Process exec(String prog, String[] envp, File directory) throws java.io.IOException {
@@ -137,13 +188,17 @@
     }
 
     /**
-     * Causes the virtual machine to stop running, and the program to exit. If
-     * runFinalizersOnExit(true) has been invoked, then all finalizers will be
-     * run first.
-     * 
-     * @param code the return code.
-     * @throws SecurityException if the running thread is not allowed to cause
-     *         the vm to exit.
+     * Causes the virtual machine to stop running and the program to exit. If
+     * {@link #runFinalizersOnExit(boolean)} has been previously invoked with a
+     * {@code true} argument, then all all objects will be properly
+     * garbage-collected and finalized first.
+     *
+     * @param code
+     *            the return code. By convention, non-zero return codes indicate
+     *            abnormal terminations.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} does not allow the
+     *             running thread to terminate the virtual machine.
      * @see SecurityManager#checkExit
      */
     public void exit(int code) {
@@ -151,49 +206,65 @@
     }
 
     /**
-     * Answers the amount of free memory resources which are available to the
+     * Returns the amount of free memory resources which are available to the
      * running program.
      * 
+     * @return the approximate amount of free memory, measured in bytes.
      */
     public long freeMemory() {
         return 0L;
     }
 
     /**
-     * Indicates to the virtual machine that it would be a good time to collect
-     * available memory. Note that, this is a hint only.
-     * 
+     * Indicates to the virtual machine that it would be a good time to run the
+     * garbage collector. Note that this is a hint only. There is no guarantee
+     * that the garbage collector will actually be run.
      */
     public void gc() {
         return;
     }
 
     /**
-     * Return the single Runtime instance
+     * Returns the single {@code Runtime} instance.
      * 
+     * @return the {@code Runtime} object for the current application.
      */
     public static Runtime getRuntime() {
         return null;
     }
 
     /**
-     * Loads and links the library specified by the argument.
-     * 
-     * @param pathName the absolute (ie: platform dependent) path to the library
-     *        to load
-     * @throws UnsatisfiedLinkError if the library could not be loaded
-     * @throws SecurityException if the library was not allowed to be loaded
+     * Loads and links the dynamic library that is identified through the
+     * specified path. This method is similar to {@link #loadLibrary(String)},
+     * but it accepts a full path specification whereas {@code loadLibrary} just
+     * accepts the name of the library to load.
+     *
+     * @param pathName
+     *            the absolute (platform dependent) path to the library to load.
+     * @throws UnsatisfiedLinkError
+     *             if the library can not be loaded.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} does not allow to load
+     *             the library.
+     * @see SecurityManager#checkLink
      */
     public void load(String pathName) {
         return;
     }
 
     /**
-     * Loads and links the library specified by the argument.
-     * 
-     * @param libName the name of the library to load
-     * @throws UnsatisfiedLinkError if the library could not be loaded
-     * @throws SecurityException if the library was not allowed to be loaded
+     * Loads and links the library with the specified name. The mapping of the
+     * specified library name to the full path for loading the library is
+     * implementation-dependent.
+     *
+     * @param libName
+     *            the name of the library to load.
+     * @throws UnsatisfiedLinkError
+     *             if the library can not be loaded.
+     * @throws SecurityException
+     *             if the current {@code SecurityManager} does not allow to load
+     *             the library.
+     * @see SecurityManager#checkLink
      */
     public void loadLibrary(String libName) {
         return;
@@ -202,18 +273,20 @@
     /**
      * Provides a hint to the virtual machine that it would be useful to attempt
      * to perform any outstanding object finalizations.
-     * 
      */
     public void runFinalization() {
         return;
     }
 
     /**
-     * Ensure that, when the virtual machine is about to exit, all objects are
-     * finalized. Note that all finalization which occurs when the system is
-     * exiting is performed after all running threads have been terminated.
-     * 
-     * @param run true means finalize all on exit.
+     * Sets the flag that indicates whether all objects are finalized when the
+     * virtual machine is about to exit. Note that all finalization which occurs
+     * when the system is exiting is performed after all running threads have
+     * been terminated.
+     *
+     * @param run
+     *            {@code true} to enable finalization on exit, {@code false} to
+     *            disable it.
      * @deprecated This method is unsafe.
      */
     @Deprecated
@@ -222,34 +295,47 @@
     }
 
     /**
-     * Answers the total amount of memory resources which is available to (or in
-     * use by) the running program.
-     * 
+     * Returns the total amount of memory which is available to the running
+     * program.
+     *
+     * @return the total amount of memory, measured in bytes.
      */
     public long totalMemory() {
         return 0L;
     }
 
     /**
-     * Turns the output of debug information for instructions on or off.
-     * 
-     * @param enable if true, turn trace on. false turns trace off.
+     * Switches the output of debug information for instructions on or off.
+     *
+     * @param enable
+     *            {@code true} to switch tracing on, {@code false} to switch it
+     *            off.
      */
     public void traceInstructions(boolean enable) {
         return;
     }
 
     /**
-     * Turns the output of debug information for methods on or off.
-     * 
-     * @param enable if true, turn trace on. false turns trace off.
+     * Switches the output of debug information for methods on or off.
+     *
+     * @param enable
+     *            {@code true} to switch tracing on, {@code false} to switch it
+     *            off.
      */
     public void traceMethodCalls(boolean enable) {
         return;
     }
 
     /**
-     * @deprecated Use InputStreamReader
+     * Returns the localized version of the specified input stream. The input
+     * stream that is returned automatically converts all characters from the
+     * local character set to Unicode after reading them from the underlying
+     * stream.
+     *
+     * @param stream
+     *            the input stream to localize.
+     * @return the localized input stream.
+     * @deprecated Use {@link java.io.InputStreamReader}.
      */
     @Deprecated
     public InputStream getLocalizedInputStream(InputStream stream) {
@@ -257,7 +343,15 @@
     }
 
     /**
-     * @deprecated Use OutputStreamWriter
+     * Returns the localized version of the specified output stream. The output
+     * stream that is returned automatically converts all characters from
+     * Unicode to the local character set before writing them to the underlying
+     * stream.
+     *
+     * @param stream
+     *            the output stream to localize.
+     * @return the localized output stream.
+     * @deprecated Use {@link java.io.OutputStreamWriter}.
      */
     @Deprecated
     public OutputStream getLocalizedOutputStream(OutputStream stream) {
@@ -265,9 +359,41 @@
     }
 
     /**
-     * Registers a new virtual-machine shutdown hook.
-     * 
-     * @param hook the hook (a Thread) to register
+     * Registers a virtual-machine shutdown hook. A shutdown hook is a
+     * {@code Thread} that is ready to run, but has not yet been started. All
+     * registered shutdown hooks will be executed once the virtual machine shuts
+     * down properly. A proper shutdown happens when either the
+     * {@link #exit(int)} method is called or the surrounding system decides to
+     * terminate the application, for example in response to a {@code CTRL-C} or
+     * a system-wide shutdown. A termination of the virtual machine due to the
+     * {@link #halt(int)} method, an {@link Error} or a {@code SIGKILL}, in
+     * contrast, is not considered a proper shutdown. In these cases the
+     * shutdown hooks will not be run.
+     * <p>
+     * Shutdown hooks are run concurrently and in an unspecified order. Hooks
+     * failing due to an unhandled exception are not a problem, but the stack
+     * trace might be printed to the console. Once initiated, the whole shutdown
+     * process can only be terminated by calling {@code halt()}.
+     * <p>
+     * If {@link #runFinalizersOnExit(boolean)} has been called with a {@code
+     * true} argument, garbage collection and finalization will take place after
+     * all hooks are either finished or have failed. Then the virtual machine
+     * terminates.
+     * <p>
+     * It is recommended that shutdown hooks do not do any time-consuming
+     * activities, in order to not hold up the shutdown process longer than
+     * necessary.
+     *
+     * @param hook
+     *            the shutdown hook to register.
+     * @throws IllegalArgumentException
+     *             if the hook has already been started or if it has already
+     *             been registered.
+     * @throws IllegalStateException
+     *             if the virtual machine is already shutting down.
+     * @throws SecurityException
+     *             if a SecurityManager is registered and the calling code
+     *             doesn't have the RuntimePermission("shutdownHooks").
      */
     public void addShutdownHook(Thread hook) {
         // Check hook for null
@@ -278,10 +404,17 @@
     }
 
     /**
-     * De-registers a previously-registered virtual-machine shutdown hook.
-     * 
-     * @param hook the hook (a Thread) to de-register
-     * @return true if the hook could be de-registered
+     * Unregisters a previously registered virtual machine shutdown hook.
+     *
+     * @param hook
+     *            the shutdown hook to remove.
+     * @return {@code true} if the hook has been removed successfully; {@code
+     *         false} otherwise.
+     * @throws IllegalStateException
+     *             if the virtual machine is already shutting down.
+     * @throws SecurityException
+     *             if a SecurityManager is registered and the calling code
+     *             doesn't have the RuntimePermission("shutdownHooks").
      */
     public boolean removeShutdownHook(Thread hook) {
         // Check hook for null
@@ -293,29 +426,38 @@
 
     /**
      * Causes the virtual machine to stop running, and the program to exit.
-     * Finalizers will not be run first. Shutdown hooks will not be run.
-     * 
+     * Neither shutdown hooks nor finalizers are run before.
+     *
      * @param code
-     *            the return code.
+     *            the return code. By convention, non-zero return codes indicate
+     *            abnormal terminations.
      * @throws SecurityException
-     *                if the running thread is not allowed to cause the vm to
-     *                exit.
+     *             if the current {@code SecurityManager} does not allow the
+     *             running thread to terminate the virtual machine.
      * @see SecurityManager#checkExit
+     * @see #addShutdownHook(Thread)
+     * @see #removeShutdownHook(Thread)
+     * @see #runFinalizersOnExit(boolean)
      */
     public void halt(int code) {
         return;
     }
 
     /**
-     * Return the number of processors, always at least one.
+     * Returns the number of processors available to the virtual machine.
+     *
+     * @return the number of available processors, at least 1.
      */
     public int availableProcessors() {
         return 0;
     }
 
     /**
-     * Return the maximum memory that will be used by the virtual machine, or
-     * Long.MAX_VALUE.
+     * Returns the maximum amount of memory that may be used by the virtual
+     * machine, or {@code Long.MAX_VALUE} if there is no such limit.
+     *
+     * @return the maximum amount of memory that the virtual machine will try to
+     *         allocate, measured in bytes.
      */
     public long maxMemory() {
         return 0L;

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/StackTraceElement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/StackTraceElement.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/StackTraceElement.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/StackTraceElement.java Wed Apr 22 12:04:10 2009
@@ -22,11 +22,10 @@
 import java.io.Serializable;
 
 /**
- * An implementation of this class is provided, but the documented constructor
- * can be used by the VM specific implementation to create instances.
- * 
- * StackTraceElement represents a stack frame.
- * 
+ * A representation of a single stack frame. Arrays of {@code StackTraceElement}
+ * are stored in {@link Throwable} objects to represent the whole state of the
+ * call stack at the time a {@code Throwable} gets thrown.
+ *
  * @see Throwable#getStackTrace()
  * @since 1.4
  */
@@ -43,21 +42,21 @@
     int lineNumber;
 
     /**
-     * <p>
-     * Constructs a <code>StackTraceElement</code> for an execution point.
-     * </p>
-     * 
-     * @param cls The fully qualified name of the class where execution is at.
-     * @param method The name of the method where execution is at.
-     * @param file The name of the file where execution is at or
-     *        <code>null</code>.
-     * @param line The line of the file where execution is at, a negative number
-     *        if unknown or <code>-2</code> if the execution is in a native
-     *        method.
-     * 
-     * @throws NullPointerException if <code>cls</code> or <code>method</code>
-     *         is <code>null</code>.
-     * 
+     * Constructs a new {@code StackTraceElement} for a specified execution
+     * point.
+     *
+     * @param cls
+     *            the fully qualified name of the class where execution is at.
+     * @param method
+     *            the name of the method where execution is at.
+     * @param file
+     *            The name of the file where execution is at or {@code null}.
+     * @param line
+     *            the line of the file where execution is at, a negative number
+     *            if unknown or {@code -2} if the execution is in a native
+     *            method.
+     * @throws NullPointerException
+     *             if {@code cls} or {@code method} is {@code null}.
      * @since 1.5
      */
     public StackTraceElement(String cls, String method, String file, int line) {
@@ -81,9 +80,22 @@
     }
 
     /**
-     * Compare this object with the object passed in
-     * 
-     * @param obj Object to compare with
+     * Compares this instance with the specified object and indicates if they
+     * are equal. In order to be equal, the following conditions must be
+     * fulfilled:
+     * <ul>
+     * <li>{@code obj} must be a stack trace element,</li>
+     * <li>the method names of this stack trace element and of {@code obj} must
+     * not be {@code null},</li>
+     * <li>the class, method and file names as well as the line number of this
+     * stack trace element and of {@code obj} must be equal.</li>
+     * </ul>
+     *
+     * @param obj
+     *            the object to compare this instance with.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code StackTraceElement}; {@code false} otherwise.
+     * @see #hashCode
      */
     @Override
     public boolean equals(Object obj) {
@@ -124,57 +136,48 @@
     }
 
     /**
-     * Returns the full name (i.e. including the package) of the class where
-     * this stack trace element is executing.
+     * Returns the fully qualified name of the class belonging to this
+     * {@code StackTraceElement}.
      * 
-     * @return the fully qualified type name of the class where this stack trace
-     *         element is executing.
+     * @return the fully qualified type name of the class
      */
     public String getClassName() {
         return (declaringClass == null) ? "<unknown class>" : declaringClass;
     }
 
     /**
-     * If available, returns the name of the file containing the Java code
-     * source which was compiled into the class where this stack trace element
-     * is executing.
+     * Returns the name of the Java source file containing class belonging to
+     * this {@code StackTraceElement}.
      * 
-     * @return if available, the name of the file containing the Java code
-     *         source for the stack trace element's executing class. If no such
-     *         detail is available, a <code>null</code> value is returned.
+     * @return the name of the file, or {@code null} if this information is not
+     *         available.
      */
     public String getFileName() {
         return fileName;
     }
 
     /**
-     * If available, returns the line number in the source for the class where
-     * this stack trace element is executing.
+     * Returns the line number in the source for the class belonging to this
+     * {@code StackTraceElement}.
      * 
-     * @return if available, the line number in the source file for the class
-     *         where this stack trace element is executing. If no such detail is
-     *         available, a number less than <code>0</code>.
+     * @return the line number, or a negative number if this information is not
+     *         available.
      */
     public int getLineNumber() {
         return lineNumber;
     }
 
     /**
-     * Returns the name of the method where this stack trace element is
-     * executing.
+     * Returns the name of the method belonging to this {@code
+     * StackTraceElement}.
      * 
-     * @return the name of the method where this stack trace element is
-     *         executing.
+     * @return the name of the method, or "<unknown method>" if this information
+     *         is not available.
      */
     public String getMethodName() {
         return (methodName == null) ? "<unknown method>" : methodName;
     }
 
-    /**
-     * Return this StackTraceElement objects hash code
-     * 
-     * @return This objects hash code
-     */
     @Override
     public int hashCode() {
         /*
@@ -190,21 +193,16 @@
     }
 
     /**
-     * Returns <code>true</code> if the method name returned by
-     * {@link #getMethodName()} is implemented as a native method.
+     * Indicates if the method name returned by {@link #getMethodName()} is
+     * implemented as a native method.
      * 
-     * @return if the method in which this stack trace element is executing is a
-     *         native method
+     * @return {@code true} if the method in which this stack trace element is
+     *         executing is a native method; {@code false} otherwise.
      */
     public boolean isNativeMethod() {
         return lineNumber == -2;
     }
 
-    /**
-     * Return a String representing this StackTraceElement object
-     * 
-     * @return String representing this object
-     */
     @Override
     public String toString() {
         StringBuilder buf = new StringBuilder(80);

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/System.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/System.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/System.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/System.java Wed Apr 22 12:04:10 2009
@@ -33,9 +33,12 @@
 import java.util.PropertyPermission;
 
 /**
- * Class System provides a standard place for programs to find system related
- * information. All System API is static.
- * 
+ * Provides access to system-related information and resources including
+ * standard input and output. Enables clients to dynamically load native
+ * libraries. All methods of this class are accessed in a static way and the
+ * class itself can not be instantiated.
+ *
+ * @see Runtime
  */
 public final class System {
 
@@ -43,24 +46,26 @@
     // Typically, these are connected to the shell which
     // ran the Java program.
     /**
-     * Default input stream
+     * Default input stream.
      */
     public static final InputStream in;
 
     /**
-     * Default output stream
+     * Default output stream.
      */
     public static final PrintStream out;
 
     /**
-     * Default error output stream
+     * Default error output stream.
      */
     public static final PrintStream err;
 
     // Get a ref to the Runtime instance for faster lookup
     private static final Runtime RUNTIME = Runtime.getRuntime();
 
-    // The System Properties table
+    /**
+     * The System Properties table.
+     */
     private static Properties systemProperties;
 
     // The System default SecurityManager
@@ -83,10 +88,15 @@
     }
 
     /**
-     * Sets the value of the static slot "in" in the receiver to the passed in
-     * argument.
+     * Sets the standard input stream to the given user defined input stream.
      * 
-     * @param newIn the new value for in.
+     * @param newIn
+     *            the user defined input stream to set as the standard input
+     *            stream.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPermission()} method does not allow the change of the
+     *             stream.
      */
     @SuppressWarnings("unused")
     public static void setIn(InputStream newIn) {
@@ -95,10 +105,15 @@
     }
 
     /**
-     * Sets the value of the static slot "out" in the receiver to the passed in
-     * argument.
+     * Sets the standard output stream to the given user defined output stream.
      * 
-     * @param newOut the new value for out.
+     * @param newOut
+     *            the user defined output stream to set as the standard output
+     *            stream.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPermission()} method does not allow the change of the
+     *             stream.
      */
     @SuppressWarnings("unused")
     public static void setOut(java.io.PrintStream newOut) {
@@ -107,10 +122,16 @@
     }
 
     /**
-     * Sets the value of the static slot "err" in the receiver to the passed in
-     * argument.
+     * Sets the standard error output stream to the given user defined output
+     * stream.
      * 
-     * @param newErr the new value for err.
+     * @param newErr
+     *            the user defined output stream to set as the standard error
+     *            output stream.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPermission()} method does not allow the change of the
+     *             stream.
      */
     @SuppressWarnings("unused")
     public static void setErr(java.io.PrintStream newErr) {
@@ -124,21 +145,27 @@
     }
 
     /**
-     * Copies the contents of <code>array1</code> starting at offset
-     * <code>start1</code> into <code>array2</code> starting at offset
-     * <code>start2</code> for <code>length</code> elements.
-     * 
-     * @param array1 the array to copy out of
-     * @param start1 the starting index in array1
-     * @param array2 the array to copy into
-     * @param start2 the starting index in array2
-     * @param length the number of elements in the array to copy
+     * Copies the number of {@code length} elements of the Array {@code src}
+     * starting at the offset {@code srcPos} into the Array {@code dest} at
+     * the position {@code destPos}.
+     *
+     * @param src
+     *            the source array to copy the content.
+     * @param srcPos
+     *            the starting index of the content in {@code src}.
+     * @param dest
+     *            the destination array to copy the data into.
+     * @param destPos
+     *            the starting index for the copied content in {@code dest}.
+     * @param length
+     *            the number of elements of the {@code array1} content they have
+     *            to be copied.
      */
-    public static void arraycopy(Object array1, int start1, Object array2, int start2,
+    public static void arraycopy(Object src, int srcPos, Object dest, int destPos,
             int length) {
         // sending getClass() to both arguments will check for null
-        Class<?> type1 = array1.getClass();
-        Class<?> type2 = array2.getClass();
+        Class<?> type1 = src.getClass();
+        Class<?> type2 = dest.getClass();
         if (!type1.isArray() || !type2.isArray()) {
             throw new ArrayStoreException();
         }
@@ -148,27 +175,27 @@
             if (componentType2.isPrimitive()) {
                 throw new ArrayStoreException();
             }
-            arraycopy((Object[]) array1, start1, (Object[]) array2, start2, length);
+            arraycopy((Object[]) src, srcPos, (Object[]) dest, destPos, length);
         } else {
             if (componentType2 != componentType1) {
                 throw new ArrayStoreException();
             }
             if (componentType1 == Integer.TYPE) {
-                arraycopy((int[]) array1, start1, (int[]) array2, start2, length);
+                arraycopy((int[]) src, srcPos, (int[]) dest, destPos, length);
             } else if (componentType1 == Byte.TYPE) {
-                arraycopy((byte[]) array1, start1, (byte[]) array2, start2, length);
+                arraycopy((byte[]) src, srcPos, (byte[]) dest, destPos, length);
             } else if (componentType1 == Long.TYPE) {
-                arraycopy((long[]) array1, start1, (long[]) array2, start2, length);
+                arraycopy((long[]) src, srcPos, (long[]) dest, destPos, length);
             } else if (componentType1 == Short.TYPE) {
-                arraycopy((short[]) array1, start1, (short[]) array2, start2, length);
+                arraycopy((short[]) src, srcPos, (short[]) dest, destPos, length);
             } else if (componentType1 == Character.TYPE) {
-                arraycopy((char[]) array1, start1, (char[]) array2, start2, length);
+                arraycopy((char[]) src, srcPos, (char[]) dest, destPos, length);
             } else if (componentType1 == Boolean.TYPE) {
-                arraycopy((boolean[]) array1, start1, (boolean[]) array2, start2, length);
+                arraycopy((boolean[]) src, srcPos, (boolean[]) dest, destPos, length);
             } else if (componentType1 == Double.TYPE) {
-                arraycopy((double[]) array1, start1, (double[]) array2, start2, length);
+                arraycopy((double[]) src, srcPos, (double[]) dest, destPos, length);
             } else if (componentType1 == Float.TYPE) {
-                arraycopy((float[]) array1, start1, (float[]) array2, start2, length);
+                arraycopy((float[]) src, srcPos, (float[]) dest, destPos, length);
             }
         }
     }
@@ -429,20 +456,22 @@
     }
 
     /**
-     * Answers the current time expressed as milliseconds since the time
-     * 00:00:00 UTC on January 1, 1970.
-     * 
-     * @return the time in milliseconds.
+     * Returns the current system time in milliseconds since January 1, 1970
+     * 00:00:00 UTC. This method shouldn't be used for measuring timeouts or
+     * other elapsed time measurements, as changing the system time can affect
+     * the results.
+     *
+     * @return the local system time in milliseconds.
      */
     public static native long currentTimeMillis();
 
     /**
-     * <p>
-     * Returns the most precise time measurement in nanoseconds that's
-     * available.
-     * </p>
-     * 
-     * @return The current time in nanoseconds.
+     * Returns the current timestamp of the most precise timer available on the
+     * local system. This timestamp can only be used to measure an elapsed
+     * period by comparing it against another timestamp. It cannot be used as a
+     * very exact system time expression.
+     *
+     * @return the current timestamp in nanoseconds.
      */
     public static native long nanoTime();
 
@@ -520,15 +549,16 @@
     }
 
     /**
-     * Causes the virtual machine to stop running, and the program to exit. If
-     * runFinalizersOnExit(true) has been invoked, then all finalizers will be
-     * run first.
-     * 
-     * @param code the return code.
-     * 
-     * @throws SecurityException if the running thread is not allowed to cause
-     *         the vm to exit.
-     * 
+     * Causes the virtual machine to stop running and the program to exit. If
+     * {@link #runFinalizersOnExit(boolean)} has been previously invoked with a
+     * {@code true} argument, then all all objects will be properly
+     * garbage-collected and finalized first.
+     *
+     * @param code
+     *            the return code.
+     * @throws SecurityException
+     *             if the running thread has not enough permission to exit the
+     *             virtual machine.
      * @see SecurityManager#checkExit
      */
     public static void exit(int code) {
@@ -536,36 +566,46 @@
     }
 
     /**
-     * Indicate to the virtual machine that it would be a good time to collect
-     * available memory. Note that, this is a hint only.
+     * Indicates to the virtual machine that it would be a good time to run the
+     * garbage collector. Note that this is a hint only. There is no guarantee
+     * that the garbage collector will actually be run.
      */
     public static void gc() {
         RUNTIME.gc();
     }
 
     /**
-     * Returns an environment variable.
-     * 
-     * @param var the name of the environment variable
-     * @return the value of the specified environment variable
+     * Returns the value of the environment variable with the given name {@code
+     * var}.
+     *
+     * @param name
+     *            the name of the environment variable.
+     * @return the value of the specified environment variable or {@code null}
+     *         if no variable exists with the given name.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPermission()} method does not allow the querying of
+     *             single environment variables.
      */
-    public static String getenv(String var) {
-        if (var == null) {
+    public static String getenv(String name) {
+        if (name == null) {
             throw new NullPointerException();
         }
         SecurityManager secMgr = System.getSecurityManager();
         if (secMgr != null) {
-            secMgr.checkPermission(new RuntimePermission("getenv." + var));
+            secMgr.checkPermission(new RuntimePermission("getenv." + name));
         }
         throw new Error();
     }
 
     /**
-     * <p>
-     * Returns all environment variables.
-     * </p>
-     * 
-     * @return A Map of all environment variables.
+     * Returns an unmodifiable map of all available environment variables.
+     *
+     * @return the map representing all environment variables.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPermission()} method does not allow the querying of
+     *             all environment variables.
      */
     public static Map<String, String> getenv() {
         SecurityManager secMgr = System.getSecurityManager();
@@ -576,12 +616,12 @@
     }
 
     /**
-     * <p>
-     * Returns the inherited channel from the system-wide provider.
-     * </p>
-     * 
-     * @return A {@link Channel} or <code>null</code>.
+     * Returns the inherited channel from the creator of the current virtual
+     * machine.
+     *
+     * @return the inherited {@link Channel} or {@code null} if none exists.
      * @throws IOException
+     *             if an I/O error occurred.
      * @see SelectorProvider
      * @see SelectorProvider#inheritedChannel()
      */
@@ -590,13 +630,14 @@
     }
 
     /**
-     * Answers the system properties. Note that this is not a copy, so that
+     * Returns the system properties. Note that this is not a copy, so that
      * changes made to the returned Properties object will be reflected in
      * subsequent calls to getProperty and getProperties.
-     * <p>
-     * Security managers should restrict access to this API if possible.
-     * 
-     * @return the system properties
+     *
+     * @return the system properties.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPropertiesAccess()} method does not allow the operation.
      */
     public static Properties getProperties() {
         SecurityManager secMgr = System.getSecurityManager();
@@ -607,7 +648,7 @@
     }
 
     /**
-     * Answers the system properties without any security checks. This is used
+     * Returns the system properties without any security checks. This is used
      * for access from within java.lang.
      * 
      * @return the system properties
@@ -617,8 +658,8 @@
     }
 
     /**
-     * Answers the value of a particular system property. Answers null if no
-     * such property exists,
+     * Returns the value of a particular system property or {@code null} if no
+     * such property exists.
      * <p>
      * The properties currently provided by the virtual machine are:
      * 
@@ -641,22 +682,32 @@
      *        java.home
      * </pre>
      * 
-     * @param prop the system property to look up
-     * @return the value of the specified system property, or null if the
-     *         property doesn't exist
+     * @param prop
+     *            the name of the system property to look up.
+     * @return the value of the specified system property or {@code null} if the
+     *         property doesn't exist.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPropertyAccess()} method does not allow the operation.
      */
     public static String getProperty(String prop) {
         return getProperty(prop, null);
     }
 
     /**
-     * Answers the value of a particular system property. If no such property is
-     * found, answers the defaultValue.
-     * 
-     * @param prop the system property to look up
-     * @param defaultValue return value if system property is not found
-     * @return the value of the specified system property, or defaultValue if
-     *         the property doesn't exist
+     * Returns the value of a particular system property. The {@code
+     * defaultValue} will be returned if no such property has been found.
+     *
+     * @param prop
+     *            the name of the system property to look up.
+     * @param defaultValue
+     *            the return value if the system property with the given name
+     *            does not exist.
+     * @return the value of the specified system property or the {@code
+     *         defaultValue} if the property does not exist.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPropertyAccess()} method does not allow the operation.
      */
     public static String getProperty(String prop, String defaultValue) {
         if (prop.length() == 0) {
@@ -671,10 +722,16 @@
 
     /**
      * Sets the value of a particular system property.
-     * 
-     * @param prop the system property to change
-     * @param value the value to associate with prop
-     * @return the old value of the property, or null
+     *
+     * @param prop
+     *            the name of the system property to be changed.
+     * @param value
+     *            the value to associate with the given property {@code prop}.
+     * @return the old value of the property or {@code null} if the property
+     *         didn't exist.
+     * @throws SecurityException
+     *             if a security manager exists and write access to the
+     *             specified property is not allowed.
      */
     public static String setProperty(String prop, String value) {
         if (prop.length() == 0) {
@@ -688,24 +745,18 @@
     }
 
     /**
-     * <p>
-     * Removes the system property for the specified key.
-     * </p>
-     * 
-     * <p>
-     * Please see the Java SE API documentation for further
-     * information on this method.
-     * <p>
-     * 
-     * @param key the system property to be removed.
-     * @return previous value or null if no value existed
-     * 
-     * @throws NullPointerException if the <code>key</code> argument is
-     *         <code>null</code>.
-     * @throws IllegalArgumentException if the <code>key</code> argument is
-     *         empty.
-     * @throws SecurityException if a security manager exists and write access
-     *         to the specified property is not allowed.
+     * Removes a specific system property.
+     *
+     * @param key
+     *            the name of the system property to be removed.
+     * @return the property value or {@code null} if the property didn't exist.
+     * @throws NullPointerException
+     *             if the argument {@code key} is {@code null}.
+     * @throws IllegalArgumentException
+     *             if the argument {@code key} is empty.
+     * @throws SecurityException
+     *             if a security manager exists and write access to the
+     *             specified property is not allowed.
      * @since 1.5
      */
     public static String clearProperty(String key) {
@@ -740,8 +791,8 @@
     private static native String getEncoding(int type);
 
     /**
-     * Answers the active security manager.
-     * 
+     * Returns the active security manager.
+     *
      * @return the system security manager object.
      */
     public static SecurityManager getSecurityManager() {
@@ -749,14 +800,14 @@
     }
 
     /**
-     * Answers an integer hash code for the parameter. The hash code returned is
-     * the same one that would be returned by java.lang.Object.hashCode(),
-     * whether or not the object's class has overridden hashCode(). The hash
-     * code for null is 0.
-     * 
-     * @param anObject the object
-     * @return the hash code for the object
-     * 
+     * Returns an integer hash code for the parameter. The hash code returned is
+     * the same one that would be returned by the method {@code
+     * java.lang.Object.hashCode()}, whether or not the object's class has
+     * overridden hashCode(). The hash code for {@code null} is {@code 0}.
+     *
+     * @param anObject
+     *            the object to calculate the hash code.
+     * @return the hash code for the given object.
      * @see java.lang.Object#hashCode
      */
     public static native int identityHashCode(Object anObject);
@@ -764,7 +815,10 @@
     /**
      * Loads the specified file as a dynamic library.
      * 
-     * @param pathName the path of the file to be loaded
+     * @param pathName
+     *            the path of the file to be loaded.
+     * @throws SecurityException
+     *             if the library was not allowed to be loaded.
      */
     public static void load(String pathName) {
         SecurityManager smngr = System.getSecurityManager();
@@ -775,12 +829,16 @@
     }
 
     /**
-     * Loads and links the library specified by the argument.
-     * 
-     * @param libName the name of the library to load
-     * 
-     * @throws UnsatisfiedLinkError if the library could not be loaded
-     * @throws SecurityException if the library was not allowed to be loaded
+     * Loads and links the shared library with the given name {@code libName}.
+     * The file will be searched in the default directory for shared libraries
+     * of the local system.
+     *
+     * @param libName
+     *            the name of the library to load.
+     * @throws UnsatisfiedLinkError
+     *             if the library could not be loaded.
+     * @throws SecurityException
+     *             if the library was not allowed to be loaded.
      */
     public static void loadLibrary(String libName) {
         ClassLoader.loadLibraryWithClassLoader(libName, ClassLoader.callerClassLoader());
@@ -795,14 +853,13 @@
     }
 
     /**
-     * Ensure that, when the virtual machine is about to exit, all objects are
+     * Ensures that, when the virtual machine is about to exit, all objects are
      * finalized. Note that all finalization which occurs when the system is
      * exiting is performed after all running threads have been terminated.
      * 
      * @param flag
-     *            true means finalize all on exit.
-     * 
-     * @deprecated This method is unsafe.
+     *            the flag determines if finalization on exit is enabled.
+     * @deprecated this method is unsafe.
      */
     @SuppressWarnings("deprecation")
     @Deprecated
@@ -811,14 +868,15 @@
     }
 
     /**
-     * Answers the system properties. Note that the object which is passed in
+     * Sets all system properties. Note that the object which is passed in
      * not copied, so that subsequent changes made to the object will be
      * reflected in calls to getProperty and getProperties.
-     * <p>
-     * Security managers should restrict access to this API if possible.
      * 
      * @param p
-     *            the property to set
+     *            the new system property.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkPropertiesAccess()} method does not allow the operation.
      */
     public static void setProperties(Properties p) {
         SecurityManager secMgr = System.getSecurityManager();
@@ -834,16 +892,18 @@
 
     /**
      * Sets the active security manager. Note that once the security manager has
-     * been set, it can not be changed. Attempts to do so will cause a security
-     * exception.
+     * been set, it can not be changed. Attempts to do that will cause a
+     * security exception.
      * 
-     * @param s
-     *            the new security manager
+     * @param sm
+     *            the new security manager.
      * 
      * @throws SecurityException
-     *             if the security manager has already been set.
+     *             if the security manager has already been set and if its
+     *             checkPermission method does not allow to redefine the
+     *             security manager.
      */
-    public static void setSecurityManager(final SecurityManager s) {
+    public static void setSecurityManager(final SecurityManager sm) {
         if (!security_initialized) {
             try {
                 // Preload and initialize Policy implementation classes
@@ -854,11 +914,11 @@
             security_initialized = true;
         }
 
-        security = s;
+        security = sm;
     }
 
     /**
-     * Answers the platform specific file name format for the shared library
+     * Returns the platform specific file name format for the shared library
      * named by the argument.
      * 
      * @param userLibName

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Thread.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Thread.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Thread.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Thread.java Wed Apr 22 12:04:10 2009
@@ -21,34 +21,55 @@
 import java.util.Map;
 
 /**
- * This class must be implemented by the VM vendor. The documented methods must
- * be implemented to support other provided class implementations in this
- * package. A Thread is a unit of concurrent execution in Java. It has its own
- * call stack for methods being called and their parameters. Threads in the same
- * VM interact and synchronize by the use of shared Objects and monitors
- * associated with these objects. Synchronized methods and part of the API in
- * Object also allow Threads to cooperate. When a Java program starts executing
- * there is an implicit Thread (called "main") which is automatically created by
- * the VM. This Thread belongs to a ThreadGroup (also called "main") which is
- * automatically created by the bootstrap sequence by the VM as well.
- * 
+ * A {@code Thread} is a concurrent unit of execution. It has its own call stack
+ * for methods being invoked, their arguments and local variables. Each virtual
+ * machine instance has at least one main {@code Thread} running when it is
+ * started; typically, there are several others for housekeeping. The
+ * application might decide to launch additional {@code Thread}s for specific
+ * purposes.
+ * <p>
+ * {@code Thread}s in the same VM interact and synchronize by the use of shared
+ * objects and monitors associated with these objects. Synchronized methods and
+ * part of the API in {@link Object} also allow {@code Thread}s to cooperate.
+ * <p>
+ * There are basically two main ways of having a {@code Thread} execute
+ * application code. One is providing a new class that extends {@code Thread}
+ * and overriding its {@link #run()} method. The other is providing a new
+ * {@code Thread} instance with a {@link Runnable} object during its creation.
+ * In both cases, the {@link #start()} method must be called to actually execute
+ * the new {@code Thread}.
+ * <p>
+ * Each {@code Thread} has an integer priority that basically determines the
+ * amount of CPU time the {@code Thread} gets. It can be set using the
+ * {@link #setPriority(int)} method. A {@code Thread} can also be made a daemon,
+ * which makes it run in the background. The latter also affects VM termination
+ * behavior: the VM does not terminate automatically as long as there are
+ * non-daemon threads running.
+ *
  * @see java.lang.Object
  * @see java.lang.ThreadGroup
  */
 public class Thread implements Runnable {
 
+    /*
+     * This class must be implemented by the VM vendor. The documented methods must
+     * be implemented to support other provided class implementations in this
+     * package.
+     */
+
+    /**
+    * A representation of a thread's state. A given thread may only be in one
+    * state at a time.
+    *
+    * @since 1.5
+    */
+
     /**
      * A representation of a thread's state. A given thread may only be in one
      * state at a time.
-     * 
-     * @since 1.5
      */
     public enum State {
         /**
-         * The thread is blocked and waiting for a lock.
-         */
-        BLOCKED,
-        /**
          * The thread has been created, but has never been started.
          */
         NEW,
@@ -57,17 +78,21 @@
          */
         RUNNABLE,
         /**
-         * The thread has been terminated.
+         * The thread is blocked and waiting for a lock.
          */
-        TERMINATED,
+        BLOCKED,
+        /**
+         * The thread is waiting.
+         */
+        WAITING,
         /**
          * The thread is waiting for a specified amount of time.
          */
         TIMED_WAITING,
         /**
-         * The thread is waiting.
+         * The thread has been terminated.
          */
-        WAITING
+        TERMINATED
     }
 
     /**
@@ -238,7 +263,10 @@
      * used to implement the interruptible channel. The action is null by
      * default. And if this method is invoked by passing in a non-null value,
      * this action's run() method will be invoked in <code>interrupt()</code>.
-     * 
+     * <p>
+     * This is required internally by NIO, so even if it looks like it's
+     * useless, don't delete it!
+     *
      * @param action the action to be executed when interruption
      */
     @SuppressWarnings("unused")
@@ -247,21 +275,25 @@
     }
 
     /**
-     * Returns the number of active threads in the running thread's ThreadGroup
+     * Returns the number of active {@code Thread}s in the running {@code
+     * Thread}'s group and its subgroups.
      * 
-     * @return Number of Threads
+     * @return the number of {@code Thread}s
      */
     public static int activeCount() {
         return 0;
     }
 
     /**
-     * This method is used for operations that require approval from a
-     * SecurityManager. If there's none installed, this method is a no-op. If
-     * there's a SecurityManager installed ,
-     * {@link SecurityManager#checkAccess(Thread)} is called for that
-     * SecurityManager.
-     * 
+     * Is used for operations that require approval from a SecurityManager. If
+     * there's none installed, this method is a no-op. If there's a
+     * SecurityManager installed, {@link SecurityManager#checkAccess(Thread)} is
+     * called for that SecurityManager.
+     * 
+     * @throws SecurityException
+     *             if a SecurityManager is installed and it does not allow
+     *             access to the Thread.
+     *
      * @see java.lang.SecurityException
      * @see java.lang.SecurityManager
      */
@@ -274,8 +306,8 @@
      * 
      * @return Number of stack frames
      * @deprecated The results of this call were never well defined. To make
-     *             things worse, it would depend if the Thread was suspended or
-     *             not, and suspend was deprecated too.
+     *             things worse, it would depend on whether the Thread was
+     *             suspended or not, and suspend was deprecated too.
      */
     @Deprecated
     public int countStackFrames() {
@@ -283,19 +315,17 @@
     }
 
     /**
-     * Answers the instance of Thread that corresponds to the running Thread
-     * which calls this method.
-     * 
-     * @return a java.lang.Thread corresponding to the code that called
-     *         <code>currentThread()</code>
+     * Returns the Thread of the caller, that is, the current Thread.
+     *
+     * @return the current Thread.
      */
     public static Thread currentThread() {
         return null;
     }
 
     /**
-     * Destroys the receiver without any monitor cleanup. Not implemented.
-     * 
+     * Destroys the receiver without any monitor cleanup.
+     *
      * @deprecated Not implemented.
      */
     @Deprecated
@@ -304,8 +334,10 @@
     }
 
     /**
-     * Prints a text representation of the stack for this Thread.
+     * Prints to the standard error stream a text representation of the current
+     * stack for this Thread.
      * 
+     * @see Throwable#printStackTrace()
      */
     public static void dumpStack() {
         return;
@@ -313,14 +345,16 @@
 
     /**
      * Copies an array with all Threads which are in the same ThreadGroup as the
-     * receiver - and subgroups - into the array <code>threads</code> passed
-     * as parameter. If the array passed as parameter is too small no exception
-     * is thrown - the extra elements are simply not copied.
+     * receiver - and subgroups - into the array <code>threads</code> passed as
+     * parameter. If the array passed as parameter is too small no exception is
+     * thrown - the extra elements are simply not copied.
      * 
-     * @param threads array into which the Threads will be copied
+     * @param threads
+     *            array into which the Threads will be copied
      * @return How many Threads were copied over
-     * @throws SecurityException if the installed SecurityManager fails
-     *         {@link SecurityManager#checkAccess(Thread)}
+     * @throws SecurityException
+     *             if the installed SecurityManager fails
+     *             {@link SecurityManager#checkAccess(Thread)}
      * @see java.lang.SecurityException
      * @see java.lang.SecurityManager
      */
@@ -329,19 +363,18 @@
     }
 
     /**
-     * <p>
-     * Returns the stack traces of all the currently live threads.
-     * </p>
+     * Returns the stack traces of all the currently live threads and puts them
+     * into the given map.
      * <p>
      * The <code>RuntimePermission("getStackTrace")</code> and
      * <code>RuntimePermission("modifyThreadGroup")</code> are checked before
      * returning a result.
-     * </p>
-     * 
+     *
      * @return A Map of current Threads to StackTraceElement arrays.
-     * @throws SecurityException if the current SecurityManager fails the
-     *         {@link SecurityManager#checkPermission(java.security.Permission)}
-     *         call.
+     * @throws SecurityException
+     *             if the current SecurityManager fails the
+     *             {@link SecurityManager#checkPermission(java.security.Permission)}
+     *             call.
      * @since 1.5
      */
     public static Map<Thread, StackTraceElement[]> getAllStackTraces() {
@@ -349,23 +382,34 @@
     }
 
     /**
-     * Returns the context ClassLoader for the receiver.
-     * 
+     * Returns the context ClassLoader for this Thread.
+     * <p>
+     * If the conditions
+     * <ol>
+     * <li>there is a security manager
+     * <li>the caller's class loader is not null
+     * <li>the caller's class loader is not the same as the requested
+     * context class loader and not an ancestor thereof
+     * </ol>
+     * are satisfied, a security check for
+     * <code>RuntimePermission("getClassLoader")</code> is performed first.
+     *
      * @return ClassLoader The context ClassLoader
      * @see java.lang.ClassLoader
      * @see #getContextClassLoader()
+     *
+     * @throws SecurityException
+     *             if the aforementioned security check fails.
      */
     public ClassLoader getContextClassLoader() {
         return null;
     }
 
     /**
-     * <p>
      * Returns the default exception handler that's executed when uncaught
      * exception terminates a thread.
-     * </p>
-     * 
-     * @return An {@link UncaughtExceptionHandler} or <code>null</code> if
+     *
+     * @return an {@link UncaughtExceptionHandler} or <code>null</code> if
      *         none exists.
      * @since 1.5
      */
@@ -374,14 +418,12 @@
     }
 
     /**
-     * <p>
      * Returns the thread's identifier. The ID is a positive <code>long</code>
-     * generated on thread creation, is unique to the thread and doesn't change
-     * during the life of the thread; the ID may be reused after the thread has
-     * been terminated.
-     * </p>
-     * 
-     * @return The thread's ID.
+     * generated on thread creation, is unique to the thread, and doesn't change
+     * during the lifetime of the thread; the ID may be reused after the thread
+     * has been terminated.
+     *
+     * @return the thread's ID.
      * @since 1.5
      */
     public long getId() {
@@ -389,18 +431,18 @@
     }
 
     /**
-     * Answers the name of the receiver.
-     * 
-     * @return the receiver's name (a java.lang.String)
+     * Returns the name of the Thread.
+     *
+     * @return the Thread's name
      */
     public final String getName() {
         return null;
     }
 
     /**
-     * Answers the priority of the receiver.
-     * 
-     * @return the receiver's priority (an <code>int</code>)
+     * Returns the priority of the Thread.
+     *
+     * @return the Thread's priority
      * @see Thread#setPriority
      */
     public final int getPriority() {
@@ -408,14 +450,12 @@
     }
 
     /**
-     * <p>
-     * Returns the current stack trace of the thread.
-     * </p>
+     * Returns the a stack trace representing the current execution state of
+     * this Thread.
      * <p>
      * The <code>RuntimePermission("getStackTrace")</code> is checked before
      * returning a result.
-     * </p>
-     * 
+     *
      * @return An array of StackTraceElements.
      * @throws SecurityException if the current SecurityManager fails the
      *         {@link SecurityManager#checkPermission(java.security.Permission)}
@@ -427,11 +467,10 @@
     }
 
     /**
-     * <p>
-     * Returns the current state of the thread for monitoring purposes.
-     * </p>
-     * 
-     * @return A State value.
+     * Returns the current state of the Thread. This method is useful for
+     * monitoring purposes.
+     *
+     * @return a {@link State} value.
      * @since 1.5
      */
     public State getState() {
@@ -439,9 +478,9 @@
     }
 
     /**
-     * Answers the ThreadGroup to which the receiver belongs
+     * Returns the ThreadGroup to which this Thread belongs.
      * 
-     * @return the receiver's ThreadGroup
+     * @return the Thread's ThreadGroup
      */
     public final ThreadGroup getThreadGroup() {
         return null;
@@ -462,24 +501,42 @@
     }
 
     /**
-     * <p>
      * Returns the thread's uncaught exception handler. If not explicitly set,
      * then the ThreadGroup's handler is returned. If the thread is terminated,
      * then <code>null</code> is returned.
-     * </p>
-     * 
-     * @return An UncaughtExceptionHandler instance or <code>null</code>.
-     * @since 1.5
+     *
+     * @return an {@link UncaughtExceptionHandler} instance or {@code null}.
      */
     public UncaughtExceptionHandler getUncaughtExceptionHandler() {
         return null;
     }
 
     /**
-     * Posts an interrupt request to the receiver.
+     * Posts an interrupt request to this {@code Thread}. Unless the caller is
+     * the {@link #currentThread()}, the method {@code checkAccess()} is called
+     * for the installed {@code SecurityManager}, if any. This may result in a
+     * {@code SecurityException} being thrown. The further behavior depends on
+     * the state of this {@code Thread}:
+     * <ul>
+     * <li>
+     * {@code Thread}s blocked in one of {@code Object}'s {@code wait()} methods
+     * or one of {@code Thread}'s {@code join()} or {@code sleep()} methods will
+     * be woken up, their interrupt status will be cleared, and they receive an
+     * {@link InterruptedException}.
+     * <li>
+     * {@code Thread}s blocked in an I/O operation of an
+     * {@link java.nio.channels.InterruptibleChannel} will have their interrupt
+     * status set and receive an
+     * {@link java.nio.channels.ClosedByInterruptException}. Also, the channel
+     * will be closed.
+     * <li>
+     * {@code Thread}s blocked in a {@link java.nio.channels.Selector} will have
+     * their interrupt status set and return immediately. They don't receive an
+     * exception in this case.
+     * <ul>
      * 
-     * @throws SecurityException if <code>group.checkAccess()</code> fails
-     *         with a SecurityException
+     * @throws SecurityException
+     *             if <code>checkAccess()</code> fails with a SecurityException
      * @see java.lang.SecurityException
      * @see java.lang.SecurityManager
      * @see Thread#interrupted
@@ -493,12 +550,12 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether the current Thread (
-     * <code>currentThread()</code>) has a pending interrupt request (
-     * <code>true</code>) or not (<code>false</code>). It also has the
-     * side-effect of clearing the flag.
+     * Returns a <code>boolean</code> indicating whether the current Thread (
+     * <code>currentThread()</code>) has a pending interrupt request (<code>
+     * true</code>) or not (<code>false</code>). It also has the side-effect of
+     * clearing the flag.
      * 
-     * @return a <code>boolean</code>
+     * @return a <code>boolean</code> indicating the interrupt status
      * @see Thread#currentThread
      * @see Thread#interrupt
      * @see Thread#isInterrupted
@@ -508,12 +565,12 @@
     }
 
     /**
-     * Answers <code>true</code> if the receiver has already been started and
-     * still runs code (hasn't died yet). Answers <code>false</code> either if
+     * Returns <code>true</code> if the receiver has already been started and
+     * still runs code (hasn't died yet). Returns <code>false</code> either if
      * the receiver hasn't been started yet or if it has already started and run
      * to completion and died.
      * 
-     * @return a <code>boolean</code>
+     * @return a <code>boolean</code> indicating the lifeness of the Thread
      * @see Thread#start
      */
     public final boolean isAlive() {
@@ -521,13 +578,13 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether the receiver is a
+     * Returns a <code>boolean</code> indicating whether the receiver is a
      * daemon Thread (<code>true</code>) or not (<code>false</code>) A
      * daemon Thread only runs as long as there are non-daemon Threads running.
      * When the last non-daemon Thread ends, the whole program ends no matter if
      * it had daemon Threads still running or not.
-     * 
-     * @return a <code>boolean</code>
+     *
+     * @return a <code>boolean</code> indicating whether the Thread is a daemon
      * @see Thread#setDaemon
      */
     public final boolean isDaemon() {
@@ -535,11 +592,11 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether the receiver has a
+     * Returns a <code>boolean</code> indicating whether the receiver has a
      * pending interrupt request (<code>true</code>) or not (
      * <code>false</code>)
-     * 
-     * @return a <code>boolean</code>
+     *
+     * @return a <code>boolean</code> indicating the interrupt status
      * @see Thread#interrupt
      * @see Thread#interrupted
      */
@@ -550,7 +607,7 @@
     /**
      * Blocks the current Thread (<code>Thread.currentThread()</code>) until
      * the receiver finishes its execution and dies.
-     * 
+     *
      * @throws InterruptedException if <code>interrupt()</code> was called for
      *         the receiver while it was in the <code>join()</code> call
      * @see Object#notifyAll
@@ -564,14 +621,14 @@
      * Blocks the current Thread (<code>Thread.currentThread()</code>) until
      * the receiver finishes its execution and dies or the specified timeout
      * expires, whatever happens first.
-     * 
-     * @param timeoutInMilliseconds The maximum time to wait (in milliseconds).
+     *
+     * @param millis The maximum time to wait (in milliseconds).
      * @throws InterruptedException if <code>interrupt()</code> was called for
      *         the receiver while it was in the <code>join()</code> call
      * @see Object#notifyAll
      * @see java.lang.ThreadDeath
      */
-    public final void join(long timeoutInMilliseconds) throws InterruptedException {
+    public final void join(long millis) throws InterruptedException {
         return;
     }
 
@@ -579,27 +636,28 @@
      * Blocks the current Thread (<code>Thread.currentThread()</code>) until
      * the receiver finishes its execution and dies or the specified timeout
      * expires, whatever happens first.
-     * 
-     * @param timeoutInMilliseconds The maximum time to wait (in milliseconds).
+     *
+     * @param millis The maximum time to wait (in milliseconds).
      * @param nanos Extra nanosecond precision
      * @throws InterruptedException if <code>interrupt()</code> was called for
      *         the receiver while it was in the <code>join()</code> call
      * @see Object#notifyAll
      * @see java.lang.ThreadDeath
      */
-    public final void join(long timeoutInMilliseconds, int nanos) throws InterruptedException {
+    public final void join(long millis, int nanos) throws InterruptedException {
         return;
     }
 
     /**
-     * This is a no-op if the receiver was never suspended, or suspended and
-     * already resumed. If the receiver is suspended, however, makes it resume
-     * to the point where it was when it was suspended.
+     * Resumes a suspended Thread. This is a no-op if the receiver was never
+     * suspended, or suspended and already resumed. If the receiver is
+     * suspended, however, makes it resume to the point where it was when it was
+     * suspended.
      * 
-     * @throws SecurityException if <code>checkAccess()</code> fails with a
-     *         SecurityException
+     * @throws SecurityException
+     *             if <code>checkAccess()</code> fails with a SecurityException
      * @see Thread#suspend()
-     * @deprecated Used with deprecated method Thread.suspend().
+     * @deprecated Used with deprecated method {@link Thread#suspend}
      */
     @Deprecated
     public final void resume() {
@@ -609,7 +667,7 @@
     /**
      * Calls the <code>run()</code> method of the Runnable object the receiver
      * holds. If no Runnable is set, does nothing.
-     * 
+     *
      * @see Thread#start
      */
     public void run() {
@@ -618,8 +676,13 @@
 
     /**
      * Set the context ClassLoader for the receiver.
-     * 
+     * <p>
+     * The <code>RuntimePermission("setContextClassLoader")</code>
+     * is checked prior to setting the handler.
+     *
      * @param cl The context ClassLoader
+     * @throws SecurityException if the current SecurityManager fails the
+     *         checkPermission call.
      * @see java.lang.ClassLoader
      * @see #getContextClassLoader()
      */
@@ -631,10 +694,10 @@
      * Set if the receiver is a daemon Thread or not. This can only be done
      * before the Thread starts running.
      * 
-     * @param isDaemon A boolean indicating if the Thread should be daemon or
-     *        not
-     * @throws SecurityException if <code>checkAccess()</code> fails with a
-     *         SecurityException
+     * @param isDaemon
+     *            indicates whether the Thread should be daemon or not
+     * @throws SecurityException
+     *             if <code>checkAccess()</code> fails with a SecurityException
      * @see Thread#isDaemon
      */
     public final void setDaemon(boolean isDaemon) {
@@ -642,17 +705,17 @@
     }
 
     /**
-     * <p>
-     * Sets the default uncaught exception handler.
-     * </p>
+     * Sets the default uncaught exception handler. This handler is invoked in
+     * case any Thread dies due to an unhandled exception.
      * <p>
      * The <code>RuntimePermission("setDefaultUncaughtExceptionHandler")</code>
      * is checked prior to setting the handler.
-     * </p>
-     * 
-     * @param handler The handler to set or <code>null</code>.
-     * @throws SecurityException if the current SecurityManager fails the
-     *         checkPermission call.
+     *
+     * @param handler
+     *            The handler to set or <code>null</code>.
+     * @throws SecurityException
+     *             if the current SecurityManager fails the checkPermission
+     *             call.
      * @since 1.5
      */
     public static void setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler handler) {
@@ -660,9 +723,9 @@
     }
 
     /**
-     * Sets the name of the receiver.
-     * 
-     * @param threadName new name for the Thread
+     * Sets the name of the Thread.
+     *
+     * @param threadName the new name for the Thread
      * @throws SecurityException if <code>checkAccess()</code> fails with a
      *         SecurityException
      * @see Thread#getName
@@ -672,16 +735,18 @@
     }
 
     /**
-     * Sets the priority of the receiver. Note that the final priority set may
-     * not be the parameter that was passed - it will depend on the receiver's
+     * Sets the priority of the Thread. Note that the final priority set may not
+     * be the parameter that was passed - it will depend on the receiver's
      * ThreadGroup. The priority cannot be set to be higher than the receiver's
      * ThreadGroup's maxPriority().
      * 
-     * @param priority new priority for the Thread
-     * @throws SecurityException if <code>checkAccess()</code> fails with a
-     *         SecurityException
-     * @throws IllegalArgumentException if the new priority is greater than
-     *         Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY
+     * @param priority
+     *            new priority for the Thread
+     * @throws SecurityException
+     *             if <code>checkAccess()</code> fails with a SecurityException
+     * @throws IllegalArgumentException
+     *             if the new priority is greater than Thread.MAX_PRIORITY or
+     *             less than Thread.MIN_PRIORITY
      * @see Thread#getPriority
      */
     public final void setPriority(int priority) {
@@ -704,12 +769,13 @@
 
     /**
      * <p>
-     * Sets the default uncaught exception handler.
-     * </p>
-     * 
-     * @param handler The handler to set or <code>null</code>.
-     * @throws SecurityException if the current SecurityManager fails the
-     *         checkAccess call.
+     * Sets the uncaught exception handler. This handler is invoked in case this
+     * Thread dies due to an unhandled exception.
+     *
+     * @param handler
+     *            The handler to set or <code>null</code>.
+     * @throws SecurityException
+     *             if the current SecurityManager fails the checkAccess call.
      * @since 1.5
      */
     public void setUncaughtExceptionHandler(UncaughtExceptionHandler handler) {
@@ -717,13 +783,15 @@
     }
 
     /**
-     * Causes the thread which sent this message to sleep an interval of time
-     * (given in milliseconds). The precision is not guaranteed - the Thread may
-     * sleep more or less than requested.
-     * 
-     * @param time The time to sleep in milliseconds.
-     * @throws InterruptedException if <code>interrupt()</code> was called for
-     *         this Thread while it was sleeping
+     * Causes the thread which sent this message to sleep for the given interval
+     * of time (given in milliseconds). The precision is not guaranteed - the
+     * Thread may sleep more or less than requested.
+     * 
+     * @param time
+     *            The time to sleep in milliseconds.
+     * @throws InterruptedException
+     *             if <code>interrupt()</code> was called for this Thread while
+     *             it was sleeping
      * @see Thread#interrupt()
      */
     public static void sleep(long time) throws InterruptedException {
@@ -731,17 +799,20 @@
     }
 
     /**
-     * Causes the thread which sent this message to sleep an interval of time
-     * (given in milliseconds). The precision is not guaranteed - the Thread may
-     * sleep more or less than requested.
-     * 
-     * @param time The time to sleep in milliseconds.
-     * @param nanos Extra nanosecond precision
-     * @throws InterruptedException if <code>interrupt()</code> was called for
-     *         this Thread while it was sleeping
+     * Causes the thread which sent this message to sleep for the given interval
+     * of time (given in milliseconds and nanoseconds). The precision is not
+     * guaranteed - the Thread may sleep more or less than requested.
+     * 
+     * @param millis
+     *            The time to sleep in milliseconds.
+     * @param nanos
+     *            Extra nanosecond precision
+     * @throws InterruptedException
+     *             if <code>interrupt()</code> was called for this Thread while
+     *             it was sleeping
      * @see Thread#interrupt()
      */
-    public static void sleep(long time, int nanos) throws InterruptedException {
+    public static void sleep(long millis, int nanos) throws InterruptedException {
         return;
     }
 
@@ -749,9 +820,8 @@
      * Starts the new Thread of execution. The <code>run()</code> method of
      * the receiver will be called by the receiver Thread itself (and not the
      * Thread calling <code>start()</code>).
-     * 
-     * @throws IllegalThreadStateException Unspecified in the Java language
-     *         specification
+     *
+     * @throws IllegalThreadStateException if the Thread has been started before
      * @see Thread#run
      */
     public void start() {
@@ -762,10 +832,11 @@
      * Requests the receiver Thread to stop and throw ThreadDeath. The Thread is
      * resumed if it was suspended and awakened if it was sleeping, so that it
      * can proceed to throw ThreadDeath.
-     * 
+     *
      * @throws SecurityException if <code>checkAccess()</code> fails with a
      *         SecurityException
-     * @deprecated
+     * @deprecated because stopping a thread in this manner is unsafe and can
+     * leave your application and the VM in an unpredictable state.
      */
     @Deprecated
     public final void stop() {
@@ -777,13 +848,14 @@
      * <code>throwable()</code>. The Thread is resumed if it was suspended
      * and awakened if it was sleeping, so that it can proceed to throw the
      * <code>throwable()</code>.
-     * 
+     *
      * @param throwable Throwable object to be thrown by the Thread
      * @throws SecurityException if <code>checkAccess()</code> fails with a
      *         SecurityException
      * @throws NullPointerException if <code>throwable()</code> is
      *         <code>null</code>
-     * @deprecated
+     * @deprecated because stopping a thread in this manner is unsafe and can
+     * leave your application and the VM in an unpredictable state.
      */
     @Deprecated
     public final void stop(Throwable throwable) {
@@ -791,14 +863,14 @@
     }
 
     /**
-     * This is a no-op if the receiver is suspended. If the receiver
-     * <code>isAlive()</code> however, suspended it until
-     * <code>resume()</code> is sent to it. Suspend requests are not queued,
-     * which means that N requests are equivalent to just one - only one resume
+     * Suspends this Thread. This is a no-op if the receiver is suspended. If
+     * the receiver <code>isAlive()</code> however, suspended it until <code>
+     * resume()</code> is sent to it. Suspend requests are not queued, which
+     * means that N requests are equivalent to just one - only one resume
      * request is needed in this case.
      * 
-     * @throws SecurityException if <code>checkAccess()</code> fails with a
-     *         SecurityException
+     * @throws SecurityException
+     *             if <code>checkAccess()</code> fails with a SecurityException
      * @see Thread#resume()
      * @deprecated May cause deadlocks.
      */
@@ -808,8 +880,8 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable description of the
+     * Thread. It includes the Thread's name, priority, and group name.
      * 
      * @return a printable representation for the receiver.
      */
@@ -819,10 +891,8 @@
     }
 
     /**
-     * Causes the thread which sent this message to yield execution to another
-     * Thread that is ready to run. The actual scheduling is
-     * implementation-dependent.
-     * 
+     * Causes the calling Thread to yield execution time to another Thread that
+     * is ready to run. The actual scheduling is implementation-dependent.
      */
     public static void yield() {
         return;



Mime
View raw message