Tools and Commands 
Part of the SAP JVM delivery is a set of tools and commands that make up a complete SDK for Java. This chapter gives a brief overview about the most commonly used tools and their most important options.
java / javaw
This is the application launcher tool. It executes standalone Java applications by starting a Java runtime environment, loading the specified class and invoking its main method. The two commands are essentially equivalent, except that with javaw there is no associated console window. When using the javaw launcher, no command prompt window will appear, but application output to stdout or stderr will not be visible as well.
Syntax
java and javaw have the same syntax.
java [ options ] class [ argument ... ] java [ options ] -jar file.jar [ argument ... ]
with
options: Options passed to the SAP JVM
class: Fully-qualified name of the class to invoke
file.jar: Name of a jar file to be invoked
argument: Argument passed to the application’s main method
By default, the first non-option argument is the name of the class to be invoked. A fully-qualified class name should be used. If the -jar option is specified, the first non-option argument is the name of a JAR archive containing class and resource files for the application, with the startup class indicated by the Main-Class manifest header.
The Java runtime searches for the startup class, and other classes used, in three sets of locations: the bootstrap class path, the installed extensions, and the user class path.
Non-option arguments after the class name or JAR file name are passed to the main function.
For a full set of supported VM parameters, see Reference
javac
Syntax
Arguments may be in any order.
java and javaw have the same syntax.
javac [ options ] [ sourcefiles ] [ @argfiles ]
with
options: Command-line options
sourcefiles: One or more source files to be compiled (such as MyClass.java).
@argfiles: One or more files that lists options and source files.
The -J options are not allowed in these files.
The javac tool reads class and interface definitions, written in the Java programming language, and compiles them into bytecode class files. There are two ways to pass source code file names to javac:
For a small number of source files, simply list the file names on the command line.
For a large number of source files, list the file names in a file, separated by blanks or line breaks. Then use the list file name on the javac command line, preceded by an @ character.
Source code file names must have .java suffixes, class file names must have .class suffixes, and both source and class files must have root names that identify the class. For example, a class called MyClass would be written in a source file called MyClass.java and compiled into a bytecode class file called MyClass.class.
Inner class definitions produce additional class files. These class files have names combining the inner and outer class names, such as MyClass$MyInnerClass.class.
You should arrange source files in a directory tree that reflects their package tree. For example, if you keep all your source files in \workspace, the source code for com.mysoft.mypack.MyClass should be in \workspace\com\mysoft\mypack\MyClass.java.
By default, the compiler puts each class file in the same directory as its source file. You can specify a separate destination directory with -d (see Options below).
Searching for types
When compiling a source file, the compiler often needs information about a type it does not yet recognize. The compiler needs type information for every class or interface used, extended, or implemented in the source file. This includes classes and interfaces not explicitly mentioned in the source file but which provide information through inheritance.
Example
For example, when you subclass java.applet.Applet, you are also using Applet's ancestor classes: java.awt.Panel, java.awt.Container, java.awt.Component, and java.awt.Object.
When the compiler needs type information, it looks for a source file or class file, which defines the type. The compiler searches first in the bootstrap and extension classes, then in the user class path. The user class path is defined by setting the CLASSPATH environment variable or by using the -classpath command line option. If you use the -sourcepath option, the compiler searches the indicated path for source files; otherwise the compiler searches the user class path both for class files and source files.
A successful type search may produce a class file, a source file, or both. Here is how javac handles each situation:
Search produces a class file but no source file: javac uses the class file.
Search produces a source file but no class file: javac compiles the source file and uses the resulting class file.
Search produces both a source file and a class file: javac determines whether the class file is out of date. If the class file is out of date, javac recompiles the source file and uses the updated class file.
Otherwise, javac just uses the class file.
javac considers a class file out of date only if it is older than the source file.
Note
javac can silently compile source files not mentioned on the command line. Use the -verbose option to trace automatic compilation
Standard Options
The compiler has a set of standard options that are supported on the current development environment and will be supported in future releases.
-classpath <classpath>
Set the user class path, overriding the user class path in the CLASSPATH environment variable. If neither CLASSPATH or -classpath is specified, the user class path consists of the current directory.
If the -sourcepath option is not specified, the user class path is searched for source files as well as class files.
-d <directory>
Set the destination directory for class files. The destination directory must already exist; javac will not create the destination directory. If a class is part of a package, javac puts the class file in a subdirectory reflecting the package name, creating directories as needed.
If -d is not specified, javac puts the class file in the same directory as the source file.
Note that the directory specified by -d is not automatically added to your user class path.
-deprecation
Show a description of each use or override of a deprecated member or class. Without -deprecation, javac shows the names of source files that use or override deprecated members or classes.
-encoding <encoding>
Set the source file encoding name, such as EUCJIS/SJIS. If -encoding is not specified, the platform default converter is used.
-g
Generate all debugging information, including local variables. By default, only line number and source file information is generated.
-g:none
Do not generate any debugging information.
-g:{keyword list}
Generate only some kinds of debugging information, specified by a comma separated list of keywords.
Valid keywords are:
source: Source file debugging information
lines: Line number debugging information
vars: Local variable debugging information
-help
Print a synopsis of standard options.
-nowarn
Disable warning messages.
-source <release>
Enables support for compiling source code containing assertions. When release is set to 1.4, the compiler accepts code containing assertions. When release is set to 1.3, the compiler does not support assertions. The compiler defaults to the 1.3 behavior if the -source flag is not used.
-sourcepath <sourcepath>
Specify the source code path to search for class or interface definitions. Source path entries can be directories, JAR archives, or ZIP archives. If packages are used, the local path name within the directory or archive must reflect the package name. Note that classes found through the classpath are subject to automatic recompilation if their sources are found.
-verbose
Verbose output. This includes information about each class loaded and each source file compiled.
Cross-Compilation Options
By default, classes are compiled against the bootstrap and extension classes of the platform that javac shipped with. But javac also supports cross-compiling, where classes are compiled against a bootstrap and extension classes of a different Java platform implementation. It is important to use -bootclasspath and -extdirs when cross-compiling.
-target <version>
Generate class files that will work on VMs with the specified version.
-bootclasspath <bootclasspath>
Cross-compile against the specified set of boot classes. Boot class path entries can be directories, JAR archives, or ZIP archives.
-extdirs <directories>
Cross-compile against the specified extension directories. Each JAR archive in the specified directories is searched for class files.
Non-Standard Options
An additional set of non-standard options isspecific to the current virtual machine and compiler implementations and are subject to change in the future. Non-standard options begin with -X, the list of non-standard options can be obtained using the command javac -X.
The -J option
-J<option>
Pass <option> to the java launcher called by javac. For example, -J-Xms48m sets the startup memory to 48 megabytes. Although it does not begin with -X, it is not a standard option of javac. It is a common convention for -J to pass options to the underlying VM executing applications written in Java.
Note
CLASSPATH, -classpath, -bootclasspath, and -extdirs do not specify the classes used to run javac. Fiddling with the implementation of the compiler in this way is usually pointless and always risky. If you do need to do this, use the -J option to pass through options to the underlying java launcher.
Command line argument files
To shorten or simplify the javac command line, you can specify one or more files that themselves contain arguments to the javac command (except -J options). This enables you to create javac commands of any length on any operating system.
An argument file can include javac options and source filenames in any combination. The arguments within a file can be space-separated or newline-separated. Filenames within an argument file are relative to the current directory, not the location of the argument file. Wildcards (*) are not allowed in these lists (such as for specifying *.java). Use of the @ character to recursively interpret files is not supported.
When executing javac, pass in the path and name of each argument file with the @ leading character. When javac encounters an argument beginning with the character @, it expands the contents of that file into the argument list.
jar
The jar tool combines multiple files into a single JAR archive file. jar is a general-purpose archiving and compression tool, based on ZIP and the ZLIB compression format. It allows multiple class files and resources to be combined into one compressed file and individual entries to be signed so that their origin can be authenticated. A JAR archive can be use as a class path entry. The syntax for the jar tool is almost identical to the syntax for the tar command.
Syntax
Create jar file
jar c[v0M]f <jarfile> [-C <dir>] <inputfiles> [-Joption]
jar c[v0]mf <manifest> <jarfile> [-C <dir>] <inputfiles> [-Joption]
jar c[v0M] [-C <dir>] <inputfiles> [-Joption]
jar c[v0]m <manifest> [-C <dir>] <inputfiles> [-Joption]
Update jar file
jar u[v0M]f <jarfile> [-C <dir>] <inputfiles> [-Joption]
jar u[v0]mf <manifest> <jarfile> [-C <dir>] <inputfiles> [-Joption]
jar u[v0M] [-C <dir>] <inputfiles> [-Joption]
jar u[v0]m <manifest> [-C <dir>] <inputfiles> [-Joption]
Extract jar file
jar x[v]f <jarfile> <inputfiles> [-Joption]
jar x[v] <inputfiles> [-Joption]
List table of contents of jar file
jar t[v]f <jarfile> <inputfiles> [-Joption]
jar t[v] <inputfiles> [-Joption]
Add index to jar file
jar i <jarfile> [-Joption]
with:
<jarfile>
Jar file to be created (c), updated (u), extracted (x), or have its table of contents viewed (t). The f option and filename <jarfile> are a pair — if either is present, they must both appear. Note that omitting f and <jarfile> accepts a jar file from standard input (for x and t) or sends the jar file to standard output (for c and u).
<inputfiles>
Files or directories, separated by spaces, to be combined into <jarfile> (for c and u), or to be extracted (for x) or listed (for t) from <jarfile>. All directories are processed recursively. The files are compressed unless option O (zero) is used.
<manifest>
Pre-existing manifest file whose name: value pairs are to be included in MANIFEST.MF in the jar file. The m option and filename manifesfile are a pair — if either is present, they must both appear. The letters m and f must appear in the same order that <manifest> and <jarfile> appear.
-C <dir>
Temporarily changes directories to <dir> while processing the following input files argument. Multiple -C <dir> <inputfiles> sets are allowed.
-J option
Option to be passed into the Java runtime environment. (There must be no space between -J and option).
Example
Typical usage to combine files into a jar file is:
jar cf myFile.jar *.class
In this example, all the class files in the current directory are placed into the file named myFile.jar. A manifest file entry named META-INF/MANIFEST.MF is automatically generated by the jar tool and is always the first entry in the jar file. The manifest file is the place where any meta-information about the archive is stored as name: value pairs. For more information about how meta-information is stored in the manifest file, see the JAR file specification under http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#JAR%20Manifest
If you have a pre-existing manifest file whose name: value pairs you want the jar tool to include for the new jar archive, you can specify it using the m option:
jar cmf myManifestFile myFile.jar *.class
Be sure that any pre-existing manifest file that you use ends with a new line. The last line of a manifest file will not be parsed if it does not end with a new line character. Note that when you specify cfm instead of cmf (i.e., you invert the order of the m and f options), you need to specify the name of the jar archive first, followed by the name of the manifest file:
jar cfm myFile.jar myManifestFile *.class
To extract the files from a jar file, use x, as in:
jar xf myFile.jar
To extract only certain files from a jar file, supply their filenames:
jar xf myFile.jar foo bar
Beginning with version 1.3 of the Java 2 SDK, the jar utility supports “JarIndex”, which allows application class loaders to load classes more efficiently from jar files. If an application or applet is bundled into multiple jar files, only the necessary jar files will be downloaded and opened to load classes. This performance optimization is enabled by running jar with the i option. It will generate package location information for the specified main jar file and all the jar files it depends on, which need to be specified in the Class-Path attribute of the main jar file's manifest.
jar i main.jar
In this example, an INDEX.LIST file is inserted into the META-INF directory of main.jar. The application class loader will use the information stored in this file for efficient class loading.
Option |
Description |
|---|---|
c |
Creates a new archive to file named <jarfile> (if f is specified) or to standard output (if f and <jarfile> are omitted). Add to it the files and directories specified by <inputfiles>. |
u |
Updates an existing file jar file (when f is specified) by adding to it files and directories specified by <inputfiles>.
jar uf foo.jar foo.class would add the file foo.class to the existing jar file foo.jar End of the example. . The u option can also update the manifest entry, as given by this example: jar umf manifest foo.jar updates the foo.jar manifest with the name: value pairs in manifest. |
x |
Extracts files and directories from jarfile (if f is specified) or standard input (if f and jarfile are omitted). If inputfiles is specified, only those specified files and directories are extracted. Otherwise, all files and directories are extracted. |
t |
Lists the table of contents from jarfile (if f is specified) or standard input (if f and jarfile are omitted). If inputfiles is specified, only those specified files and directories are listed. Otherwise, all files and directories are listed. |
i |
Generate index information for the specified jarfile and its dependent jar files.
jar i foo.jar would generate an INDEX.LIST file in foo.jar, which contains location information for each package in foo.jar and all the jar files specified in the Class-Path attribute of foo.jar. End of the example. |
f |
Specifies the file jarfile to be created (c), updated (u), extracted (x), indexed (i), or viewed (t). The f option and filename jarfile are a pair — if present, they must both appear. Omitting f and jarfile accepts a “jar file” from standard input (for x and t) or sends the “jar file” to standard output (for c and u). |
v |
Generates verbose output to standard output. |
0 |
(zero) Store without using ZIP compression |
M |
Do not create a manifest file entry (for c and u), or delete a manifest file entry if one exists (for u). |
m |
Includes name: value attribute pairs from the specified manifest file manifest in the file at META-INF/MANIFEST.MF. A name: value pair is added unless one already exists with the same name, in which case its value is updated. On the command line, the letters m and f must appear in the same order that manifest and jarfile appear.
jar cmf myManifestFile myFile.jar *.class You can add special-purpose name: value attribute pairs to the manifest that aren't contained in the default manifest. End of the example. |
-C <dir> |
Temporarily changes directories (cd <dir>) during execution of the jar command while processing the following inputfiles argument. Its operation is intended to be similar to the -C option of the UNIX tar utility.
jar uf foo.jar -C classes . -C bin xyz.class would change to the classes directory and add to foo.jar all files within the classes directory (without creating a classes directory in the jar file), then change back to the original directory before changing to the bin directory to add xyz.class to foo.jar. End of the example. |
-J<option> |
Pass option to the Java runtime environment, for example, -J-Xmx48M sets the maximum memory to 48 megabytes. |
Command line argument files
To shorten or simplify the jar command line, you can specify one or more files that themselves contain arguments to the jar command (except -J options). This enables you to create jar commands of any length, overcoming command line limits imposed by the operating system.
An argument file can include options and file names. The arguments within a file can be space-separated or newline-separated. File names within an argument file are relative to the current directory, not the location of the argument file. Wildcards (*) that might otherwise be expanded by the operating system shell are not expanded. Use of the @ character to recursively interpret files is not supported.
When executing jar, pass in the path and name of each argument file with the @ leading character. When jar encounters an argument beginning with the character @, it expands the contents of that file into the argument list.
Example
You can use a single argument file named classes.list" to hold the names of the files:
dir /b *.class > classes.list
Then execute the jar command passing in the <argfile>:
jar cf my.jar @classes.list
An argument file can be passed in with a path, but any file names inside the argument file that have relative paths are relative to the current working directory, not the path passed in.