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
|