20.18 The Class java.lang.System

The System class contains a number of useful class variables and class methods. It cannot be instantiated. Among the facilities provided by the System class are standard input, output, and error output streams; access to externally defined "properties"; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.

public final class System {
	public static InputStream in;
	public static PrintStream out;
	public static PrintStream err;
	public static SecurityManager getSecurityManager();
	public static void setSecurityManager(SecurityManager s)
		throws SecurityException;
	public static long currentTimeMillis();
	public static Properties getProperties()
		throws SecurityException;
	public static void setProperties(Properties props)
		throws SecurityException;
	public static String getProperty(String key)
		throws SecurityException;
	public static String getProperty(String key, String default)
		throws SecurityException;
	public static void exit(int status) throws SecurityException;
	public static void gc();
	public static void runFinalization();
	public static void load(String filename)
		throws SecurityException, UnsatisfiedLinkError;
	public static void loadLibrary(String libname)
		throws SecurityException, UnsatisfiedLinkError;
	public static void arraycopy(Object src, int srcOffset,
			Object dst, int dstOffset, int length)

		throws NullPointerException,
			ArrayStoreException, IndexOutOfBoundsException;
}

20.18.1 public static InputStream in;

The initial value of this variable is a "standard" input stream, already open and ready to supply input data. Typically, this corresponds to keyboard input or another input source specified by the host environment or user. Note that this field is not final, so its value may be updated if necessary.

20.18.2 public static PrintStream out;

The initial value of this variable is a "standard" output stream, already open and ready to accept output data. Typically, this corresponds to display output or another output destination specified by the host environment or user. Note that this field is not final, so its value may be updated if necessary.

For simple Java applications, a typical way to write a line of output data is:

System.out.println(data)

See the println method of class PrintStream (§22.22).

20.18.3 public static PrintStream err;

The initial value of this variable is a "standard" error output stream, already open and ready to accept output data. Typically, this corresponds to display output or another output destination specified by the host environment or user. By convention, this output stream is used to display error messages or other information that should come to the immediate attention of a user even if the principal output stream, the value of the variable out, has been redirected to a file or other destination that is typically not continuously monitored. Note that this field is not final, so its value may be updated if necessary.

20.18.4 public static SecurityManager getSecurityManager()

If a security manager has already been established for the currently running Java system, a reference to that security manager is returned. Otherwise, null is returned.

20.18.5 public static void setSecurityManager(SecurityManager s) throws SecurityException

If a security manager has already been established for the currently running Java system, a SecurityException is thrown. Otherwise, the argument is established as the current security manager. If the argument is null and no security manager has been established, then no action is taken and the method simply returns normally.

20.18.6 public static long currentTimeMillis()

Returns the difference, measured in milliseconds, between the current time and the standard base time known as "the epoch," 00:00:00 GMT on January 1, 1970. See the description of the class Date (§21.3) for a discussion of slight discrepancies that may arise between "computer time" and UTC (Coordinated Universal Time).

20.18.7 public static Properties getProperties() throws SecurityException

First, if there is a security manager, its checkPropertiesAccess method (§20.17.15) is called with no arguments.

The current set of system properties for use by the getProperty method is returned as a Properties object (§21.6). If there is no current set of system properties, a set of system properties is first created and initialized. This set of system properties always includes values for the following keys:

Key							Description of associated value
java.version							Java version number
java.vendor							Java-vendor-specific string
java.vendor.url							Java vendor URL
java.home							Java installation directory
java.class.version							Java class format version number
java.class.path							Java classpath
os.name							Operating system name
os.arch							Operating system architecture
os.version							Operating system version
file.separator							File separator (/ on UNIX)
path.separator							Path separator (: on UNIX)
line.separator							Line separator (\n on UNIX)
user.name							User account name
user.home							User home directory
user.dir							User's current working directory

Note that even if the security manager does not permit the getProperties operation, it may choose to permit the getProperty operation (§20.18.9).

20.18.8 public static void setProperties(Properties props) throws SecurityException

First, if there is a security manager, its checkPropertiesAccess method (§20.17.15) is called with no arguments.

The argument becomes the current set of system properties for use by the getProperty method. See the class Properties (§21.6). If the argument is null, then the current set of system properties is forgotten.

20.18.9 public static String getProperty(String key) throws SecurityException

First, if there is a security manager, its checkPropertyAccess method (§20.17.16) is called with the key as its argument.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method (§20.18.7).

The system property value associated with the specified key string is returned. If there is no property with that key, then null is returned.

20.18.10 public static String getProperty(String key, String default) throws SecurityException

First, if there is a security manager, its checkPropertyAccess method (§20.17.16) is called with the key as its argument.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method (§20.18.7).

The system property value associated with the specified key string is returned. If there is no property with that key, then the argument default is returned.

20.18.11 public static void exit(int status) throws SecurityException

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.

The call System.exit(n) is effectively equivalent to the call:

Runtime.getRuntime().exit(n)

For a more complete description, see the exit method of class Runtime (§20.16.2).

20.18.12 public static 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 call System.gc() is effectively equivalent to the call:

Runtime.getRuntime().gc()

For a more complete description, see the gc method of class Runtime (§20.16.9).

20.18.13 public static void runFinalization()

Calling this method suggests that the Java Virtual Machine expend effort toward running the finalization methods of objects that have been found to be discarded but whose finalization 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 call System.runFinalization() is effectively equivalent to the call:

Runtime.getRuntime().runFinalization()

For a more complete description, see the runFinalization method of class Runtime (§20.16.10).

20.18.14 public static void load(String filename) throws SecurityException, UnsatisfiedLinkError

This method loads a code file with the specified file name from the local file system.

The call System.load(name) is effectively equivalent to the call:

Runtime.getRuntime().load(name)

For a more complete description, see the load method of class Runtime (§20.16.14).

20.18.15 public static void loadLibrary(String libname) throws SecurityException, UnsatisfiedLinkError

This method loads a library code file with the specified library name from the local file system.

The call System.loadLibrary(name) is effectively equivalent to the call

Runtime.getRuntime().loadLibrary(name)

For a more complete description, see the loadLibrary method of class Runtime (§20.16.13).

20.18.16 public static void arraycopy(Object src, int srcOffset, Object dst, int dstOffset, int length) throws NullPointerException, ArrayStoreException, IndexOutOfBoundsException

A subsequence of array components is copied from the source array referenced by src to the destination array referenced by dst. The number of components copied is equal to the length argument. The components at the positions srcOffset through srcOffset+length-1 in the source array are copied into the positions dstOffset through dstOffset+length-1, respectively, of the destination array.

If the src and dst arguments refer to the same array object, then copying is performed as if the components of the source array at positions srcOffset through srcOffset+length-1 were first copied to a temporary array of length length and then the contents of the temporary array were copied into positions dstOffset through dstOffset+length-1 of the destination array.

If dst is null, then a NullPointerException is thrown.

If src is null, then a NullPointerException is thrown and the destination array is not modified.

Otherwise, if any of the following is true, then an ArrayStoreException is thrown and the destination is not modified:

The src argument refers to an object that is not an array.
The dst argument refers to an object that is not an array.
The src argument and dst argument refer to arrays whose component types are different primitive types.
The src argument refers to an array of primitive component type and the dst argument refers to an array of reference component type.
The src argument refers to an array of reference component type and the dst argument refers to an array of primitive component type.

Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

The srcOffset argument is negative.
The dstOffset argument is negative.
The length argument is negative.
srcOffset+length is greater than src.length, the length of the src array.
dstOffset+length is greater than dst.length, the length of the dst array.

Otherwise, if the actual value of any component of the source array from position srcOffset through srcOffset+length-1 cannot be converted to the component type of the destination array by assignment conversion, then an ArrayStoreException is thrown. In this case, let k be the smallest nonnegative integer less than length such that src[srcOffset+k] cannot be converted to the component type of the destination array. When the exception is thrown, the source array components from positions srcOffset through srcOffset+k-1 have been copied to destination array positions dstOffset through dstOffset+k-1 and no other positions of the destination array will have been modified. (Because of the restrictions already itemized, this paragraph effectively applies only to the situation where both arrays have component types that are reference types.)