|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.lang
as colored differences. Deletions are shownlike 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.
TheByte
class wraps a value of primitive typebyte
in an object. An object of typeByte
contains a single field whose type isbyte
.In addition this class provides several methods for converting a
byte
to aString
and aString
to abyte
as well as other constants and methods useful when dealing with abyte
. @author Nakul Saraiya @version 1.28 1229 02/0306/0102 @see java.lang.Number @since JDK1.1
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
@author Mike McCloskey @version 1.becapable 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.4 015 02/1204/0323 @since 1.4 @spec JSR-51
Instances of the classClass Class, Field getDeclaredField(String)Class
represent classes and interfaces in a running Java application. Every array also belongs to a class that is reflected as aClass
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
anddouble
) and the keywordvoid
are also represented asClass
objects.
Class
has no public constructor. InsteadClass
objects are constructed automatically by the Java Virtual Machine as classes are loaded and by calls to thedefineClass
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:
@author unascribed @version 1.135 05/25/01 @see java.lang.ClassLoader#defineClass(byte[] int int) @since JDK1.0System.out.println("The name of class Foo is: "+Foo.class.getName());
Returns aClass Class, Method getDeclaredMethod(String, Class[])Field
object that reflects the specified declared field of the class or interface represented by thisClass
object. Thename
parameter is aString
that specifies the simple name of the desired field. Note that this method will not reflect thelength
field of an array class.If there is a security manager this method first calls the security manager's
checkMemberAccess
method withthis
andMember.DECLARED
as its arguments. If the class is in a package then this method also calls the security manager'scheckPackageAccess
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 theField
object for the specified field in this class @exception NoSuchFieldException if a field with the specified name is not found. @exception NullPointerException ifname
isnull
@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
Returns aClass Class, Field getField(String)Method
object that reflects the specified declared method of the class or interface represented by thisClass
object. Thename
parameter is aString
that specifies the simple name of the desired method and theparameterTypes
parameter is an array ofClass
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>" aNoSuchMethodException
is raised.If there is a security manager this method first calls the security manager's
checkMemberAccess
method withthis
andMember.DECLARED
as its arguments. If the class is in a package then this method also calls the security manager'scheckPackageAccess
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 theMethod
object for the method of this class matching the specified name and parameters @exception NoSuchMethodException if a matching method is not found. @exception NullPointerException ifname
isnull
@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
Returns aClass Class, Method getMethod(String, Class[])Field
object that reflects the specified public member field of the class or interface represented by thisClass
object. Thename
parameter is aString
specifying the simple name of the desired field.If there is a security manager this method first calls the security manager's
checkMemberAccess
method withthis
andMember.PUBLIC
as its arguments. If the class is in a package then this method also calls the security manager'scheckPackageAccess
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:
- If C declares a public field with the name specified that is the field to be reflected.
- 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.
- 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 byname
@exception NoSuchFieldException if a field with the specified name is not found. @exception NullPointerException ifname
isnull
@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
Returns aMethod
object that reflects the specified public member method of the class or interface represented by thisClass
object. Thename
parameter is aString
specifying the simple name the desired method. TheparameterTypes
parameter is an array ofClass
objects that identify the method's formal parameter types in declared order. IfparameterTypes
isnull
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 withthis
andMember.PUBLIC
as its arguments. If the class is in a package then this method also calls the security manager'scheckPackageAccess
method with the package name as its argument. Either of these calls could result in a SecurityException.If the
name
is "<init>"or "<clinit>" aNoSuchMethodException
is raised. Otherwise the method to be reflected is determined by the algorithm that follows. Let C be the class represented by this object: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.
- 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.
- 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.
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 specifiedname
andparameterTypes
@exception NoSuchMethodException if a matching method is not found or ifthenthe name is "<init>"or "<clinit>". @exception NullPointerException ifname
isnull
@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
A class loader is an object that is responsible for loading classes. The classClass ClassLoader, constructor ClassLoader()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 theClassLoader
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 ofClassLoader
has an associated parent class loader. When called upon to find a class or resource aClassLoader
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 aClassLoader
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 classClass
. Instances of this newly defined class can be created using thenewInstance
method in classClass
.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
andloadClassData
to load a class from the network. Once it has downloaded the bytes that make up the class it should use the methoddefineClass
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.16016212/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
Creates a new class loader using theClassLoader
returned by the methodgetSystemClassLoader()
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 itscheckCreateClassLoader
method is called. This may result in a security exception. @throws SecurityException if a security manager exists and itscheckCreateClassLoader
method doesn't allow creation of a new class loader. @see java.lang.SecurityException @see java.lang.SecurityManager#checkCreateClassLoader()
TheClass Double, double longBitsToDouble(long)Double
class wraps a value of the primitive typedouble
in an object. An object of typeDouble
contains a single field whose type isdouble
.In addition this class provides several methods for converting a
double
to aString
and aString
to adouble
as well as other constants and methods useful when dealing with adouble
. @author Lee Boynton @author Arthur van Hoff @version 1.79 1280 04/0309/0102 @since JDK1.0
Returns theClass Double, double MAX_VALUEdouble
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
through0x7fffffffffffffffL
or in the range0xfff0000000000001L
through0xffffffffffffffffL
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 theDouble.doubleToRawLongBits
method.In all other cases let s e and m be three values that can be computed from the argument:
Then the floating-point result equals the value of the mathematical expression s·m·2e-1075.int s = ((bits >> 63) == 0) 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L;Note that this method may not be able to return a
double
NaN with exactly same bit pattern as thelong
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. SolongBitsToDouble
may not be able to return adouble
with a signaling NaN bit pattern. Consequently for somelong
valuesdoubleToRawLongBits(longBitsToDouble(start))
may not equalstart
. 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 anylong
integer. @return thedouble
floating-point value with the same bit pattern.
A constant holding the largest positive finite value of typeClass Double, double MIN_VALUEdouble
(2-2-52)·21023. It is equal to the value returned by:Double.longBitsToDouble(0x7fefffffffffffffL)
.
A constant holding the smallest positive nonzero value of typedouble
2-1074. It is equal to the value returned byDouble.longBitsToDouble(0x1L)
.
TheClass Float, float intBitsToFloat(int)Float
class wraps a value of primitive typefloat
in an object. An object of typeFloat
contains a single field whose type isfloat
.In addition this class provides several methods for converting a
float
to aString
and aString
to afloat
as well as other constants and methods useful when dealing with afloat
. @author Lee Boynton @author Arthur van Hoff @version 1.77 1278 04/0309/0102 @since JDK1.0
Returns theClass Float, float MAX_VALUEfloat
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
through0x7fffffff
or in the range0xff800001
through0xffffffff
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 theFloat.floatToRawIntBits
method.In all other cases let s e and m be three values that can be computed from the argument:
Then the floating-point result equals the value of the mathematical expression s·m·2e-150.int s = ((bits >> 31) == 0) 1 : -1; int e = ((bits >> 23) & 0xff); int m = (e == 0) (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;Note that this method may not be able to return a
float
NaN with exactly same bit pattern as theint
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. SointBitsToFloat
may not be able to return afloat
with a signaling NaN bit pattern. Consequently for someint
valuesfloatToRawIntBits(intBitsToFloat(start))
may not equalstart
. 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 thefloat
floating-point value with the same bit pattern.
A constant holding the largest positive finite value of typeClass Float, float MIN_VALUEfloat
(2-2-23)·2127. It is equal to the value returned byFloat.intBitsToFloat(0x7f7fffff)
.
A constant holding the smallest positive nonzero value of typefloat
2-149. It is equal to the value returned byFloat.intBitsToFloat(0x1)
.
TheInteger
class wraps a value of the primitive typeint
in an object. An object of typeInteger
contains a single field whose type isint
.In addition this class provides several methods for converting an
int
to aString
and aString
to anint
as well as other constants and methods useful when dealing with anint
. @author Lee Boynton @author Arthur van Hoff @version 1.73 1274 02/0306/0102 @since JDK1.0
TheClass Long, constructor Long(String)Long
class wraps a value of the primitive typelong
in an object. An object of typeLong
contains a single field whose type islong
.In addition this class provides several methods for converting a
long
to aString
and aString
to along
as well as other constants and methods useful when dealing with along
. @author Lee Boynton @author Arthur van Hoff @version 1.626412/03/0121/02 @since JDK1.0
Constructs a newly allocatedLong
object that represents thelong
value indicated by theString
parameter. The string is converted to along
value in exactly the manner used by theparseLong
method for radix 10. @param s theString
to be converted to aLong
. @exception NumberFormatException if theString
does not contain a parsablelong
. @see java.lang.Long#valueOfparseLong(java.lang.String int)
The classClass Math, long max(long, long)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 classMath
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 inStrictMath
for their implementation. Code generators are encouraged to use platform-specific native libraries or microprocessor instructions where available to provide higher-performance implementations ofMath
methods. Such higher-performance implementations still must conform to the specification forMath
.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 theMath
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
Returns the greater of twoClass Math, double sqrt(double)long
values. That is the result is the argument closer to the value ofLong.MAX_VALUE
. If theargumensarguments have the same value the result is that same value. @param a an argument. @param b another argument. @return the larger ofa
andb
. @see java.lang.Long#MAX_VALUE
Returns the correctly rounded positive square root of adouble
value. Special cases:Otherwise the result is the
- If the argument is NaN or less than zero then the result is NaN.
- If the argument is positive infinity then the result is positive infinity.
- If the argument is positive zero or negative zero then the result is the same as the argument.
double
value closest to the truemathetmaticalmathematical square root of the argument value. @param a a value. <--@return the value of √a
.--> @return the positive square root ofa
. If the argument is NaN or less than zero the result is NaN.
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
Return the hash code computed from the package name. @return thehodehash code computed from the package name.
TheRuntime.exec
methods create a native process and return an instance of a subclass ofProcess
that can be used to control the process and obtain information about it. The classProcess
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 onWin32Microsoft 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 theProcess
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
Every Java application has a single instance of classClass Runtime, void addShutdownHook(Thread)Runtime
that allows the application to interface with the environment in which the application is running. The current runtime can be obtained from thegetRuntime
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
Registers a new virtual-machine shutdown hook.Class Runtime, Process exec(String)The Java virtual machine shuts down in response to two kinds of events:
- The program exits normally when the last non-daemon thread exits or when the {@link #exit exit} (equivalently {@link System#exit(int) System.exit}) method is invoked or
- The virtual machine is terminated in response to a user interrupt such as typing ^C or a system-wide event such as user logoff or system shutdown.
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
Executes the specified string command in a separate process.Class Runtime, Process exec(String, String[])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:with no further modifications of the character categories. This method has exactly the same effect asnew StringTokenizer(command)exec(command null)
. @param command a specified system command. @return aProcess
object for managing the subprocess. @exception SecurityException if a security manager exists and itscheckExec
method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException ifcommand
isnull
@exception IllegalArgumentException ifcommand
is empty @see java.lang.Runtime#exec(java.lang.String java.lang.String[]) @see java.lang.SecurityManager#checkExec(java.lang.String)
Executes the specified string command in a separate process with the specified environment.Class Runtime, Process exec(String, String[], File)This method breaks the
command
string into tokens and creates a new arraycmdarray
containing the tokens in the order that they were produced by the string tokenizer; it then performs the callexec(cmdarray envp)
. The token parsing is done by a java.util.StringTokenizer created by the call:with no further modification of the character categories.new StringTokenizer(command)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 itscheckExec
method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException ifcmd
is null @exception IllegalArgumentException ifcmd
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)
Executes the specified string command in a separate process with the specified environment and working directory.Class Runtime, Process exec(String[])This method breaks the
command
string into tokens and creates a new arraycmdarray
containing the tokens in the order that they were produced by the string tokenizer; it then performs the callexec(cmdarray envp)
. The token parsing is done by a java.util.StringTokenizer created by the call:with no further modification of the character categories.new StringTokenizer(command)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 itscheckExec
method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException ifcommand
isnull
@exception IllegalArgumentException ifcommand
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
Executes the specified command and arguments in a separate process.Class Runtime, Process exec(String[], String[])The command specified by the tokens in
cmdarray
is executed as a command in a separate process. This has exactly the same effect asexec(cmdarray null)
.If there is a security manager its
checkExec
method is called with the first component of the arraycmdarray
as its argument. This may result in a security exception. @param cmdarray array containing the command to call and its arguments. @return aProcess
object for managing the subprocess. @exception SecurityException if a security manager exists and itscheckExec
method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException ifcmdarray
isnull
@exception IndexOutOfBoundsException ifcmdarray
is an empty array (has length0
). @see java.lang.Runtime#exec(java.lang.String[] java.lang.String[]) @see java.lang.SecurityManager#checkExec(java.lang.String)
Executes the specified command and arguments in a separate process with the specified environment.Class Runtime, Process exec(String[], String[], File)Given an array of strings
cmdarray
representing the tokens of a command line and an array of stringsenvp
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 itscheckExec
method doesn't allow creation of a subprocess. @exception IOException if an I/O error occurs @exception NullPointerException ifcmdarray
isnull
.@exception IndexOutOfBoundsException ifcmdarray
is an empty array (has length0
). @exception IOException if an I/O error occurs @see java.lang.Process @see java.lang.SecurityException @see java.lang.SecurityManager#checkExec(java.lang.String)
Executes the specified command and arguments in a separate process with the specified environment and working directory.Class Runtime, void exit(int)If there is a security manager its
checkExec
method is called with the first component of the arraycmdarray
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 stringsenvp
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 itscheckExec
method doesn't allow creation of a subprocess. @exception NullPointerException ifcmdarray
isnull
.@exception IndexOutOfBoundsException ifcmdarray
is an empty array (has length0
). @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
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 haltsIf 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)
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.Class RuntimePermission, constructor RuntimePermission(String, String)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.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.
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
andsetName
methodsThis allows an attacker to start or suspend any thread in the system. stopThread Stopping of threads via calls to the Thread stop
methodThis 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
andsuspend
methodsThis 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 SecurityManagercheckPackageAcesss
methodThis 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 SecurityManagercheckPackageDefinition
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
orjava.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. 40 0141 02/1202/0301 @author Marianne Mueller @author Roland Schemers
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.
TheShort
class wraps a value of primitive typeshort
in an object. An object of typeShort
contains a single field whose type isshort
.In addition this class provides several methods for converting a
short
to aString
and aString
to ashort
as well as other constants and methods useful when dealing with ashort
. @author Nakul Saraiya @version 1.31 1232 02/0306/0102 @see java.lang.Number @since JDK1.1
The classClass StrictMath, long max(long, long)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. Wherefdlibm
provides more than one definition for a function (such asacos
) use the "IEEE 754 core function" version (residing in a file whose name begins with the lettere
). @author unascribed @version 1.13 1214 02/0306/0102 @since 1.3
Returns the greater of twoClass StrictMath, double sqrt(double)long
values. That is the result is the argument closer to the value ofLong.MAX_VALUE
. If theargumensarguments have the same value the result is that same value. @param a an argument. @param b another argument. @return the larger ofa
andb
. @see java.lang.Long#MAX_VALUE
Returns the correctly rounded positive square root of adouble
value. Special cases:Otherwise the result is the
- If the argument is NaN or less than zero then the result is NaN.
- If the argument is positive infinity then the result is positive infinity.
- If the argument is positive zero or negative zero then the result is the same as the argument.
double
value closest to the truemathetmaticalmathematical square root of the argument value. @param a a value. <--@return the value of √a
.--> @return the positive square root ofa
.
TheClass String, constructor String()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 theStringBuffer
class and itsappend
method. String conversions are implemented through the methodtoString
defined byObject
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.1501520102/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
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 createdClass String, constructor String(byte[])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 oforiginal
is needed use of this constructor is unnecessary since Strings are immutable. @param original aString
. @throws NullPointerException iforiginal
isnull
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.Class String, constructor String(byte[], String)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
isnull
@since JDK1.1
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.Class String, constructor String(byte[], int, int)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 thebytes
array isnull
@since JDK1.1
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.Class String, constructor String(byte[], int, int, String)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 thelength
arguments index characters outside the bounds of thebytes
array @throws NullPointerException ifbytes
array isnull
@since JDK1.1
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.Class String, int compareToIgnoreCase(String)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
Compares two strings lexicographically ignoring caseconsiderationsdifferences. 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 callingCharacter
.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
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.Class StringBuffer, constructor StringBuffer(String)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:
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.x = new StringBuffer().append("a").append(4).append("c") .toString()The principal operations on a
StringBuffer
are theappend
andinsert
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. Theappend
method always adds these characters at the end of the buffer; theinsert
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 callz.append("le")
would cause the string buffer to contain "startle
" whereasz.insert(4 "le")
would alter the string buffer to contain "starlet
".In general if sb refers to an instance of a
StringBuffer
thensb.append(x)
has the same effect assb.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.
707312/03/0105/02 @see java.io.ByteArrayOutputStream @see java.lang.String @since JDK1.0
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 isClass StringBuffer, void setCharAt(int, char)16
plus the length of the string argument. @param str the initial contents of the buffer. @exception NullPointerException ifstr
isnull
The character at the specified index of this string buffer is set toClass StringBuffer, void setLength(int)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 characterch
at positionindex
.The
offsetindex argument must be greater than or equal to0
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 ifindex
is negative or greater than or equal tolength()
. @see java.lang.StringBuffer#length()
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 thannewLength
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'\u0000'
. In other words if thenewLength
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 thenewLength
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 thenewLength
argument.The
newLength
argument must be greater than or equal to0
. @param newLength the new length of the buffer. @exception IndexOutOfBoundsException if thenewLength
argument is negative. @see java.lang.StringBuffer#length()
TheThrowable
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 Javathrow
statement. Similarly only this class or one of its subclasses can be the argument type in acatch
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(); } catchBecause 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:LowLevelException(LowLevelException le) { throw new HighLevelException(le); // Chaining-aware constructor }try { lowLevelOp(); } catchLowLevelException(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 aString
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 aThrowable
(the cause) and one that takes aString
(the detail message) and aThrowable
(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