Generated by
JDiff

java.lang Documentation Differences

This file contains all the changes in documentation in the package java.lang as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Byte

The Byte class wraps a value of primitive type byte in an object. An object of type Byte contains a single field whose type is byte.

In addition this class provides several methods for converting a byte to a String and a String to a byte as well as other constants and methods useful when dealing with a byte. @author Nakul Saraiya @version 1.28 1229 02/0306/0102 @see java.lang.Number @since JDK1.1


Class CharSequence

A CharSequence is a readable sequence of characters. This interface provides uniform read-only access to many different kinds of character sequences.

This interface does not refine the general contracts of the equals and hashCode methods. The result of comparing two objects that implement CharSequence is therefore in general undefined. Each object may be implemented by a different class and there is no guarantee that each class will be be capable of testing its instances for equality with those of the other. It is therefore inappropriate to use arbitrary CharSequence instances as elements in a set or as keys in a map.

@author Mike McCloskey @version 1.4 015 02/1204/0323 @since 1.4 @spec JSR-51

Class Class

Instances of the class Class represent classes and interfaces in a running Java application. Every array also belongs to a class that is reflected as a Class object that is shared by all arrays with the same element type and number of dimensions. The primitive Java types (boolean byte char short int long float and double) and the keyword void are also represented as Class objects.

Class has no public constructor. Instead Class objects are constructed automatically by the Java Virtual Machine as classes are loaded and by calls to the defineClass method in the class loader.

The following example uses a Class object to print the class name of an object:

 void printClassName(Object obj) { System.out.println("The class of " + obj + " is " + obj.getClass().getName()); } 

It is also possible to get the Class object for a named type (or for void) using a class literal (JLS Section 15.8.2). For example:

 System.out.println("The name of class Foo is: "+Foo.class.getName()); 
@author unascribed @version 1.135 05/25/01 @see java.lang.ClassLoader#defineClass(byte[] int int) @since JDK1.0
Class Class, Field getDeclaredField(String)

Returns a Field object that reflects the specified declared field of the class or interface represented by this Class object. The name parameter is a String that specifies the simple name of the desired field. Note that this method will not reflect the length field of an array class.

If there is a security manager this method first calls the security manager's checkMemberAccess method with this and Member.DECLARED as its arguments. If the class is in a package then this method also calls the security manager's checkPackageAccess method with the package name as its argument. Either of these calls could result in a SecurityException. @param name the name of the field @return the Field object for the specified field in this class @exception NoSuchFieldException if a field with the specified name is not found. @exception NullPointerException if name is null @exception SecurityException if access to the information is denied. @see java.lang.reflect.Field @see SecurityManager#checkMemberAccess(Class int) @see SecurityManager#checkPackageAccess(String) @since JDK1.1

Class Class, Method getDeclaredMethod(String, Class[])

Returns a Method object that reflects the specified declared method of the class or interface represented by this Class object. The name parameter is a String that specifies the simple name of the desired method and the parameterTypes parameter is an array of Class objects that identify the method's formal parameter types in declared order. If more than one method with the same parameter types is declared in a class and one of these methods has a return type that is more specific than any of the others that method is returned; otherwise one of the methods is chosen arbitrarily. If the name is "<init>"or "<clinit>" a NoSuchMethodException is raised.

If there is a security manager this method first calls the security manager's checkMemberAccess method with this and Member.DECLARED as its arguments. If the class is in a package then this method also calls the security manager's checkPackageAccess method with the package name as its argument. Either of these calls could result in a SecurityException. @param name the name of the method @param parameterTypes the parameter array @return the Method object for the method of this class matching the specified name and parameters @exception NoSuchMethodException if a matching method is not found. @exception NullPointerException if name is null @exception SecurityException if access to the information is denied. @see java.lang.reflect.Method @see SecurityManager#checkMemberAccess(Class int) @see SecurityManager#checkPackageAccess(String) @since JDK1.1

Class Class, Field getField(String)

Returns a Field object that reflects the specified public member field of the class or interface represented by this Class object. The name parameter is a String specifying the simple name of the desired field.

If there is a security manager this method first calls the security manager's checkMemberAccess method with this and Member.PUBLIC as its arguments. If the class is in a package then this method also calls the security manager's checkPackageAccess method with the package name as its argument. Either of these calls could result in a SecurityException.

The field to be reflected is determined by the algorithm that follows. Let C be the class represented by this object:

  1. If C declares a public field with the name specified that is the field to be reflected.
  2. If no field was found in step 1 above this algorithm is applied recursively to each direct superinterface of C. The direct superinterfaces are searched in the order they were declared.
  3. If no field was found in steps 1 and 2 above and C has a superclass S then this algorithm is invoked recursively upon S. If C has no superclass then a NoSuchFieldException is thrown.

See The Java Language Specification sections 8.2 and 8.3. @param name the field name @return the Field object of this class specified by name @exception NoSuchFieldException if a field with the specified name is not found. @exception NullPointerException if name is null @exception SecurityException if access to the information is denied. @see java.lang.reflect.Field @see SecurityManager#checkMemberAccess(Class int) @see SecurityManager#checkPackageAccess(String) @since JDK1.1

Class Class, Method getMethod(String, Class[])

Returns a Method object that reflects the specified public member method of the class or interface represented by this Class object. The name parameter is a String specifying the simple name the desired method. The parameterTypes parameter is an array of Class objects that identify the method's formal parameter types in declared order. If parameterTypes is null it is treated as if it were an empty array.

If there is a security manager this method first calls the security manager's checkMemberAccess method with this and Member.PUBLIC as its arguments. If the class is in a package then this method also calls the security manager's checkPackageAccess method with the package name as its argument. Either of these calls could result in a SecurityException.

If the name is "<init>"or "<clinit>" a NoSuchMethodException is raised. Otherwise the method to be reflected is determined by the algorithm that follows. Let C be the class represented by this object:

  1. C is searched for any matching methods. If no matching method is found the algorithm of step 1 is invoked recursively on the superclass of C.
  2. If no method was found in step 1 above the superinterfaces of C are searched for a matching method. If any such method is found it is reflected.
To find a matching method in a class C:  If C declares exactly one public method with the specified name and exactly the same formal parameter types that is the method reflected. If more than one such method is found in C and one of these methods has a return type that is more specific than any of the others that method is reflected; otherwise one of the methods is chosen arbitrarily.

See The Java Language Specification sections 8.2 and 8.4. @param name the name of the method @param parameterTypes the list of parameters @return the Method object that matches the specified name and parameterTypes @exception NoSuchMethodException if a matching method is not found or if thenthe name is "<init>"or "<clinit>". @exception NullPointerException if name is null @exception SecurityException if access to the information is denied. @see java.lang.reflect.Method @see SecurityManager#checkMemberAccess(Class int) @see SecurityManager#checkPackageAccess(String) @since JDK1.1


Class ClassLoader

A class loader is an object that is responsible for loading classes. The class ClassLoader is an abstract class. Given the name of a class a class loader should attempt to locate or generate data that constitutes a definition for the class. A typical strategy is to transform the name into a file name and then read a "class file" of that name from a file system.

Every Class object contains a reference to the ClassLoader that defined it.

Class objects for array classes are not created by class loaders but are created automatically as required by the Java runtime. The class loader for an array class as returned by Class#getClassLoader() is the same as the class loader for its element type; if the element type is a primitive type then the array class has no class loader.

Applications implement subclasses of ClassLoader in order to extend the manner in which the Java virtual machine dynamically loads classes.

Class loaders may typically be used by security managers to indicate security domains.

The ClassLoader class uses a delegation model to search for classes and resources. Each instance of ClassLoader has an associated parent class loader. When called upon to find a class or resource a ClassLoader instance will delegate the search for the class or resource to its parent class loader before attempting to find the class or resource itself. The virtual machine's built-in class loader called the bootstrap class loader does not itself have a parent but may serve as the parent of a ClassLoader instance.

Normally the Java virtual machine loads classes from the local file system in a platform-dependent manner. For example on UNIX systems the virtual machine loads classes from the directory defined by the CLASSPATH environment variable.

However some classes may not originate from a file; they may originate from other sources such as the network or they could be constructed by an application. The method defineClass converts an array of bytes into an instance of class Class. Instances of this newly defined class can be created using the newInstance method in class Class.

The methods and constructors of objects created by a class loader may reference other classes. To determine the class(es) referred to the Java virtual machine calls the loadClass method of the class loader that originally created the class.

For example an application could create a network class loader to download class files from a server. Sample code might look like:

 ClassLoader loader = new NetworkClassLoader(host  port); Object main = loader.loadClass("Main" true).newInstance();  . . . 

The network class loader subclass must define the methods findClass and loadClassData to load a class from the network. Once it has downloaded the bytes that make up the class it should use the method defineClass to create a class instance. A sample implementation is:


 class NetworkClassLoader extends ClassLoader { String host; int port; public Class findClass(String name) { byte[] b = loadClassData(name); return defineClass(name b 0 b.length); } private byte[] loadClassData(String name) { // load the class data from the connection  . . . } } 

@version 1.160162 12/03/0119/02 @see java.lang.Class @see java.lang.Class#newInstance() @see java.lang.ClassLoader#defineClass(byte[] int int) @see java.lang.ClassLoader#loadClass(java.lang.String boolean) @see java.lang.ClassLoader#resolveClass(java.lang.Class) @since JDK1.0
Class ClassLoader, constructor ClassLoader()

Creates a new class loader using the ClassLoader returned by the method getSystemClassLoader() as the parent class loader.

This constructor is invoked for every newly created class loader. Because the class ClassLoader is abstract it is not possible to create a new instance of the class ClassLoader itself; however every constructor for a subclass of ClassLoader necessarily invokes this constructor explicitly or implicitly directly or indirectly. If there is a security manager its checkCreateClassLoader method is called. This may result in a security exception. @throws SecurityException if a security manager exists and its checkCreateClassLoader method doesn't allow creation of a new class loader. @see java.lang.SecurityException @see java.lang.SecurityManager#checkCreateClassLoader()


Class Double

The Double class wraps a value of the primitive type double in an object. An object of type Double contains a single field whose type is double.

In addition this class provides several methods for converting a double to a String and a String to a double as well as other constants and methods useful when dealing with a double. @author Lee Boynton @author Arthur van Hoff @version 1.79 1280 04/0309/0102 @since JDK1.0

Class Double, double longBitsToDouble(long)

Returns the double value corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double format" bit layout.

If the argument is 0x7ff0000000000000L the result is positive infinity.

If the argument is 0xfff0000000000000L the result is negative infinity.

If the argument is any value in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL the result is a NaN. No IEEE 754 floating-point operation provided by Java can distinguish between two NaN values of the same type with different bit patterns. Distinct values of NaN are only distinguishable by use of the Double.doubleToRawLongBits method.

In all other cases let s e and m be three values that can be computed from the argument:

 int s = ((bits >> 63) == 0) 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L; 
Then the floating-point result equals the value of the mathematical expression s·m·2e-1075.

Note that this method may not be able to return a double NaN with exactly same bit pattern as the long argument. IEEE 754 distinguishes between two kinds of NaNs quiet NaNs and signaling NaNs. The differences between the two kinds of NaN are generally not visible in Java. Arithmetic operations on signaling NaNs turn them into quiet NaNs with a different but often similar bit pattern. However on some processors merely copying a signaling NaN also performs that conversion. In particular copying a signaling NaN to return it to the calling method may perform this conversion. So longBitsToDouble may not be able to return a double with a signaling NaN bit pattern. Consequently for some long values doubleToRawLongBits(longBitsToDouble(start)) may not equal start. Moreover which particular bit patterns represent signaling NaNs is platform dependent; although all NaN bit patterns quiet or signaling must be in the NaN range identified above. @param bits any long integer. @return the double floating-point value with the same bit pattern.

Class Double, double MAX_VALUE

A constant holding the largest positive finite value of type double (2-2-52)·21023. It is equal to the value returned by: Double.longBitsToDouble(0x7fefffffffffffffL).
Class Double, double MIN_VALUE

A constant holding the smallest positive nonzero value of type double 2-1074. It is equal to the value returned by Double.longBitsToDouble(0x1L).

Class Float

The Float class wraps a value of primitive type float in an object. An object of type Float contains a single field whose type is float.

In addition this class provides several methods for converting a float to a String and a String to a float as well as other constants and methods useful when dealing with a float. @author Lee Boynton @author Arthur van Hoff @version 1.77 1278 04/0309/0102 @since JDK1.0

Class Float, float intBitsToFloat(int)

Returns the float value corresponding to a given bit represention. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "single format" bit layout.

If the argument is 0x7f800000 the result is positive infinity.

If the argument is 0xff800000 the result is negative infinity.

If the argument is any value in the range 0x7f800001 through 0x7fffffff or in the range 0xff800001 through 0xffffffff the result is a NaN. No IEEE 754 floating-point operation provided by Java can distinguish between two NaN values of the same type with different bit patterns. Distinct values of NaN are only distinguishable by use of the Float.floatToRawIntBits method.

In all other cases let s e and m be three values that can be computed from the argument:

 int s = ((bits >> 31) == 0) 1 : -1; int e = ((bits >> 23) & 0xff); int m = (e == 0) (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000; 
Then the floating-point result equals the value of the mathematical expression s·m·2e-150.

Note that this method may not be able to return a float NaN with exactly same bit pattern as the int argument. IEEE 754 distinguishes between two kinds of NaNs quiet NaNs and signaling NaNs. The differences between the two kinds of NaN are generally not visible in Java. Arithmetic operations on signaling NaNs turn them into quiet NaNs with a different but often similar bit pattern. However on some processors merely copying a signaling NaN also performs that conversion. In particular copying a signaling NaN to return it to the calling method may perform this conversion. So intBitsToFloat may not be able to return a float with a signaling NaN bit pattern. Consequently for some int values floatToRawIntBits(intBitsToFloat(start)) may not equal start. Moreover which particular bit patterns represent signaling NaNs is platform dependent; although all NaN bit patterns quiet or signaling must be in the NaN range identified above. @param bits an integer. @return the float floating-point value with the same bit pattern.

Class Float, float MAX_VALUE

A constant holding the largest positive finite value of type float (2-2-23)·2127. It is equal to the value returned by Float.intBitsToFloat(0x7f7fffff).
Class Float, float MIN_VALUE

A constant holding the smallest positive nonzero value of type float 2-149. It is equal to the value returned by Float.intBitsToFloat(0x1).

Class Integer

The Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int.

In addition this class provides several methods for converting an int to a String and a String to an int as well as other constants and methods useful when dealing with an int. @author Lee Boynton @author Arthur van Hoff @version 1.73 1274 02/0306/0102 @since JDK1.0


Class Long

The Long class wraps a value of the primitive type long in an object. An object of type Long contains a single field whose type is long.

In addition this class provides several methods for converting a long to a String and a String to a long as well as other constants and methods useful when dealing with a long. @author Lee Boynton @author Arthur van Hoff @version 1.6264 12/03/0121/02 @since JDK1.0

Class Long, constructor Long(String)

Constructs a newly allocated Long object that represents the long value indicated by the String parameter. The string is converted to a long value in exactly the manner used by the parseLong method for radix 10. @param s the String to be converted to a Long. @exception NumberFormatException if the String does not contain a parsable long. @see java.lang.Long#valueOfparseLong(java.lang.String int)

Class Math

The class Math contains methods for performing basic numeric operations such as the elementary exponential logarithm square root and trigonometric functions.

Unlike some of the numeric methods of class StrictMath all implementations of the equivalent functions of class Math are not defined to return the bit-for-bit same results. This relaxation permits better-performing implementations where strict reproducibility is not required.

By default many of the Math methods simply call the equivalent method in StrictMath for their implementation. Code generators are encouraged to use platform-specific native libraries or microprocessor instructions where available to provide higher-performance implementations of Math methods. Such higher-performance implementations still must conform to the specification for Math.

The quality of implementation specifications concern two properties accuracy of the returned result and monotonicity of the method. Accuracy of the floating-point Math methods is measured in terms of ulps units in the last place. For a given floating-point format an ulp of a specific real number value is the difference between the two floating-point values closest to that numerical value. When discussing the accuracy of a method as a whole rather than at a specific argument the number of ulps cited is for the worst-case error at any argument. If a method always has an error less than 0.5 ulps the method always returns the floating-point number nearest the exact result; such a method is correctly rounded. A correctly rounded method is generally the best a floating-point approximation can be; however it is impractical for many floating-point methods to be correctly rounded. Instead for the Math class a larger error bound of 1 or 2 ulps is allowed for certain methods. Informally with a 1 ulp error bound when the exact result is a representable number the exact result should be returned; otherwise either of the two floating-point numbers closest to the exact result may be returned. Besides accuracy at individual arguments maintaining proper relations between the method at different arguments is also important. Therefore methods with more than 0.5 ulp errors are required to be semi-monotonic: whenever the mathematical function is non-decreasing so is the floating-point approximation likewise whenever the mathematical function is non-increasing so is the floating-point approximation. Not all approximations that have 1 ulp accuracy will automatically meet the monotonicity requirements. @author unascribed @version 1.54 1255 02/0306/0102 @since JDK1.0

Class Math, long max(long, long)

Returns the greater of two long values. That is the result is the argument closer to the value of Long.MAX_VALUE. If the argumensarguments have the same value the result is that same value. @param a an argument. @param b another argument. @return the larger of a and b. @see java.lang.Long#MAX_VALUE
Class Math, double sqrt(double)

Returns the correctly rounded positive square root of a double value. Special cases: Otherwise the result is the double value closest to the true mathetmaticalmathematical square root of the argument value. @param a a value. <--@return the value of √ a.--> @return the positive square root of a. If the argument is NaN or less than zero the result is NaN.

Class NumberFormatException

Thrown to indicate that the application has attempted to convert a string to one of the numeric types but that the string does not have the appropriate format. @author unascribed @version 1.17 1218 02/0306/0102 @see java.lang.Integer#toString() @since JDK1.0

Class Package, int hashCode()

Return the hash code computed from the package name. @return the hodehash code computed from the package name.

Class Process

The Runtime.exec methods create a native process and return an instance of a subclass of Process that can be used to control the process and obtain information about it. The class Process provides methods for performing input from the process performing output to the process waiting for the process to complete checking the exit status of the process and destroying (killing) the process.

The Runtime.exec methods may not work well for special processes on certain native platforms such as native windowing processes daemon processes Win16/DOS processes on Win32Microsoft Windows or shell scripts. The created subprocess does not have its own terminal or console. All its standard io (i.e. stdin stdout stderr) operations will be redirected to the parent process through three streams (Process.getOutputStream() Process.getInputStream() Process.getErrorStream()). The parent process uses these streams to feed input to and get output from the subprocess. Because some native platforms only provide limited buffer size for standard input and output streams failure to promptly write the input stream or read the output stream of the subprocess may cause the subprocess to block and even deadlock.

The subprocess is not killed when there are no more references to the Process object but rather the subprocess continues executing asynchronously.

There is no requirement that a process represented by a Process object execute asynchronously or concurrently with respect to the Java process that owns the Process object. @author unascribed @version 1.18 1219 04/0304/0102 @see java.lang.Runtime#exec(java.lang.String) @see java.lang.Runtime#exec(java.lang.String java.lang.String[]) @see java.lang.Runtime#exec(java.lang.String[]) @see java.lang.Runtime#exec(java.lang.String[] java.lang.String[]) @since JDK1.0


Class Runtime

Every Java application has a single instance of class Runtime that allows the application to interface with the environment in which the application is running. The current runtime can be obtained from the getRuntime method.

An application cannot create its own instance of this class. @author unascribed @version 1.62 1265 04/0304/0102 @see java.lang.Runtime#getRuntime() @since JDK1.0

Class Runtime, void addShutdownHook(Thread)

Registers a new virtual-machine shutdown hook.

The Java virtual machine shuts down in response to two kinds of events:

A shutdown hook is simply an initialized but unstarted thread. When the virtual machine begins its shutdown sequence it will start all registered shutdown hooks in some unspecified order and let them run concurrently. When all the hooks have finished it will then run all uninvoked finalizers if finalization-on-exit has been enabled. Finally the virtual machine will halt. Note that daemon threads will continue to run during the shutdown sequence as will non-daemon threads if shutdown was initiated by invoking the {@link #exit exit} method.

Once the shutdown sequence has begun it can be stopped only by invoking the {@link #halt halt} method which forcibly terminates the virtual machine.

Once the shutdown sequence has begun it is impossible to register a new shutdown hook or de-register a previously-registered hook. Attempting either of these operations will cause an {@link IllegalStateException} to be thrown.

Shutdown hooks run at a delicate time in the life cycle of a virtual machine and should therefore be coded defensively. They should in particular be written to be thread-safe and to avoid deadlocks insofar as possible. They should also not rely blindly upon services that may have registered their own shutdown hooks and therefore may themselves in the process of shutting down.

Shutdown hooks should also finish their work quickly. When a program invokes {@link #exit exit} the expectation is that the virtual machine will promptly shut down and exit. When the virtual machine is terminated due to user logoff or system shutdown the underlying operating system may only allow a fixed amount of time in which to shut down and exit. It is therefore inadvisable to attempt any user interaction or to perform a long-running computation in a shutdown hook.

Uncaught exceptions are handled in shutdown hooks just as in any other thread by invoking the {@link ThreadGroup#uncaughtException uncaughtException} method of the thread's {@link ThreadGroup} object. The default implementation of this method prints the exception's stack trace to {@link System#err} and terminates the thread; it does not cause the virtual machine to exit or halt.

In rare circumstances the virtual machine may abort that is stop running without shutting down cleanly. This occurs when the virtual machine is terminated externally for example with the SIGKILL signal on Unix or the TerminateProcess call on Win32Microsoft Windows. The virtual machine may also abort if a native method goes awry by for example corrupting internal data structures or attempting to access nonexistent memory. If the virtual machine aborts then no guarantee can be made about whether or not any shutdown hooks will be run.

@param hook An initialized but unstarted {@link Thread} object @throws IllegalArgumentException If the specified hook has already been registered or if it can be determined that the hook is already running or has already been run @throws IllegalStateException If the virtual machine is already in the process of shutting down @throws SecurityException If a security manager is present and it denies {@link RuntimePermission}("shutdownHooks") @see #removeShutdownHook @see #halt(int) @see #exit(int) @since 1.3

Class Runtime, Process exec(String)

Executes the specified string command in a separate process.

The command argument is parsed into tokens and then executed as a command in a separate process. The token parsing is done by a java.util.StringTokenizer created by the call:

 new StringTokenizer(command) 
with no further modifications of the character categories. This method has exactly the same effect as exec(command null). @param command a specified system command. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException if command is null @exception IllegalArgumentException if command is empty @see java.lang.Runtime#exec(java.lang.String java.lang.String[]) @see java.lang.SecurityManager#checkExec(java.lang.String)
Class Runtime, Process exec(String, String[])

Executes the specified string command in a separate process with the specified environment.

This method breaks the command string into tokens and creates a new array cmdarray containing the tokens in the order that they were produced by the string tokenizer; it then performs the call exec(cmdarray envp). The token parsing is done by a java.util.StringTokenizer created by the call:

 new StringTokenizer(command) 
with no further modification of the character categories.

The environment variable settings are specified by envp. If envp is null the subprocess inherits the environment settings of the current process. @param cmd a specified system command. @param envp array of strings each element of which has environment variable settings in format name=value. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException if cmd is null @exception IllegalArgumentException if cmd is empty @see java.lang.Runtime#exec(java.lang.String[]) @see java.lang.Runtime#exec(java.lang.String[] java.lang.String[]) @see java.lang.SecurityManager#checkExec(java.lang.String)

Class Runtime, Process exec(String, String[], File)

Executes the specified string command in a separate process with the specified environment and working directory.

This method breaks the command string into tokens and creates a new array cmdarray containing the tokens in the order that they were produced by the string tokenizer; it then performs the call exec(cmdarray envp). The token parsing is done by a java.util.StringTokenizer created by the call:

 new StringTokenizer(command) 
with no further modification of the character categories.

The environment variable settings are specified by envp. If envp is null the subprocess inherits the environment settings of the current process.

The working directory of the new subprocess is specified by dir. If dir is null the subprocess inherits the current working directory of the current process. @param command a specified system command. @param envp array of strings each element of which has environment variable settings in format name=value. @param dir the working directory of the subprocess or null if the subprocess should inherit the working directory of the current process. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException if command is null @exception IllegalArgumentException if command is empty @see java.lang.Runtime#exec(java.lang.String[] java.lang.String[] File) @see java.lang.SecurityManager#checkExec(java.lang.String) @since 1.3

Class Runtime, Process exec(String[])

Executes the specified command and arguments in a separate process.

The command specified by the tokens in cmdarray is executed as a command in a separate process. This has exactly the same effect as exec(cmdarray null).

If there is a security manager its checkExec method is called with the first component of the array cmdarray as its argument. This may result in a security exception. @param cmdarray array containing the command to call and its arguments. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException if cmdarray is null @exception IndexOutOfBoundsException if cmdarray is an empty array (has length 0). @see java.lang.Runtime#exec(java.lang.String[] java.lang.String[]) @see java.lang.SecurityManager#checkExec(java.lang.String)

Class Runtime, Process exec(String[], String[])

Executes the specified command and arguments in a separate process with the specified environment.

Given an array of strings cmdarray representing the tokens of a command line and an array of strings envp representing "environment" variable settings this method creates a new process in which to execute the specified command.

If envp is null the subprocess inherits the environment settings of the current process. @param cmdarray array containing the command to call and its arguments. @param envp array of strings each element of which has environment variable settings in format name=value. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException if cmdarray is null. @exception IndexOutOfBoundsException if cmdarray is an empty array (has length 0). @exception IOException if an I/O error occurs @see java.lang.Process @see java.lang.SecurityException @see java.lang.SecurityManager#checkExec(java.lang.String)

Class Runtime, Process exec(String[], String[], File)

Executes the specified command and arguments in a separate process with the specified environment and working directory.

If there is a security manager its checkExec method is called with the first component of the array cmdarray as its argument. This may result in a security exception.

Given an array of strings cmdarray representing the tokens of a command line and an array of strings envp representing "environment" variable settings this method creates a new process in which to execute the specified command.

If envp is null the subprocess inherits the environment settings of the current process.

The working directory of the new subprocess is specified by dir. If dir is null the subprocess inherits the current working directory of the current process. @param cmdarray array containing the command to call and its arguments. @param envp array of strings each element of which has environment variable settings in format name=value. @param dir the working directory of the subprocess or null if the subprocess should inherit the working directory of the current process. @return a Process object for managing the subprocess. @exception SecurityException if a security manager exists and its checkExec method doesn't allow creation of a subprocess. @exception NullPointerException if cmdarray is null. @exception IndexOutOfBoundsException if cmdarray is an empty array (has length 0). @exception IOException if an I/O error occurs. @see java.lang.Process @see java.lang.SecurityException @see java.lang.SecurityManager#checkExec(java.lang.String) @since 1.3

Class Runtime, void exit(int)

Terminates the currently running Java virtual machine by initiating its shutdown sequence. This method never returns normally. The argument serves as a status code; by convention a nonzero status code indicates abnormal termination.

The virtual machine's shutdown sequence constistsconsists of two phases. In the first phase all registered shutdow hooks} if any are started in some unspecified order and allowed to run concurrently until they finish. In the second phase all uninvoked finalizers are run if finalization-on-exit has been enabled. Once this is done the virtual machine halts

If this method is invoked after the virtual machine has begun its shutdown sequence then if shutdown hooks are being run this method will block indefinitely. If shutdown hooks have already been run and on-exit finalization has been enabled then this method halts the virtual machine with the given status code if the status is nonzero; otherwise it blocks indefinitely.

The {@link System#exit(int) System.exit} method is the conventional and convenient means of invoking this method.

@param status Termination status. By convention a nonzero status code indicates abnormal termination. @throws SecurityException If a security manager is present and its {@link SecurityManager#checkExit checkExit} method does not permit exiting with the specified status @see java.lang.SecurityException @see java.lang.SecurityManager#checkExit(int) @see #addShutdownHook @see #removeShutdownHook @see #runFinalizersOnExit @see #halt(int)


Class RuntimePermission

This class is for runtime permissions. A RuntimePermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the runtime permission (see below). The naming convention follows the hierarchical property naming convention. Also an asterisk may appear at the end of the name following a "." or by itself to signify a wildcard match. For example: "loadLibrary.*" or "*" is valid "*loadLibrary" or "a*b" is not valid.

The following table lists all the possible RuntimePermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name What the Permission Allows Risks of Allowing this Permission
createClassLoader Creation of a class loader This is an extremely dangerous permission to grant. Malicious applications that can instantiate their own class loaders could then load their own rogue classes into the system. These newly loaded classes could be placed into any protection domain by the class loader thereby automatically granting the classes the permissions for that domain.
getClassLoader Retrieval of a class loader (e.g. the class loader for the calling class) This would grant an attacker permission to get the class loader for a particular class. This is dangerous because having access to a class's class loader allows the attacker to load other classes available to that class loader. The attacker would typically otherwise not have access to those classes.
setContextClassLoader Setting of the context class loader used by a thread The context class loader is used by system code and extensions when they need to lookup resources that might not exist in the system class loader. Granting setContextClassLoader permission would allow code to change which context class loader is used for a particular thread including system threads.
setSecurityManager Setting of the security manager (possibly replacing an existing one) The security manager is a class that allows applications to implement a security policy. Granting the setSecurityManager permission would allow code to change which security manager is used by installing a different possibly less restrictive security manager thereby bypassing checks that would have been enforced by the original security manager.
createSecurityManager Creation of a new security manager This gives code access to protected sensitive methods that may disclose information about other classes or the execution stack.
exitVM Halting of the Java Virtual Machine This allows an attacker to mount a denial-of-service attack by automatically forcing the virtual machine to halt. Note: The "exitVM" permission is automatically granted to all code loaded from the application class path thus enabling applications to terminate themselves.
shutdownHooks Registration and cancellation of virtual-machine shutdown hooks This allows an attacker to register a malicious shutdown hook that interferes with the clean shutdown of the virtual machine.
setFactory Setting of the socket factory used by ServerSocket or Socket or of the stream handler factory used by URL This allows code to set the actual implementation for the socket server socket stream handler or RMI socket factory. An attacker may set a faulty implementation which mangles the data stream.
setIO Setting of System.out System.in and System.err This allows changing the value of the standard system streams. An attacker may change System.in to monitor and steal user input or may set System.err to a "null" OutputSteam which would hide any error messages sent to System.err.
modifyThread Modification of threads e.g. via calls to Thread stop suspend resume setPriority and setName methods This allows an attacker to start or suspend any thread in the system.
stopThread Stopping of threads via calls to the Thread stop method This allows code to stop any thread in the system provided that it is already granted permission to access that thread. This poses as a threat because that code may corrupt the system by killing existing threads.
modifyThreadGroup modification of thread groups e.g. via calls to ThreadGroup destroy getParent resume setDaemon setMaxPriority stop and suspend methods This allows an attacker to create thread groups and set their run priority.
getProtectionDomain Retrieval of the ProtectionDomain for a class This allows code to obtain policy information for a particular code source. While obtaining policy information does not compromise the security of the system it does give attackers additional information such as local file names for example to better aim an attack.
readFileDescriptor Reading of file descriptors This would allow code to read the particular file associated with the file descriptor read. This is dangerous if the file contains confidential data.
writeFileDescriptor Writing to file descriptors This allows code to write to a particular file associated with the descriptor. This is dangerous because it may allow malicious code to plant viruses or at the very least fill up your entire disk.
loadLibrary.{library name} Dynamic linking of the specified library It is dangerous to allow an applet permission to load native code libraries because the Java security architecture is not designed to and does not prevent malicious behavior at the level of native code.
accessClassInPackage.{package name} Access to the specified package via a class loader's loadClass method when that class loader calls the SecurityManager checkPackageAcesss method This gives code access to classes in packages to which it normally does not have access. Malicious code may use these classes to help in its attempt to compromise security in the system.
defineClassInPackage.{package name} Definition of classes in the specified package via a class loader's defineClass method when that class loader calls the SecurityManager checkPackageDefinition method. This grants code permission to define a class in a particular package. This is dangerous because malicious code with this permission may define rogue classes in trusted packages like java.security or java.lang for example.
accessDeclaredMembers Access to the declared members of a class This grants code permission to query a class for its public protected default (package) access and private fields and/or methods. Although the code would have access to the private and protected field and method names it would not have access to the private/protected field data and would not be able to invoke any private methods. Nevertheless malicious code may use this information to better aim an attack. Additionally it may invoke any public methods and/or access public fields in the class. This could be dangerous if the code would normally not be able to invoke those methods and/or access the fields because it can't cast the object to the class/interface with those methods and fields.
queuePrintJob Initiation of a print job request This could print sensitive information to a printer or simply waste paper.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.40 0141 02/1202/0301 @author Marianne Mueller @author Roland Schemers

Class RuntimePermission, constructor RuntimePermission(String, String)

Creates a new RuntimePermission object with the specified name. The name is the symbolic name of the RuntimePermission and the actions String is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new Permission objects. @param name the name of the RuntimePermission. @param actions should be null.

Class Short

The Short class wraps a value of primitive type short in an object. An object of type Short contains a single field whose type is short.

In addition this class provides several methods for converting a short to a String and a String to a short as well as other constants and methods useful when dealing with a short. @author Nakul Saraiya @version 1.31 1232 02/0306/0102 @see java.lang.Number @since JDK1.1


Class StrictMath

The class StrictMath contains methods for performing basic numeric operations such as the elementary exponential logarithm square root and trigonometric functions.

To help ensure portability of Java programs the definitions of many of the numeric functions in this package require that they produce the same results as certain published algorithms. These algorithms are available from the well-known network library netlib as the package "Freely Distributable Math Library" (fdlibm). These algorithms which are written in the C programming language are then to be understood as executed with all floating-point operations following the rules of Java floating-point arithmetic.

The network library may be found on the World Wide Web at:

 http://metalab.unc.edu/ 

The Java math library is defined with respect to the version of fdlibm dated January 4 1995. Where fdlibm provides more than one definition for a function (such as acos) use the "IEEE 754 core function" version (residing in a file whose name begins with the letter e). @author unascribed @version 1.13 1214 02/0306/0102 @since 1.3

Class StrictMath, long max(long, long)

Returns the greater of two long values. That is the result is the argument closer to the value of Long.MAX_VALUE. If the argumensarguments have the same value the result is that same value. @param a an argument. @param b another argument. @return the larger of a and b. @see java.lang.Long#MAX_VALUE
Class StrictMath, double sqrt(double)

Returns the correctly rounded positive square root of a double value. Special cases: Otherwise the result is the double value closest to the true mathetmaticalmathematical square root of the argument value. @param a a value. <--@return the value of √ a.--> @return the positive square root of a.

Class String

The String class represents character strings. All string literals in Java programs such as "abc" are implemented as instances of this class.

Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example:

 String str = "abc"; 

is equivalent to:

 char data[] = {'a' 'b' 'c'}; String str = new String(data); 

Here are some more examples of how strings can be used:

 System.out.println("abc"); String cde = "cde"; System.out.println("abc" + cde); String c = "abc".substring(2 3); String d = cde.substring(1 2); 

The class String includes methods for examining individual characters of the sequence for comparing strings for searching strings for extracting substrings and for creating a copy of a string with all characters translated to uppercase or to lowercase. Case mapping relies heavily on the information provided by the Unicode Consortium's Unicode 3.0 specification. The specification's UnicodeData.txt and SpecialCasing.txt files are used extensively to provide case mapping.

The Java language provides special support for the string concatentationconcatenation operator ( + ) and for conversion of other objects to strings. String concatenation is implemented through the StringBuffer class and its append method. String conversions are implemented through the method toString defined by Object and inherited by all classes in Java. For additional information on string concatenation and conversion see Gosling Joy and Steele The Java Language Specification. @author Lee Boynton @author Arthur van Hoff @version 1.150152 0102/1201/03 @see java.lang.Object#toString() @see java.lang.StringBuffer @see java.lang.StringBuffer#append(boolean) @see java.lang.StringBuffer#append(char) @see java.lang.StringBuffer#append(char[]) @see java.lang.StringBuffer#append(char[] int int) @see java.lang.StringBuffer#append(double) @see java.lang.StringBuffer#append(float) @see java.lang.StringBuffer#append(int) @see java.lang.StringBuffer#append(long) @see java.lang.StringBuffer#append(java.lang.Object) @see java.lang.StringBuffer#append(java.lang.String) @see java.nio.charset.Charset @since JDK1.0

Class String, constructor String()

Initializes a newly created String object so that it represents an empty character sequence. Note that use of this constructor is unnecessary since Strings are immutable.
Class String, constructor String(String)

Initializes a newly created String object so that it represents the same sequence of characters as the argument; in other words the newly created string is a copy of the argument string. Unless an explicit copy of original is needed use of this constructor is unnecessary since Strings are immutable. @param original a String. @throws NullPointerException if original is null
Class String, constructor String(byte[])

Constructs a new String by decoding the specified array of bytes using the platform's default charset. The length of the new String is a function of the charset and hence may not be equal to the length of the byte array.

The behavior of this constructor when the given bytes are not valid in the default charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required. @param bytes the bytes to be decoded into characters @throws NullPointerException if bytes is null @since JDK1.1

Class String, constructor String(byte[], String)

Constructs a new String by decoding the specified array of bytes using the specified charset. The length of the new String is a function of the charset and hence may not be equal to the length of the byte array.

The behavior of this constructor when the given bytes are not valid in the given charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required. @param bytes the bytes to be decoded into characters @param charsetName the name of a supported charset @exception UnsupportedEncodingException If the named charset is not supported @exception NullPointerException If charsetName or the bytes array is null @since JDK1.1

Class String, constructor String(byte[], int, int)

Constructs a new String by decoding the specified subarray of bytes using the platform's default charset. The length of the new String is a function of the charset and hence may not be equal to the length of the subarray.

The behavior of this constructor when the given bytes are not valid in the default charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required. @param bytes the bytes to be decoded into characters @param offset the index of the first byte to decode @param length the number of bytes to decode @throws IndexOutOfBoundsException if the offset and the length arguments index characters outside the bounds of the bytes array @throws NullPointerException if bytes array is null @since JDK1.1

Class String, constructor String(byte[], int, int, String)

Constructs a new String by decoding the specified subarray of bytes using the specified charset. The length of the new String is a function of the charset and hence may not be equal to the length of the subarray.

The behavior of this constructor when the given bytes are not valid in the given charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required. @param bytes the bytes to be decoded into characters @param offset the index of the first byte to decode @param length the number of bytes to decode @param charsetName the name of a supported charset @throws UnsupportedEncodingException if the named charset is not supported @throws IndexOutOfBoundsException if the offset and length arguments index characters outside the bounds of the valuebytes array @throws NullPointerException if charsetName is null @since JDK1.1

Class String, int compareToIgnoreCase(String)

Compares two strings lexicographically ignoring case considerationsdifferences. This method returns an integer whose sign is that of calling this.toUpperCase().toLowerCase().compareTo( strwith normalized versions of the strings where case differences have been eliminated by calling Character.toUpperCasetoLowerCase()Character.toLowerCasetoUpperCase(character)) on each character.

Note that this method does not take locale into account and will result in an unsatisfactory ordering for certain locales. The java.text package provides collators to allow locale-sensitive ordering. @param str the String to be compared. @return a negative integer zero or a positive integer as the the specified String is greater than equal to or less than this String ignoring case considerations. @see java.text.Collator#compare(String String) @since 1.2


Class StringBuffer

A string buffer implements a mutable sequence of characters. A string buffer is like a String but can be modified. At any point in time it contains some particular sequence of characters but the length and content of the sequence can be changed through certain method calls.

String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved.

String buffers are used by the compiler to implement the binary string concatenation operator +. For example the code:

 x = "a" + 4 + "c" 

is compiled to the equivalent of:

 x = new StringBuffer().append("a").append(4).append("c") .toString() 
which creates a new string buffer (initially empty) appends the string representation of each operand to the string buffer in turn and then converts the contents of the string buffer to a string. Overall this avoids creating many temporary strings.

The principal operations on a StringBuffer are the append and insert methods which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point.

For example if z refers to a string buffer object whose current contents are "start" then the method call z.append("le") would cause the string buffer to contain "startle" whereas z.insert(4 "le") would alter the string buffer to contain "starlet".

In general if sb refers to an instance of a StringBuffer then sb.append(x) has the same effect as sb.insert(sb.length()  x).

Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity it is not necessary to allocate a new internal buffer array. If the internal buffer overflows it is automatically made larger. @author Arthur van Hoff @version 1.7073 12/03/0105/02 @see java.io.ByteArrayOutputStream @see java.lang.String @since JDK1.0

Class StringBuffer, constructor StringBuffer(String)

Constructs a string buffer so that it represents the same sequence of characters as the string argument; in other words the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is 16 plus the length of the string argument. @param str the initial contents of the buffer. @exception NullPointerException if str is null
Class StringBuffer, void setCharAt(int, char)

The character at the specified index of this string buffer is set to ch. The string buffer is altered to represent a new character sequence that is identical to the old character sequence except that it contains the character ch at position index.

The offsetindex argument must be greater than or equal to 0 and less than the length of this string buffer. @param index the index of the character to modify. @param ch the new character. @exception IndexOutOfBoundsException if index is negative or greater than or equal to length(). @see java.lang.StringBuffer#length()

Class StringBuffer, void setLength(int)

Sets the length of this String buffer. This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index k less than newLength the character at index k in the new character sequence is the same as the character at index k in the old sequence if k is less than the length of the old character sequence; otherwise it is the null character '&#92;u0000'. In other words if the newLength argument is less than the current length of the string buffer the string buffer is truncated to contain exactly the number of characters given by the newLength argument.

If the newLength argument is greater than or equal to the current length sufficient null characters ('\u0000') are appended to the string buffer so that length becomes the newLength argument.

The newLength argument must be greater than or equal to 0. @param newLength the new length of the buffer. @exception IndexOutOfBoundsException if the newLength argument is negative. @see java.lang.StringBuffer#length()


Class Throwable

The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly only this class or one of its subclasses can be the argument type in a catch clause.

Instances of two subclasses java.lang.Error and java.lang.Exception are conventionally used to indicate that exceptional situations have occurred. Typically these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data).

A throwable contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error. Finally it can contain a cause: another throwable that caused this throwable to get thrown. The cause facility is new in release 1.4. It is also known as the chained exception facility as the cause can itself have a cause and so on leading to a "chain" of exceptions each caused by another.

One reason that a throwable may have a cause is that the class that throws it is built atop a lower layered abstraction and an operation on the upper layer fails due to a failure in the lower layer. It would be bad design to let the throwable thrown by the lower layer propagate outward as it is generally unrelated to the abstraction provided by the upper layer. Further doing so would tie the API of the upper layer to the details of its implementation assuming the lower layer's exception was a checked exception. Throwing a "wrapped exception" (i.e. an exception containing a cause) allows the upper layer to communicate the details of the failure to its caller without incurring either of these shortcomings. It preserves the flexibility to change the implementation of the upper layer without changing its API (in particular the set of exceptions thrown by its methods).

A second reason that a throwable may have a cause is that the method that throws it must conform to a general-purpose interface that does not permit the method to throw the cause directly. For example suppose a persistent collection conforms to the Collection interface and that its persistence is implemented atop java.io. Suppose the internals of the put method can throw an IOException The implementation can communicate the details of the IOException to its caller while conforming to the Collection interface by wrapping the IOException in an appropriate unchecked exception. (The specification for the persistent collection should indicate that it is capable of throwing such exceptions.)

A cause can be associated with a throwable in two ways: via a constructor that takes the cause as an argument or via the #initCause(Throwable) method. New throwable classes that wish to allow causes to be associated with them should provide constructors that take a cause and delegate (perhaps indirectly) to one of the Throwable constructors that takes a cause. For example:

 try { lowLevelOp(); } catch LowLevelException(LowLevelException le) { throw new HighLevelException(le); // Chaining-aware constructor } 
Because the initCause method is public it allows a cause to be associated with any throwable even a "legacy throwable" whose implementation predates the addition of the exception chaining mechanism to Throwable. For example:
 try { lowLevelOp(); } catch LowLevelException(LowLevelException le) { throw (HighLevelException) new HighLevelException().initCause(le); // Legacy constructor } 

Prior to release 1.4 there were many throwables that had their own non-standard exception chaining mechanisms ( ExceptionInInitializerError ClassNotFoundException java.lang.reflect.UndeclaredThrowableException java.lang.reflect.InvocationTargetException java.io.WriteAbortedException java.security.PrivilegedActionException java.awt.print.PrinterIOException and A of release 1.4 all of these throwables have been retrofitted to use the standard exception chaining mechanism while continuing to implement their "legacy" chaining mechanisms for compatibility.

Further as of release 1.4 many general purpose Throwable classes (for example Exception RuntimeException hav been retrofitted with constructors that take a cause. This was not strictly necessary due to the existence of the initCause method but it is more convenient and expressive to delegate to a constructor that takes a cause.

By convention class Throwable and its subclasses have two constructors one that takes no arguments and one that takes a String argument that can be used to produce a detail message. Further those subclasses that might likely have a cause associated with them should have two more constructors one that takes a Throwable (the cause) and one that takes a String (the detail message) and a Throwable (the cause).

Also introduced in release 1.4 is the #getStackTrace() method which allows programmatic access to the stack trace information that was previously available only in text form via the various forms of the #printStackTrace() method. This information has been added to the serialized representation of this class so getStackTrace and printStackTrace will operate properly on a throwable that was obtained by deserialization. @author unascribed @author Josh Bloch (Added exception chaining and programmatic access to stack trace in 1.4.) @version 1.49 1250 02/0319/0102 @since JDK1.0