Synopsis

java [ interpreter-options ] classname [ program-arguments ]
java [ interpreter-options ] -jar jarfile [ program-arguments ]

Description

java is the Java byte-code interpreter; it runs Java programs. The program to be run is the class specified by classname. This must be a fully qualified name: it must include the package name of the class but not the .class file extension. For example:

% java david.games.Checkers
% java Test

The specified class must define a main( ) method with exactly the following signature:

public static void main(String[] args)

This method serves as the program entry point: the interpreter begins execution here.

In Java 1.2 and later, a program can be packaged in an executable JAR file. To run a program packaged in this fashion, use the -jar option to specify the JAR file. The manifest of an executable JAR file must contain a Main-Class attribute that specifies which class within the JAR file contains the main( ) method at which the interpreter is to begin execution.

Any command-line options that precede the name of the class or JAR file to execute are options to the Java interpreter itself. Any options that follow the class name or JAR filename are options to the program; they are ignored by the Java interpreter and passed as an array of strings to the main() method of the program.

The Java interpreter runs until the main( ) method exits, and any threads (except for threads marked as daemon threads) created by the program have also exited.

Interpreter versions

The java program is the basic version of the Java interpreter. In addition to this program, however, there are several other versions of the Java interpreter. Each of these versions is similar to java but has a specialized function. This list includes all the interpreter versions, including those that are no longer in use.

java

This is the basic version of the Java interpreter; it is usually the correct one to use.

javaw

This version of the interpreter is included only on Windows platforms. Use javaw when you want to run a Java program (from a script, for example) without forcing a console window to appear.

Client or Server VM

Sun's "HotSpot" virtual machine comes in two versions: one is tuned for use with short-lived client applications and one is for use with long-running server code. As of Java 1.4, you can select the server version of the VM with the -server option. You can specify the client VM (which is the default) with the -client option. In Java 5.0, the interpreter automatically enters server mode if it detects that it is running on "server-class" hardware (typically a computer with multiple CPUs).

Legacy interpreter versions

oldjava

This version of the interpreter was included in Java 1.2 and Java 1.3 for compatibility with the Java 1.1 interpreter. It loaded classes using the Java 1.1 class-loading scheme. Very few Java applications needed to use this version of the interpreter, and it was removed in Java 1.4.

oldjavaw

In Java 1.2 and 1.3, this version of the interpreter, included only on Windows platforms, combined the features of oldjava and javaw.

java_g

In Java 1.0 and Java 1.1, java_g was a debugging version of the Java interpreter. It included a few specialized command-line options. Windows platforms also had a javaw_g program. java_g is not included in Java 1.2 or later versions.

Classic VM

In Java 1.3, you could use the -classic option to specify that you wanted to use the "Classic VM" (essentially the same as the Java 1.2 VM) instead of the HotSpot VM (which uses incremental compilation). This option was removed in Java 1.4.

Just-in-time compiler

In Java 1.2 and Java 1.3 when you specified the -classic option, the Java interpreter used a just-in-time compiler (if one were available for your platform). A JIT converts Java byte codes to native machine instructions at runtime and significantly speeds up the execution of a typical Java program. If you do not want to use the JIT, you can disable it by setting the JAVA_COMPILER environment variable to "NONE" or the java.compiler system property to "NONE" using the -D option:

% setenv JAVA_COMPILER NONE                        // Unix csh syntax
% java -Djava.compiler=NONE MyProgram

If you want to use a different JIT compiler implementation, set the environment variable or system property to the name of the desired implementation. This environment variable and property are no longer used as of Java 1.4, which uses the HotSpot VM, which includes efficient JIT technology.

Threading systems

On Solaris and related Unix platforms, you had a choice of the type of threads used by the Java 1.2 interpreter and the "Classic VM" of Java 1.3. To use native OS threads, you could specify -native. To use nonnative, or green, threads (the default), you could specify -green. In Java 1.3, the default "Client VM" used native threads. Specifying -green or -native in Java 1.3 implicitly specified -classic as well. These options are no longer supported (or necessary) as of Java 1.4.

Common options

The following options are the most commonly used.

-classpath path

Specifies the directories and JAR files java searches when trying to load a class. In Java 1.2 and later, this option specifies only the location of application classes. In Java 1.0 and 1.1, and with the oldjava interpreter, this option specified the location of system classes, extension classes, and application classes.

-cp

A synonym for -classpath. Java 1.2 and later.

-D propertyname= value

Defines propertyname to equal value in the system properties list. Your Java program can then look up the specified value by its property name. You can specify any number of -D options. For example:

% java -Dawt.button.color=gray -Dmy.class.pointsize=14 my.class

-fullversion

Prints the full Java version string, including build number, and exits. Compare with -version.

-help, -?

Prints a usage message and exits. See also -X.

-jar jarfile

Runs the specified executable jarfile. The manifest of the specified jarfile must contain a Main-Class attribute that identifies the class with the main() method at which program execution is to begin. Java 1.2 and later.

-showversion

Works like the -version option, except that the interpreter continues running after printing the version information. Java 1.3 and later.

-version

Prints the version of the Java interpreter and exits.

-X

Displays usage information for the nonstandard interpreter options (those beginning with -X) and exits. See also -help. Java 1.2 and later.

-Xbootclasspath :path

Specifies a search path consisting of directories, ZIP files, and JAR files the java interpreter should use to look up system classes. Use of this option is very rare. Java 1.2 and later.

-Xbootclasspath/a :path

Appends the specified path to the system classpath. Java 1.3 and later.

-Xbootclasspath/p :path

Prepends the specified path to the system boot classpath. Java 1.3 and later.

Assertion options

The following options specify whether and where assertions are tested. These options were added in Java 1.4.

-disableassertions[ :where]

Disables assertions. It is new in Java 1.4 and can be abbreviated -da. Used alone, it disables all assertions (except those in the system classes), which is the default. To disable assertions in a single class, follow the option with a colon and the fully qualified class name. To disable assertions in an entire package (and all of its subpackages), follow this option with a colon, the name of the package, and three dots. See also -enableassertions and -disablesystemassertions.

-da[ :where]

Disables assertions. See -disableassertions.

-disablesystemassertions

Disables assertions in all system classes (which is the default). It can be abbreviated -dsa and takes no options.

-dsa

An abbreviation for -disablesystemassertions.

-enableassertions[ :where]

Enables assertions. This option can be abbreviated -ea. Used alone, it enables all assertions (except in system classes). To enable assertions in a single class, follow the option with a colon and the full class name. To enable assertions in an entire package (and its subpackages), follow the option with a colon, the package name, and three dots. See also -disableassertions and -enablesystemassertions.

-ea[ :where]

Enables assertions. An abbreviation for -enableassertions.

-enablesystemassertions

Enables assertions in all system classes. May be abbreviated -esa.

-esa

An abbreviation for -enablesystemassertions.

Performance tuning options

The following options select which version of the VM is to be run and fine-tune its memory allocation, garbage collection, and incremental compilation. Options beginning with -X are nonstandard and may change from release to release.

-classic

Runs the "Classic VM" instead of the default high-performance "Client VM." Java 1.3 only.

-client

Optimizes the incremental compilation of the HotSpot VM for typical client-side applications. This option typically defers some compilation to favor quicker application launch times. Java 1.4 and later. See also the -server option.

-d32

Runs in 32-bit mode. This option is valid in Java 1.4 and later but is currently implemented only for Solaris platforms.

-d64

Runs in 64-bit mode. This option is valid in Java 1.4 and later but is currently implemented only for Solaris platforms.

-green

Selects nonnative, or green, threads on operating systems such as Solaris and Linux that support multiple styles of threading. This is the default in Java 1.2. In Java 1.3, using this option also selects the -classic option. See also -native. Java 1.2 and 1.3 only.

-native

Selects native threads, instead of the default green threads, on operating systems such as Solaris that support multiple styles of threading. Using native threads can be advantageous in some circumstances, such as when running on a multi-CPU computer. In Java 1.3, the default HotSpot virtual machine uses native threads. Java 1.2 and 1.3 only.

-server

Optimizes the incremental compilation of the VM for server-class applications. In general, this option results in slower startup time but better subsequent performance. Java 1.4 and later. In Java 5.0 and later, many VMs automatically select this option if they are running on "server-class" hardware such as a dual-processor machine. See also -client.

-Xbatch

Tells the HotSpot VM to perform all just-in-time compilation in the foreground, regardless of the time required for compilation. Without this option, the VM compiles methods in the background while interpreting them in the foreground. Java 1.3 and later.

-Xincgc

Uses incremental garbage collection. In this mode, the garbage collector runs continuously in the background, and a running program is rarely, if ever, subject to noticeable pauses while garbage collection occurs. Using this option typically results in a 10% decrease in overall performance, however. Java 1.3 and later.

-Xint

Tells the HotSpot VM to operate in interpreted mode only, without performing any just-in-time compilation. Java 1.3 and later.

-Xmixed

Tells the HotSpot VM to perform just-in-time compilation on frequently used methods ("hotspots") and execute other methods in interpreted mode. This is the default behavior. Contrast with -Xbatch and -Xint. Java 1.3 and later.

-Xms initmem[k|m]

Specifies how much memory is allocated for the heap when the interpreter starts up. By default, initmem is specified in bytes. You can specify it in kilobytes by appending the letter k or in megabytes by appending the letter m. The default is 2 MB. For large or memory-intensive applications (such as the Java compiler), you can improve runtime performance by starting the interpreter with a larger amount of memory. You must specify an initial heap size of at least 1 MB. Java 1.2 and later. Prior to Java 1.2, use -ms.

-Xmx maxmem[k|m]

Specifies the maximum heap size the interpreter uses for dynamically allocated objects and arrays. maxmem is specified in bytes by default. You can specify maxmem in kilobytes by appending the letter k and in megabytes by appending the letter m. The default is 64 MB. You cannot specify a heap size less than 2 MB. Java 1.2 and later. Prior to Java 1.2, use -mx.

-Xnoclassgc

Does not garbage-collect classes. Java 1.2 and later. In Java 1.1, use -noclassgc.

-Xss size[k|m]

Sets the thread stack size in bytes, kilobytes, or megabytes. Java 1.3 and later.

Instrumentation options

The following options support debugging, profiling, and other VM instrumentation. Options beginning with -X are nonstandard and may change from release to release.

-agentlib :agent[=options]

New in Java 5.0, this option specifies a JVMTI agent, and options for it, to be started along with the interpeter. JVMTI is the Java Virtual Machine Tool Interface, and it is slated to supercede the JVMDI and JVMPI (debugging and profiling interfaces) in a future release. This means that the general -agentlib option will replace tool-specific options such as -Xdebug and -Xrunhprof. Examples:

% java -agentlib:hprof=help                
% java -agentlib:jdwp=help

-agentpath :path-to-agent[=options]

Like -agentlib, but with an explicitly specified path to the agent library. Java 5.0 and later.

-debug

Causes java to start up in a way that allows the jdb debugger to attach itself to the interpreter session. In Java 1.2 and later, this option has been replaced with -Xdebug.

-javaagent :jarfile[=options]

Load a Java-language instrumentation agent when the interpreter starts. The specified jarfile must have a manifest that includes an Agent-Class attribute. This attribute must name a class that includes the agent's premain() method. Any options will be passed to this premain( ) method along with a java.lang.instrument.Instrumentation object. See java.lang.instrument for further detail.

-verbose, -verbose:class

Prints a message each time java loads a class. In Java 1.2 and later, you can use -verbose:class as a synonym.

-verbose:gc

Prints a message when garbage collection occurs. Java 1.2 and later. Prior to Java 1.2, use -verbosegc.

-verbose:jni

Prints a message when native methods are called. Java 1.2 and later.

-Xcheck:jni

Performs additional validity checks when using Java Native Interface functions. Java 1.2 and later.

-Xdebug

Starts the interpreter in a way that allows a debugger to communicate with it. Java 1.2 and later. Prior to Java 1.2, use -debug. Deprecated in Java 5.0 in favor of the -agentlib option.

-Xfuture

Strictly checks the format of all class files loaded. Without this option, java performs the same checks that were performed in Java 1.1. Java 1.2 and later.

-Xloggc :filename

Logs garbage collection events with timestamps to the named file.

-Xprof

Prints profiling output to standard output. Java 1.3 and later. In Java 1.2, or when using the -classic option, use -Xrunhprof. Prior to Java 1.2, use -prof.

-Xrunhprof :suboptions

Turns on CPU, heap, or monitor profiling. suboptions is a comma-separated list of name=value pairs. Use -Xrunhprof:help for a list of supported options and values. Java 1.2 and later. Deprecated in Java 5.0 in favor of the -agentlib option.

Advanced options

The Java interpreter also supports quite a few advanced configuration options that begin with -XX. These options are release and platform-dependent, and Sun's documentation describes them as "not recommended for casual use." If you want to fine-tune the threading, memory allocation, garbage collection, signal-handling, or just-in-time compilation performance of a production application, however, you may be interested in them. See http://java.sun.com/docs/hotspot/.

Loading classes

The Java interpreter knows where to find the system classes that comprise the Java platform. In Java 1.2 and later, it also knows where to find the class files for all extensions installed in the system extensions directory. However, the interpreter must be told where to find the nonsystem classes that comprise the application to be run.

Class files are stored in a directory that corresponds to their package name. For example, the class com.davidflanagan.utils.Util is stored in a file com/davidflanagan/utils/Util.class. By default, the interpreter uses the current working directory as the root and looks for all classes in and beneath this directory.

The interpreter can also search for classes within ZIP and JAR files. To tell the interpreter where to look for classes, you specify a classpath: a list of directories and ZIP and JAR archives. When looking for a class, the interpreter searches each of the specified locations in the order in which they are specified.

The easiest way to specify a classpath is to set the CLASSPATH environment variable, which works much like the PATH variable used by a Unix shell or a Windows command-interpreter path. To specify a classpath in Unix, you might type a command like this:

% setenv CLASSPATH .:~/myclasses:/usr/lib/javautils.jar:/usr/lib/javaapps

On a Windows system, you might use a command like the following:

C:\> set CLASSPATH=.;c:\myclasses;c:\javatools\classes.zip;d:\javaapps

Note that Unix and Windows use different characters to separate directory and path components.

You can also specify a classpath with the -classpath or -cp options to the Java interpreter. A path specified with one of these options overrides any path specified by the CLASSPATH environment variable. In Java 1.2 and later, the -classpath option specifies only the search path for application and user classes. Prior to Java 1.2, or when using the oldjava interpreter, this option specified the search path for all classes, including system classes and extension classes.

See also

javac, jdb