20.16 The Class java.lang.Runtime

public class Runtime {
	public static Runtime getRuntime();
	public void exit(int status);
	public Process exec(String command)

		throws IOException, SecurityException;
	public Process exec(String command, String envp[])

		throws IOException, SecurityException;
	public Process exec(String cmdarray[])

		throws IOException, SecurityException;
	public Process exec(String cmdarray[], String envp[])

		throws IOException, SecurityException;
	public long totalMemory();
	public long freeMemory();
	public void gc();
	public void runFinalization();
	public void traceInstructions(boolean on);
	public void traceMethodCalls(boolean on);
	public void load(String filename)
		throws SecurityException, UnsatisfiedLinkError;
	public void loadLibrary(String libname)
		throws SecurityException, UnsatisfiedLinkError;
	public InputStream getLocalizedInputStream(InputStream in);
	public OutputStream

		getLocalizedOutputStream(OutputStream out);
}

20.16.1 public static Runtime getRuntime()

This method returns the current Runtime object. Most of the methods of class Runtime are instance methods and must be invoked with respect to the current runtime object.

20.16.2 public void exit(int status)
throws SecurityException

First, if there is a security manager, its checkExit method (§20.17.13) is called with the status value as its argument.

This method terminates the currently running Java Virtual Machine. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

This method never returns normally.

See also the method exit (§20.18.11) of class System, which is the conventional and convenient means of invoking this method.

20.16.3 public Process exec(String command)
throws IOException, SecurityException,
IndexOutOfBoundsException

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 (§21.10) created by the call:

new StringTokenizer(command)

with no further modification of the character categories.

This method behaves exactly as if it performs the call:

exec(command, null)

See §20.16.4.

20.16.4 public Process exec(String command, String envp[])
throws IOException, SecurityException,
IndexOutOfBoundsException

The command argument is parsed into tokens and then executed as a command in a separate process with an environment specified by envp. The token parsing is done by a StringTokenizer (§21.10) created by the call:

new StringTokenizer(command)

with no further modification of the character categories.

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 behaves exactly as if it performs the call:

exec(cmdarray, envp)

See §20.16.6.

20.16.5 public Process exec(String cmdarray[])
throws IOException, SecurityException,
NullPointerException, IndexOutOfBoundsException

The command specified by the tokens in cmdarray is executed as a command in a separate process.

This method behaves exactly as if it performs the call:

exec(cmdarray, null)

See §20.16.6.

20.16.6 public Process exec(String cmdarray[], String envp[])
throws IOException, SecurityException,
NullPointerException, IndexOutOfBoundsException

First, if there is a security manager, its checkExec method (§20.17.14) is called with the first component of the array cmdarray as its argument.

If cmdarray is null, a NullPointerException is thrown. If cmdarray is an empty array (has length 0), an IndexOutOfBoundsException is thrown.

Given an array of strings cmdarray, representing the tokens of a command line, and an array of strings envp, representing an "environment" that defines system properties, this method creates a new process in which to execute the specified command and returns a Process object (§20.15) representing the new process.

20.16.7 public long totalMemory()

The total amount of memory currently available for current and future created objects, measured in bytes, is returned. The value returned by this method may vary over time, depending on the host environment.

Note that the amount of memory required to hold an object of any given type may be implementation-dependent.

20.16.8 public long freeMemory()

An approximation to the total amount of memory currently available for future created objects, measured in bytes, is returned. This value is always less than the current value returned by the totalMemory method. Calling the gc method may increase the value returned by freeMemory.

20.16.9 public void gc()

Calling this method suggests that the Java Virtual Machine expend effort toward recycling discarded objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to recycle all discarded objects. (The name gc stands for "garbage collector.")

The Java runtime system will perform this recycling process automatically as needed, in a separate thread, if the gc method is not invoked explicitly.

See also the method gc (§20.18.12) of class System, which is the conventional and convenient means of invoking this method.

20.16.10 public void runFinalization()

Calling this method suggests that the Java Virtual Machine expend effort toward running the 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 Java Virtual Machine has made a best effort to complete all outstanding finalizations.

The Java runtime system will perform the finalization process automatically as needed, in a separate thread, if the runFinalization method is not invoked explicitly.

See also the method runFinalization (§20.18.13) of class System, which is the conventional and convenient means of invoking this method.

20.16.11 public void traceInstructions(boolean on)

Calling this method with argument true suggests that the Java Virtual Machine emit debugging information for every instruction it executes. The format of this information, and the file or other output stream to which it is emitted, depends on the host environment.

Calling this method with argument false suggests that the Java Virtual Machine cease emitting per-instruction debugging information.

20.16.12 public void traceMethodCalls(boolean on)

Calling this method with argument true suggests that the Java Virtual Machine emit debugging information for every method call it executes. The format of this information, and the file or other output stream to which it is emitted, depends on the host environment.

Calling this method with argument false suggests that the Java Virtual Machine cease emitting per-call debugging information.

20.16.13 public void loadLibrary(String libname)

First, if there is a security manager, its checkLink method (§20.17.17) is called with the libname as its argument.

A file containing native code is loaded from the local file system from a place where library files are conventionally obtained. The details of this process are implementation-dependent.

See also the method loadLibrary (§20.18.15) of class System, which 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:

static { System.loadLibrary("LibFile"); }

within the class declaration. When the class is loaded and initialized (§12.4), the necessary native code implementation for the native methods will then be loaded as well.

20.16.14 public void load(String filename)

First, if there is a security manager, its checkLink method (§20.17.17) is called with the filename as its argument.

This is similar to the method loadLibrary (§20.16.13), but accepts a general file name as an argument rather than just a library name, allowing any file of native code to be loaded.

See also the method load (§20.18.14) of class System, which is the conventional and convenient means of invoking this method.

20.16.15 public InputStream
getLocalizedInputStream(InputStream in)

This method takes an InputStream (§22.3) and returns an InputStream equivalent to the argument in all respects except that it is localized: as data is read from the stream, it is automatically converted from the local format to Unicode. If the argument is already a localized stream, then it will be returned as the result.

20.16.16 public OutputStream
getLocalizedOutputStream(OutputStream out)

This method takes an OutputStream (§22.15) and returns an OutputStream equivalent to the argument in all respects except that it is localized: as data is written to the stream, it is automatically converted from Unicode to the local format. If the argument is already a localized stream, then it will be returned as the result.