jar and javadoc
A jar is a zip file of class files with a manifest, and it is how a Java program is delivered: one file that a launcher can run and a library can be added to a classpath. The jar tool makes one, and javadoc turns the doc comments of the source into a folder of HTML. This lesson runs both on one small program.
A program with documentation
The program is two methods and a private constructor, and every declaration carries a doc comment: a sentence, the tags @param and @return where they apply. Those comments are what javadoc reads, and they are also what an editor shows on hover.
/**
* A small program that prints its arguments.
*/
public class App {
/** Not used: the class is a program. */
private App() {
}
/**
* Prints one line and the arguments it was given.
*
* @param args the words to print, possibly none
*/
public static void main(String[] args) {
String greeting = greeting();
System.out.println(greeting + " " + args.length + " args");
for (String arg : args) {
System.out.println(" " + arg);
}
}
/**
* Answers the greeting of the program.
*
* @return the word hello
*/
static String greeting() {
return "hello";
}
}
javac -Xlint:all -d out App.java
java -cp out App one two
hello 2 args
one
two
The private constructor is there for the documentation: without it javadoc warns that the class uses the default constructor and has no comment for it, and a build that treats warnings as errors stops. A class that is only a holder of static methods says so with a private constructor, and a comment explains why.
jar
The tool takes the compiled folder and writes the archive, and --main-class writes the manifest entry that makes it runnable:
jar --create --file app.jar --main-class App -C out .
The command prints nothing on success, and the file is a zip of 1084 bytes for one class. jar --list shows what went in, and the three entries are the folder, the manifest and the class:
jar --list --file app.jar
META-INF/
META-INF/MANIFEST.MF
App.class
The -C out . is the part to read twice: it changes to the folder and adds everything under it, so the archive holds App.class at its root and not out/App.class. A jar whose classes are one folder too deep does not run, and that is the most common mistake of the command.
The manifest
The manifest is a text file of Name: value lines, and the Main-Class line is the one the launcher reads:
Manifest-Version: 1.0
Created-By: 21.0.13.1 (Alpine)
Main-Class: App
Created-By names the tool and the version that wrote the file. A jar built by a build tool has more entries, such as Implementation-Version or Multi-Release: true, and a program can read any of them at run time through getClass().getPackage() or the manifest of its own class loader.
The manifest can also be written by hand and given with --manifest. That is how a build stamps a version and how a jar that is a library, and not a program, says what it is: a library has no Main-Class and is used from a classpath.
java -jar
The launcher reads the manifest of the archive and starts the class it names, with the arguments after the jar:
java -jar app.jar one two
hello 2 args
one
two
The output is the same as the classpath run because it is the same class. The archive carries its own classes, so the command works from any folder and on any machine with a JDK of a version that can read the class files. A jar without Main-Class answers no main manifest attribute and is meant to be used with -cp instead.
javadoc
The tool reads the doc comments and writes one HTML page per class, an index, a tree and a search index into the folder it is given:
javadoc -d docs -quiet App.java
The command printed nothing because every declaration has a comment; a missing one is a warning, as the default constructor was before it had a comment and a private constructor. The folder holds 25 entries, and the first ones are the pages a reader opens:
App.html
allclasses-index.html
allpackages-index.html
copy.svg
element-list
help-doc.html
index-all.html
index.html
legal
link.svg
member-search-index.js
module-search-index.js
overview-tree.html
package-search-index.js
package-summary.html
package-tree.html
resources
script-dir
script.js
search-page.js
search.html
search.js
stylesheet.css
tag-search-index.js
type-search.html
index.html is the page to open, and it links to App.html, which holds the two methods and their comments. -quiet hides the progress lines; without it the tool prints one line per file it reads, which is noise in a script and useful once.
Exercises
- Add a second class to the package, build both, and make a jar of the two.
- Write a manifest of your own with a version line and build the jar with --manifest.
- Run javadoc without -quiet and read the progress lines.
- Put the class in a package, rebuild the jar and check that java -jar still runs it.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is a jar file?
Answer
A zip of class files with a manifest
The launcher reads the zip and the manifest, and the class files inside are what run.
-
What does
Main-Classin the manifest do?Answer
Names the class that java -jar starts
Without the line the launcher has no class to run, and it says so.
-
Why does
-C out .matter to the jar command?Answer
It puts the class files at the root of the archive
A jar with the classes one folder deep cannot find them, which is the classic mistake.
-
What does this program print?
/** A greeting. */ public class Q1 { /** * Prints one word. * * @param args ignored */ public static void main(String[] args) { System.out.println("doc"); } }Answer
doc
Doc comments are comments: the program prints its line and javadoc reads the text.
-
Which file does javadoc write as the entry page of the documentation?
Answer
index.html
The index links the class pages, and App.html is one of them.
-
Why does a class of only static methods get a private constructor?
Answer
So nobody instantiates it, and javadoc has a constructor to document
The default constructor exists otherwise and has no comment, which is a javadoc warning.
-
What happens with
java -jaron a jar without a Main-Class?Answer
The launcher reports that the manifest has no main attribute
The entry point is the manifest line, and a library jar does not have one.
-
What does this program print?
public class Q2 { public static void main(String[] args) { System.out.println(args.length); System.out.println(args[0]); } }run asjava Q2 alpha beta.Answer
2 / alpha
The two words after the class become the two elements of args.
-
What does the Created-By line of a manifest name?
Answer
The tool and the version that wrote the archive
It is written by the jar tool, and a program can read it with the manifest API.
-
What does
-d docsdo for javadoc?Answer
Writes the generated pages into that folder
The folder is the destination of the HTML, and it is created if it is missing.
The modern project group packs a service with the same two commands and runs the three checkers over it: the jar and the three tools is the long form of this page.
The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.
Article author: Arthur Isaev