You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/22 14:04:11 UTC
svn commit: r767477 [3/5] - in
/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang:
./ ref/ reflect/
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;