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.
*
* @author unascribed
* @see java.lang.Runtime#getRuntime()
* @since JDK1.0
*/
public class Runtime {
private static Runtime currentRuntime = new Runtime();
/**
* Returns the runtime object associated with the current Java application.
* Most of the methods of class Runtime are instance
* methods and must be invoked with respect to the current runtime object.
*
* @return the Runtime object associated with the current
* Java application.
*/
public static Runtime getRuntime() {
return currentRuntime;
}
/** Don't let anyone else instantiate this class */
private Runtime() {}
/**
* 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 consists of two phases. In * the first phase all registered {@link #addShutdownHook 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 {@link #runFinalizersOnExit finalization-on-exit} * has been enabled. Once this is done the virtual machine {@link #halt * 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 {@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) */ public void exit(int status) { SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkExit(status); } Shutdown.exit(status); } /** * Registers a new virtual-machine shutdown hook. * *
The Java virtual machine shuts down in response to two kinds * of events: * *
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. Attempts to use other thread-based * services such as the AWT event-dispatch thread, for example, may lead to * deadlocks. * *
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 * 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.
* * @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 */ public void addShutdownHook(Thread hook) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new RuntimePermission("shutdownHooks")); } ApplicationShutdownHooks.add(hook); } /** * De-registers a previously-registered virtual-machine shutdown hook.
* * @param hook the hook to remove * @return true if the specified hook had previously been * registered and was successfully de-registered, false * otherwise. * * @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 #addShutdownHook * @see #exit(int) * @since 1.3 */ public boolean removeShutdownHook(Thread hook) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new RuntimePermission("shutdownHooks")); } return ApplicationShutdownHooks.remove(hook); } /** * Forcibly terminates the currently running Java virtual machine. This * method never returns normally. * *
This method should be used with extreme caution. Unlike the * {@link #exit 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.
* * @param status * Termination status. By convention, a nonzero status code * indicates abnormal termination. If the {@link Runtime#exit * exit} (equivalently, {@link System#exit(int) * System.exit}) method has already been invoked then this * status code will override the status code passed to that method. * * @throws SecurityException * If a security manager is present and its {@link * SecurityManager#checkExit checkExit} method does not permit * an exit with the specified status * * @see #exit * @see #addShutdownHook * @see #removeShutdownHook * @since 1.3 */ public void halt(int status) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkExit(status); } Shutdown.halt(status); } /** * Enable or disable finalization on exit; doing so specifies that the * finalizers of all objects that have finalizers that have not yet been * automatically invoked are to be run before the Java runtime exits. * By default, finalization on exit is disabled. * *
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.
*
* @param value true to enable finalization on exit, false to disable
* @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.
*
* @throws SecurityException
* if a security manager exists and its checkExit
* method doesn't allow the exit.
*
* @see java.lang.Runtime#exit(int)
* @see java.lang.Runtime#gc()
* @see java.lang.SecurityManager#checkExit(int)
* @since JDK1.1
*/
@Deprecated
public static void runFinalizersOnExit(boolean value) {
SecurityManager security = System.getSecurityManager();
if (security != null) {
try {
security.checkExit(0);
} catch (SecurityException e) {
throw new SecurityException("runFinalizersOnExit");
}
}
Shutdown.setRunFinalizersOnExit(value);
}
/**
* Executes the specified string command in a separate process.
*
*
This is a convenience method. An invocation of the form
* exec(command)
* behaves in exactly the same way as the invocation
* {@link #exec(String, String[], File) exec}(command, null, null).
*
* @param command a specified system command.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If command is null
*
* @throws IllegalArgumentException
* If command is empty
*
* @see #exec(String[], String[], File)
* @see ProcessBuilder
*/
public Process exec(String command) throws IOException {
return exec(command, null, null);
}
/**
* Executes the specified string command in a separate process with the
* specified environment.
*
*
This is a convenience method. An invocation of the form
* exec(command, envp)
* behaves in exactly the same way as the invocation
* {@link #exec(String, String[], File) exec}(command, envp, null).
*
* @param command a specified system command.
*
* @param envp array of strings, each element of which
* has environment variable settings in the format
* name=value, or
* null if the subprocess should inherit
* the environment of the current process.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If command is null,
* or one of the elements of envp is null
*
* @throws IllegalArgumentException
* If command is empty
*
* @see #exec(String[], String[], File)
* @see ProcessBuilder
*/
public Process exec(String command, String[] envp) throws IOException {
return exec(command, envp, null);
}
/**
* Executes the specified string command in a separate process with the
* specified environment and working directory.
*
*
This is a convenience method. An invocation of the form
* exec(command, envp, dir)
* behaves in exactly the same way as the invocation
* {@link #exec(String[], String[], File) exec}(cmdarray, envp, dir),
* where cmdarray is an array of all the tokens in
* command.
*
*
More precisely, the command string is broken
* into tokens using a {@link StringTokenizer} created by the call
* new {@link StringTokenizer}(command) with no
* further modification of the character categories. The tokens
* produced by the tokenizer are then placed in the new string
* array cmdarray, in the same order.
*
* @param command a specified system command.
*
* @param envp array of strings, each element of which
* has environment variable settings in the format
* name=value, or
* null if the subprocess should inherit
* the environment of the current process.
*
* @param dir the working directory of the subprocess, or
* null if the subprocess should inherit
* the working directory of the current process.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If command is null,
* or one of the elements of envp is null
*
* @throws IllegalArgumentException
* If command is empty
*
* @see ProcessBuilder
* @since 1.3
*/
public Process exec(String command, String[] envp, File dir)
throws IOException {
if (command.length() == 0)
throw new IllegalArgumentException("Empty command");
StringTokenizer st = new StringTokenizer(command);
String[] cmdarray = new String[st.countTokens()];
for (int i = 0; st.hasMoreTokens(); i++)
cmdarray[i] = st.nextToken();
return exec(cmdarray, envp, dir);
}
/**
* Executes the specified command and arguments in a separate process.
*
*
This is a convenience method. An invocation of the form
* exec(cmdarray)
* behaves in exactly the same way as the invocation
* {@link #exec(String[], String[], File) exec}(cmdarray, null, null).
*
* @param cmdarray array containing the command to call and
* its arguments.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If cmdarray is null,
* or one of the elements of cmdarray is null
*
* @throws IndexOutOfBoundsException
* If cmdarray is an empty array
* (has length 0)
*
* @see ProcessBuilder
*/
public Process exec(String cmdarray[]) throws IOException {
return exec(cmdarray, null, null);
}
/**
* Executes the specified command and arguments in a separate process
* with the specified environment.
*
*
This is a convenience method. An invocation of the form
* exec(cmdarray, envp)
* behaves in exactly the same way as the invocation
* {@link #exec(String[], String[], File) exec}(cmdarray, envp, null).
*
* @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 the format
* name=value, or
* null if the subprocess should inherit
* the environment of the current process.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If cmdarray is null,
* or one of the elements of cmdarray is null,
* or one of the elements of envp is null
*
* @throws IndexOutOfBoundsException
* If cmdarray is an empty array
* (has length 0)
*
* @see ProcessBuilder
*/
public Process exec(String[] cmdarray, String[] envp) throws IOException {
return exec(cmdarray, envp, null);
}
/**
* Executes the specified command and arguments in a separate process with
* the specified environment and working directory.
*
*
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.
*
*
This method checks that cmdarray is a valid operating
* system command. Which commands are valid is system-dependent,
* but at the very least the command must be a non-empty list of
* non-null strings.
*
*
If envp is null, the subprocess inherits the * environment settings of the current process. * *
A minimal set of system dependent environment variables may * be required to start a process on some operating systems. * As a result, the subprocess may inherit additional environment variable * settings beyond those in the specified environment. * *
{@link ProcessBuilder#start()} is now the preferred way to * start a process with a modified environment. * *
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. * *
If a security manager exists, its
* {@link SecurityManager#checkExec checkExec}
* method is invoked with the first component of the array
* cmdarray as its argument. This may result in a
* {@link SecurityException} being thrown.
*
*
Starting an operating system process is highly system-dependent. * Among the many things that can go wrong are: *
In such cases an exception will be thrown. The exact nature
* of the exception is system-dependent, but it will always be a
* subclass of {@link IOException}.
*
*
* @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 the format
* name=value, or
* null if the subprocess should inherit
* the environment of the current process.
*
* @param dir the working directory of the subprocess, or
* null if the subprocess should inherit
* the working directory of the current process.
*
* @return A new {@link Process} object for managing the subprocess
*
* @throws SecurityException
* If a security manager exists and its
* {@link SecurityManager#checkExec checkExec}
* method doesn't allow creation of the subprocess
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
* If cmdarray is null,
* or one of the elements of cmdarray is null,
* or one of the elements of envp is null
*
* @throws IndexOutOfBoundsException
* If cmdarray is an empty array
* (has length 0)
*
* @see ProcessBuilder
* @since 1.3
*/
public Process exec(String[] cmdarray, String[] envp, File dir)
throws IOException {
return new ProcessBuilder(cmdarray)
.environment(envp)
.directory(dir)
.start();
}
/**
* Returns the number of processors available to the Java virtual machine.
*
*
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.
* * @return the maximum number of processors available to the virtual * machine; never smaller than one * @since 1.4 */ public native int availableProcessors(); /** * Returns the amount of free memory in the Java Virtual Machine. * Calling the *gc method may result in increasing the value returned
* by freeMemory.
*
* @return an approximation to the total amount of memory currently
* available for future allocated objects, measured in bytes.
*/
public native long freeMemory();
/**
* Returns the total amount of memory in the Java virtual machine.
* 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. * * @return the total amount of memory currently available for current * and future objects, measured in bytes. */ public native long totalMemory(); /** * Returns the maximum amount of memory that the Java virtual machine will * attempt to use. If there is no inherent limit then the value {@link * java.lang.Long#MAX_VALUE} will be returned.
* * @return the maximum amount of memory that the virtual machine will * attempt to use, measured in bytes * @since 1.4 */ public native long maxMemory(); /** * Runs the garbage collector. * Calling this method suggests that the Java virtual machine expend * effort toward recycling unused objects in order to make the memory * they currently occupy available for quick reuse. When control * returns from the method call, the virtual machine has made * its best effort to recycle all discarded objects. *
* 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 {@link System#gc()} is the conventional and convenient
* means of invoking this method.
*/
public native void gc();
/* Wormhole for calling java.lang.ref.Finalizer.runFinalization */
private static native void runFinalization0();
/**
* Runs the finalization methods of any objects pending finalization.
* 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 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 {@link System#runFinalization()} is the conventional
* and convenient means of invoking this method.
*
* @see java.lang.Object#finalize()
*/
public void runFinalization() {
runFinalization0();
}
/**
* Enables/Disables tracing of instructions.
* If the 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.
*
* @param on true to enable instruction tracing;
* false to disable this feature.
*/
public native void traceInstructions(boolean on);
/**
* Enables/Disables tracing of method calls.
* If the 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.
*
* @param on true to enable instruction tracing;
* false to disable this feature.
*/
public native void traceMethodCalls(boolean on);
/**
* Loads the specified filename as a dynamic library. The filename
* argument must be a complete path name,
* (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 {@link #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 {@link System#load(String)} is the conventional and
* convenient means of invoking this method.
*
* @param filename the file to load.
* @exception SecurityException if a security manager exists and its
* checkLink method doesn't allow
* loading of the specified dynamic library
* @exception UnsatisfiedLinkError if the file does not exist.
* @exception NullPointerException if filename is
* null
* @see java.lang.Runtime#getRuntime()
* @see java.lang.SecurityException
* @see java.lang.SecurityManager#checkLink(java.lang.String)
*/
public void load(String filename) {
load0(System.getCallerClass(), filename);
}
synchronized void load0(Class fromClass, String filename) {
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkLink(filename);
}
if (!(new File(filename).isAbsolute())) {
throw new UnsatisfiedLinkError(
"Expecting an absolute path of the library: " + filename);
}
ClassLoader.loadLibrary(fromClass, filename, true);
}
/**
* Loads the dynamic library with the specified library name.
* 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. The
* mapping from a library name to a specific filename is done in a
* system-specific manner.
*
* 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 {@link 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:
*
* static { System.loadLibrary("LibFile"); }
*
* If this method is called more than once with the same library
* name, the second and subsequent calls are ignored.
*
* @param libname the name of the library.
* @exception SecurityException if a security manager exists and its
* checkLink method doesn't allow
* loading of the specified dynamic library
* @exception UnsatisfiedLinkError if the library does not exist.
* @exception NullPointerException if libname is
* null
* @see java.lang.SecurityException
* @see java.lang.SecurityManager#checkLink(java.lang.String)
*/
public void loadLibrary(String libname) {
loadLibrary0(System.getCallerClass(), libname);
}
synchronized void loadLibrary0(Class fromClass, String libname) {
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkLink(libname);
}
if (libname.indexOf((int)File.separatorChar) != -1) {
throw new UnsatisfiedLinkError(
"Directory separator should not appear in library name: " + libname);
}
ClassLoader.loadLibrary(fromClass, libname, false);
}
/**
* Creates a localized version of an input stream. This method takes
* an 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.
*
* @param in InputStream to localize
* @return a localized input stream
* @see java.io.InputStream
* @see java.io.BufferedReader#BufferedReader(java.io.Reader)
* @see java.io.InputStreamReader#InputStreamReader(java.io.InputStream)
* @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.
*/
@Deprecated
public InputStream getLocalizedInputStream(InputStream in) {
return in;
}
/**
* Creates a localized version of an output stream. This method
* takes an 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.
*
* @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.
*
* @param out OutputStream to localize
* @return a localized output stream
* @see java.io.OutputStream
* @see java.io.BufferedWriter#BufferedWriter(java.io.Writer)
* @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
* @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
*/
@Deprecated
public OutputStream getLocalizedOutputStream(OutputStream out) {
return out;
}
}