java.lang

Class 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 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.
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.
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) Return a localized version of this InputStream, meaning all characters are localized before they come out the other end.
OutputStream	getLocalizedOutputStream(OutputStream out) Return a localized version of this OutputStream, meaning all characters are localized before they are sent to the other end.
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) Tell the VM to run the finalize() method on every single Object before it exits.
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).

Method Detail

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

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

exec

public Process exec(String cmdline)

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)

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)

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)

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)

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)

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

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

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

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.

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

UNKNOWN: This implementation does not localize, yet.

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

UNKNOWN: This implementation does not localize, yet.

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

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

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.

The library is loaded using the class loader associated with the class associated with the invoking method.

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.

Note: Besides java.library.path a VM may chose to search for native libraries in a path that is specified by the gnu.classpath.boot.library.path system property. However this is for internal usage or development of GNU Classpath only. A Java application must not load a non-system library by changing this property otherwise it will break compatibility.

The library is loaded using the class loader associated with the class associated with the invoking method.

Parameters: libname the library to load

Throws: SecurityException if permission is denied UnsatisfiedLinkError if the library is not found

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

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

runFinalization

public void runFinalization()

Run finalization on all Objects that are waiting to be finalized. Again, a suggestion, though a stronger one than {@link #gc()}. This calls the finalize method of all objects waiting to be collected.

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

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

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