Java Commands & Options

by

The java commands supports a wide range of options:

  • All options start with a single hyphen or minus-sign (-): the GNU/Linux convention of using — for “long” options is not supported.
  • Options must appear before the or the -jar argument to be recognized. Any arguments after them will be treated as arguments to be passed to the Java app that is being run.
  • Options that do not start with -X or -XX are standard options. You can rely on all Java implementations1 to support any standard option.
  • Options that start with -X are non-standard options and may be withdrawn from one Java version to the next.
  • Options that start with -XX are advanced options, and may also be withdrawn

Setting system properties with -D

The -D= option is used to set a property in the system Properties object. This parameter can be repeated to set different properties.

Memory, Stack and Garbage Collector options

The main options for controlling the heap and stack sizes are documented in Setting the Heap, PermGen, and Stack sizes.

Enabling and disabling assertions

The -ea and -da options respectively enable and disable Java assert checking:

  • All assertion checking is disabled by default.
  • The -ea option enables checking of all assertions
  • The -ea:… enables checking of assertions in a package and all subpackages.
  • The -ea:… enables checking of assertions in a class.
  • The -da option disables checking of all assertions
  • The -da:… disables checking of assertions in a package and all subpackages.
  • The -da:… disables checking of assertions in a class.
  • The -esa option enables checking for all system classes.
  • The -dsa option disables checking for all system classes.

The options can be combined. For example.

$ # Enable all assertion checking in non-system classes
$ java -ea -dsa MyApp
$ # Enable assertions for all classes in a package except for one.
$ java -ea:com.wombat.fruitbat… -da:com.wombat.fruitbat.Brickbat MyApp

Note that enabling to assertion checking is liable to alter the behavior of a Java programming.

  • It is liable to make the application slower in general.
  • It can cause specific methods to take longer to run, which could change the timing of threads in a multi-threaded application.
  • It can introduce serendipitous happens-before relations which can cause memory anomalies to disappear.
  • An incorrectly implemented assert statement could have unwanted side-effects.

Selecting the VM type

The -client and -server options allow you to select between two different forms of the HotSpot VM:

  • The “client” form is tuned for user applications and offers faster startup.
  • The “server” form is tuned for long-running applications. It takes longer capturing statistics during JVM “warm-up” which allows the JIT compiler to do a better job of optimizing the native code.

By default, the JVM will run in 64bit mode if possible, depending on the capabilities of the platform. The -d32 and –
d64 options allow you to select the mode explicitly.

1 – Check the official manual for the java commands. Sometimes a standard option is described as “subject to
change”.

Spaces and other special characters in arguments

First of all, the problem of handling spaces in arguments is NOT actually a Java problem. Rather it is a problem that needs to be handled by the command shell that you are using when you run a Java program.

As an example, let us suppose that we have the following simple program that prints the size of a file:

import java.io.File;
public class PrintFileSizes {
     public static void main(String[] args) {
     for (String name: args) {
     File file = new File(name);
          System.out.println("Size of '" + file + "' is " + file.size());
          }
     }
}

Now suppose that we want print the size of a file whose pathname has spaces in it; e.g. /home/steve/Test File.txt. If we run the command like this:

$ java PrintFileSizes /home/steve/Test File.txt

the shell won’t know that /home/steve/Test File.txt is actually one pathname. Instead, it will pass 2 distinct arguments to the Java application, which will attempt to find their respective file sizes, and fail because files with
those paths (probably) do not exist.

Solutions using a POSIX shell

POSIX shells include sh as well derivatives such as bash and ksh. If you are using one of these shells, then you can
solve the problem by quoting the argument.

$ java PrintFileSizes “/home/steve/Test File.txt”

The double-quotes around the pathname tell the shell that it should be passed as a single argument. The quotes will be removed when this happens. There are a couple of other ways to do this:

$ java PrintFileSizes '/home/steve/Test File.txt'

Single (straight) quotes are treated like double-quotes except that they also suppress various expansions within the argument.

$ java PrintFileSizes /home/steve/Test\ File.txt

A backslash escapes the following space and causes it not to be interpreted as an argument separator.

For more comprehensive documentation, including descriptions of how to deal with other special characters in arguments, please refer to the quoting topic in the Bash documentation.

Solution for Windows

The fundamental problem for Windows is that at the OS level, the arguments are passed to a child process as a single string (source). This means that the ultimate responsibility of parsing (or re-parsing) the command line falls on either program or its runtime libraries. There is lot of inconsistency.

In the Java case, to cut a long story short:

  • You can put double-quotes around an argument in a java commands, and that will allow you to pass arguments with spaces in them.
  • Apparently, the java command itself is parsing the command string, and it gets it more or less right
  • However, when you try to combine this with the use of SET and variable substitution in a batch file, it gets really complicated as to whether double-quotes get removed.
  • The cmd.exe shell apparently has other escaping mechanisms; e.g. doubling double-quotes, and using escapes.

Running an executable JAR file

Executable JAR files are the simplest way to assemble Java code into a single file that can be executed. *(Editorial
Note: Creation of JAR files should be covered by a separate Topic.) *

Assuming that you have an executable JAR file with pathname , you should be able to run it as follows:

java -jar <jar-path>

If the command requires command-line arguments, add them after the . For example:

java -jar arg1 arg2 arg3

If you need to provide additional JVM options on the java command line, they need to go before the -jar option. Note that a -cp / -classpath option will be ignored if you use -jar. The application’s classpath is determined by the
JAR file manifest.

Running a Java applications via a “main” class

When an application has not been packaged as an executable JAR, you need to provide the name of an entry-point class on the java command line.

Running the HelloWorld class

The “HelloWorld” example is described in Creating a new Java program. It consists of a single class called HelloWorld which satisfies the requirements for an entry-point.

Assuming that the (compiled) “HelloWorld.class” file is in the current directory, it can be launched as follows:

java HelloWorld

Some important things to note are:

  • We must provide the name of the class: not the pathname for the “.class” file or the “.java” file.
  • If the class is declared in a package (as most Java classes are), then the class name we supply to the java commands must be the full class name. For instance, if SomeClass is declared in the com. example package, then the full class name will be com.example.SomeClass.

Specifying a classpath

Unless we are using in the java -jar command syntax, the java commands looks for the class to be loaded by searching the classpath; see The Classpath. The above command is relying on the default classpath being (or
including) the current directory. We can be more explicit about this by specifying the classpath to be used using the -cp option.

java -cp . HelloWorld

This says to make the current directory (which is what “.” refers to) the sole entry on the classpath.

The -cp is an option that is processed by the java command. All options that are intended for the java command should be before the class name. Anything after the class will be treated as a command-line argument for the Java application and will be passed to the application in the String[] that is passed to the main method.

(If no -cp option is provided, the java will use the classpath that is given by the CLASSPATH environment variable. If that variable is unset or empty, java uses “.” as the default classpath.)

Leave a Comment