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\*.javaThis 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\*.javaAlso, 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.LauncherPassing 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.LauncherSet 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.LauncherRun a jar file whose manifest specifies a Main-Class attribute:
C:\@build\dist>java -jar example-app-1.1.jarThe 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\javadocThe 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.
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.)
Would you use this technique?