This appendix is a reprint of the JDK Tools Reference documentation written by Sun Microsystems. The material is unaltered from the documentation version and is a copyright of Sun Microsystems, Inc. Reprinted with permission.
javac is the program that compiles Java source code into byte-code format.
javac [ options ] filename.java ...
javac_g [ options ] filename.java ...
The javac command compiles Java source code into Java bytecodes. You then use the Java interpreter-the java command-to interpret the Java bytecodes.
Java source code must be contained in files whose filenames end with the .java extension. For every class defined in the source files passed to javac, the compiler stores the resulting bytecodes in a file named classname.class. The compiler places the resulting .class files in the same directory as the corresponding .java file (unless you specify the -d option).
When you define your own classes you need to specify their location. Use CLASSPATH to do this. CLASSPATH consists of a semicolon-separated list of directories that specifies the path. If the source files passed to javac reference a class not defined in any of the other files passed to javac, then javac searches for the referenced class using the class path. For example:
.;C:\users\dac\classes
Note that the system always appends the location of the system classes onto the end of the class path unless you use the -classpath option to specify a path.
javac_g is a non-optimized version of javac suitable for use with debuggers like jdb.
Specifies the path javac uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by semicolons. Thus the general format for a path is as follows:
.;<your_path>
For example:
.;C:\users\dac\classes;C:\tools\java\classes
Specifies the root directory of the class hierarchy. Thus doing:
javac -d <my_dir> MyProgram.java
causes the .class files for the classes in the MyProgram.java source file to be saved in the directory my_dir.
Enables generation of debugging tables. Debugging tables contain information about line numbers and local variables-information used by Java debugging tools. By default, only line numbers are generated, unless optimization (-O) is turned on.
Turns off warnings. If used, the compiler does not print out any warnings.
Optimizes compiled code by inlining static, final, and private methods. Note that your classes may get larger in size.
Causes the compiler and linker to print out messages about what source files are being compiled and what class files are being loaded.
Used to provide the system a path to user-defined classes. Directories are separated by semi-colons, for example:
.;C:\users\dac\classes;C:\tools\java\classes
java, jdb, javah, javap, javadoc
java interprets (executes) Java bytecodes.
java [ options ] classname <args>
java_g [ options ] classname <args>
The java command executes Java bytecodes created by the Java compiler-javac.
The classname argument is the name of the class to be executed. classname must be fully qualified by including its package in the name, for example:
java java.lang.String
Note that any arguments that appear after classname on the command line are passed to the class's main() method.
java expects the bytecodes for the class to be in a file called classname.class which is generated by compiling the corresponding source file with javac. All Java bytecode files end with the filename extension .class which the compiler automatically adds when the class is compiled. classname must contain a main() method defined as follows:
class Aclass
{
public static void
main( String argv[] )
{
. . .
}
}
java executes the main() method and then exits unless main() creates one or more threads. If any threads are created by main() then java doesn't exit until the last thread exits.
When you define your own classes you need to specify their location. Use CLASSPATH to do this. CLASSPATH consists of a semicolon-separated list of directories that specifies the path. For example:
.;C:\users\dac\classes
Note that the system always appends the location of the system classes onto the end of the class path unless you use the -classpath option to specify a path.
Ordinarily, you compile source files with javac then run the program using java. However, java can be used to compile and run programs when the -cs option is used. As each class is loaded, its modification date is compared to the modification date of the class source file. If the source has been modified more recently, it is recompiled and the new bytecode file is loaded. java repeats this procedure until all the classes are correctly compiled and loaded.
The interpreter can determine whether a class is legitimate through the mechanism of verification. Verification ensures that the bytecodes being interpreted do not violate any language constraints.
java_g is a non-optimized version of java suitable for use with debuggers like jdb.
Allows the Java debugger-jdb -to attach itself to this java session. When -debug is specified on the command line java displays a password which must be used when starting the debugging session.
When a compiled class is loaded, this option causes the modification time of the class bytecode file to be compared to that of the class source file. If the source has been modified more recently, it is recompiled and the new bytecode file is loaded.
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 a path is:
.;<your_path>
For example:
.;C:\users\dac\classes;C:\tools\java\classes
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 > 1000 bytes.
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.
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.
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.
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.
Each Java thread has two stacks: one for Java code and one for C code. The -ss 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. x must be > 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 (-ss 128k).
Each Java thread has two stacks: one for Java code and one for C code. The -oss 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. x must be > 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 (-oss 400k).
Prints a trace of the instructions executed (java_g only).
Causes java to print a message to stdout each time a class file is loaded.
Runs the verifier on all code.
Runs the verifier on all code that is loaded into the system via a classloader. verifyremote is the default for the interpreter.
Turns verification off.
Causes the garbage collector to print out messages whenever it frees memory.
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.
jdb helps you find and fix bugs in Java language programs.
jdb [ options ]
The Java Debugger, jdb, is a dbx-like command-line debugger for Java classes. It uses the Java Debugger to provide inspection and debugging of a local or remote Java interpreter.
Like dbx, there are two ways jdb can be used for debugging. The most frequently used way is have jdb start the Java interpreter with the class to be debugged. This is done by substituting the command jdb for java in the command line. For example, to start HotJava under jdb, you use the following:
C:\> jdb browser.hotjava
or
C:\> jdb -classpath %INSTALL_DIR%\classes -ms4m browser.hotjava
When started this way, jdb invokes a second Java interpreter with any specified parameters, loads the specified class, and stops before executing that class's first instruction.
The second way to use jdb is by attaching it to a Java interpreter that is already running. For security reasons, Java interpreters can only be debugged if they have been started with the -debug option. When started with the -debug option, the Java interpreter prints out a password for jdb's use.
To attach jdb to a running Java interpreter (once the session password is known), invoke it as follows:
C:\> jdb -host <hostname> -password <password>
The following is a list of the basic jdb
commands. The Java Debugger supports other commands which you
can list using jdb's help
command.
| Note |
To browse local (stack) variables, the class must have been compiled with the -g option. |
The most important jdb command, help displays the list of recognized commands with a brief description.
Browses Java objects. The print command calls the object's toString() method, so it will be formatted differently depending on its class.
Classes are specified by either their object ID or by name. If a class is already loaded, a substring can be used, such as Thread for java.lang.Thread. If a class isn't loaded, its full name must be specified, and the class will be loaded as a side effect. This is needed to set breakpoints in referenced classes before an applet runs.
print supports Java expressions, such as print MyClass.clsVar. Method invocation will not be supported in the 1.0 release, however, as the compiler needs to be enhanced first.
Dumps an object's instance variables. Objects are specified by their object ID (a hexadecimal integer).
Classes are specified by either their object ID or by name. If a class is already loaded, a substring can be used, such as Thread for java.lang.Thread. If a class isn't loaded, its full name must be specified, and the class will be loaded as a side effect. This is needed to set breakpoints in referenced classes before an applet runs.
The dump command supports Java expressions such as dump 0x12345678.myCache[3].foo. Method invocation will not be supported in the 1.0 release, however, because the compiler needs to be enhanced first.
Lists the current threads. This lists all threads in the default threadgroup, which is normally the first non-system group. (The threadgroups command lists all threadgroups.) Threads are referenced by their object ID, or if they are in the default thread group, with the form t@<index>, such as t@3.
Dumps the stack of either a specified thread, or the current thread (which is set with the thread command). If that thread is suspended (either because it's at a breakpoint or via the suspend command), local (stack) and instance variables can be browsed with the print and dump commands. The up and down commands select which stack frame is current.
Breakpoints are set in jdb in classes, such as "stop at MyClass:45". The source file line number must be specified, or the name of the method (the breakpoint will then be set at the first instruction of that method). The clear command removes breakpoints using a similar syntax, while the cont command continues execution.
Single-stepping is not currently implemented, but is hoped to be available for version 1.0.
When an exception occurs for which there isn't a catch statement anywhere up a Java program's stack, the Java runtime normally dumps an exception trace and exits. When running under jdb, however, that exception is treated as a non-recoverable breakpoint, and jdb stops at the offending instruction. If that class was compiled with the -g option, instance and local variables can be printed to determine the cause of the exception.
Specific exceptions may be optionally debugged with the catch command, for example:
catch FileNotFoundException
or
catch mypackage.BigTroubleException.
The Java debugging facility keeps a list of these exceptions,
and when one is thrown, it is treated as if a breakpoint was set
on the instruction which caused the exception. The ignore
command removes exception classes from this list.
| Note |
The ignore command does not cause the Java interpreter to ignore specific exceptions, only the debugger. |
When you use jdb in place of the Java interpreter on the command line, jdb accepts the same options as the java command.
When you use jdb to attach to a running Java interpreter session, jdb accepts these options:
-host <hostname>
Sets the name of the host machine on which the interpreter session to attach to is running.
-password <password>
Logs in to the active interpreter session. This is the password the Java interpreter prints out when invoked with the -debug option.
javah produces C header files and C source files from a Java class. These files provide the connective glue that allows your Java and C code to interact.
javah [ options ] classname. . .
javah_g [ options ] classname. . .
javah generates C header and source files that are needed to implement native methods. The generated header and source files are used by C programs to reference an object's instance variables from native source code. The .h file contains a struct definition whose layout parallels the layout of the corresponding class. The fields in the struct correspond to instance variables in the class.
The name of the header file and the structure declared within it are derived from the name of the class. If the class passed to javah is inside a package, the package name is prepended to both the header filename and the structure name. Underscores (_) are used as name delimiters.
By default javah creates a header file for each class listed on the command line and puts the files in the current directory. Use the -stubs option to create source files. Use the -o option to concatenate the results for all listed classes into a single file.
javah_g is a non-optimized version of javah suitable for use with debuggers like jdb.
Concatenates the resulting header or source files for all the classes listed on the command line into outputfile.
Sets the directory where javah saves the header files or the stub files.
Sets the directory where javah stores temporary files. By default, javah stores temporary files in the directory specified by the %TEMP% environment variable. If %TEMP% is unspecified, then javah checks for a %TMP% environment variable. And finally, if %TMP% is unspecified, javah creates the directory C:\tmp and stores the files there.
Causes javah to generate C declarations from the Java object file.
Causes javah to print a message to stdout concerning the status of the generated files.
Specifies the path javah uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by semicolons. Thus the general format for path is:
.;<your_path>
For example:
.;C:\users\dac\classes;C:\tools\java\classes
Disassembles class files.
javap [ options ] class. . .
The javap command disassembles a class file. Its output depends on the options used. If no options are used, javap prints out the public fields and methods of the classes passed to it. javap prints its output to stdout. For example, compile the following class declaration:
class C {
static int a = 1;
static int b = 2;
static {
System.out.println(a);
}
static {
a++;
b = 7;
System.out.println(a);
System.out.println(b);
}
static {
System.out.println(b);
}
public static void main(String args[]) {
C c = new C();
}
}
When the resulting class C is passed to javap using no options the following output results:
Compiled from C:\users\dac\C.java
private class C extends java\lang\Object {
static int a;
static int b;
public static void main(java\lang\String []);
public C();
static void ();
}
Prints out line and local variable tables.
Prints out the private and protected methods and fields of the class in addition to the public ones.
Prints out disassembled code, (the instructions that comprise the Java bytecodes, for each of the methods in the class). For example, passing class C to javap using the -c flag results in the following output:
Compiled from C:\users\dac\C.java
private class C extends java\lang\Object {
static int a;
static int b;
public static void main(java\lang\String []);
public C();
static void ();
Method void main(java\lang\String [])
0 new #4
3 invokenonvirtual #9 ()V>
6 return
Method C()
0 aload_0 0
1 invokenonvirtual #10 ()V>
4 return
Method void ()
0 iconst_1
1 putstatic #7
4 getstatic #6
7 getstatic #7
10 invokevirtual #8
13 getstatic #7
16 iconst_1
17 iadd
18 putstatic #7
21 bipush 7
23 putstatic #5
26 getstatic #6
29 getstatic #7
32 invokevirtual #8
35 getstatic #6
38 getstatic #5
41 invokevirtual #8
44 iconst_2
45 putstatic #5
48 getstatic #6
51 getstatic #5
54 invokevirtual #8
57 return
}
Specifies the path javap uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by semicolons. Thus the general format for path is:
.;your_path
For example:
.;C:\users\dac\classes;C:\tools\java\classes
Generates API documentation from source files.
javadoc [ options ] package | filename.java...
javadoc parses the declarations and doc comments in Java source files and formats the public API into a set of HTML pages. As an argument to javadoc you can pass in either a package name or a list of Java source files.
Within doc comments, javadoc supports the use of special doc tags to augment the API documentation. javadoc also supports standard HTML within doc comments. This is useful for code samples and for formatting text.
The package specified on the command line must be in your CLASSPATH. Note that javadoc uses .java files, not .class files.
javadoc reformats and displays all public and protected declarations for
Java source files can include doc comments. Doc comments begin with /** and indicate text to be included automatically in generated documentation.
You can embed standard HTML tags within a doc comment. However, don't use tags heading tags like <h1> or <hr>, because javadoc creates an entire structured document and these structural tags interfere with the formatting of the generated document.
javadoc parses special tags that are recognized when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an @.
Tags must start at the beginning of a line. Keep tags with the same name together within a doc comment. For example, put all your @author tags together so javadoc can tell where the list ends.
@see classname
Adds a hyperlinked See Also
entry to the class.
@see fully-qualified-classname
Adds a hyperlinked See Also
entry to the class.
@see fully-qualified-classname#method-name
Adds a hyperlinked See Also
entry to the method in the specified class.
@version version-text
Adds a Version
entry.
@author your-name
Creates an Author
entry. There can be multiple author tags.
An example of a class comment:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @see awt.BaseWindow
* @see awt.Button
* @version 1.2 12 Dec 1994
* @author Sami Shaio
*/
class Window extends BaseWindow {
...
}
In addition to HTML text, variable comments can contain only the @see tag (see above).
An example of a variable comment:
/**
* The X-coordinate of the window
* @see window#1
*/
int x = 1263732;
Can contain @see tags, as well as:
@param parameter-name description...
Adds a parameter to the Parameters
section. The description may be continued on the next line.
@return description...
Adds a Returns
section, which contains the description of the return value.
@exception fully-qualified-class-name
description...
Adds a Throws
entry, which contains the name of the exception that may be thrown
by the method. The exception is linked to its class documentation.
Here is an example of a method comment:
/**
* Return the character at the specified index. An index ranges
* from <tt>0</tt> to <tt>length() - 1</tt>.
* @param index The index of the desired character
* @return The desired character
* @exception StringIndexOutOfRangeException When the index
* is not in the range <tt>0</tt>> to <tt>length() - 1</tt>.
*/
public char charAt(int index) {
...
}
Specifies the path javadoc uses to look up the .java files. Overrides the default or the CLASSPATH environment variable, if it is set. Directories are separated by semicolons, for example:
.;C:\users\dac\classes;C:\tools\java\classes
Specifies the directory where javadoc stores the generated HTML files. For example:
javadoc -d C:\usrs\dac\public_html\doc java.lang
Causes the compiler and linker to print out messages about what source files are being compiled and what object files are being loaded.
The appletviewer command allows you to run applets outside of the context of a World Wide Web browser.
appletviewer [ options ] urls ...
The appletviewer command connects to the document(s) or resource(s) designated by urls and displays each applet referenced by that document in its own window. Note: if the document(s) referred to by urls does not reference any applets with the APPLET tag, appletviewer does nothing.
Starts the applet viewer in the Java debugger-jdb-thus allowing you to debug the applets in the document.