Java Practices->Command line operations

Command line operations

Most Java programmers use an Integrated Development Environment (IDE) such as IntelliJ, NetBeans, or Eclipse. Modern IDEs are usually pleasant to use, and go a long way in simplifying things for a typical programmer.

However, being familiar with Java's basic command line tools is still very useful. It not only gives you a better understanding of what's happening, it's essential in situations where you need to use the command line tools directly (scripts, tools, and so on).

The most commonly used tools are:

javac - the java compiler
java - launching programs on the Java Runtime Environment
javadoc - generating documentation for your project

Here are some examples of running command line tools. It assumes a project with the following directory structure:

PROJECT_HOME
  -> lib (jar files)
  -> src (java code)
    -> hirondelle (top-level package; no .java files)
      -> ante (.java files)
        -> deluvian (.java files)

Compiling With javac

PROJECT_HOME>javac -cp lib\\* src\\hirondelle\\ante\\*.java src\\hirondelle\\ante\\deluvian\\*.java

This compiles in place, and creates .class files beside .java files. If you want to place generated class files elsewhere, use the -d option to put them into an existing directory:

PROJECT_HOME>javac -cp lib\\* -d build src\\hirondelle\\ante\\*.java src\\hirondelle\\ante\\deluvian\\*.java

Also, notice that all jars in a directory can be succinctly referenced using 'lib\\*'. However, referencing the source files that you need to compile is a different story: all of your packages need to be listed one by one. That is, you can't simply specify a single root directory for your source files. This is a rather serious defect of javac.

If your jars are in various directories, then the classpath is a list delimited by semi-colons:

-cp lib\\*;C:\\abc\\one.jar;C:\\xyz\\two.jar

Running With java

Any class having a main method may be run as a Java program. The main method must have the form:

public static void main(String... aArgs){...}

An application is run by referencing a fully-qualified class name, but without the .class suffix. Assuming that the classes have been compiled in place, our example application can be run using:

PROJECT_HOME>java -cp lib\\*;src hirondelle.ante.Launcher

Passing 3 arguments to the program:

PROJECT_HOME>java -cp lib\\*;src hirondelle.ante.Launcher arg1 arg2 "Arg Three"

Setting a System property value with -D:

PROJECT_HOME>java -Dblah=whatever -cp lib\\*;src hirondelle.ante.Launcher

Set the initial and maximum size of the object allocation pool to 5 Meg and 100 Meg, respectively:

PROJECT_HOME>java -cp lib\\*;src -Xms5m -Xmx100m hirondelle.ante.Launcher

Run a jar file whose manifest specifies a Main-Class attribute:

C:\\@build\\dist>java -jar example-app-1.1.jar

The javaw command is the same as the java command, with the only difference being that javaw has no associated console window.

Using javadoc

For files under the src directory, the following command will javadoc all packages starting with 'hirondelle.ante', and output the result to C:\\@build\\javadoc:

javadoc -sourcepath src -subpackages hirondelle.ante -classpath lib\\* -d C:\\@build\\javadoc

The javadoc tool has many options. You may find these especially useful:

-linksource: links your javadoc to a static snapshot of the underlying source code (very nice).
-windowtitle, -header and -footer: often useful for showing the name and version of your application.
-link: link to the JDK's javadoc as well
-noqualifier: remove tedious package prefixes from JDK classes
define the minimum class scope to be processed, using one of: -private, -package, -protected, -public.

Here's a second example, with more options:

javadoc 
 -sourcepath src 
 -subpackages hirondelle.ante 
 -package
 -classpath lib\\* 
 -d C:\\@build\\javadoc
 -linksource
 -link http://docs.oracle.com/javase/7/docs/api/
 -noqualifier java.*:javax.*
 -windowtitle "My App 1.0"
 -header "<b>My App 1.0</b>"
 -footer "<a href='http://www.blah.com'>My App</a>"

Javadoc can also be controlled using the following items, placed beside your source code:

package-info.java - Each package can include a package-info.java file. It contains package-level documentation. Despite its extension, a package-info.java file is not a Java class file.
doc-files subdirectories - each package can include a 'doc-files' subdirectory, containing items that can be linked from javadoc (images, html files, and so on) using ordinary hypertext links.
overview.html - a single file describing general aspects of your project. (This file doesn't necessarily reside in your source tree, but it makes sense to place it there, in analogy with the package-info.java files.)