java.lang
Class Runtime

java.lang.Object
  extended by java.lang.Runtime

public class Runtime
extends Object

Runtime represents the Virtual Machine.


Method Summary
 void addShutdownHook(Thread hook)
          Register a new shutdown hook.
 int availableProcessors()
          Returns the number of available processors currently available to the virtual machine.
 Process exec(String cmdline)
          Create a new subprocess with the specified command line.
 Process exec(String[] cmd)
          Create a new subprocess with the specified command line, already tokenized.
 Process exec(String[] cmd, String[] env)
          Create a new subprocess with the specified command line, already tokenized, and specified environment.
 Process exec(String[] cmd, String[] env, File dir)
          Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory.
 Process exec(String cmdline, String[] env)
          Create a new subprocess with the specified command line and environment.
 Process exec(String cmdline, String[] env, File dir)
          Create a new subprocess with the specified command line, environment, and working directory.
 void exit(int status)
          Exit the Java runtime.
 long freeMemory()
          Find out how much memory is still free for allocating Objects on the heap.
 void gc()
          Run the garbage collector.
 InputStream getLocalizedInputStream(InputStream in)
          Deprecated. InputStreamReader is the preferred way to read local encodings
 OutputStream getLocalizedOutputStream(OutputStream out)
          Deprecated. OutputStreamWriter is the preferred way to write local encodings
static Runtime getRuntime()
          Get the current Runtime object for this JVM.
 void halt(int status)
          Forcibly terminate the virtual machine.
 void load(String filename)
          Load a native library using the system-dependent filename.
 void loadLibrary(String libname)
          Load a native library using a system-independent "short name" for the library.
 long maxMemory()
          Returns the maximum amount of memory the virtual machine can attempt to use.
 boolean removeShutdownHook(Thread hook)
          De-register a shutdown hook.
 void runFinalization()
          Run finalization on all Objects that are waiting to be finalized.
static void runFinalizersOnExit(boolean finalizeOnExit)
          Deprecated. never rely on finalizers to do a clean, thread-safe, mop-up from your code
 long totalMemory()
          Find out how much memory total is available on the heap for allocating Objects.
 void traceInstructions(boolean on)
          Tell the VM to trace every bytecode instruction that executes (print out a trace of it).
 void traceMethodCalls(boolean on)
          Tell the VM to trace every method call that executes (print out a trace of it).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getRuntime

public static Runtime getRuntime()
Get the current Runtime object for this JVM. This is necessary to access the many instance methods of this class.

Returns:
the current Runtime object

exit

public void exit(int status)
Exit the Java runtime. This method will either throw a SecurityException or it will never return. The status code is returned to the system; often a non-zero status code indicates an abnormal exit. Of course, there is a security check, checkExit(status).

First, all shutdown hooks are run, in unspecified order, and concurrently. Next, if finalization on exit has been enabled, all pending finalizers are run. Finally, the system calls halt.

If this is run a second time after shutdown has already started, there are two actions. If shutdown hooks are still executing, it blocks indefinitely. Otherwise, if the status is nonzero it halts immediately; if it is zero, it blocks indefinitely. This is typically called by System.exit.

Parameters:
status - the status to exit with
Throws:
SecurityException - if permission is denied
See Also:
addShutdownHook(Thread), runFinalizersOnExit(boolean), runFinalization(), halt(int)

addShutdownHook

public void addShutdownHook(Thread hook)
Register a new shutdown hook. This is invoked when the program exits normally (because all non-daemon threads ended, or because System.exit was invoked), or when the user terminates the virtual machine (such as by typing ^C, or logging off). There is a security check to add hooks, RuntimePermission("shutdownHooks").

The hook must be an initialized, but unstarted Thread. The threads are run concurrently, and started in an arbitrary order; and user threads or daemons may still be running. Once shutdown hooks have started, they must all complete, or else you must use halt, to actually finish the shutdown sequence. Attempts to modify hooks after shutdown has started result in IllegalStateExceptions.

It is imperative that you code shutdown hooks defensively, as you do not want to deadlock, and have no idea what other hooks will be running concurrently. It is also a good idea to finish quickly, as the virtual machine really wants to shut down!

There are no guarantees that such hooks will run, as there are ways to forcibly kill a process. But in such a drastic case, shutdown hooks would do little for you in the first place.

Parameters:
hook - an initialized, unstarted Thread
Throws:
IllegalArgumentException - if the hook is already registered or run
IllegalStateException - if the virtual machine is already in the shutdown sequence
SecurityException - if permission is denied
Since:
1.3
See Also:
removeShutdownHook(Thread), exit(int), halt(int)

removeShutdownHook

public boolean removeShutdownHook(Thread hook)
De-register a shutdown hook. As when you registered it, there is a security check to remove hooks, RuntimePermission("shutdownHooks").

Parameters:
hook - the hook to remove
Returns:
true if the hook was successfully removed, false if it was not registered in the first place
Throws:
IllegalStateException - if the virtual machine is already in the shutdown sequence
SecurityException - if permission is denied
Since:
1.3
See Also:
addShutdownHook(Thread), exit(int), halt(int)

halt

public void halt(int status)
Forcibly terminate the virtual machine. This call never returns. It is much more severe than exit, as it bypasses all shutdown hooks and initializers. Use caution in calling this! Of course, there is a security check, checkExit(status).

Parameters:
status - the status to exit with
Throws:
SecurityException - if permission is denied
Since:
1.3
See Also:
exit(int), addShutdownHook(Thread)

runFinalizersOnExit

public static void runFinalizersOnExit(boolean finalizeOnExit)
Deprecated. never rely on finalizers to do a clean, thread-safe, mop-up from your code

Tell the VM to run the finalize() method on every single Object before it exits. Note that the JVM may still exit abnormally and not perform this, so you still don't have a guarantee. And besides that, this is inherently unsafe in multi-threaded code, as it may result in deadlock as multiple threads compete to manipulate objects. This value defaults to false. There is a security check, checkExit(0).

Parameters:
finalizeOnExit - whether to finalize all Objects on exit
Throws:
SecurityException - if permission is denied
Since:
1.1
See Also:
exit(int), gc()

exec

public Process exec(String cmdline)
             throws IOException
Create a new subprocess with the specified command line. Calls exec(cmdline, null, null). A security check is performed, checkExec.

Parameters:
cmdline - the command to call
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmdline is null
IndexOutOfBoundsException - if cmdline is ""

exec

public Process exec(String cmdline,
                    String[] env)
             throws IOException
Create a new subprocess with the specified command line and environment. If the environment is null, the process inherits the environment of this process. Calls exec(cmdline, env, null). A security check is performed, checkExec.

Parameters:
cmdline - the command to call
env - the environment to use, in the format name=value
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmdline is null, or env has null entries
IndexOutOfBoundsException - if cmdline is ""

exec

public Process exec(String cmdline,
                    String[] env,
                    File dir)
             throws IOException
Create a new subprocess with the specified command line, environment, and working directory. If the environment is null, the process inherits the environment of this process. If the directory is null, the process uses the current working directory. This splits cmdline into an array, using the default StringTokenizer, then calls exec(cmdArray, env, dir). A security check is performed, checkExec.

Parameters:
cmdline - the command to call
env - the environment to use, in the format name=value
dir - the working directory to use
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmdline is null, or env has null entries
IndexOutOfBoundsException - if cmdline is ""
Since:
1.3

exec

public Process exec(String[] cmd)
             throws IOException
Create a new subprocess with the specified command line, already tokenized. Calls exec(cmd, null, null). A security check is performed, checkExec.

Parameters:
cmd - the command to call
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmd is null, or has null entries
IndexOutOfBoundsException - if cmd is length 0

exec

public Process exec(String[] cmd,
                    String[] env)
             throws IOException
Create a new subprocess with the specified command line, already tokenized, and specified environment. If the environment is null, the process inherits the environment of this process. Calls exec(cmd, env, null). A security check is performed, checkExec.

Parameters:
cmd - the command to call
env - the environment to use, in the format name=value
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmd is null, or cmd or env has null entries
IndexOutOfBoundsException - if cmd is length 0

exec

public Process exec(String[] cmd,
                    String[] env,
                    File dir)
             throws IOException
Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory. If the environment is null, the process inherits the environment of this process. If the directory is null, the process uses the current working directory. A security check is performed, checkExec.

Parameters:
cmd - the command to call
env - the environment to use, in the format name=value
dir - the working directory to use
Returns:
the Process object
Throws:
SecurityException - if permission is denied
IOException - if an I/O error occurs
NullPointerException - if cmd is null, or cmd or env has null entries
IndexOutOfBoundsException - if cmd is length 0
Since:
1.3

availableProcessors

public int availableProcessors()
Returns the number of available processors currently available to the virtual machine. This number may change over time; so a multi-processor program want to poll this to determine maximal resource usage.

Returns:
the number of processors available, at least 1

freeMemory

public long freeMemory()
Find out how much memory is still free for allocating Objects on the heap.

Returns:
the number of bytes of free memory for more Objects

totalMemory

public long totalMemory()
Find out how much memory total is available on the heap for allocating Objects.

Returns:
the total number of bytes of memory for Objects

maxMemory

public long maxMemory()
Returns the maximum amount of memory the virtual machine can attempt to use. This may be Long.MAX_VALUE if there is no inherent limit (or if you really do have a 8 exabyte memory!).

Returns:
the maximum number of bytes the virtual machine will attempt to allocate

gc

public void gc()
Run the garbage collector. This method is more of a suggestion than anything. All this method guarantees is that the garbage collector will have "done its best" by the time it returns. Notice that garbage collection takes place even without calling this method.


runFinalization

public void runFinalization()
Run finalization on all Objects that are waiting to be finalized. Again, a suggestion, though a stronger one than gc(). This calls the finalize method of all objects waiting to be collected.

See Also:
Object.finalize()

traceInstructions

public void traceInstructions(boolean on)
Tell the VM to trace every bytecode instruction that executes (print out a trace of it). No guarantees are made as to where it will be printed, and the VM is allowed to ignore this request.

Parameters:
on - whether to turn instruction tracing on

traceMethodCalls

public void traceMethodCalls(boolean on)
Tell the VM to trace every method call that executes (print out a trace of it). No guarantees are made as to where it will be printed, and the VM is allowed to ignore this request.

Parameters:
on - whether to turn method tracing on

load

public void load(String filename)
Load a native library using the system-dependent filename. This is similar to loadLibrary, except the only name mangling done is inserting "_g" before the final ".so" if the VM was invoked by the name "java_g". There may be a security check, of checkLink.

Parameters:
filename - the file to load
Throws:
SecurityException - if permission is denied
UnsatisfiedLinkError - if the library is not found

loadLibrary

public void loadLibrary(String libname)
Load a native library using a system-independent "short name" for the library. It will be transformed to a correct filename in a system-dependent manner (for example, in Windows, "mylib" will be turned into "mylib.dll"). This is done as follows: if the context that called load has a ClassLoader cl, then cl.findLibrary(libpath) is used to convert the name. If that result was null, or there was no class loader, this searches each directory of the system property java.library.path for a file named System.mapLibraryName(libname). There may be a security check, of checkLink.

Parameters:
libname - the library to load
Throws:
SecurityException - if permission is denied
UnsatisfiedLinkError - if the library is not found
See Also:
System.mapLibraryName(String), ClassLoader.findLibrary(String)

getLocalizedInputStream

public InputStream getLocalizedInputStream(InputStream in)
Deprecated. InputStreamReader is the preferred way to read local encodings

Return a localized version of this InputStream, meaning all characters are localized before they come out the other end.

Parameters:
in - the stream to localize
Returns:
the localized stream

getLocalizedOutputStream

public OutputStream getLocalizedOutputStream(OutputStream out)
Deprecated. OutputStreamWriter is the preferred way to write local encodings

Return a localized version of this OutputStream, meaning all characters are localized before they are sent to the other end.

Parameters:
out - the stream to localize
Returns:
the localized stream