|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.lang.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.
getRuntime()
Method Summary | |
void |
addShutdownHook(Thread hook)
Registers a new virtual-machine shutdown hook. |
int |
availableProcessors()
Returns the number of processors available to the Java virtual machine. |
Process |
exec(String command)
Executes the specified string command in a separate process. |
Process |
exec(String[] cmdarray)
Executes the specified command and arguments in a separate process. |
Process |
exec(String[] cmdarray,
String[] envp)
Executes the specified command and arguments in a separate process with the specified environment. |
Process |
exec(String[] cmdarray,
String[] envp,
File dir)
Executes the specified command and arguments in a separate process with the specified environment and working directory. |
Process |
exec(String cmd,
String[] envp)
Executes the specified string command in a separate process with the specified environment. |
Process |
exec(String command,
String[] envp,
File dir)
Executes the specified string command in a separate process with the specified environment and working directory. |
void |
exit(int status)
Terminates the currently running Java virtual machine by initiating its shutdown sequence. |
long |
freeMemory()
Returns the amount of free memory in the Java Virtual Machine. |
void |
gc()
Runs the garbage collector. |
InputStream |
getLocalizedInputStream(InputStream in)
Deprecated. As of JDK 1.1, the preferred way to translate a byte stream in the local encoding into a character stream in Unicode is via the InputStreamReader and BufferedReader
classes. |
OutputStream |
getLocalizedOutputStream(OutputStream out)
Deprecated. As of JDK 1.1, the preferred way to translate a Unicode character stream into a byte stream in the local encoding is via the OutputStreamWriter , BufferedWriter , and
PrintWriter classes. |
static Runtime |
getRuntime()
Returns the runtime object associated with the current Java application. |
void |
halt(int status)
Forcibly terminates the currently running Java virtual machine. |
void |
load(String filename)
Loads the specified filename as a dynamic library. |
void |
loadLibrary(String libname)
Loads the dynamic library with the specified library name. |
long |
maxMemory()
Returns the maximum amount of memory that the Java virtual machine will attempt to use. |
boolean |
removeShutdownHook(Thread hook)
De-registers a previously-registered virtual-machine shutdown hook. |
void |
runFinalization()
Runs the finalization methods of any objects pending finalization. |
static void |
runFinalizersOnExit(boolean value)
Deprecated. This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock. |
long |
totalMemory()
Returns the total amount of memory in the Java virtual machine. |
void |
traceInstructions(boolean on)
Enables/Disables tracing of instructions. |
void |
traceMethodCalls(boolean on)
Enables/Disables tracing of method calls. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
public static Runtime getRuntime()
Runtime
are instance
methods and must be invoked with respect to the current runtime object.
Runtime
object associated with the current
Java application.public void exit(int status)
The virtual machine's shutdown sequence consists of two phases. In
the first phase all registered shutdown 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 System.exit
method is the
conventional and convenient means of invoking this method.
status
- Termination status. By convention, a nonzero status code
indicates abnormal termination.
SecurityException
- If a security manager is present and its checkExit
method does not permit
exiting with the specified statusSecurityException
,
SecurityManager.checkExit(int)
,
addShutdownHook(java.lang.Thread)
,
removeShutdownHook(java.lang.Thread)
,
runFinalizersOnExit(boolean)
,
halt(int)
public void addShutdownHook(Thread hook)
The Java virtual machine shuts down in response to two kinds of events:
exit
(equivalently,
System.exit
) method is invoked, or
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 exit
method.
Once the shutdown sequence has begun it can be stopped only by
invoking the 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
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 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 uncaughtException
method of the thread's ThreadGroup
object. The default implementation of this method
prints the exception's stack trace to 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 Microsoft 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.
hook
- An initialized but unstarted Thread
object
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
IllegalStateException
- If the virtual machine is already in the process
of shutting down
SecurityException
- If a security manager is present and it denies
RuntimePermission
("shutdownHooks")removeShutdownHook(java.lang.Thread)
,
halt(int)
,
exit(int)
public boolean removeShutdownHook(Thread hook)
hook
- the hook to remove
IllegalStateException
- If the virtual machine is already in the process of shutting
down
SecurityException
- If a security manager is present and it denies
RuntimePermission
("shutdownHooks")addShutdownHook(java.lang.Thread)
,
exit(int)
public void halt(int status)
This method should be used with extreme caution. Unlike the
exit
method, this method does not cause shutdown
hooks to be started and does not run uninvoked finalizers if
finalization-on-exit has been enabled. If the shutdown sequence has
already been initiated then this method does not wait for any running
shutdown hooks or finalizers to finish their work.
status
- Termination status. By convention, a nonzero status code
indicates abnormal termination. If the exit
(equivalently, System.exit
) method has already been invoked then this
status code will override the status code passed to that method.
SecurityException
- If a security manager is present and its checkExit
method does not permit
an exit with the specified statusexit(int)
,
addShutdownHook(java.lang.Thread)
,
removeShutdownHook(java.lang.Thread)
public static void runFinalizersOnExit(boolean value)
If there is a security manager,
its checkExit
method is first called
with 0 as its argument to ensure the exit is allowed.
This could result in a SecurityException.
value
- true to enable finalization on exit, false to disable
SecurityException
- if a security manager exists and its checkExit
method doesn't allow the exit.exit(int)
,
gc()
,
SecurityManager.checkExit(int)
public Process exec(String command) throws IOException
The command
argument is parsed into tokens and then
executed as a command in a separate process. The token parsing is
done by a 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)
.
command
- a specified system command.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a subprocess.
IOException
- if an I/O error occurs
NullPointerException
- if command
is
null
IllegalArgumentException
- if command
is emptyexec(java.lang.String, java.lang.String[])
,
SecurityManager.checkExec(java.lang.String)
public Process exec(String cmd, String[] envp) throws IOException
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 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.
cmd
- a specified system command.envp
- array of strings, each element of which
has environment variable settings in format
name=value.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a subprocess.
IOException
- if an I/O error occurs
NullPointerException
- if cmd
is null
IllegalArgumentException
- if cmd
is emptyexec(java.lang.String[])
,
exec(java.lang.String[], java.lang.String[])
,
SecurityManager.checkExec(java.lang.String)
public Process exec(String command, String[] envp, File dir) throws IOException
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 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.
command
- a specified system command.envp
- array of strings, each element of which
has environment variable settings in format
name=value.dir
- the working directory of the subprocess, or
null if the subprocess should inherit
the working directory of the current process.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a subprocess.
IOException
- if an I/O error occurs
NullPointerException
- if command
is
null
IllegalArgumentException
- if command
is emptyexec(java.lang.String[], java.lang.String[], File)
,
SecurityManager.checkExec(java.lang.String)
public Process exec(String[] cmdarray) throws IOException
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.
cmdarray
- array containing the command to call and
its arguments.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a subprocess.
IOException
- if an I/O error occurs
NullPointerException
- if cmdarray
is
null
IndexOutOfBoundsException
- if cmdarray
is an
empty array (has length 0
).exec(java.lang.String[], java.lang.String[])
,
SecurityManager.checkExec(java.lang.String)
public Process exec(String[] cmdarray, String[] envp) throws IOException
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.
cmdarray
- array containing the command to call and
its arguments.envp
- array of strings, each element of which
has environment variable settings in format
name=value.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a subprocess.
IOException
- if an I/O error occurs
NullPointerException
- if cmdarray
is
null
IndexOutOfBoundsException
- if cmdarray
is an
empty array (has length 0
).Process
,
SecurityException
,
SecurityManager.checkExec(java.lang.String)
public Process exec(String[] cmdarray, String[] envp, File dir) throws IOException
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.
cmdarray
- array containing the command to call and
its arguments.envp
- array of strings, each element of which
has environment variable settings in format
name=value.dir
- the working directory of the subprocess, or
null if the subprocess should inherit
the working directory of the current process.
Process
object for managing the subprocess.
SecurityException
- if a security manager exists and its
checkExec
method doesn't allow creation of a
subprocess.
NullPointerException
- if cmdarray
is
null
IndexOutOfBoundsException
- if cmdarray
is an
empty array (has length 0
).
IOException
- if an I/O error occurs.Process
,
SecurityException
,
SecurityManager.checkExec(java.lang.String)
public int availableProcessors()
This value may change during a particular invocation of the virtual machine. Applications that are sensitive to the number of available processors should therefore occasionally poll this property and adjust their resource usage appropriately.
public long freeMemory()
gc
method may result in increasing the value returned
by freeMemory.
public long totalMemory()
Note that the amount of memory required to hold an object of any given type may be implementation-dependent.
public long maxMemory()
Long.MAX_VALUE
will be returned.
public void gc()
The name gc
stands for "garbage
collector". The virtual machine performs this recycling
process automatically as needed, in a separate thread, even if the
gc
method is not invoked explicitly.
The method System.gc()
is the conventional and convenient
means of invoking this method.
public void runFinalization()
finalize
methods of objects
that have been found to be discarded but whose finalize
methods have not yet been run. When control returns from the
method call, the virtual machine has made a best effort to
complete all outstanding finalizations.
The virtual machine performs the finalization process
automatically as needed, in a separate thread, if the
runFinalization
method is not invoked explicitly.
The method System.runFinalization()
is the conventional
and convenient means of invoking this method.
Object.finalize()
public void traceInstructions(boolean on)
boolean
argument is true
, this
method suggests that the Java virtual machine emit debugging
information for each instruction in the virtual machine as it
is executed. The format of this information, and the file or other
output stream to which it is emitted, depends on the host environment.
The virtual machine may ignore this request if it does not support
this feature. The destination of the trace output is system
dependent.
If the boolean
argument is false
, this
method causes the virtual machine to stop performing the
detailed instruction trace it is performing.
on
- true
to enable instruction tracing;
false
to disable this feature.public void traceMethodCalls(boolean on)
boolean
argument is true
, this
method suggests that the Java virtual machine emit debugging
information for each method in the virtual machine as it is
called. The format of this information, and the file or other output
stream to which it is emitted, depends on the host environment. The
virtual machine may ignore this request if it does not support
this feature.
Calling this method with argument false suggests that the virtual machine cease emitting per-call debugging information.
on
- true
to enable instruction tracing;
false
to disable this feature.public void load(String filename)
java_g
it will automagically insert "_g" before the
".so" (for example
Runtime.getRuntime().load("/home/avh/lib/libX11.so");
).
First, if there is a security manager, its checkLink
method is called with the filename
as its argument.
This may result in a security exception.
This is similar to the method loadLibrary(String)
, but it
accepts a general file name as an argument rather than just a library
name, allowing any file of native code to be loaded.
The method System.load(String)
is the conventional and
convenient means of invoking this method.
filename
- the file to load.
SecurityException
- if a security manager exists and its
checkLink
method doesn't allow
loading of the specified dynamic library
UnsatisfiedLinkError
- if the file does not exist.getRuntime()
,
SecurityException
,
SecurityManager.checkLink(java.lang.String)
public void loadLibrary(String libname)
First, if there is a security manager, its checkLink
method is called with the libname
as its argument.
This may result in a security exception.
The method System.loadLibrary(String)
is the conventional
and convenient means of invoking this method. If native
methods are to be used in the implementation of a class, a standard
strategy is to put the native code in a library file (call it
LibFile
) and then to put a static initializer:
within the class declaration. When the class is loaded and initialized, the necessary native code implementation for the native methods will then be loaded as well.static { System.loadLibrary("LibFile"); }
If this method is called more than once with the same library name, the second and subsequent calls are ignored.
libname
- the name of the library.
SecurityException
- if a security manager exists and its
checkLink
method doesn't allow
loading of the specified dynamic library
UnsatisfiedLinkError
- if the library does not exist.SecurityException
,
SecurityManager.checkLink(java.lang.String)
public InputStream getLocalizedInputStream(InputStream in)
InputStreamReader
and BufferedReader
classes.
InputStream
and returns an InputStream
equivalent to the argument in all respects except that it is
localized: as characters in the local character set are read from
the stream, they are automatically converted from the local
character set to Unicode.
If the argument is already a localized stream, it may be returned as the result.
in
- InputStream to localize
InputStream
,
BufferedReader.BufferedReader(java.io.Reader)
,
InputStreamReader.InputStreamReader(java.io.InputStream)
public OutputStream getLocalizedOutputStream(OutputStream out)
OutputStreamWriter
, BufferedWriter
, and
PrintWriter
classes.
OutputStream
and returns an
OutputStream
equivalent to the argument in all respects
except that it is localized: as Unicode characters are written to
the stream, they are automatically converted to the local
character set.
If the argument is already a localized stream, it may be returned as the result.
out
- OutputStream to localize
OutputStream
,
BufferedWriter.BufferedWriter(java.io.Writer)
,
OutputStreamWriter.OutputStreamWriter(java.io.OutputStream)
,
PrintWriter.PrintWriter(java.io.OutputStream)
|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.