java - The Java Interpreter

java interprets (executes) Java bytecodes.

SYNOPSIS

java [ options ] classname <args>
java [ options ] -jar jarfile <args>
java_g [ options ] classname <args>
java_g [ options ] -jar jarfile <args>
javaw [ options ] classname <args>
javaw [ options ] -jar jarfile <args>
javaw_g [ options ] classname <args>
javaw_g [ options ] -jar jarfile <args>

DESCRIPTION

The java command is a simple command-line interface for the Java Virtual Machine. java executes compiled Java bytecodes in the specified class. The specified class must have a method with this signature: 

    public static void main(String[])

java initiates execution by loading classname and calling its main() method.

Typically, the compiled class is in a .class file produced by a java compiler, such as javac. For example if the file MyClass.class contains class MyClass, then this command: 

    C:\> java MyClass
loads MyClass from MyClass.class and calls MyClass.main(). Any additional command line arguments are passed to main().

The specific behavior of java depends on the CLASSPATH environment variable. The .class file can be in any directory, ZIP archive, or JAR archive mentioned in CLASSPATH. (Archives must not use compression.) Note that java won't search the current directory unless the current directory is in CLASSPATH.

If CLASSPATH is properly set and java still can't find classname, use a fully-qualified class name. For example: 

    C:\> java COM.MyCompany.MyPackage.MyClass

The virtual machine also uses CLASSPATH to resolve any class references in the Java code.

java also supports the execution of complete Java programs encapsulated in JAR archives. See the -jar option.

The interpreter can determine whether a class is legitimate through the mechanism of verification. Verification ensures prior to their execution that class files do not violate any language constraints.

On WIN32 platforms, java has three variants:

java_g
A non-optimized version suitable for use with debuggers.

javaw
A version that creates a special console window for the standard output.

javaw_g
A debug version of javaw.

OPTIONS
The Java Interpreter has a set of standard options that are supported on the current Java Virtual Machine (VM) and will be supported on future VMs. In addition, there is a set of non-standard options that are supported on the current VM, but are subject to change in future VMs. The non-standard options begin with -X.



Standard Options

-classpath path
Specifies the path java uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by colons. Thus the general format for path is: 
   .:<your_path>
For example: 
   C:\xyz\classes;C:\usr\local\java\classes

-version
Print the build version information.

-help
Print a usage message.

-v, -verbose
Causes java to print a message to stdout each time a class file is loaded.

-verbosegc
Causes the garbage collector to print out messages whenever it frees memory.

-verbosejni
Prints JNI-related messages including information about which native methods have been linked and warnings about excessive creation of local references.

-DpropertyName=newValue
Redefines a property value. propertyName is the name of the property whose value you want to change and newValue is the value to change it to. For example, this command line 
   % java -Dawt.button.color=green ...
sets the value of the property awt.button.color to "green". java accepts any number of -D options on the command line.

-jar  jarfile
Execute a Java program encapsulated in jarfile. Instead of referring to the command line, java gets the initial class from the jarfile manifest header Main-Class. For example, if the program entry point is COM.MyCompany.MyPackage.MyClass.main(), then this entry must appear in the manifest: 
    Main-Class: COM.MyCompany.MyPackage.MyClass

IMPORTANT NOTE: The -jar option was not implemented in time to include it the JDK 1.2 Beta 2 release. This will be fixed in a later release. As a temporary workaround, use the sun.misc.Launcher class. The argument refering to this class must precede all other arguments, including options. For example: 

java sun.misc.Launcher -verbosejni -jar myprogram.jar

Note that sun.misc.Launcher is an unsupported class and not part of the standard Java API. Do not rely on sun.misc.Launcher being available or supporting the same usage in future releases.

-X
Prints help on non-standard options and exits.



Non-Standard Options

-Xdebug
Allows the Java debugger, jdb, to attach itself to this java session. When -Xdebug is specified on the command line java displays a password which must be used when starting the debugging session.

-Xmx x
Sets the maximum size of the memory allocation pool (the garbage collected heap) to x. The default is 16 megabytes of memory. x must be greater than or equal to 1000 bytes. The maximum memory size must be greater than or equal to the startup memory size (specified with the -Xms option, default 16 megabytes).

By default, x is measured in bytes. You can specify x in either kilobytes or megabytes by appending the letter "k" for kilobytes or the letter "m" for megabytes.

-Xms x
Sets the startup size of the memory allocation pool (the garbage collected heap) to x. The default is 1 megabyte of memory. x must be > 1000 bytes. The startup memory size must be less than or equal to the maximum memory size (specified with the -Xmx option, default 16 megabytes).

By default, x is measured in bytes. You can specify x in either kilobytes or megabytes by appending the letter "k" for kilobytes or the letter "m" for megabytes.

-Xnoasyncgc
Turns off asynchronous garbage collection. When activated no garbage collection takes place unless it is explicitly called or the program runs out of memory. Normally garbage collection runs as an asynchronous thread in parallel with other threads.

-Xnoclassgc
Turns off garbage collection of Java classes. By default, the Java interpreter reclaims space for unused Java classes during garbage collection.

-Xprof
Starts the Java Runtime with Java profiling enabled. By default, this puts profile results in the file .\java.prof.

-Xprof:   file
Starts the Java Runtime with Java profiling enabled. This form of the flag allows the user to specify a different output file for the profile information. For example, the flag -Xprof:myprog.prof enables profiling and puts the profile results in the file myprog.prof rather than in the default file .\java.prof.

-Xhprof[:file=<file>,depth=<n>,top=<n>,sort=a|l]
Outputs heap profiling data.
file=<file> specify output file (default is .\heap.prof).
depth=<n> limit the stack trace to n (default is 5).
top=<n> print the top n allocation sites (default is 20).
sort=<a|l> sort the output based on the number of allocation (a) or the number of live objects (l) (default is "a").

-Xss x
Each Java thread has two stacks: one for Java code and one for C code. The -Xss option sets the maximum stack size that can be used by C code in a thread to x. Every thread that is spawned during the execution of the program passed to java has x as its C stack size. The default units for x are bytes. The value of x must be greater than or equal to 1000 bytes.

You can modify the meaning of x by appending either the letter "k" for kilobytes or the letter "m" for megabytes. The default stack size is 128 kilobytes ("-Xss 128k").

-Xoss x
Each Java thread has two stacks: one for Java code and one for C code. The -Xoss option sets the maximum stack size that can be used by Java code in a thread to x. Every thread that is spawned during the execution of the program passed to java has x as its Java stack size. The default units for x are bytes. The value of x must be greater than or equal to 1000 bytes.

You can modify the meaning of x by appending either the letter "k" for kilobytes or the letter "m" for megabytes. The default stack size is 400 kilobytes ("-Xoss 400k").

-Xverify
Performs byte-code verification on the class file. Beware, however, that java -Xverify does not perform a full verification in all situations. Any code path that is not actually executed by the interpreter is not verified. Therefore, java -Xverify cannot be relied upon to certify class files unless all code paths in the class file are actually run.

-Xverifyremote
Runs the verifier on all code that is loaded into the system via a classloader. Xverifyremote is the default for the interpreter.

-Xnoverify
Turns verification off.

ENVIRONMENT VARIABLES

CLASSPATH
Used to provide the system a path to user-defined classes. Directories are separated by semicolons. For example: 
   C:\xyz\classes;C:\usr\local\java\classes
CLASSPATH
A colon-separated list of locations to search for classes. Each entry is a file directory, a ZIP archive, or JAR archive. The following example searches the current directory, a private classes directory, a public JAR archive, and a public ZIP archive. 

.:c:\home\me\classes:c:\usr\local\java\classes.jar:c:\usr\local\browser\java.zip

SEE ALSO

javac, jdb, javah, javap, javadoc, CLASSPATH