Core Java

https://docs.oracle.com/javase/9/tools/javac.
htm#JSWOR627
https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html
Java Platform Standard Edition 8 Documentation

https://docs.oracle.com/javase/8/docs/
Oracle has two products that implement Java Platform Standard Edition (Java SE) 8: Java SE Development Kit (JDK)
8 and Java SE Runtime Environment (JRE) 8.
JDK 8 is a superset of JRE 8, and contains everything that is in JRE 8, plus tools such as the compilers and
debuggers necessary for developing applets and applications. JRE 8 provides the libraries, the Java Virtual Machine
(JVM), and other components to run applets and applications written in the Java programming language. Note that
the JRE includes components not required by the Java SE specification, including both standard and non-standard
Java components.
The following conceptual diagram illustrates the components of Oracle's Java SE products
JAVA: https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html
JAVAC: https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html
JAVADOC: https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
APPLETVIEWER:
https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/applet_dev_guide.html
JDBC: https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/index.html
About the Java Technology

Java technology is both a programming language and a platform.
The Java Programming Language
The Java programming language is a high-level language that can be characterized by all of the following
buzzwords:
 Simple  Architecture neutral

 Object oriented  Portable
 Distributed  High performance
 Multithreaded  Robust
 Dynamic  Secure
Each of the preceding buzzwords is explained in The Java Language Environment , a white paper written by
James Gosling and Henry McGilton.
In the Java programming language, all source code is first written in plain text files ending with
the .java extension. Those source files are then compiled into .class files by the javac compiler.
A .class file does not contain code that is native to your processor; it instead contains bytecodes — the
machine language of the Java Virtual Machine1 (Java VM). The java launcher tool then runs your application
with an instance of the Java Virtual Machine.
An overview of the software development process.

Because the Java VM is available on many different operating systems, the same .class files are capable of
running on Microsoft Windows, the Solaris™ Operating System (Solaris OS), Linux, or Mac OS. Some virtual
machines, such as the Java SE HotSpot at a Glance, perform additional steps at runtime to give your
application a performance boost. This includes various tasks such as finding performance bottlenecks and
recompiling (to native code) frequently used sections of code.
Through the Java VM, the same application is capable of running on multiple platforms.
The Java Platform
A platform is the hardware or software environment in which a program runs. We've already mentioned some
of the most popular platforms like Microsoft Windows, Linux, Solaris OS, and Mac OS. Most platforms can be
described as a combination of the operating system and underlying hardware. The Java platform differs from
most other platforms in that it's a software-only platform that runs on top of other hardware-based platforms.
The Java platform has two components:
 The Java Virtual Machine

 The Java Application Programming Interface (API)
You've already been introduced to the Java Virtual Machine; it's the base for the Java platform and is ported
onto various hardware-based platforms.
The API is a large collection of ready-made software components that provide many useful capabilities. It is
grouped into libraries of related classes and interfaces; these libraries are known as packages. The next
section, What Can Java Technology Do? highlights some of the functionality provided by the API.
The API and Java Virtual Machine insulate the program from the underlying hardware.
As a platform-independent environment, the Java platform can be a bit slower than native code. However,
advances in compiler and virtual machine technologies are bringing performance close to that of native code
without threatening portability.
The terms"Java Virtual Machine" and "JVM" mean a Virtual Machine for the Java platform.
What Can Java Technology Do?

The general-purpose, high-level Java programming language is a powerful software platform. Every full
implementation of the Java platform gives you the following features:
 Development Tools: The development tools provide everything you'll need for compiling, running,
monitoring, debugging, and documenting your applications. As a new developer, the main tools you'll
be using are the javac compiler, the java launcher, and the javadoc documentation tool.
 Application Programming Interface (API): The API provides the core functionality of the Java
programming language. It offers a wide array of useful classes ready for use in your own applications.
It spans everything from basic objects, to networking and security, to XML generation and database
access, and more. The core API is very large; to get an overview of what it contains, consult the Java
Platform Standard Edition 8 Documentation.
 Deployment Technologies: The JDK software provides standard mechanisms such as the Java Web
Start software and Java Plug-In software for deploying your applications to end users.
 User Interface Toolkits: The JavaFX, Swing, and Java 2D toolkits make it possible to create
sophisticated Graphical User Interfaces (GUIs).
 Integration Libraries: Integration libraries such as the Java IDL API, JDBC API, Java Naming and
Directory Interface (JNDI) API, Java RMI, and Java Remote Method Invocation over Internet Inter-
ORB Protocol Technology (Java RMI-IIOP Technology) enable database access and manipulation of
remote objects.
How Will Java Technology Change My Life?

We can't promise you fame, fortune, or even a job if you learn the Java programming language. Still, it is likely
to make your programs better and requires less effort than other languages. We believe that Java technology
will help you do the following:
 Get started quickly: Although the Java programming language is a powerful object-oriented
language, it's easy to learn, especially for programmers already familiar with C or C++.
 Write less code: Comparisons of program metrics (class counts, method counts, and so on)
suggest that a program written in the Java programming language can be four times smaller than
the same program written in C++.
 Write better code: The Java programming language encourages good coding practices, and
automatic garbage collection helps you avoid memory leaks. Its object orientation, its JavaBeans™
component architecture, and its wide-ranging, easily extendible API let you reuse existing, tested
code and introduce fewer bugs.
 Develop programs more quickly: The Java programming language is simpler than C++, and as
such, your development time could be up to twice as fast when writing in it. Your programs will also
require fewer lines of code.
 Avoid platform dependencies: You can keep your program portable by avoiding the use of
libraries written in other languages.
 Write once, run anywhere: Because applications written in the Java programming language are
compiled into machine-independent bytecodes, they run consistently on any Java platform.
 Distribute software more easily: With Java Web Start software, users will be able to launch your
applications with a single click of the mouse. An automatic version check at startup ensures that
users are always up to date with the latest version of your software. If an update is available, the
Java Web Start software will automatically update their installation.
Lesson: The "Hello World!" Application

The sections listed below provide detailed instructions for compiling and running a simple "Hello World!"
application. The first section provides information on getting started with the NetBeans IDE, an integrated
development environment that greatly simplifies the software development process. The NetBeans IDE runs on
all of the platforms listed below. The remaining sections provide platform-specific instructions for getting started
without an integrated development environment. If you run into problems, be sure to consult the common
problems section; it provides solutions for many issues encountered by new users.
"Hello World!" for the NetBeans IDE These instructions are for users of the NetBeans IDE. The NetBeans IDE
runs on the Java platform, which means that you can use it with any operating system for which there is a JDK
7 available. These operating systems include Microsoft Windows, Solaris OS, Linux, and Mac OS X. We
recommend using the NetBeans IDE instead of the command line whenever possible.
"Hello World!" for Microsoft Windows These command-line instructions are for users of Windows XP
Professional, Windows XP Home, Windows Server 2003, Windows 2000 Professional, and Windows Vista.
"Hello World!" for Solaris OS and Linux These command-line instructions are for users of Solaris OS and
Linux. Common Problems (and Their Solutions) Consult this page if you have problems compiling or running
your application.
"Hello World!" for Microsoft Windows

It's time to write your first application! The following instructions are for users of Windows Vista, Windows 7,
and Windows 8. Instructions for other platforms are in "Hello World!" for Solaris OS and Linux and "Hello
World!" for the NetBeans IDE.
If you encounter problems with the instructions on this page, consult the Common Problems (and Their
Solutions).
 A Checklist
 Creating Your First Application
o Create a Source File
o Compile the Source File into a .class File
o Run the Program
A Checklist
To write your first program, you'll need:
1. The Java SE Development Kit 8 (JDK 8)
You can download the Windows version now. (Make sure you download the JDK, not the JRE.)
Consult the installation instructions.
2. A text editor
In this example, we'll use Notepad, a simple editor included with the Windows platforms. You can
easily adapt these instructions if you use a different text editor.
These two items are all you'll need to write your first application.
Creating Your First Application
Your first application, HelloWorldApp, will simply display the greeting "Hello world!". To create this program,
you will:
 Create a source file
A source file contains code, written in the Java programming language, that you and other
programmers can understand. You can use any text editor to create and edit source files.
 Compile the source file into a .class file
The Java programming language compiler (javac) takes your source file and translates its text into
instructions that the Java virtual machine can understand. The instructions contained within this file are
known as bytecodes.
 Run the program
The Java application launcher tool (java) uses the Java virtual machine to run your application.
Create a Source File
To create a source file, you have two options:
 You can save the file HelloWorldApp.java on your computer and avoid a lot of typing. Then, you
can go straight to Compile the Source File into a .class File.
 Or, you can use the following (longer) instructions.
First, start your editor. You can launch the Notepad editor from the Start menu by selecting Programs >
Accessories > Notepad. In a new document, type in the following code:
/**
* The HelloWorldApp class implements an application that
* simply prints "Hello World!" to standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); // Display the string.
}
}
Be Careful When You Type
Note: Type all code, commands, and file names exactly as shown. Both the compiler (javac) and launcher
(java) are case-sensitive, so you must capitalize consistently.
HelloWorldApp is not the same as helloworldapp.
Save the code in a file with the name HelloWorldApp.java. To do this in Notepad, first choose the File >
Save As menu item. Then, in the Save As dialog box:
1. Using the Save in combo box, specify the folder (directory) where you'll save your file. In this example,
the directory is myapplication on the C drive.
2. In the File name text field, type "HelloWorldApp.java", including the quotation marks.
3. From the Save as type combo box, choose Text Documents (*.txt).
4. In the Encoding combo box, leave the encoding as ANSI.
When you're finished, the dialog box should look like this.
The Save As dialog just before you click Save.
Now click Save, and exit Notepad.

Compile the Source File into a .class File
Bring up a shell, or "command," window. You can do this from the Start menu by choosing Run... and then
entering cmd. The shell window should look similar to the following figure.
A shell window.
The prompt shows your current directory. When you bring up the prompt, your current directory is usually your
home directory for Windows XP (as shown in the preceding figure.
To compile your source file, change your current directory to the directory where your file is located. For
example, if your source directory is myapplication on the C drive, type the following command at the
prompt and press Enter:
cd C:\myapplication
Now the prompt should change to C:\myapplication>.

Note:
To change to a directory on a different drive, you must type an extra command: the name of the drive. For
example, to change to the myapplication directory on the D drive, you must enter D:, as follows:
C:\>D:
D:\>cd myapplication
D:\myapplication>
If you enter dir at the prompt, you should see your source file, as follows:
C:\>cd myapplication
C:\myapplication>dir
Volume in drive C is System
Volume Serial Number is F2E8-C8CC
Directory of C:\myapplication
2014-04-24 01:34 PM <DIR> .

2014-04-24 01:34 PM <DIR> ..
2014-04-24 01:34 PM 267 HelloWorldApp.java
1 File(s) 267 bytes
2 Dir(s) 93,297,991,680 bytes free
C:\myapplication>
Now you are ready to compile. At the prompt, type the following command and press Enter.
javac HelloWorldApp.java
The compiler has generated a bytecode file, HelloWorldApp.class. At the prompt, type dir to see the
new file that was generated as follows:
C:\myapplication>javac HelloWorldApp.java
C:\myapplication>dir
Volume in drive C is System
Volume Serial Number is F2E8-C8CC
Directory of C:\myapplication
2014-04-24 02:07 PM <DIR> .

2014-04-24 02:07 PM <DIR> ..
2014-04-24 02:07 PM 432 HelloWorldApp.class
2014-04-24 01:34 PM 267 HelloWorldApp.java
2 File(s) 699 bytes
2 Dir(s) 93,298,032,640 bytes free
C:\myapplication>
Now that you have a .class file, you can run your program.
If you encounter problems with the instructions in this step, consult the Common Problems (and Their
Solutions).
Run the Program
In the same directory, enter the following command at the prompt:
java -cp . HelloWorldApp
You should see the following on your screen:
C:\myapplication>java -cp . HelloWorldApp

Hello World!
C:\myapplication>
Congratulations! Your program works!
If you encounter problems with the instructions in this step, consult the Common Problems (and Their
Solutions).
Features of Java
The primary objective of Java programming language creation was to make it portable,
simple and secure programming language. Apart from this, there are also some excellent
features which play an important role in the popularity of this language. The features of
Java are also known as java buzzwords.
A list of most important features of Java language is given below.
1. Simple
2. Object-Oriented
3. Portable
4. Platform independent
5. Secured
6. Robust
7. Architecture neutral
8. Interpreted
9. High Performance
10. Multithreaded
11. Distributed
12. Dynamic
Simple
Java is very easy to learn, and its syntax is simple, clean and easy to understand. According
to Sun, Java language is a simple programming language because:
o Java syntax is based on C++ (so easier for programmers to learn it after C++).
o Java has removed many complicated and rarely-used features, for example, explicit
pointers, operator overloading, etc.
o There is no need to remove unreferenced objects because there is an Automatic
Garbage Collection in Java.
Object-oriented
Java is an object-oriented programming language. Everything in Java is an object. Object-
oriented means we organize our software as a combination of different types of objects that
incorporates both data and behavior.
Object-oriented programming (OOPs) is a methodology that simplifies software

development and maintenance by providing some rules.
Basic concepts of OOPs are:
1. Object
2. Class
3. Inheritance
4. Polymorphism
5. Abstraction
6. Encapsulation
Platform Independent
Java is platform independent because it is different from other languages like C, C++, etc.
which are compiled into platform specific machines while Java is a write once, run anywhere
language. A platform is the hardware or software environment in which a program runs.
There are two types of platforms software-based and hardware-based. Java provides a
software-based platform.
The Java platform differs from most other platforms in the sense that it is a software-based
platform that runs on the top of other hardware-based platforms. It has two components:
1. Runtime Environment
2. API(Application Programming Interface)
Java code can be run on multiple platforms, for example, Windows, Linux, Sun Solaris,
Mac/OS, etc. Java code is compiled by the compiler and converted into bytecode. This
bytecode is a platform-independent code because it can be run on multiple platforms, i.e.,
Write Once and Run Anywhere(WORA).
Secured
Java is best known for its security. With Java, we can develop virus-free systems. Java is
secured because:
o No explicit pointer
o Java Programs run inside a virtual machine sandbox
o Classloader: Classloader in Java is a part of the Java Runtime Environment(JRE)

which is used to load Java classes into the Java Virtual Machine dynamically. It adds
security by separating the package for the classes of the local file system from those
that are imported from network sources.
o Bytecode Verifier: It checks the code fragments for illegal code that can violate
access right to objects.
o Security Manager: It determines what resources a class can access such as reading
and writing to the local disk.
Java language provides these securities by default. Some security can also be provided by
an application developer explicitly through SSL, JAAS, Cryptography, etc.
Robust
Robust simply means strong. Java is robust because:
o It uses strong memory management.
o There is a lack of pointers that avoids security problems.
o There is automatic garbage collection in java which runs on the Java Virtual Machine
to get rid of objects which are not being used by a Java application anymore.
o There are exception handling and the type checking mechanism in Java. All these
points make Java robust.
Architecture-neutral
Java is architecture neutral because there are no implementation dependent features, for
example, the size of primitive types is fixed.
In C programming, int data type occupies 2 bytes of memory for 32-bit architecture and 4
bytes of memory for 64-bit architecture. However, it occupies 4 bytes of memory for both
32 and 64-bit architectures in Java.
Portable
Java is portable because it facilitates you to carry the Java bytecode to any platform. It
doesn't require any implementation.
High-performance
Java is faster than other traditional interpreted programming languages because Java
bytecode is "close" to native code. It is still a little bit slower than a compiled language
(e.g., C++). Java is an interpreted language that is why it is slower than compiled
languages, e.g., C, C++, etc.
Distributed
Java is distributed because it facilitates users to create distributed applications in Java. RMI
and EJB are used for creating distributed applications. This feature of Java makes us able to
access files by calling the methods from any machine on the internet.
Multi-threaded
A thread is like a separate program, executing concurrently. We can write Java programs
that deal with many tasks at once by defining multiple threads. The main advantage of
multi-threading is that it doesn't occupy memory for each thread. It shares a common
memory area. Threads are important for multi-media, Web applications, etc.
Dynamic
Java is a dynamic language. It supports dynamic loading of classes. It means classes are
loaded on demand. It also supports functions from its native languages, i.e., C and C++.
Java supports dynamic compilation and automatic memory management (garbage

collection).
JDK Environment and tools
Basic Tools
These tools are the foundation of the JDK. They are the tools you use to create and
build applications.
Tool Name Brief Description
javac The compiler for the Java programming language.
java The launcher for Java applications. In this release, a single

launcher is used both for development and deployment.
The old deployment launcher, jre, is no longer provided.
javadoc API documentation generator.

See Javadoc Tool page for doclet and taglet APIs.
apt Annotation processing tool.

See Annotation Processing Tool for program annotation
processing.
appletviewer Run and debug applets without a web browser.
jar Create and manage Java Archive (JAR) files.

See Java Archive Files page for the JAR specification.
jdb The Java Debugger.
See JPDA for the debugger architecture specifications.
javah C header and stub generator. Used to write native methods.
javap Class file disassembler
extcheck Utility to detect Jar conflicts.
Components of JDK
Following is a list of primary components of JDK:
appletviewer: This tool is used to run and debug Java applets without a web
browser.
apt: It is an annotation-processing tool.
extcheck: it is a utility that detects JAR file conflicts.
idlj: An IDL-to-Java compiler. This utility generates Java bindings from

a given Java IDL file.
jabswitch: It is a Java Access Bridge. Exposes assistive technologies on

Microsoft Windows systems.
java: The loader for Java applications. This tool is an interpreter and can
interpret the class files generated by the javac compiler. Now a
single launcher is used for both development and deployment. The
old deployment launcher, jre, no longer comes with Sun JDK, and
instead it has been replaced by this new java loader.
javac: It specifies the Java compiler, which converts source code into
Java bytecode.
javadoc: The documentation generator, which automatically generates
documentation from source code comments
jar: The specifies the archiver, which packages related class libraries
into a single JAR file. This tool also helps manage JAR files.
javafxpackager: It is a tool to package and sign JavaFX applications.
jarsigner: the jar signing and verification tool.
javah: the C header and stub generator, used to write native methods.
javap: the class file disassembler.
javaws: the Java Web Start launcher for JNLP applications.
JConsole: Java Monitoring and Management Console.
jdb: the debugger.
jhat: Java Heap Analysis Tool (experimental).
jinfo: This utility gets configuration information from a running Java

process or crash dump.
jmap: Oracle jmap - Memory Map- This utility outputs the memory map
for Java and can print shared object memory maps or heap
memory details of a given process or core dump.
jmc: Java Mission Control
jps: Java Virtual Machine Process Status Tool lists the instrumented
HotSpot Java Virtual Machines (JVMs) on the target system.
jrunscript: Java command-line script shell.
jstack: It is a utility that prints Java stack traces of Java threads

(experimental).
jstat: Java Virtual Machine statistics monitoring tool (experimental).
jstatd: jstat daemon (experimental).
keytool: It is a tool for manipulating the keystore.
pack200: JAR compression tool.
Policytool: It specifies the policy creation and management tool, which can
determine policy for a Java runtime, specifying which permissions
are available for code from various sources.
VisualVM: It is a visual tool integrating several command-line JDK tools and

lightweight [clarification needed] performance and memory
profiling capabilities
wsimport: It generates portable JAX-WS artifacts for invoking a web service.
xjc: It is the part of the Java API for XML Binding (JAXB) API. It accepts
an XML schema and generates Java classes.
C++ vs Java
There are many differences and similarities between the C++ programming language
and Java. A list of top differences between C++ and Java are given below:
Comparison C++ Java

Index
Platform- C++ is platform- Java is platform-independent.

independent dependent.
Mainly used for C++ is mainly used for Java is mainly used for
system programming. application programming. It is
widely used in window, web-
based, enterprise and mobile
applications.
Design Goal C++ was designed for Java was designed and created
systems and applications as an interpreter for printing
programming. It was an systems but later extended as a
extension of C support network computing. It
programming language. was designed with a goal of being
easy to use and accessible to a
broader audience.
Goto C++ supports Java doesn't support the goto

the gotostatement. statement.
Multiple C++ supports multiple Java doesn't support multiple

inheritance inheritance. inheritance through class. It can
be achieved by interfaces in java.
Operator C++ supports operator Java doesn't support operator

Overloading overloading. overloading.
Pointers C++ supports pointers. Java supports pointer internally.

You can write pointer However, you can't write the
program in C++. pointer program in java. It means
java has restricted pointer
support in java.
Compiler and C++ uses compiler only. Java uses compiler and
Interpreter C++ is compiled and run interpreter both. Java source
using the compiler which code is converted into bytecode
converts source code into at compilation time. The
machine code so, C++ is interpreter executes this
platform dependent. bytecode at runtime and
produces output. Java is
interpreted that is why it is
platform independent.
Call by Value C++ supports both call by Java supports call by value only.
and Call by value and call by reference. There is no call by reference in
reference java.
Structure and C++ supports structures Java doesn't support structures

Union and unions. and unions.
Thread Support C++ doesn't have built-in Java has built-in thread support.
support for threads. It
relies on third-party
libraries for thread support.
Documentation C++ doesn't support Java supports documentation

comment documentation comment. comment (/** ... */) to create
documentation for java source
code.
Virtual Keyword C++ supports virtual Java has no virtual keyword. We

keyword so that we can can override all non-static
decide whether or not methods by default. In other
override a function. words, non-static methods are
virtual by default.
unsigned right C++ doesn't support >>> Java supports unsigned right shift
shift >>> operator. >>> operator that fills zero at
the top for the negative numbers.
For positive numbers, it works
same like >> operator.
Inheritance C++ creates a new Java uses a single inheritance

Tree inheritance tree always. tree always because all classes
are the child of Object class in
java. The object class is the root
of the inheritance tree in java.
Hardware C++ is nearer to hardware. Java is not so interactive with

hardware.
Object-oriented C++ is an object-oriented Java is also an object-

language. However, in C oriented language. However,
language, single root everything (except fundamental
hierarchy is not possible. types) is an object in Java. It is a
single root hierarchy as
everything gets derived from
java.lang.Object.
Note
o Java doesn't support default arguments like C++.
o Java does not support header files like C++. Java uses the import keyword to include
different classes and methods.
C++ Example
File: main.cpp
1. #include <iostream>
2. using namespace std;
3. int main() {
4. cout << "Hello C++ Programming";
5. return 0;
6. }
Java Example
File: Simple.java
1. class Simple{
2. public static void main(String args[]){
3. System.out.println("Hello Java");
4. }
5. }
Structure of Java Program
Lesson: A Closer Look at the "Hello World!" Application

Now that you've seen the "Hello World!" application (and perhaps even compiled and run it), you might be
wondering how it works. Here again is its code:
}
}
The "Hello World!" application consists of three primary components: source code
comments, the HelloWorldApp class definition, and the main method. The following explanation will provide
you with a basic understanding of the code, but the deeper implications will only become apparent after you've
finished reading the rest of the tutorial.
Source Code Comments
The following bold text defines the comments of the "Hello World!" application:
/**
* simply prints "Hello World!" to standard output.
*/
}
}
Comments are ignored by the compiler but are useful to other programmers. The Java programming language
supports three kinds of comments:
/* text */
The compiler ignores everything from /* to */.
/** documentation */
This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of
comment, just like it ignores comments that use /* and */. The javadoc tool uses doc comments
when preparing automatically generated documentation. For more information on javadoc, see
the Javadoc™ tool documentation .
// text
The compiler ignores everything from // to the end of the line.
The HelloWorldApp Class Definition
The following bold text begins the class definition block for the "Hello World!" application:
/**
* simply displays "Hello World!" to the standard output.
*/
}
}
As shown above, the most basic form of a class definition is:
class name {
. . .
}
The keyword class begins the class definition for a class named name, and the code for each class appears
between the opening and closing curly braces marked in bold above. Chapter 2 provides an overview of
classes in general, and Chapter 4 discusses classes in detail. For now it is enough to know that every
application begins with a class definition.
The main Method
The following bold text begins the definition of the main method:
/**
* simply displays "Hello World!" to the standard output.
*/
System.out.println("Hello World!"); //Display the string.
}
}
In the Java programming language, every application must contain a main method whose signature is:
public static void main(String[] args)
The modifiers public and static can be written in either order (public static or static public),
but the convention is to use public static as shown above. You can name the argument anything you
want, but most programmers choose "args" or "argv".
The main method is similar to the main function in C and C++; it's the entry point for your application and will
subsequently invoke all the other methods required by your program.
The main method accepts a single argument: an array of elements of type String.
public static void main(String[] args)
This array is the mechanism through which the runtime system passes information to your application. For
example:
java MyApp arg1 arg2
Each string in the array is called a command-line argument. Command-line arguments let users affect the
operation of the application without recompiling it. For example, a sorting program might allow the user to
specify that the data be sorted in descending order with this command-line argument:
-descending
The "Hello World!" application ignores its command-line arguments, but you should be aware of the fact that
such arguments do exist.
Finally, the line:
System.out.println("Hello World!");
uses the System class from the core library to print the "Hello World!" message to standard output. Portions of
this library (also known as the "Application Programming Interface", or "API") will be discussed throughout the
remainder of the tutorial.
J2SE Contents
Javadoc 5.0
Tool
Javadoc is a tool that parses the declarations and documentation comments in a set of
source files and produces a set of HTML pages describing the classes, interfaces,
constructors, methods, and fields.
You can use Javadoc doclets to customize Javadoc output. A doclet is a program
written with the Doclet API that specifies the content and format of the output to be
generated by the Javadoc tool. You can write a doclet to generate any kind of text-file
output, such as HTML, SGML, XML, RTF, and MIF. Sun provides a "standard" TM
doclet for generating HTML-format API documentation and an experimental MIF

doclet for generating MIF, PDF, FrameMaker, and other formats. Doclets can also be
used to perform special tasks not related to producing
appletviewer - The Java Applet Viewer

The appletviewer command allows you to run applets outside of a web browser.
SYNOPSIS
appletviewer [ options ] urls ...
DESCRIPTION
The appletviewer command connects to the documents or resources designated by urls and displays each applet
referenced by the documents in its own window. Note: if the documents referred to by urls do not reference any
applets with the OBJECT, EMBED, or APPLET tag, then appletviewer does nothing. For details on the HTML tags
that appletviewer supports, see AppletViewer Tags.
Note: The appletviewer is intended for development purposes only. See About Sample / Test Applications and
Code for more information.
The Java 2 JDK contains two implementations of the Java virtual machine:
Note: The appletviewer requires encoded URLs according to the escaping mechanism defined in RFC2396. Only
encoded URLs are supported. However, file names must be unencoded, as specified in RFC2396.
 The Java HotSpot™ Client VM

The Java HotSpot Client VM is the default virtual machine. Its use of Java HotSpot technology gives it superior
performance as compared with the Classic VM. Unless special command-line options are used to invoke the
Classic VM instead (see below), appletviewer will always launch an applet to run on the Client VM.
 The Java 2 Classic VM
The Java 2 Classic VM is essentially the same virtual machine implementation as in version 1.2 of the Java 2
SDK. It may be invoked by using the -classic command-line option, as in this example:
 appletviewer -classic MyApplet.html
OPTIONS
-debug
Starts the applet viewer in the Java debugger, jdb, thus allowing you to debug the applets in the document.
-encoding encoding name

Specifies the input HTML file encoding name.
-Jjavaoption
Passes through the string javaoption as a single argument to the Java interpreter which runs the
appletviewer. The argument should not contain spaces. Multiple argument words must all begin with the
prefix -J, which is stripped. This is useful for adjusting the compiler's execution environment or memory
usage
Skip to Content
Search
javac - Java programming language compiler

 Synopsis
 Description
 Options
 Command Line Argument Files
 Annotation Processing
 Searching for Types
 Programmatic Interface
 Examples
 See Also
SYNOPSIS
javac [ options ] [ sourcefiles ] [ classes ] [ @argfiles ]
Arguments may be in any order.
options
Command-line options.
sourcefiles
One or more source files to be compiled (such as MyClass.java).
classes
One or more classes to be processed for annotations (such as MyPackage.MyClass).
@argfiles
One or more files that lists options and source files. The -J options are not allowed in these files.
DESCRIPTION
The javac tool reads class and interface definitions, written in the Java programming language, and compiles them
into bytecode class files. It can also process annotations in Java source files and classes.
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 C:\workspace, the source code for com.mysoft.mypack.MyClass should be
in C:\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).
OPTIONS
The compiler has a set of standard options that are supported on the current development environment and will be
supported in future releases. An additional set of non-standard options are specific to the current virtual machine and
compiler implementations and are subject to change in the future. Non-standard options begin with -X.
Standard Options
-Akey[=value]
Options to pass to annotation processors. These are not interpreted by javac directly, but are made
available for use by individual processors. key should be one or more identifiers separated by ".".
-cp path or -classpath path
Specify where to find user class files, and (optionally) annotation processors and source files. This class
path overrides the user class path in the CLASSPATH environment variable. If neither CLASSPATH, -
cp nor -classpath is specified, the user class path consists of the current directory. See Setting the Class
Path for more details.
If the -sourcepath option is not specified, the user class path is also searched for source files.
If the -processorpath option is not specified, the class path is also searched for annotation processors.
-Djava.ext.dirs=directories
Override the location of installed extensions.
-Djava.endorsed.dirs=directories
Override the location of endorsed standards path.
-d directory
Set the destination directory for class files. The directory must already exist; javac will not create it. If a class
is part of a package, javac puts the class file in a subdirectory reflecting the package name, creating
directories as needed. For example, if you specify -d C:\myclasses and the class is
called com.mypackage.MyClass, then the class file is
called C:\myclasses\com\mypackage\MyClass.class.
If -d is not specified, javac puts each class files in the same directory as the source file from which it was
generated.
Note: 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 a summary of the source files that use or override deprecated members or
classes. -deprecation is shorthand for -Xlint:deprecation.
-encoding encoding
Set the source file encoding name, such as EUC-JP and UTF-8. If -encoding is not specified, the
platform default converter is used.
-endorseddirs directories
Override the location of endorsed standards path.
-extdirs directories
Overrides the location of the ext directory. The directories variable is a colon-separated list of directories.
Each JAR archive in the specified directories is searched for class files. All JAR archives found are
automatically part of the class path.
If you are cross-compiling (compiling classes against bootstrap and extension classes of a different Java
platform implementation), this option specifies the directories that contain the extension classes. See Cross-
Compilation Options for more information.
-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.
-implicit:{class,none}
Controls the generation of class files for implicitly loaded source files. To automatically generate class files,
use -implicit:class. To suppress class file generation, use -implicit:none. If this option is not specified, the
default is to automatically generate class files. In this case, the compiler will issue a warning if any such
class files are generated when also doing annotation processing. The warning will not be issued if this option
is set explicitly. See Searching For Types.
-Joption
Pass option to the java launcher called by javac. For example, -J-Xms48m sets the startup memory to 48
megabytes. 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.
-nowarn
Disable warning messages. This has the same meaning as -Xlint:none.
-proc: {none,only}
Controls whether annotation processing and/or compilation is done. -proc:none means that compilation
takes place without annotation processing. -proc:only means that only annotation processing is done,
without any subsequent compilation.
-processor class1[,class2,class3...]
Names of the annotation processors to run. This bypasses the default discovery process.
-processorpath path
Specify where to find annotation processors; if this option is not used, the class path will be searched for
processors.
-s dir
Specify the directory where to place generated source files. The directory must already exist; javac will not
create it. If a class is part of a package, the compiler puts the source file in a subdirectory reflecting the
package name, creating directories as needed. For example, if you specify -s C:\mysrc and the class is
called com.mypackage.MyClass, then the source file will be placed
in C:\mysrc\com\mypackage\MyClass.java.
-source release
Specifies the version of source code accepted. The following values for release are allowed:
1.3
The compiler does not support assertions, generics, or other language features introduced after Java SE
1.3.
1.4
The compiler accepts code containing assertions, which were introduced in Java SE 1.4.
1.5
The compiler accepts code containing generics and other language features introduced in Java SE 5.
Synonym for 1.5.
1.6
No language changes were introduced in Java SE 6. However, encoding errors in source files are now
reported as errors instead of warnings as in previous releases of Java SE.
Synonym for 1.6.
1.7
This is the default value. The compiler accepts code with features introduced in Java SE 7.
Synonym for 1.7.
-sourcepath sourcepath
Specify the source code path to search for class or interface definitions. As with the user class path, source
path entries are separated by semicolons (;) and 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: Classes found through the class path may be subject to automatic recompilation if their sources are
also found. See Searching For Types.
-verbose
Verbose output. This includes information about each class loaded and each source file compiled.
-version
Print version information.
-Werror
Terminate compilation if warnings occur.
-X
Display information about non-standard options and exit.

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;
see Cross-Compilation Example below.
-target version
Generate class files that target a specified version of the VM. Class files will run on the specified target and
on later versions, but not on earlier versions of the VM. Valid targets
are 1.1, 1.2, 1.3, 1.4, 1.5 (also 5), 1.6 (also 6), and 1.7 (also 7).
The default for -target depends on the value of -source:
 If -source is not specified, the value of -target is 1.7

 If -source is 1.2, the value of -target is 1.4
 For all other values of -source, the value of -target is the value of -source.
-bootclasspath bootclasspath
Cross-compile against the specified set of boot classes. As with the user class path, boot class path entries
are separated by colons (:) and can be directories, JAR archives, or ZIP archives.
Non-Standard Options
-Xbootclasspath/p:path
Prepend to the bootstrap class path.
-Xbootclasspath/a:path
Append to the bootstrap class path.
-Xbootclasspath/:path
Override location of bootstrap class files.
-Xlint
Enable all recommended warnings. In this release, enabling all available warnings is recommended.
-Xlint:all
Enable all recommended warnings. In this release, enabling all available warnings is recommended.
-Xlint:none
Disable all warnings.
-Xlint:name
Enable warning name. See the section Warnings That Can Be Enabled or Disabled with -Xlint Option for a
list of warnings you can enable with this option.
-Xlint:-name
Disable warning name. See the section Warnings That Can Be Enabled or Disabled with -Xlint Option for a
list of warnings you can disable with this option.
-Xmaxerrs number
Set the maximum number of errors to print.
-Xmaxwarns number
Set the maximum number of warnings to print.
-Xstdout filename
Send compiler messages to the named file. By default, compiler messages go to System.err.
-Xprefer:{newer,source}
Specify which file to read when both a source file and class file are found for a type. (See Searching For
Types). If -Xprefer:newer is used, it reads the newer of the source or class file for a type (default). If the -
Xprefer:source option is used, it reads source file. Use -Xprefer:source when you want to be sure that any
annotation processors can access annotations declared with a retention policy of SOURCE.
-Xpkginfo:{always,legacy,nonempty}
Specify handling of package-info files
-Xprint
Print out textual representation of specified types for debugging purposes; perform neither annotation
processing nor compilation. The format of the output may change.
-XprintProcessorInfo
Print information about which annotations a processor is asked to process.
-XprintRounds
Print information about initial and subsequent annotation processing rounds.
Warnings That Can Be Enabled or Disabled with -Xlint Option

Enable warning name with the option -Xlint:name, where name is one of the following warning names. Similarly, you
can disable warning name with the option -Xlint:-name:
cast
Warn about unnecessary and redundant casts. For example:
String s = (String)"Hello!"
classfile
Warn about issues related to classfile contents.
deprecation
Warn about use of deprecated items. For example:
java.util.Date myDate = new java.util.Date();

int currentDay = myDate.getDay();
The method java.util.Date.getDay has been deprecated since JDK 1.1.
dep-ann
Warn about items that are documented with an @deprecated Javadoc comment, but do not have
a @Deprecated annotation. For example:
/**
* @deprecated As of Java SE 7, replaced by {@link #newMethod()}
*/
public static void deprecatedMethood() { }
public static void newMethod() { }

divzero
Warn about division by constant integer 0. For example:
int divideByZero = 42 / 0;
empty
Warn about empty statements after if statements. For example:
class E {
void m() {
if (true) ;
}
}
fallthrough
Check switch blocks for fall-through cases and provide a warning message for any that are found. Fall-
through cases are cases in a switch block, other than the last case in the block, whose code does not
include a break statement, allowing code execution to "fall through" from that case to the next case. For
example, the code following the case 1label in this switch block does not end with a break statement:
switch (x) {
case 1:
System.out.println("1");
// No break statement here.
case 2:
}
If the -Xlint:fallthrough flag were used when compiling this code, the compiler would emit a
warning about "possible fall-through into case," along with the line number of the case in question.
finally
Warn about finally clauses that cannot complete normally. For example:
public static int m() {

try {
throw new NullPointerException();
} catch (NullPointerException e) {
System.err.println("Caught NullPointerException.");
return 1;
} finally {
return 0;
}
}
The compiler generates a warning for finally block in this example. When this method is called, it
returns a value of 0, not 1. A finally block always executes when the tryblock exits. In this example, if
control is transferred to the catch, then the method exits. However, the finally block must be
executed, so it is executed, even though control has already been transferred outside the method.
options
Warn about issues relating to the use of command line options. See Cross-Compilation Example for an
example of this kind of warning.
overrides
Warn about issues regarding method overrides. For example, consider the following two classes:
public class ClassWithVarargsMethod {

void varargsMethod(String... s) { }
}
public class ClassWithOverridingMethod extends ClassWithVarargsMethod {
@Override
void varargsMethod(String[] s) { }
}
The compiler generates a warning similar to the following:
warning: [override] varargsMethod(String[]) in

ClassWithOverridingMethod overrides varargsMethod(String...) in
ClassWithVarargsMethod; overriding method is missing '...'
When the compiler encounters a varargs method, it translates the varargs formal parameter into an array. In
the method ClassWithVarargsMethod.varargsMethod, the compiler translates the varargs
formal parameter String... s to the formal parameter String[] s, an array, which matches the
formal parameter of the method ClassWithOverridingMethod.varargsMethod. Consequently,
this example compiles.
path
Warn about invalid path elements and nonexistent path directories on the command line (with regards to the
class path, the source path, and other paths). Such warnings cannot be suppressed with
the @SuppressWarnings annotation. For example:
javac -Xlint:path -classpath C:\nonexistentpath Example.java

processing
Warn about issues regarding annotation processing. The compiler generates this warning if you have a
class that has an annotation, and you use an annotation processor that cannot handle that type of
exception. For example, the following is a simple annotation processor:
Source file AnnoProc.java:
import java.util.*;
import javax.annotation.processing.*;
import javax.lang.model.*;
import javax.lang.model.element.*;
@SupportedAnnotationTypes("NotAnno")
public class AnnoProc extends AbstractProcessor {
public boolean process(Set<? extends TypeElement> elems,
RoundEnvironment renv) {
return true;
}
public SourceVersion getSupportedSourceVersion() {

return SourceVersion.latest();
}
}
Source file AnnosWithoutProcessors.java:
@interface Anno { }
@Anno
class AnnosWithoutProcessors { }
The following commands compile the annotation processor AnnoProc, then run this annotation processor
against the source file AnnosWithoutProcessors.java:
C:\>javac AnnoProc.java
C:\>javac -cp . -Xlint:processing -processor AnnoProc -proc:only
AnnosWithoutProcessors.java
When the compiler runs the annotation processor against the source
file AnnosWithoutProcessors.java, it generates the following warning:
warning: [processing] No processor claimed any of these annotations:

Anno
To resolve this issue, you can rename the annotation defined and used in the
class AnnosWithoutProcessors from Anno to NotAnno.
rawtypes
Warn about unchecked operations on raw types. The following statement generates a rawtypes warning:
void countElements(List l) { ... }

The following does not generate a rawtypes warning:
void countElements(List<?> l) { ... }

List is a raw type. However, List<?> is a unbounded wildcard parameterized type. Because List is a
parameterized interface, you should always specify its type argument. In this example, the List formal
argument is specified with a unbounded wildcard (?) as its formal type parameter, which means that
the countElements method can accept any instantiation of the List interface.
serial
Warn about missing serialVersionUID definitions on serializable classes. For example:
public class PersistentTime implements Serializable

{
private Date time;
public PersistentTime() {
time = Calendar.getInstance().getTime();
}
public Date getTime() {
return time;
}
}
The compiler generates the following warning:
warning: [serial] serializable class PersistentTime has no definition

of serialVersionUID
If a serializable class does not explicitly declare a field named serialVersionUID, then the serialization
runtime will calculate a default serialVersionUID value for that class based on various aspects of the
class, as described in the Java Object Serialization Specification. However, it is strongly recommended that
all serializable classes explicitly declare serialVersionUID values because the default process of
computing serialVersionUID vales is highly sensitive to class details that may vary depending on
compiler implementations, and can thus result in unexpected InvalidClassExceptions during
deserialization. Therefore, to guarantee a consistent serialVersionUID value across different Java
compiler implementations, a serializable class must declare an explicit serialVersionUID value.
static
Warn about issues relating to use of statics. For example:
class XLintStatic {
static void m1() { }
void m2() { this.m1(); }
}
warning: [static] static method should be qualified by type name,

XLintStatic, instead of by an expression
To resolve this issue, you can call the static method m1 as follows:
XLintStatic.m1();
Alternatively, you can remove the static keyword from the declaration of the method m1.
try
Warn about issues relating to use of try blocks, including try-with-resources statements. For example, a
warning is generated for the following statement because the resource acdeclared in the try statement is
not used:
try ( AutoCloseable ac = getResource() ) {

// do nothing
}
unchecked
Give more detail for unchecked conversion warnings that are mandated by the Java Language Specification.
For example:
List l = new ArrayList<Number>();

List<String> ls = l; // unchecked warning
During type erasure, the
types ArrayList<Number> and List<String> become ArrayList and List, respectively.
The variable ls has the parameterized type List<String>. When the List referenced by l is
assigned to ls, the compiler generates an unchecked warning; the compiler is unable to determine at
compile time, and moreover knows that the JVM will not be able to determine at runtime, if l refers to
a List<String> type; it does not. Consequently, heap pollution occurs.
In detail, a heap pollution situation occurs when the List object l, whose static type is List<Number>,
is assigned to another List object, ls, that has a different static type, List<String>. However, the
compiler still allows this assignment. It must allow this assignment to preserve backwards compatibility with
versions of Java SE that do not support generics. Because of type
erasure, List<Number> and List<String> both become List. Consequently, the compiler allows
the assignment of the object l, which has a raw type of List, to the object ls.
varargs
Warn about unsafe usages of variable arguments (varargs) methods, in particular, those that contain non-
reifiable arguments. For example:
public class ArrayBuilder {

public static <T> void addToList (List<T> listArg, T... elements) {
for (T x : elements) {
listArg.add(x);
}
}
}
The compiler generates the following warning for the definition of the
method ArrayBuilder.addToList:
warning: [varargs] Possible heap pollution from parameterized vararg

type T
When the compiler encounters a varargs method, it translates the varargs formal parameter into an array.
However, the Java programming language does not permit the creation of arrays of parameterized types. In
the method ArrayBuilder.addToList, the compiler translates the varargs formal parameter T...
elements to the formal parameter T[] elements, an array. However, because of type erasure, the
compiler converts the varargs formal parameter to Object[] elements. Consequently, there is a
possibility of heap pollution.
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. If a filename contains embedded spaces, put the whole filename in double
quotes, and double each backslash ("My Files\\Stuff.java").
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. The -J options are not supported because they are passed to the launcher, which does not support
argument files.
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.
Example - Single Arg File

You could use a single argument file named "argfile" to hold all javac arguments:
C:\>javac @argfile
This argument file could contain the contents of both files shown in the next example.
Example - Two Arg Files

You can create two argument files -- one for the javac options and the other for the source filenames: (Notice the
following lists have no line-continuation characters.)
Create a file named "options" containing:
-d classes
-g
-sourcepath C:\java\pubs\ws\1.3\src\share\classes
Create a file named "classes" containing:
MyClass1.java
MyClass2.java
MyClass3.java
You would then run javac with:
C:\>javac @options @classes
Example - Arg Files with Paths

The argument files can have paths, but any filenames inside the files are relative to the current working directory
(not path1 or path2):
C:\>javac @path1\options @path2\classes
ANNOTATION PROCESSING
javac provides direct support for annotation processing, superseding the need for the separate annotation processing
tool, apt.
The API for annotation processors is defined in

the javax.annotation.processing and javax.lang.model packages and subpackages.
Overview of annotation processing

Unless annotation processing is disabled with the -proc:none option, the compiler searches for any annotation
processors that are available. The search path can be specified with the -processorpath option; if it is not given, the
user class path is used. Processors are located by means of service provider-configuration files named META-
INF/services/javax.annotation.processing.Processor on the search path. Such files should
contain the names of any annotation processors to be used, listed one per line. Alternatively, processors can be
specified explicitly, using the -processor option.
After scanning the source files and classes on the command line to determine what annotations are present, the
compiler queries the processors to determine what annotations they process. When a match is found, the processor
will be invoked. A processor may "claim" the annotations it processes, in which case no further attempt is made to
find any processors for those annotations. Once all annotations have been claimed, the compiler does not look for
additional processors.
If any processors generate any new source files, another round of annotation processing will occur: any newly
generated source files will be scanned, and the annotations processed as before. Any processors invoked on
previous rounds will also be invoked on all subsequent rounds. This continues until no new source files are
generated.
After a round occurs where no new source files are generated, the annotation processors will be invoked one last
time, to give them a chance to complete any work they may need to do. Finally, unless the -proc:only option is used,
the compiler will compile the original and all the generated source files.
Implicitly loaded source files

To compile a set of source files, the compiler may need to implicitly load additional source files. (See Searching For
Types). Such files are currently not subject to annotation processing. By default, the compiler will give a warning if
annotation processing has occurred and any implicitly loaded source files are compiled. See the -implicit option for
ways to suppress the warning.
SEARCHING FOR TYPES

When compiling a source file, the compiler often needs information about a type whose definition did not appear in
the source files given on the command line. 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.
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.lang.Object.
When the compiler needs type information, it looks for a source file or class file which defines the type. The compiler
searches for class files first in the bootstrap and extension classes, then in the user class path (which by default is the
current directory). The user class path is defined by setting the CLASSPATH environment variable or by using the -
classpath command line option. (For details, see Setting the Class Path).
If you set the -sourcepath option, the compiler searches the indicated path for source files; otherwise the compiler
searches the user class path for both class files and source files.
You can specify different bootstrap or extension classes with the -bootclasspath and -extdirs options; see Cross-
Compilation Options below.
A successful type search may produce a class file, a source file, or both. If both are found, you can use the -
Xprefer option to instruct the compiler which to use. If newer is given, the compiler will use the newer of the two files.
If source is given, it will use the source file. The default is newer.
If a type search finds a source file for a required type, either by itself, or as a result of the setting for -Xprefer, the
compiler will read the source file to get the information it needs. In addition, it will by default compile the source file as
well. You can use the -implicit option to specify the behavior. If none is given, no class files will be generated for the
source file. If classis given, class files will be generated for the source file.
The compiler may not discover the need for some type information until after annotation processing is complete. If the
type information is found in a source file and no -implicit option is given, the compiler will give a warning that the file
is being compiled without being subject to annotation processing. To disable the warning, either specify the file on the
command line (so that it will be subject to annotation processing) or use the -implicit option to specify whether or not
class files should be generated for such source files.
PROGRAMMATIC INTERFACE
javac supports the new Java Compiler API defined by the classes and interfaces in the javax.tools package.
Example
To perform a compilation using arguments as you would give on the command line, you can use the following:
JavaCompiler javac = ToolProvider.getSystemJavaCompiler();

int rc = javac.run(null, null, null, args);
This will write any diagnostics to the standard output stream, and return the exit code that javac would give when
invoked from the command line.
You can use other methods on the javax.tools.JavaCompiler interface to handle diagnostics, control where
files are read from and written to, and so on.
Old Interface
Note: This API is retained for backwards compatibility only; all new code should use the Java Compiler API,
described above.
The com.sun.tools.javac.Main class provides two static methods to invoke the compiler from a program:
public static int compile(String[] args);

public static int compile(String[] args, PrintWriter out);
The args parameter represents any of the command line arguments that would normally be passed to the javac
program and are outlined in the above Synopsis section.
The out parameter indicates where the compiler's diagnostic output is directed.
The return value is equivalent to the exit value from javac.
Note that all other classes and methods found in a package whose name starts
with com.sun.tools.javac (informally known as sub-packages of com.sun.tools.javac) are strictly
internal and subject to change at any time.
EXAMPLES
Compiling a Simple Program
The following source file, C:\greetings\Hello.java, defines a class called greetings.Hello:
package greetings;
public class Hello {

for (int i=0; i < args.length; i++) {
System.out.println("Hello " + args[i]);
}
}
}
The greetings directory is the package directory both for the source file and the class file and is off the current
directory. This allows us to use the default user class path. It also makes it unnecessary to specify a separate
destination directory with -d.
C:\>javac greetings\Hello.java
C:\>dir greetings /B
Hello.class
Hello.java
C:\>java greetings.Hello World Universe Everyone
Hello World
Hello Universe
Hello Everyone
Compiling Multiple Source Files
This example compiles all the source files in the package greetings.
C:\>dir /B
greetings
Aloha.java
GutenTag.java
Hello.java
Hi.java
C:\>javac greetings\*.java
Aloha.class
Aloha.java
GutenTag.class
GutenTag.java
Hello.class
Hello.java
Hi.class
Hi.java
Specifying a User Class Path
Having changed one of the source files in the previous example, we recompile it:
C:\>cd
\examples
C:\>javac greetings\Hi.java
Since greetings.Hi refers to other classes in the greetings package, the compiler needs to find these other
classes. The example above works, because our default user class path happens to be the directory containing the
package directory. But suppose we want to recompile this file and not worry about which directory we're in? Then we
need to add \examplesto the user class path. We can do this by setting CLASSPATH, but here we'll use the -
classpath option.
C:\>javac -classpath \examples \examples\greetings\Hi.java
If we change greetings.Hi again, to use a banner utility, that utility also needs to be accessible through the user
class path.
C:\>javac -classpath \examples;\lib\Banners.jar ^

\examples\greetings\Hi.java
To execute a class in greetings, we need access both to greetings and to the classes it uses.
C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi
Separating Source Files and Class Files

It often makes sense to keep source files and class files in separate directories, especially on large projects. We use -
d to indicate the separate class file destination. Since the source files are not in the user class path, we use -
sourcepath to help the compiler find them.
C:\>dir /B
classes
lib
src
C:\>dir src
farewells
C:\>dir src\farewells
Base.java
GoodBye.java
C:\>dir lib
Banners.jar
C:\>dir classes
C:\>javac -sourcepath src -classpath classes;lib\Banners.jar ^
src\farewells\GoodBye.java -d classes
C:\>dir classes
farewells
C:\>dir classes\farewells
Base.class
GoodBye.class
Note: The compiler compiled src\farewells\Base.java, even though we didn't specify it on the command
line. To trace automatic compiles, use the -verbose option.
Cross-Compilation Example
The following example uses javac to compile code that will run on a 1.6 VM.
C\:>javac -source 1.6 -target 1.6 -bootclasspath C:\jdk1.6.0\lib\rt.jar ^

-extdirs "" OldCode.java
The -source 1.6 option specifies that version 1.6 (or 6) of the Java programming language be used to
compile OldCode.java. The option -target 1.6 option ensures that the generated class files will be compatible
with 1.6 VMs. Note that in most cases, the value of the -target option is the value of the -source option; in this
example, you can omit the -targetoption.
You must specify the -bootclasspath option to specify the correct version of the bootstrap classes
(the rt.jar library). If not, the compiler generates a warning:
C:\>javac -source 1.6 OldCode.java

warning: [options] bootstrap class path not set in conjunction with -source 1.6
If you do not specify the correct version of bootstrap classes, the compiler will use the old language rules (in this
example, it will use version 1.6 of the Java programming language) combined with the new bootstrap classes, which
can result in class files that do not work on the older platform (in this case, Java SE 6) because reference to non-
existent methods can get included.
SEE ALSO
 javac Guide
 java - the Java Application Launcher
 jdb - Java Application Debugger
 javah - C Header and Stub File Generator
 javap - Class File Disassembler
 javadoc - API Documentation Generator
 jar - JAR Archive Tool
 The Java Extensions Framework
Copyright © 1993, 2018, Oracle and/or its affiliates. All rights reserved.
Contact Us
javadoc
Generates HTML pages of API documentation from Java source files.
Synopsis
javadoc {packages|source-files} [options] [@argfiles]
packages
Names of packages that you want to document, separated by spaces, for example java.lang
java.lang.reflect java.awt. If you want to also document the subpackages, use the -
subpackages option to specify the packages.
By default, javadoc looks for the specified packages in the current directory and subdirectories. Use the -
sourcepath option to specify the list of directories where to look for packages.
source-files
Names of Java source files that you want to document, separated by spaces, for example Class.java
Object.java Button.java. By default, javadoc looks for the specified classes in the current
directory. However, you can specify the full path to the class file and use wildcard characters, for
example /home/src/java/awt/Graphics*.java. You can also specify the path relative to the
current directory.
options
Command-line options, separated by spaces. See Options.
@argfiles
Names of files that contain a list of javadoc command options, package names and source file names in
any order.
Description
The javadoc command parses the declarations and documentation comments in a set of Java source files and
produces a corresponding set of HTML pages that describe (by default) the public and protected classes, nested
classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use
the javadoc command to generate the API documentation or the implementation documentation for a set of source
files.
You can run the javadoc command on entire packages, individual source files, or both. When documenting entire
packages, you can either use the -subpackages option to recursively traverse a directory and its subdirectories,
or to pass in an explicit list of package names. When you document individual source files, pass in a list of Java
source file names. See Simple Examples.
Conformance
The standard doclet does not validate the content of documentation comments for conformance nor does it attempt to
correct any errors in documentation comments. Be aware of the problems that may arise when generating non-
conforming output or output containing executable content, such as JavaScript, when running
the javadoc command. The standard doclet does provide the -Xdoclint option to help you detect common
problems in documentation comments; however, it is also recommended to check the generated output with any
appropriate conformance and checking tools.
For more information about conformance requirements for HTML5 documents, see Conformance requirements in the
HTML5 specification. For more information about security issues related to web pages, see Open Web Application
Security Project (OWASP).
Process Source Files

The javadoc command processes files that end in source and other files described in Source Files. If you run
the javadoc command by passing in individual source file names, then you can determine exactly which source
files are processed. However, that is not how most developers want to work, because it is simpler to pass in package
names. The javadoccommand can be run three ways without explicitly specifying the source file names. You can
pass in package names, use the -subpackages option, or use wild cards with source file names. In these cases,
the javadoc command processes a source file only when the file fulfills all of the following requirements:
 The file name prefix (with .java removed) is a valid class name.
 The path name relative to the root of the source tree is a valid package name after the separators are converted
to dots.
 The package statement contains the valid package name.
Processing Links
During a run, the javadoc command adds cross-reference links to package, class, and member names that are
being documented as part of that run. Links appear in the following places. See Javadoc Tags for a description of the
@ tags.
 Declarations (return types, argument types, and field types).
 See Also sections that are generated from @see tags.
 Inline text generated from {@link} tags.
 Exception names generated from @throws tags.
 Specified by links to interface members and Overrides links to class members. See Method Comment
Inheritance.
 Summary tables listing packages, classes and members.
 Package and class inheritance trees.
 The index.
You can add links to existing text for classes not included on the command line (but generated separately) by way of
the -link and -linkoffline options.
Processing Details
The javadoc command produces one complete document every time it runs. It does not do incremental builds that
modify or directly incorporate the results from earlier runs. However, the javadoc command can link to results from
other runs.
The javadoc command implementation requires and relies on the Java compiler. The javadoc command calls
part of the javac command to compile the declarations and ignore the member implementations.
The javadoc command builds a rich internal representation of the classes that includes the class hierarchy and use
relationships to generate the HTML. The javadoc command also picks up user-supplied documentation from
documentation comments in the source code. See Documentation Comments.
The javadoc command runs on source files that are pure stub files with no method bodies. This means you can
write documentation comments and run the javadoc command in the early stages of design before API
implementation.
Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which
may rely on implicit, rather than explicit, source code. For example, the javadoc command documents default
constructors that are present in the compiled class files but not in the source code.
In many cases, the javadoc command lets you generate documentation for source files with incomplete or
erroneous code. You can generate documentation before all debugging and troubleshooting is done.
The javadoc command does primitive checking of documentation comments.
When the javadoc command builds its internal structure for the documentation, it loads all referenced classes.
Because of this, the javadoc command must be able to find all referenced classes, whether bootstrap classes,
extensions, or user classes. See How Classes Are Found at
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html
Typically, classes you create must either be loaded as an extension or in the javadoc command class path.
Javadoc Doclets
You can customize the content and format of the javadoc command output with doclets. The javadoc command
has a default built-in doclet, called the standard doclet, that generates HTML-formatted API documentation. You can
modify or make a subclass of the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or
whatever output format you want.
When a custom doclet is not specified with the -doclet option, the javadoc command uses the default standard
doclet. The javadoc command has several options that are available regardless of which doclet is being used. The
standard doclet adds a supplementary set of command-line options. See Options.
Source Files
The javadoc command generates output that originates from the following types of source files: Java language
source files for classes (.java), package comment files, overview comment files, and miscellaneous unprocessed
files. This section also describes test files and template files that can also be in the source tree, but that you want to
be sure not to document.
Class Source Files

Each class or interface and its members can have their own documentation comments contained in a source file.
See Documentation Comments.
Package Comment Files

Each package can have its own documentation comment, contained in its own source file, that
the javadoc command merges into the generated package summary page. You typically include in this comment
any documentation that applies to the entire package.
To create a package comment file, you can place your comments in one of the following files:
 The package-info.java file can contain the package declaration, package annotations, package
comments, and Javadoc tags. This file is preferred.
 The package.html file contains only package comments and Javadoc tags. No package annotations.
A package can have a single package.html file or a single package-info.java file, but not both. Place
either file in the package directory in the source tree with your source files.
The package-info.java File
The package-info.java file can contain a package comment of the following structure. The comment is placed
before the package declaration.
Note: The comment separators /** and */ must be present, but the leading asterisks on the intermediate lines can
be left off.
/**
* Provides the classes necessary to create an
* applet and the classes an applet uses
* to communicate with its applet context.
* 
* The applet framework involves two entities:
* the applet and the applet context.
* An applet is an embeddable window (see the
* {@link java.awt.Panel} class) with a few extra
* methods that the applet context can use to
* initialize, start, and stop the applet.
*
* @since 1.0
* @see java.awt
*/
package java.lang.applet;
The package.html File
The package.html file can contain a package comment of the following structure. The comment is placed in
the <body> element.
File: java/applet/package.html
<HTML>
<BODY>
Provides the classes necessary to create an applet and the
classes an applet uses to communicate with its applet context.

The applet framework involves two entities: the applet
and the applet context. An applet is an embeddable
window (see the {@link java.awt.Panel} class) with a
few extra methods that the applet context can use to
initialize, start, and stop the applet.
@since 1.0
@see java.awt
</BODY>
</HTML>
The package.html file is a typical HTML file and does not include a package declaration. The content of the
package comment file is written in HTML with one exception. The documentation comment should not include the
comment separators /** and */ or leading asterisks. When writing the comment, make the first sentence a
summary about the package, and do not put a title or any other text between the <body> tag and the first sentence.
You can include package tags. All block tags must appear after the main description. If you add an @see tag in a
package comment file, then it must have a fully qualified name.
Processing the Comment File
When the javadoc command runs, it searches for the package comment file. If the package comment file is found,
then the javadoc command does the following:
 Copies the comment for processing. For package.html, the javadoc command copies all content between
the <body> and </body> HTML tags. You can include a <head> section to put a <title> tag, source file
copyright statement, or other information, but none of these appear in the generated documentation.
 Processes the package tags. See Package Tags.

 Inserts the processed text at the bottom of the generated package summary page. See Java Platform, Standard
Edition API Specification Overview at
http://docs.oracle.com/javase/8/docs/api/overview-summary.html
 Copies the first sentence of the package comment to the top of the package summary page.
The javadoc command also adds the package name and this first sentence to the list of packages on the
overview page. See Java Platform, Standard Edition API Specification Overview at
The end of the sentence is determined by the same rules used for the end of the first sentence of class and
member main descriptions.
Overview Comment Files

Each application or set of packages that you are documenting can have its own overview documentation comment
that is kept in its own source file, that the javadoc command merges into the generated overview page. You
typically include in this comment any documentation that applies to the entire application or set of packages.
You can name the file anything you want such as overview.html and place it anywhere. A typical location is at the top
of the source tree.
For example, if the source files for the java.applet package are contained in the C:\user\src\java\applet
directory, then you could create an overview comment file at C:\user\src\overview.html.
You can have multiple overview comment files for the same set of source files in case you want to run
the javadoc command multiple times on different sets of packages. For example, you could run
the javadoc command once with -private for internal documentation and again without that option for public
documentation. In this case, you could describe the documentation as public or internal in the first sentence of each
overview comment file.
The content of the overview comment file is one big documentation comment that is written in HTML. Make the first
sentence a summary about the application or set of packages. Do not put a title or any other text between
the <body> tag and the first sentence. All tags except inline tags, such as an { @link} tag, must appear after the
main description. If you add an @see tag, then it must have a fully qualified name.
When you run the javadoc command, specify the overview comment file name with the -overview option. The
file is then processed similarly to that of a package comment file. The javadoc command does the following:
 Copies all content between the <body> and </body> tags for processing.
 Processes the overview tags that are present. See Overview Tags.
 Inserts the processed text at the bottom of the generated overview page. See Java Platform Standard Edition
API Specification Overview at
 Copies the first sentence of the overview comment to the top of the overview summary page.
Unprocessed Files
Your source files can include any files that you want the javadoc command to copy to the destination directory.
These files usually include graphic files, example Java source and class files, and self-standing HTML files with a lot
of content that would overwhelm the documentation comment of a typical Java source file.
To include unprocessed files, put them in a directory called doc-files. The doc-files directory can be a subdirectory of
any package directory that contains source files. You can have one doc-files subdirectory for each package.
For example, if you want to include the image of a button in the java.awt.Button class documentation, then
place the image file in the \src\java\awt\doc-files directory. Do not place the doc-files directory at \src\java\doc-files,
because java is not a package. It does not contain any source files.
All links to the unprocessed files must be included in the code because the javadoc command does not look at the
files. The javadoc command copies the directory and all of its contents to the destination. The following example
shows how the link in the Button.java documentation comment might look:
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
Test and Template Files

You can store test and template files in the source tree in the same directory with or in a subdirectory of the directory
where the source files reside. To prevent test and template files from being processed, run the javadoc command
and explicitly pass in individual source file names.
Test files are valid, compilable source files. Template files are not valid, compatible source files, but they often have
the .java suffix.
Test Files
If you want your test files to belong to either an unnamed package or to a package other than the package that the
source files are in, then put the test files in a subdirectory underneath the source files and give the directory an invalid
name. If you put the test files in the same directory with the source and call the javadoc command with a
command-line argument that indicates its package name, then the test files cause warnings or errors. If the files are
in a subdirectory with an invalid name, then the test file directory is skipped and no errors or warnings are issued. For
example, to add test files for source files in com.package1, put them in a subdirectory in an invalid package name.
The following directory name is invalid because it contains a hyphen:
com\package1\test-files\
If your test files contain documentation comments, then you can set up a separate run of the javadoc command to
produce test file documentation by passing in their test source file names with wild cards, such
as com/package1/test-files/*.java.
Template Files
If you want a template file to be in the source directory, but not generate errors when you execute
the javadoc command, then give it an invalid file name such as Buffer-Template.java to prevent it from
being processed. The javadoc command only processes source files with names, when stripped of
the .java suffix, that are valid class names.
Generated Files
By default, the javadoc command uses a standard doclet that generates HTML-formatted documentation. The
standard doclet generates basic content, cross-reference, and support pages described here. Each HTML page
corresponds to a separate file. The javadoc command generates two types of files. The first type is named after
classes and interfaces. The second type contain hyphens (such as package-summary.html) to prevent conflicts with
the first type of file.
Basic Content Pages
 One class or interface page (classname.html) for each class or interface being documented.
 One package page (package-summary.html) for each package being documented. The javadoc command
includes any HTML text provided in a file with the name package.html or package-info.java in the package
directory of the source tree.
 One overview page (overview-summary.html) for the entire set of packages. The overview page is the front page
of the generated document. The javadoc command includes any HTML text provided in a file specified by
the -overview option. The Overview page is created only when you pass two or more package names into
the javadoc command. See HTML Frames and Options.
Cross-Reference Pages
 One class hierarchy page for the entire set of packages (overview-tree.html). To view the hierarchy page,
click Overview in the navigation bar and click Tree.
 One class hierarchy page for each package (package-tree.html) To view the hierarchy page, go to a particular
package, class, or interface page, and click Tree to display the hierarchy for that package.
 One use page for each package (package-use.html) and a separate use page for each class and interface
(class-use/classname.html). The use page describes what packages, classes, methods, constructors and fields
use any part of the specified class, interface, or package. For example, given a class or interface A, its use page
includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with
parameters of type A. To view the use page, go to the package, class, or interface and click the Uselink in the
navigation bar.
 A deprecated API page (deprecated-list.html) that lists all deprecated APIs and their suggested replacements.
Avoid deprecated APIs because they can be removed in future implementations.
 A constant field values page (constant-values.html) for the values of static fields.
 A serialized form page (serialized-form.html) that provides information about serializable and externalizable
classes with field and method descriptions. The information on this page is of interest to reimplementors, and not
to developers who want to use the API. To access the serialized form page, go to any serialized class and
click Serialized Form in the See Also section of the class comment. The standard doclet generates a serialized
form page that lists any class (public or non-public) that implements Serializable with
its readObjectand writeObject methods, the fields that are serialized, and the documentation comments
from the @serial, @serialField, and @serialData tags. Public serializable classes can be excluded
by marking them (or their package) with @serial exclude, and package-private serializable classes can be
included by marking them (or their package) with an @serial include. As of Release 1.4, you can generate the
complete serialized form for public and private classes by running the javadoc command without specifying
the -private option. See Options.
 An index page (index-*.html) of all class, interface, constructor, field and method names, in alphabetical
order. The index page is internationalized for Unicode and can be generated as a single file or as a separate file
for each starting character (such as AZ for English).
Support Pages
 A help page (help-doc.html) that describes the navigation bar and the previous pages. Use -helpfile to
override the default help file with your own custom help file.
 One index.html file that creates the HTML frames for display. Load this file to display the front page with frames.
The index.html file contains no text content.
 Several frame files (*-frame.html) that contains lists of packages, classes, and interfaces. The frame files
display the HTML frames.
 A package list file (package-list) that is used by the -link and -linkoffline options. The package list file
is a text file that is not reachable through links.
 A style sheet file (stylesheet.css) that controls a limited amount of color, font family, font size, font style, and
positioning information on the generated pages.
 A doc-files directory that holds image, example, source code, or other files that you want copied to the
destination directory. These files are not processed by the javadoccommand. This directory is not processed
unless it exists in the source tree.
See Options.
HTML Frames
The javadoc command generates the minimum number of frames (two or three) necessary based on the values
passed to the command. It omits the list of packages when you pass a single package name or source files that
belong to a single package as an argument to the javadoc command. Instead, the javadoc command creates
one frame in the left-hand column that displays the list of classes. When you pass two or more package names,
the javadoc command creates a third frame that lists all packages and an overview page (overview-
summary.html). To bypass frames, click the No Frames link or enter the page set from the overview-summary.html
page.
Generated File Structure

The generated class and interface files are organized in the same directory hierarchy that Java source files and class
files are organized. This structure is one directory per subpackage.
For example, the document generated for the java.applet.Applet class would be located at
java\applet\Applet.html.
The file structure for the java.applet package follows, assuming that the destination directory is
named apidocs. All files that contain the word frame appear in the upper-left or lower-left frames, as noted. All
other HTML files appear in the right-hand frame.
Directories are bold. The asterisks (*) indicate the files and directories that are omitted when the arguments to
the javadoc command are source file names rather than package names. When arguments are source file names,
an empty package list is created. The doc-files directory is not created in the destination unless it exists in the source
tree. See Generated Files.
 apidocs: Top-level directory
o index.html: Initial Page that sets up HTML frames
o *overview-summary.html: Package list with summaries
o overview-tree.html: Class hierarchy for all packages
o deprecated-list.html: Deprecated APIs for all packages

o constant-values.html: Static field values for all packages
o serialized-form.html: Serialized forms for all packages
o *overview-frame.html: All packages for display in upper-left frame
o allclasses-frame.html: All classes for display in lower-left frame
o help-doc.html: Help about Javadoc page organization
o index-all.html: Default index created without -splitindex option
o index-files: Directory created with -splitindex option
 index-<number>.html: Index files created with -splitindex option
o package-list: Package names for resolving external references
o stylesheet.css: Defines fonts, colors, positions, and so on
 java: Package directory
o applet: Subpackage directory
 Applet.html: Applet class page
 AppletContext.html: AppletContext interface
 AppletStub.html: AppletStub interface
 AudioClip.html: AudioClip interface
 package-summary.html: Classes with summaries
 package-frame.html: Package classes for display in lower-left frame
 package-tree.html: Class hierarchy for this package
 package-use.html: Where this package is used
 doc-files: Image and example files directory
 class-use: Image and examples file location
- Applet.html: Uses of the Applet class
- AppletContext.html: Uses of the AppletContext interface
- AppletStub.html: Uses of the AppletStub interface
- AudioClip.html: Uses of the AudioClip interface
 src-html: Source code directory

o java: Package directory
 applet: Subpackage directory
- Applet.html: Applet source code
- AppletContext.html: AppletContext source code
- AppletStub.html: AppletStub source code
- AudioClip.html: AudioClip source code
Generated API Declarations

The javadoc command generates a declaration at the start of each class, interface, field, constructor, and method
description for that API item. For example, the declaration for the Boolean class is:
public final class Boolean

extends Object
implements Serializable
The declaration for the Boolean.valueOf method is:
public static Boolean valueOf(String s)

The javadoc command can include the
modifiers public, protected, private, abstract, final, static, transient, and volatile, but
not synchronized or native. The synchronized and native modifiers are considered implementation
detail and not part of the API specification.
Rather than relying on the keyword synchronized, APIs should document their concurrency semantics in the
main description of the comment. For example, a description might be: A single enumeration cannot be used by
multiple threads concurrently. The document should not describe how to achieve these semantics. As another
example, while the Hashtableoption should be thread-safe, there is no reason to specify that it is achieved by
synchronizing all of its exported methods. It is better to reserve the right to synchronize internally at the bucket level
for higher concurrency.
Documentation Comments
This section describes source code comments and comment inheritance.
Source Code Comments

You can include documentation comments in the source code, ahead of declarations for any class, interface, method,
constructor, or field. You can also create documentation comments for each package and another one for the
overview, though their syntax is slightly different. A documentation comment consists of the characters
between /** and */ that end it. Leading asterisks are allowed on each line and are described further in the
following section. The text in a comment can continue onto multiple lines.
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
To save space you can put a comment on one line:
/** This comment takes up only one line. */

Placement of Comments
Documentation comments are recognized only when placed immediately before class, interface, constructor, method,
or field declarations. Documentation comments placed in the body of a method are ignored.
The javadoc command recognizes only one documentation comment per declaration statement. See Where Tags
Can Be Used.
A common mistake is to put an import statement between the class comment and the class declaration. Do not put
an import statement at this location because the javadoccommand ignores the class comment.
/**
* This is the class comment for the class Whatever.
*/
import com.example; // MISTAKE - Important not to put import statement

here
public class Whatever{ }

Parts of Comments
A documentation comment has a main description followed by a tag section. The main description begins after the
starting delimiter /** and continues until the tag section. The tag section starts with the first block tag, which is
defined by the first @ character that begins a line (ignoring leading asterisks, white space, and leading
separator /**). It is possible to have a comment with only a tag section and no main description. The main
description cannot continue after the tag section begins. The argument to a tag can span multiple lines. There can be
any number of tags, and some types of tags can be repeated while others cannot. For example, this @see tag starts
the tag section:
/**
* This sentence holds the main description for this documentation
comment.
* @see java.lang.Object
*/
Block and inline Tags
A tag is a special keyword within a documentation comment that the javadoc command processes. There are two
kinds of tags: block tags, which appear as an @tag tag (also known as standalone tags), and inline tags, which
appear within braces, as an {@tag} tag. To be interpreted, a block tag must appear at the beginning of a line,
ignoring leading asterisks, white space, and the separator ( /**). This means you can use the @ character elsewhere
in the text and it will not be interpreted as the start of a tag. If you want to start a line with the @character and not have
it be interpreted, then use the HTML entity @. Each block tag has associated text, which includes any text
following the tag up to, but not including, either the next tag, or the end of the documentation comment. This
associated text can span multiple lines. An inline tag is allowed and interpreted anywhere that text is allowed. The
following example contains the @deprecated block tag and the {@link} inline tag. See Javadoc Tags.
/**
* @deprecated As of JDK 1.1, replaced by {@link
#setBounds(int,int,int,int)}
*/
Write Comments in HTML
The text must be written in HTML with HTML entities and HTML tags. You can use whichever version of HTML your
browser supports. The standard doclet generates HTML 3.2-compliant code elsewhere (outside of the documentation
comments) with the inclusion of cascading style sheets and frames. HTML 4.0 is preferred for generated files
because of the frame sets.
For example, entities for the less than symbol (<) and the greater than symbol (>) should be written
as < and >. Similarly, the ampersand (&) should be written as &. The bold HTML tag is shown in
the following example.
/**
* This is a doc comment.
* @see java.lang.Object
*/
Leading Asterisks
When the javadoc command parses a documentation comment, leading asterisks (*) on each line are discarded,
and blanks and tabs that precede the initial asterisks (*) are also discarded. If you omit the leading asterisk on a line,
then the leading white space is no longer removed so that you can paste code examples directly into a
documentation comment inside a <PRE> tag with its indentation preserved. Spaces are interpreted by browsers
more uniformly than tabs. Indentation is relative to the left margin (rather than the separator /** or <PRE> tag).
First Sentence
The first sentence of each documentation comment should be a summary sentence that contains a concise but
complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or
line terminator, or at the first block tag. The javadoc command copies this first sentence to the member summary
at the top of the HTML page.
Multiple-Field Declarations
The Java platform lets you declare multiple fields in a single statement, but this statement can have only one
documentation comment that is copied for all fields. If you want individual documentation comments for each field,
then declare each field in a separate statement. For example, the following documentation comment does not make
sense written as a single declaration and would be better handled as two declarations:
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
The javadoc command generates the following documentation from the previous code:
public int x
The horizontal and vertical distances of point (x, y).
public int y
The horizontal and vertical distances of point (x, y).
Use of Header Tags
When writing documentation comments for members, it is best not to use HTML heading tags such
as <H1> and <H2>, because the javadoc command creates an entire structured document, and these structural
tags might interfere with the formatting of the generated document. However, you can use these headings in class
and package comments to provide your own structure.
Method Comment Inheritance

The javadoc command allows method comment inheritance in classes and interfaces to fill in missing text or to
explicitly inherit method comments. Constructors, fields, and nested classes do not inherit documentation comments.
Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the
documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the
command line. This contrasts with Release 1.3.n and earlier releases, where the class had to be a documented class.
Fill in Missing Text
When a main description, or @return, @param, or @throws tag is missing from a method comment,
the javadoc command copies the corresponding main description or tag comment from the method it overrides or
implements (if any). See Method Comment Inheritance.
When an @param tag for a particular parameter is missing, the comment for that parameter is copied from the
method further up the inheritance hierarchy. When an @throws tag for a particular exception is missing,
the @throws tag is copied only when that exception is declared.
This behavior contrasts with Release 1.3 and earlier, where the presence of any main description or tag would
prevent all comments from being inherited.
See Javadoc Tags and Options.
Explicit Inheritance
Insert the {@inheritDoc} inline tag in a method main description or @return, @param, or @throws tag
comment. The corresponding inherited main description or tag comment is copied into that spot.
Class and Interface Inheritance

Comment inheritance occurs in all possible cases of inheritance from classes and interfaces:
 When a method in a class overrides a method in a superclass
 When a method in an interface overrides a method in a superinterface
 When a method in a class implements a method in an interface
In the first two cases, the javadoc command generates the subheading Overrides in the documentation for the
overriding method. A link to the method being overridden is included, whether or not the comment is inherited.
In the third case, when a method in a specified class implements a method in an interface, the javadoc command
generates the subheading Specified by in the documentation for the overriding method. A link to the method being
implemented is included, whether or not the comment is inherited.
Method Comments Algorithm

If a method does not have a documentation comment, or has an {@inheritDoc} tag, then
the javadoc command uses the following algorithm to search for an applicable comment. The algorithm is
designed to find the most specific applicable documentation comment, and to give preference to interfaces over
superclasses:
1. Look in each directly implemented (or extended) interface in the order they appear following the
word implements (or extends) in the method declaration. Use the first documentation comment found for
this method.
2. If Step 1 failed to find a documentation comment, then recursively apply this entire algorithm to each directly
implemented (or extended) interface in the same order they were examined in Step 1.
3. When Step 2 fails to find a documentation comment and this is a class other than the Object class, but not an
interface:
1. If the superclass has a documentation comment for this method, then use it.
2. If Step 3a failed to find a documentation comment, then recursively apply this entire algorithm to the
superclass.
Javadoc Tags
The javadoc command parses special tags when they are embedded within a Java documentation comment.
The javadoc tags let you autogenerate a complete, well-formatted API from your source code. The tags start with
an at sign (@) and are case-sensitive. They must be typed with the uppercase and lowercase letters as shown. A tag
must start at the beginning of a line (after any leading spaces and an optional asterisk), or it is treated as text. By
convention, tags with the same name are grouped together. For example, put all @seetags together. For more
information, see Where Tags Can Be Used.
Tags have the following types:
 Bock tags: Place block tags only in the tag section that follows the description. Block tags have the form: @tag.
 Inline tags: Place inline tags anywhere in the main description or in the comments for block tags. Inline tags are
enclosed within braces: {@tag}.
For custom tags, see -tag tagname:Xaoptcmf:"taghead". See also Where Tags Can Be Used.
Tag Descriptions
@author name-text
Introduced in JDK 1.0
Adds an Author entry with the specified name text to the generated documents when the -author option
is used. A documentation comment can contain multiple @author tags. You can specify one name
per @author tag or multiple names per tag. In the former case, the javadoc command inserts a comma
(,) and space between names. In the latter case, the entire text is copied to the generated document without
being parsed. Therefore, you can use multiple names per line if you want a localized name separator other
than a comma. See @author in How to Write Doc Comments for the Javadoc Tool at
http://www.oracle.com/technetwork/java/javase/documentation/index-
137868.html#@author
{@code text}
Equivalent to <code>{@literal}</code>.
Displays text in code font without interpreting the text as HTML markup or nested Javadoc tags. This
enables you to use regular angle brackets (< and >) instead of the HTML entities ( < and >) in
documentation comments, such as in parameter types (<Object>), inequalities (3 < 4), or arrows (<-).
For example, the documentation comment text {@code AC} displayed in the generated HTML page
unchanged as AC. This means that the is not interpreted as bold and is in code font. If you want
the same functionality without the code font, then use the {@literal} tag.
@deprecated deprecated-text
Adds a comment indicating that this API should no longer be used (even though it may continue to work).
The javadoc command moves deprecated-text ahead of the main description, placing it in italics
and preceding it with a bold warning: Deprecated. This tag is valid in all documentation comments: overview,
package, class, interface, constructor, method and field.
The first sentence of deprecated text should tell the user when the API was deprecated and what to use as a
replacement. The javadoc command copies the first sentence to the summary section and index.
Subsequent sentences can also explain why it was deprecated. You should include an {@link} tag (for
Javadoc 1.2 or later) that points to the replacement API.
Use the @deprecated annotation tag to deprecate a program element. See How and When to Deprecate
APIs at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecati
on/deprecation.html
See also @deprecated in How to Write Doc Comments for the Javadoc Tool at
137868.html#@deprecated
{@docRoot}
Represents the relative path to the generated document's (destination) root directory from any generated
page. This tag is useful when you want to include a file, such as a copyright page or company logo, that you
want to reference from all generated pages. Linking to the copyright page from the bottom of each page is
common.
This {@docRoot} tag can be used both on the command line and in a documentation comment. This tag
is valid in all documentation comments: overview, package, class, interface, constructor, method and field,
and includes the text portion of any tag (such as the @return, @param and @deprecated tags).
 On the command line, where the header, footer, or bottom are defined: javadoc -bottom '<a
href="{@docRoot}/copyright.html">Copyright</a>'.
When you use the {@docRoot} tag this way in a make file, some makefile programs require a
special way to escape for the brace {} characters. For example, the Inprise MAKE version 5.2 running
on Windows requires double braces: {{@docRoot}}. It also requires double (rather than single)
quotation marks to enclose arguments to options such as the -bottom option (with the quotation
marks around the href argument omitted).
 In a documentation comment:
 /**
 * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
 */
This tag is needed because the generated documents are in hierarchical directories, as deep as the
number of subpackages. The expression: <a
href="{@docRoot}/copyright.html"> resolves to <a
href="../../copyright.html"> for java/lang/Object.java and <a
href="../../../copyright.html"> for java/lang/ref/Reference.java.
@exception class-name description

Identical to the @throws tag. See @throws class-name description.
{@inheritDoc}
Inherits (copies) documentation from the nearest inheritable class or implementable interface into the current
documentation comment at this tag's location. This enables you to write more general comments higher up
the inheritance tree and to write around the copied text.
This tag is valid only in these places in a documentation comment:
 In the main description block of a method. In this case, the main description is copied from a class or
interface up the hierarchy.
 In the text arguments of the @return, @param, and @throws tags of a method. In this case, the
tag text is copied from the corresponding tag up the hierarchy.
See Method Comment Inheritance for a description of how comments are found in the inheritance hierarchy.
Note that if this tag is missing, then the comment is or is not automatically inherited according to rules
described in that section.
{@link package.class#member label}
Inserts an inline link with a visible text label that points to the documentation for the specified package,
class, or member name of a referenced class. This tag is valid in all documentation comments: overview,
package, class, interface, constructor, method and field, including the text portion of any tag, such as
the @return, @param and @deprecated tags. See @link in How to Write Doc Comments for the
Javadoc Tool at
137868.html#{@link
This tag is similar to the @see tag. Both tags require the same references and accept the same syntax
for package.class#member and label. The main difference is that the {@link} tag generates an
inline link rather than placing the link in the See Also section. The {@link} tag begins and ends with
braces to separate it from the rest of the inline text. If you need to use the right brace ( }) inside the label,
then use the HTML entity notation }.
There is no limit to the number of {@link} tags allowed in a sentence. You can use this tag in the main
description part of any documentation comment or in the text portion of any tag, such as
the @deprecated, @return or @param tags.
For example, here is a comment that refers to the getComponentAt(int, int) method:
Use the {@link #getComponentAt(int, int) getComponentAt} method.

From this code, the standard doclet generates the following HTML (assuming it refers to another class in the
same package):
Use the <a href="Component.html#getComponentAt(int,

int)">getComponentAt</a> method.
The previous line appears on the web page as:
Use the getComponentAt method.
{@linkplain package.class#member label}
Behaves the same as the {@link} tag, except the link label is displayed in plain text rather than code font.
Useful when the label is plain text. For example, Refer to {@linkplain add() the
overridden method}. displays as: Refer to the overridden method.
{@literal text}
Displays text without interpreting the text as HTML markup or nested Javadoc tags. This enables you to use
angle brackets (< and >) instead of the HTML entities (< and >) in documentation comments,
such as in parameter types (<Object>), inequalities (3 < 4), or arrows (<-). For example, the
documentation comment text {@literal AC} displays unchanged in the generated HTML page in
your browser, as AC. The is not interpreted as bold (and it is not in code font). If you want the
same functionality with the text in code font, then use the {@code} tag.
@param parameter-name description
Adds a parameter with the specified parameter-name followed by the specified description to the
Parameters section. When writing the documentation comment, you can continue the description onto
multiple lines. This tag is valid only in a documentation comment for a method, constructor, or class. See
@param in How to Write Doc Comments for the Javadoc Tool at
137868.html#@param
The parameter-name can be the name of a parameter in a method or constructor, or the name of a type
parameter of a class, method, or constructor. Use angle brackets around this parameter name to specify the
use of a type parameter.
Example of a type parameter of a class:
/**
* @param <E> Type of element stored in a list
*/
public interface List<E> extends Collection<E> {
}
Example of a type parameter of a method:
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}
@return description

Adds a Returns section with the description text. This text should describe the return type and permissible
range of values. This tag is valid only in a documentation comment for a method. See @return in How to
Write Doc Comments for the Javadoc Tool at
137868.html#@return
@see reference
Adds a See Also heading with a link or text entry that points to a reference. A documentation comment can
contain any number of @see tags, which are all grouped under the same heading. The @see tag has three
variations. The form is the most common. This tag is valid in any documentation comment: overview,
package, class, interface, constructor, method, or field. For inserting an inline link within a sentence to a
package, class, or member, see {@link}.
Form 1. The @see string tag form adds a text entry for string. No link is generated. The string is a book
or other reference to information not available by URL. The javadoccommand distinguishes this from the
previous cases by searching for a double quotation mark (") as the first character. For example, @see
"The Java Programming Language" that generates the following text:
See Also:
"The Java Programming Language"
Form 2. The @see <a href="URL#value">label</a> form adds a link as defined

by URL#value. The URL#value parameter is a relative or absolute URL. The javadoccommand
distinguishes this from other cases by searching for a less-than symbol (<) as the first character. For
example, @see <a href="spec.html#section">Java Spec</a> generates the following link:
See Also:
Java Spec
Form 3. The @see package.class#member label form adds a link with a visible text label that
points to the documentation for the specified name in the Java Language that is referenced. The label is
optional. If the label is omitted, then the name appears instead as visible text, suitably shortened. Use the -
noqualifier option to globally remove the package name from this visible text. Use the label when you
want the visible text to be different from the autogenerated visible text. See How a Name Appears.
In Java SE 1.2 only, the name but not the label automatically appears in <code> HTML tags. Starting with
Java SE 1.2.2, the <code> tag is always included around the visible text, whether or not a label is used.
 package.class#member is any valid program element name that is referenced, such as a

package, class, interface, constructor, method or field name, except that the character ahead of the
member name should be a number sign (#). The class represents any top-level or nested class or
interface. The member represents any constructor, method, or field (not a nested class or interface). If
this name is in the documented classes, then the javadoc command create a link to it. To create
links to external referenced classes, use the -link option. Use either of the other two @see tag forms
to refer to the documentation of a name that does not belong to a referenced class. See Specify a
Name.
Note: External referenced classes are classes that are not passed into the javadoc command on the
command line. Links in the generated documentation to external referenced classes are called external
references or external links. For example, if you run the javadoc command on only the java.awt
package, then any class in java.lang, such as Object, is an external referenced class. Use
the -link and -linkoffline options to link to external referenced classes. The source comments
of external referenced classes are not available to the javadoc command run.
 label is optional text that is visible as the link label. The label can contain white space. If label is
omitted, then package.class.member appears, suitably shortened relative to the current class
and package. See How a Name Appears.
 A space is the delimiter between package.class#member and label. A space inside

parentheses does not indicate the start of a label, so spaces can be used between parameters in a
method.
In the following example, an @see tag (in the Character class) refers to the equals method in
the String class. The tag includes both arguments: the name String#equals(Object) and the
label equals.
/**
* @see String#equals(Object) equals
*/
The standard doclet produces HTML that is similar to:
<dl>
<dt>See Also:
<dd><a
href="../../java/lang/String#equals(java.lang.Object)"><code>equal
s<code></a>
</dl>
The previous code looks similar to the following in a browser, where the label is the visible link text:
See Also:
equals
Specify a Name
This package.class#member name can be either fully qualified, such

as java.lang.String#toUpperCase() or not, such
as String#toUpperCase() or #toUpperCase(). If the name is less than fully qualified, then
the javadoc command uses the standard Java compiler search order to find it. See Search Order for the @see
Tag. The name can contain white space within parentheses, such as between method arguments.The advantage to
providing shorter, partially qualified names is that they are shorter to type and there is less clutter in the source code.
The following listing shows the different forms of the name, where Class can be a class or interface; Type can be a
class, interface, array, or primitive; and method can be a method or constructor.
Typical forms for @see package.class#member

Referencing a member of the current class
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
Referencing another class in the current or imported packages

@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class
Referencing an element in another package (fully qualified)

@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package
Notes about the previous listing:
 The first set of forms with no class or package causes the javadoc command to search only through the
current class hierarchy. It finds a member of the current class or interface, one of its superclasses or
superinterfaces, or one of its enclosing classes or interfaces (search Items 13). It does not search the rest of the
current package or other packages (search Items 45). See Search Order for the @see Tag.
 If any method or constructor is entered as a name with no parentheses, such as getValue, and if there is no
field with the same name, then the javadoc command still creates a link to the method. If this method is
overloaded, then the javadoc command links to the first method its search encounters, which is unspecified.
 Nested classes must be specified as outer.inner, not simply inner, for all forms.
 As stated, the number sign (#), rather than a dot (.) separates a member from its class. This enables
the javadoc command to resolve ambiguities, because the dot also separates classes, nested classes,
packages, and subpackages. However, the javadoc command properly parses a dot when there is no
ambiguity, but prints a warning to alert you.
Search Order for the @see Tag
The javadoc command processes an @see tag that appears in a source file, package file, or overview file. In the
latter two files, you must fully qualify the name you supply with the @see tag. In a source file, you can specify a name
that is fully qualified or partially qualified.
The following is the search order for the @see tag.
1. The current class or interface.
2. Any enclosing classes and interfaces searching the closest first.
3. Any superclasses and superinterfaces, searching the closest first.
4. The current package.
5. Any imported packages, classes, and interfaces, searching in the order of the import statement.
The javadoc command continues to search recursively through Items 1-3 for each class it encounters until it finds
a match. That is, after it searches through the current class and its enclosing class E, it searches through the
superclasses of E before the enclosing classes of E. In Items 4 and 5, the javadoc command does not search
classes or interfaces within a package in any specified order (that order depends on the particular compiler). In Item
5, the javadoc command searches in java.lang because that is imported by all programs.
When the javadoc command encounters an @see tag in a source file that is not fully qualified, it searches for the
specified name in the same order as the Java compiler would, except the javadoc command does not detect
certain name space ambiguities because it assumes the source code is free of these errors. This search order is
formally defined in the Java Language Specification. The javadoc command searches for that name through all
related and imported classes and packages. In particular, it searches in this order:
1. The current class or interface.
2. Any enclosing classes and interfaces, searching the closest first.
3. Any superclasses and superinterfaces, searching the closest first.
4. The current package.
5. Any imported packages, classes, and interfaces, searching in the order of the import statements.
The javadoc command does not necessarily look in subclasses, nor will it look in other packages even when their
documentation is being generated in the same run. For example, if the @see tag is in
the java.awt.event.KeyEvent class and refers to a name in the java.awt package, then
the javadoc command does not look in that package unless that class imports it.
How a Name Appears
If label is omitted, then package.class.member appears. In general, it is suitably shortened relative to the
current class and package. Shortened means the javadoc command displays only the minimum name necessary.
For example, if the String.toUpperCase() method contains references to a member of the same class and to
a member of a different class, then the class name is displayed only in the latter case, as shown in the following
listing. Use the -noqualifier option to globally remove the package names.
Type of reference: The @see tag refers to a member of the same class, same package
Example in: @see String#toLowerCase()
Appears as: toLowerCase() - omits the package and class names
Type of reference: The @see tag refers to a member of a different class, same package
Example in: @see Character#toLowerCase(char)
Appears as: Character.toLowerCase(char) - omits the package name, includes the class name
Type of reference: The @see tag refers to a member of a different class, different package
Example in: @see java.io.File#exists()
Appears as: java.io.File.exists() - includes the package and class names
Examples of the @see Tag
The comment to the right shows how the name appears when the @see tag is in a class in another package, such
as java.applet.Applet. See @see in How to Write Doc Comments for the Javadoc Tool at
137868.html#@see
See also:
@see java.lang.String // String
@see java.lang.String The String class // The String class
@see String // String
@see String#equals(Object) // String.equals(Object)
@see String#equals //
String.equals(java.lang.Object)
@see java.lang.Object#wait(long) // java.lang.Object.wait(long)
@see Character#MAX_RADIX // Character.MAX_RADIX
@see <a href="spec.html">Java Spec</a> // Java Spec
@see "The Java Programming Language" // "The Java Programming
Language"
Note: You can extend the @see tag to link to classes not being documented with the -link option.
@serial field-description | include | exclude
Used in the documentation comment for a default serializable field. See Documenting Serializable Fields
and Data for a Class at
http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serial
-arch.html#5251
See also Oracle's Criteria for Including Classes in the Serialized Form Specification at
http://www.oracle.com/technetwork/java/javase/documentation/serialized-
criteria-137781.html
An optional field-description should explain the meaning of the field and list the acceptable values.
When needed, the description can span multiple lines. The standard doclet adds this information to the
serialized form page. See Cross-Reference Pages.
If a serializable field was added to a class after the class was made serializable, then a statement should be
added to its main description to identify at which version it was added.
The include and exclude arguments identify whether a class or package should be included or
excluded from the serialized form page. They work as follows:
 A public or protected class that implements Serializable is included unless that class (or its
package) is marked with the @serial exclude tag.
 A private or package-private class that implements Serializable is excluded unless that class (or
its package) is marked with the @serial include tag.
For example, the javax.swing package is marked with the @serial exclude tag in package.html or
package-info.java. The public class java.security.BasicPermission is marked with
the @serial exclude tag. The package-private
class java.util.PropertyPermissionCollection is marked with the @serial
include tag.
The @serial tag at the class level overrides the @serial tag at the package level.
@serialData data-description
Uses the data description value to document the types and order of data in the serialized form. This data
includes the optional data written by the writeObject method and all data (including base classes)
written by the Externalizable.writeExternal method.
The @serialData tag can be used in the documentation comment for
the writeObject, readObject, writeExternal, readExternal, writeReplace,
and readResolve methods.
@serialField field-name field-type field-description
Documents an ObjectStreamField component of the serialPersistentFields member of

a Serializable class. Use one @serialField tag for each ObjectStreamField component.
@since since-text
Adds a Since heading with the specified since-text value to the generated documentation. The text has
no special internal structure. This tag is valid in any documentation comment: overview, package, class,
interface, constructor, method, or field. This tag means that this change or feature has existed since the
software release specified by the since-text value, for example: @since 1.5.
For Java platform source code, the @since tag indicates the version of the Java platform API specification,
which is not necessarily when the source code was added to the reference implementation.
Multiple @since tags are allowed and are treated like multiple @author tags. You could use multiple tags
when the program element is used by more than one API.
@throws class-name description
Behaves the same as the @exception tag. See @throws in How to Write Doc Comments for the Javadoc
Tool at
137868.html#@exception
The @throws tag adds a Throws subheading to the generated documentation, with the class-
name and description text. The class-name is the name of the exception that might be thrown by the
method. This tag is valid only in the documentation comment for a method or constructor. If this class is not
fully specified, then the javadoc command uses the search order to look up this class.
Multiple @throws tags can be used in a specified documentation comment for the same or different
exceptions. See Search Order for the @see Tag.
To ensure that all checked exceptions are documented, when an @throws tag does not exist for an
exception in the throws clause, the javadoc command adds that exception to the HTML output (with no
description) as though it were documented with the @throws tag.
The @throws documentation is copied from an overridden method to a subclass only when the exception
is explicitly declared in the overridden method. The same is true for copying from an interface method to an
implementing method. You can use the {@inheritDoc} tag to force the @throws tag to inherit
documentation.
{@value package.class#field}
Displays constant values. When the {@value} tag is used without an argument in the documentation
comment of a static field, it displays the value of that constant:
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
When used with the argument package.class#field in any documentation comment,
he {@value} tag displays the value of the specified constant:
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {}
The argument package.class#field takes a form similar to that of the @see tag argument, except
that the member must be a static field.
The values of these constants are also displayed in Constant Field Values at
http://docs.oracle.com/javase/8/docs/api/constant-values.html
@version version-text
Adds a Version subheading with the specified version-text value to the generated documents when
the -version option is used. This tag is intended to hold the current release number of the software that
this code is part of, as opposed to the @since tag, which holds the release number where this code was
introduced. The version-textvalue has no special internal structure. See @version in How to Write Doc
Comments for the Javadoc Tool at
137868.html#@version
A documentation comment can contain multiple @version tags. When it makes sense, you can specify
one release number per @version tag or multiple release numbers per tag. In the former case,
the javadoc command inserts a comma (,) and a space between the names. In the latter case, the entire
text is copied to the generated document without being parsed. Therefore, you can use multiple names per
line when you want a localized name separator other than a comma.
Where Tags Can Be Used

The following sections describe where tags can be used. Note that the following tags can be used in all
documentation comments: @see, @since, @deprecated, {@link}, {@linkplain}, and {@docroot}.
Overview Tags
Overview tags are tags that can appear in the documentation comment for the overview page (which resides in the
source file typically named overview.html). Similar to any other documentation comments, these tags must appear
after the main description
Note: The {@link} tag has a bug in overview documents in Java SE 1.2. The text appears correctly but has no
link. The {@docRoot} tag does not currently work in overview documents.
The overview tags are the following:
@see reference || @since since-text || @serialField field-name field-type field-description || @author name-
text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member
label} || {@docRoot} ||
Package Tags
Package tags are tags that can appear in the documentation comment for a package, that resides in the source file
named package.html or package-info.java. The @serial tag can only be used here with
the include or exclude argument.
The package tags are the following:
@see reference || @since since-text || @serial field-description | include | exclude || @author name-
text || @version version-text || {@linkplain package.class#member label} || {@linkplain package.class#member
label} || {@docRoot} ||
Class and Interface Tags

The following are tags that can appear in the documentation comment for a class or interface. The @serial tag can
only be used within the documentation for a class or interface with an include or exclude argument.
@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include |

exclude || @author name-text || @version version-text || {@link package.class#member
label} || {@linkplain package.class#member label} || {@docRoot} ||
Class comment example:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
Field Tags
These tags can appear in fields:
@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include |

exclude || @serialField field-name field-type field-description || {@link package.class#member
label} || {@linkplain package.class#member label} || {@docRoot} || {@value package.class#field}
Field comment example:
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
Constructor and Method Tags
The following tags can appear in the documentation comment for a constructor or a method, except for
the @return tag, which cannot appear in a constructor, and the {@inheritDoc}tag, which has restrictions.
@see reference || @since since-text || @deprecated deprecated-text || @param parameter-name

description || @return description || @throws class-name description || @exception class-name
description || @serialData data-description || {@link package.class#member
label} || {@linkplain package.class#member label} || {@inheritDoc} || {@docRoot}
Note: The @serialData tag can only be used in the documentation comment for
the writeObject, readObject, writeExternal, readExternal, writeReplace,
and readResolve methods.
Method comment example:
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
Options
The javadoc command uses doclets to determine its output. The javadoc command uses the default standard
doclet unless a custom doclet is specified with the -doclet option. The javadoc command provides a set of
command-line options that can be used with any doclet. These options are described in Javadoc Options. The
standard doclet provides an additional set of command-line options that are described in Standard Doclet Options. All
option names are not case-sensitive, but their arguments are case-sensitive.
 See also Javadoc Options
 See also Standard Doclet Options
The options are:
 -1.1
 -author
 -bootclasspath classpathlist
 -bottom text
 -breakiterator
 -charset name
 -classpath classpathlist
 -d directory
 -docencoding name
 -docfilesubdirs
 -doclet class
 -docletpath classpathlist
 -doctitle title
 -encoding
 -exclude packagename1:packagename2:...
 -excludedocfilessubdir name1:name2
 -extdirs dirist
 -footer footer
 -group groupheading packagepattern:packagepattern
 -header header
 -help
 -helpfile path\filename
 -Jflag
 -javafx
 -keywords
 -link extdocURL
 -linkoffline extdocURL packagelistLoc
 -linksource
 -locale language_country_variant
 -nocomment
 -nodeprecated
 -nodeprecatedlist
 -nohelp
 -noindex
 -nonavbar
 -noqualifier all | packagename1:packagename2...
 -nosince
 -notimestamp
 -notree
 -overview path\filename
 -package
 -private
 -protected
 -public
 -quiet
 -serialwarn
 -source release
 -sourcepath sourcepathlist
 -sourcetab tablength
 -splitindex
 -stylesheet path\filename
 -tag tagname:Xaoptcmf:"taghead"
 -subpackages package1:package2:...
 -taglet class
 -tagletpath tagletpathlist
 -title title
 -top
 -use
 -verbose
 -version
 -windowtitle title
The following options are the core Javadoc options that are available to all doclets. The standard doclet provides the
rest of the doclets: -bootclasspath, -breakiterator, -classpath, -doclet, -docletpath, -
encoding, -exclude, -extdirs, -help, -locale, -overview, -package, -private, -
protected, -public, -quiet, -source, -sourcepath, -subpackages, and -verbose.
Javadoc Options
-overview path\filename
Specifies that the javadoc command should retrieve the text for the overview documentation from the
source file specified by the path\filename and place it on the Overview page (overview-summary.html).
The path\filename is relative to the current directory.
While you can use any name you want for the filename value and place it anywhere you want for the
path, it is typical to name it overview.html and place it in the source tree at the directory that contains the
topmost package directories. In this location, no path is needed when documenting packages, because
the -sourcepath option points to this file.
For example, if the source tree for the java.lang package is \src\classes\java\lang\, then you could place
the overview file at \src\classes\overview.html
See Real-World Examples.
For information about the file specified by path\filename, see Overview Comment Files.
The overview page is created only when you pass two or more package names to the javadoc command.
For a further explanation, see HTML Frames. The title on the overview page is set by -doctitle.
-Xdoclint:(all|none|[-]<group>)
Reports warnings for bad references, lack of accessibility and missing Javadoc comments, and reports
errors for invalid Javadoc syntax and missing HTML tags.
This option enables the javadoc command to check for all documentation comments included in the
generated output. As always, you can select which items to include in the generated output with the
standard options -public, -protected, -package and -private.
When the -Xdoclint is enabled, it reports issues with messages similar to the javac command.
The javadoc command prints a message, a copy of the source line, and a caret pointing at the exact
position where the error was detected. Messages may be either warnings or errors, depending on their
severity and the likelihood to cause an error if the generated documentation were run through a validator.
For example, bad references or missing Javadoc comments do not cause the javadoc command to
generate invalid HTML, so these issues are reported as warnings. Syntax errors or missing HTML end tags
cause the javadoc command to generate invalid output, so these issues are reported as errors.
By default, the -Xdoclint option is enabled. Disable it with the option -Xdoclint:none.
Change what the -Xdoclint option reports with the following options:
 -Xdoclint
none : disable the -Xdoclint option
 -Xdoclint
group : enable group checks
 -Xdoclint
all : enable all groups of checks
 -Xdoclint
all,-group : enable all except group checks
The variable group has one of the following values:
 accessibility : Checks for the issues to be detected by an accessibility checker (for example, no
caption or summary attributes specified in a <table> tag).
 html : Detects high-level HTML issues, like putting block elements inside inline elements, or not
closing elements that require an end tag. The rules are derived from the HTML 4.01 Specification. This
type of check enables the javadoc command to detect HTML issues that many browsers might
accept.
 missing : Checks for missing Javadoc comments or tags (for example, a missing comment or class,
or a missing @return tag or similar tag on a method).
 reference : Checks for issues relating to the references to Java API elements from Javadoc tags
(for example, item not found in @see , or a bad name after @param).
 syntax : Checks for low level issues like unescaped angle brackets (< and >) and ampersands (&)
and invalid Javadoc tags.
You can specify the -Xdoclint option multiple times to enable the option to check errors and warnings in
multiple categories. Alternatively, you can specify multiple error and warning categories by using the
preceding options. For example, use either of the following commands to check for the HTML, syntax, and
accessibility issues in the file filename.
javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility

filename
javadoc -Xdoclint:html,syntax,accessibility filename
Note: The javadoc command does not guarantee the completeness of these checks. In particular, it is not
a full HTML compliance checker. The goal of the -Xdoclint option is to enable the javadoc command
to report majority of common errors.
The javadoc command does not attempt to fix invalid input, it just reports it.
-public
Shows only public classes and members.
-protected
Shows only protected and public classes and members. This is the default.
-package
Shows only package, protected, and public classes and members.
-private
Shows all classes and members.
-help
Displays the online help, which lists all of the javadoc and doclet command-line options.
-doclet class
Specifies the class file that starts the doclet used in generating the documentation. Use the fully qualified
name. This doclet defines the content and formats the output. If the -doclet option is not used, then
the javadoc command uses the standard doclet for generating the default HTML format. This class must
contain the start(Root) method. The path to this starting class is defined by the -
docletpath option. See Doclet Overview at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/ov
erview.html
-docletpath classpathlist
Specifies the path to the doclet starting class file (specified with the -doclet option) and any JAR files it
depends on. If the starting class file is in a JAR file, then this option specifies the path to that JAR file. You
can specify an absolute path or a path relative to the current directory. If classpathlist contains
multiple paths or JAR files, then they should be separated with a colon (:) on Oracle Solaris and a semi-
colon (;) on Windows. This option is not necessary when the doclet starting class is already in the search
path. See Doclet Overview at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/ov
erview.html
-1.1
Removed from Javadoc 1.4 with no replacement. This option created documentation with the appearance
and functionality of documentation generated by Javadoc 1.1 (it never supported nested classes). If you
need this option, then use Javadoc 1.2 or 1.3 instead.
-source release
Specifies the release of source code accepted. The following values for the release parameter are
allowed. Use the value of release that corresponds to the value used when you compile code with
the javac command.
 Release Value: 1.5. The javadoc command accepts code containing generics and other language
features introduced in JDK 1.5. The compiler defaults to the 1.5 behavior when the -source option is
not used.
 Release Value: 1.4. The javadoc command accepts code containing assertions, which were
introduced in JDK 1.4.
 Release Value: 1.3. The javadoc command does not support assertions, generics, or other
language features introduced after JDK 1.3.
-sourcepath sourcepathlist
Specifies the search paths for finding source files when passing package names or the -
subpackages option into the javadoc command.
Separate multiple paths with a. semicolon (;).
The javadoc command searches all subdirectories of the specified paths. Note that this option is not only
used to locate the source files being documented, but also to find source files that are not being
documented, but whose comments are inherited by the source files being documented.
You can use the -sourcepath option only when passing package names into the javadoc command.
This will not locate source files passed into the javadoc command. To locate source files, change to that
directory or include the path ahead of each file, as shown at Document One or More Classes. If you omit -
sourcepath, then the javadoccommand uses the class path to find the source files (see -
classpath). The default -sourcepath is the value of class path. If -classpath is omitted and you
pass package names into the javadoc command, then the javadoc command searches in the current
directory and subdirectories for the source files.
Set sourcepathlist to the root directory of the source tree for the package you are documenting.
For example, suppose you want to document a package called com.mypackage, whose source files are
located at:\user\src\com\mypackage\*.java . Specify the sourcepath to \user\src, the directory that contains
com\mypackage, and then supply the package name as follows:
javadoc -sourcepath C:\user\src com.mypackage

Notice that if you concatenate the value of sourcepath and the package name together and change the dot
to a backslash (\), then you have the full path to the package:
\user\src\com\mypackage.
To point to two source paths:
javadoc -sourcepath \user1\src;\user2\src com.mypackage

-classpath classpathlist
Specifies the paths where the javadoc command searches for referenced classes These are the
documented classes plus any classes referenced by those classes.
Separate multiple paths with a semicolon (;).
The javadoc command searches all subdirectories of the specified paths. Follow the instructions in the
class path documentation for specifying the classpathlist value.
If you omit -sourcepath, then the javadoc command uses -classpath to find the source files and
class files (for backward compatibility). If you want to search for source and class files in separate paths,
then use both -sourcepath and -classpath.
For example, if you want to document com.mypackage, whose source files reside in the directory
\user\src\com\mypackage, and if this package relies on a library in , \user\lib, then you would use the
following command:
javadoc -sourcepath \user\lib -classpath \user\src com.mypackage

Similar to other tools, if you do not specify -classpath, then the javadoc command uses
the CLASSPATH environment variable when it is set. If both are not set, then the javadoc command
searches for classes from the current directory.
For an in-depth description of how the javadoc command uses -classpath to find user classes as it
relates to extension classes and bootstrap classes, see How Classes Are Found at
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.htm
l
A class path element that contains a base name of * is considered equivalent to specifying a list of all the
files in the directory with the extension .jar or .JAR.
For example, if directory mydir contains a.jar and b.JAR, then the class path element foo/* is
expanded to a A.jar:b.JAR, except that the order of JAR files is unspecified. All JAR files in the
specified directory including hidden files are included in the list. A class path entry that consists of * expands
to a list of all the jar files in the current directory. The CLASSPATH environment variable is similarly
expanded. Any class path wildcard expansion occurs before the Java Virtual Machine (JVM) starts. No Java
program ever sees unexpanded wild cards except by querying the environment, for example, by calling
System.getenv("CLASSPATH").
-subpackages package1:package2:...
Generates documentation from source files in the specified packages and recursively in their subpackages.
This option is useful when adding new subpackages to the source code because they are automatically
included. Each package argument is any top-level subpackage (such as java) or fully qualified package
(such as javax.swing) that does not need to contain source files. Arguments are separated by colons on
all operating systems. Wild cards are not allowed. Use -sourcepath to specify where to find the
packages. This option does not process source files that are in the source tree but do not belong to the
packages. See Process Source Files.
For example, the following command generates documentation for packages

named java and javax.swing and all of their subpackages.
javadoc -d docs -sourcepath \user\src -subpackages

java:javax.swing
-exclude packagename1:packagename2:...
Unconditionally excludes the specified packages and their subpackages from the list formed by -
subpackages. It excludes those packages even when they would otherwise be included by some earlier
or later -subpackages option.
The following example would include java.io, java.util, and java.math (among others), but
would exclude packages rooted at java.net and java.lang. Notice that this example
excludes java.lang.ref, which is a subpackage of java.lang.
javadoc -sourcepath \user\src -subpackages java -exclude

java.net:java.lang
-bootclasspath classpathlist
Specifies the paths where the boot classes reside. These are typically the Java platform classes.
The bootclasspath is part of the search path the javadoc command uses to look up source and
class files. For more information, see How Classes Are Found at
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.htm
l
Separate directories in the classpathlist parameters with semicolons (;) for Windows and colons (:)
for Oracle Solaris.
-extdirs dirist
Specifies the directories where extension classes reside. These are any classes that use the Java Extension
mechanism. The extdirs option is part of the search path the javadoc command uses to look up
source and class files. See the -classpath option for more information. Separate directories
in dirlist with semicolons (;) for Windows and colons (:) for Oracle Solaris.
-verbose
Provides more detailed messages while the javadoc command runs. Without the verbose option,
messages appear for loading the source files, generating the documentation (one message per source file),
and sorting. The verbose option causes the printing of additional messages that specify the number of
milliseconds to parse each Java source file.
-quiet
Shuts off messages so that only the warnings and errors appear to make them easier to view. It also
suppresses the version string.
-breakiterator
Uses the internationalized sentence boundary of java.text.BreakIterator to determine the end of

the first sentence in the main description of a package, class, or member for English. All other locales
already use the BreakIterator class, rather than an English language, locale-specific algorithm. The
first sentence is copied to the package, class, or member summary and to the alphabetic index. From JDK
1.2 and later, the BreakIterator class is used to determine the end of a sentence for all languages
except for English. Therefore, the -breakiterator option has no effect except for English from 1.2 and
later. English has its own default algorithm:
 English default sentence-break algorithm. Stops at a period followed by a space or an HTML block tag,
such as .
 Breakiterator sentence-break algorithm. Stops at a period, question mark, or exclamation point followed
by a space when the next word starts with a capital letter. This is meant to handle most abbreviations
(such as "The serial no. is valid", but will not handle "Mr. Smith"). The -breakiterator option does
not stop at HTML tags or sentences that begin with numbers or symbols. The algorithm stops at the last
period in ../filename, even when embedded in an HTML tag.
In Java SE 1.5 the -breakiterator option warning messages are removed, and the default sentence-
break algorithm is unchanged. If you have not modified your source code to eliminate the -
breakiterator option warnings in Java SE 1.4.x, then you do not have to do anything. The warnings go
away starting with Java SE 1.5.0.
-locale language_country_variant
Specifies the locale that the javadoc command uses when it generates documentation. The argument is
the name of the locale, as described in java.util.Localedocumentation, such as en_US (English,
United States) or en_US_WIN (Windows variant).
Note: The -locale option must be placed ahead (to the left) of any options provided by the standard
doclet or any other doclet. Otherwise, the navigation bars appear in English. This is the only command-line
option that depends on order. See Standard Doclet Options.
Specifying a locale causes the javadoc command to choose the resource files of that locale for messages
such as strings in the navigation bar, headings for lists and tables, help file contents, comments in the
stylesheet.css file, and so on. It also specifies the sorting order for lists sorted alphabetically, and the
sentence separator to determine the end of the first sentence. The -locale option does not determine the
locale of the documentation comment text specified in the source files of the documented classes.
-encoding
Specifies the encoding name of the source files, such as EUCJIS/SJIS. If this option is not specified, then
the platform default converter is used. See also the -docencoding name and -
charset name options.
-Jflag
Passes flag directly to the Java Runtime Environment (JRE) that runs the javadoc command. For
example, if you must ensure that the system sets aside 32 MB of memory in which to process the generated
documentation, then you would call the -Xmx option as follows: javadoc -J-Xmx32m -J-Xms32m
com.mypackage. Be aware that -Xms is optional because it only sets the size of initial memory, which is
useful when you know the minimum amount of memory required.
There is no space between the J and the flag.
Use the -version option to find out what version of the javadoc command you are using. The version
number of the standard doclet appears in its output stream. See Running the Javadoc Command.
javadoc -J-version
java version "1.7.0_09"
Java(TM) SE Runtime Environment (build 1.7.0_09-b05)
Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode)
-javafx
Generates HTML documentation using the JavaFX extensions to the standard doclet. The generated
documentation includes a Property Summary section in addition to the other summary sections generated
by the standard Java doclet. The listed properties are linked to the sections for the getter and setter methods
of each property.
If there are no documentation comments written explicitly for getter and setter methods, the documentation
comments from the property method are automatically copied to the generated documentation for these
methods. This option also adds a new @defaultValue tag that allows documenting the default value for
a property.
Example:
javadoc -javafx MyClass.java -d testdir
Standard Doclet Options

-d directory
Specifies the destination directory where the javadoc command saves the generated HTML files. If you
omit the -d option, then the files are saved to the current directory. The directory value can be absolute
or relative to the current working directory. As of Java SE 1.4, the destination directory is automatically
created when the javadoc command runs.
For example, the following command generates the documentation for the package com.mypackage and
saves the results in the \user\doc\ directory: javadoc -d \user\doc\com.mypackage.
-use
Includes one Use page for each documented class and package. The page describes what packages,
classes, methods, constructors and fields use any API of the specified class or package. Given class C,
things that use class C would include subclasses of C, fields declared as C, methods that return C, and
methods and constructors with parameters of type C. For example, you can look at the Use page for
the String type. Because the getName method in the java.awt.Font class returns type String,
the getName method uses String and so the getName method appears on the Use page
for String.This documents only uses of the API, not the implementation. When a method uses String in
its implementation, but does not take a string as an argument or return a string, that is not considered a use
of String.To access the generated Use page, go to the class or package and click the Use link in the
navigation bar.
-version
Includes the @version text in the generated docs. This text is omitted by default. To find out what version of
the javadoc command you are using, use the -J-version option.
-author
Includes the @author text in the generated docs.
-splitindex
Splits the index file into multiple files, alphabetically, one file per letter, plus a file for any index entries that
start with non-alphabetical symbols.
-windowtitle title
Specifies the title to be placed in the HTML <title> tag. The text specified in the title tag appears in
the window title and in any browser bookmarks (favorite places) that someone creates for this page. This
title should not contain any HTML tags because the browser does not interpret them correctly. Use escape
characters on any internal quotation marks within the title tag. If the -windowtitle option is omitted,
then the javadoc command uses the value of the -doctitle option for the -windowtitleoption.
For example, javadoc -windowtitle "Java SE Platform" com.mypackage.
-doctitle title
Specifies the title to place near the top of the overview summary file. The text specified in the title tag is
placed as a centered, level-one heading directly beneath the top navigation bar. The title tag can contain
HTML tags and white space, but when it does, you must enclose the title in quotation marks. Internal
quotation marks within the titletag must be escaped. For example, javadoc -header "Java
Platform v1.4" com.mypackage.
-title title
No longer exists. It existed only in Beta releases of Javadoc 1.2. It was renamed to -doctitle. This
option was renamed to make it clear that it defines the document title, rather than the window title.
-header header
Specifies the header text to be placed at the top of each output file. The header is placed to the right of the
upper navigation bar. The header can contain HTML tags and white space, but when it does,
the header must be enclosed in quotation marks. Use escape characters for internal quotation marks
within a header. For example, javadoc -header "Java Platform v1.4"
com.mypackage.
-footer footer
Specifies the footer text to be placed at the bottom of each output file. The footer value is placed to the right
of the lower navigation bar. The footer value can contain HTML tags and white space, but when it does,
the footer value must be enclosed in quotation marks. Use escape characters for any internal quotation
marks within a footer.
-top
Specifies the text to be placed at the top of each output file.
-bottom text
Specifies the text to be placed at the bottom of each output file. The text is placed at the bottom of the page,
underneath the lower navigation bar. The text can contain HTML tags and white space, but when it does, the
text must be enclosed in quotation marks. Use escape characters for any internal quotation marks within
text.
-link extdocURL
Creates links to existing Javadoc-generated documentation of externally referenced classes.

The extdocURL argument is the absolute or relative URL of the directory that contains the external Javadoc-
generated documentation you want to link to. You can specify multiple -link options in a
specified javadoc command run to link to multiple documents.
The package-list file must be found in this directory (otherwise, use the -linkoffline option).
The javadoc command reads the package names from the package-list file and links to those packages at
that URL. When the javadoc command runs, the extdocURL value is copied into the <A HREF> links
that are created. Therefore, extdocURL must be the URL to the directory, and not to a file. You can use
an absolute link for extdocURL to enable your documents to link to a document on any web site, or you can
use a relative link to link only to a relative location. If you use a relative link, then the value you pass in
should be the relative path from the destination directory (specified with the -doption) to the directory
containing the packages being linked to.When you specify an absolute link, you usually use an HTTP link.
However, if you want to link to a file system that has no web server, then you can use a file link. Use a file
link only when everyone who wants to access the generated documentation shares the same file system.In
all cases, and on all operating systems, use a slash as the separator, whether the URL is absolute or
relative, and http: or file: as specified in the URL Memo: Uniform Resource Locators at
http://www.ietf.org/rfc/rfc1738.txt
-link http://<host>/<directory>/<directory>/.../<name>
-link file://<host>/<directory>/<directory>/.../<name>
-link <directory>/<directory>/.../<name>
Differences between the -linkoffline and -link options
Use the -link option in the following cases:
 When you use a relative path to the external API document.
 When you use an absolute URL to the external API document if your shell lets you open a connection to that
URL for reading.
Use the -linkoffline option when you use an absolute URL to the external API document, if your shell does not
allow a program to open a connection to that URL for reading. This can occur when you are behind a firewall and the
document you want to link to is on the other side.
Example 1 - Absolute Link to External Documents
Use the following command if you want to link to the java.lang, java.io and other Java platform
packages, shown at
http://docs.oracle.com/javase/8/docs/api/index.html
javadoc -link http://docs.oracle.com/javase/8/docs/api/

com.mypackage
The command generates documentation for the package com.mypackage with links to the Java SE
packages. The generated documentation contains links to the Object class, for example, in the
class trees. Other options, such as the -sourcepath and -d options, are not shown.
Example 2 - Relative Link to External Documents
In this example, there are two packages with documents that are generated in different runs of
the javadoc command, and those documents are separated by a relative path. The packages
are com.apipackage, an API, and com.spipackage, an Service Provide Interface (SPI). You want
the documentation to reside in docs/api/com/apipackage and docs/spi/com/spipackage. Assuming that the
API package documentation is already generated, and that docs is the current directory, you document the
SPI package with links to the API documentation by running: javadoc -d ./spi -link ../api
com.spipackage.
Notice the -link option is relative to the destination directory (docs/spi).
Notes
The -link option lets you link to classes referenced to by your code, but not documented in the
current javadoc command run. For these links to go to valid pages, you must know where those HTML pages are
located and specify that location with extdocURL. This allows third-party documentation to link to java.*
documentation at
http://docs.oracle.com.Omit the -link option when you want the javadoc command to create links
only to APIs within the documentation it is generating in the current run. Without the -link option,
the javadoc command does not create links to documentation for external references because it does not know
whether or where that documentation exists.The -link option can create links in several places in the generated
documentation. See Process Source Files. Another use is for cross-links between sets of packages: Execute
the javadoc command on one set of packages, then run the javadoc command again on another set of
packages, creating links both ways between both sets.
How to Reference a Class
For a link to an externally referenced class to appear (and not just its text label), the class must be referenced in the
following way. It is not sufficient for it to be referenced in the body of a method. It must be referenced in either
an import statement or in a declaration. Here are examples of how the class java.io.File can be referenced:
In any kind of import statement. By wildcard import, import explicitly by name, or automatically import
for java.lang.*.
In Java SE 1.3.n and 1.2.n, only an explicit import by name works. A wildcard import statement does not work, nor
does the automatic import java.lang.*.
In a declaration: void mymethod(File f) {}
The reference can be in the return type or parameter type of a method, constructor, field, class, or interface, or in an
implements, extends, or throws statement.
An important corollary is that when you use the -link option, there can be many links that unintentionally do not
appear due to this constraint. The text would appear without being a link. You can detect these by the warnings they
emit. The simplest way to properly reference a class and add the link would be to import that class.
Package List
The -link option requires that a file named package-list, which is generated by the javadoc command, exists at
the URL you specify with the -link option. The package-list file is a simple text file that lists the names of packages
documented at that location. In the earlier example, the javadoc command searches for a file named package-list
at the specified URL, reads in the package names, and links to those packages at that URL.
For example, the package list for the Java SE API is located at
http://docs.oracle.com/javase/8/docs/api/package-list
The package list starts as follows:
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
and so on ....
When javadoc is run without the -link option and encounters a name that belongs to an externally referenced
class, it prints the name with no link. However, when the -link option is used, the javadoc command searches
the package-list file at the specified extdocURL location for that package name. When it finds the package name, it
prefixes the name with extdocURL.
For there to be no broken links, all of the documentation for the external references must exist at the specified URLs.
The javadoc command does not check that these pages exist, but only that the package-list exists.
Multiple Links
You can supply multiple -link options to link to any number of externally generated documents. Javadoc 1.2 has a
known bug that prevents you from supplying more than one -linkoptions. This was fixed in Javadoc 1.2.2. Specify
a different link option for each external document to link to javadoc -link extdocURL1 -link
extdocURL2 ... -link extdocURLn com.mypackage where extdocURL1, extdocURL2, ...
extdocURLn point respectively to the roots of external documents, each of which contains a file named package-
list.
Cross Links
Note that bootstrapping might be required when cross-linking two or more documents that were previously generated.
If package-list does not exist for either document when you run the javadoc command on the first document, then
the package-list does not yet exist for the second document. Therefore, to create the external links, you must
regenerate the first document after you generate the second document.
In this case, the purpose of first generating a document is to create its package-list (or you can create it by hand if
you are certain of the package names). Then, generate the second document with its external links.
The javadoc command prints a warning when a needed external package-list file does not exist.
-linkoffline extdocURL packagelistLoc
This option is a variation of the -link option. They both create links to Javadoc-generated documentation
for externally referenced classes. Use the -linkoffline option when linking to a document on the web
when the javadoc command cannot access the document through a web connection. Use the -
linkoffline option when package-list file of the external document is not accessible or does not exist at
the extdocURL location, but does exist at a different location that can be specified
by packageListLoc (typically local). If extdocURL is accessible only on the World Wide Web, then
the -linkoffline option removes the constraint that the javadoc command must have a web
connection to generate documentation. Another use is as a work-around to update documents: After you
have run the javadoc command on a full set of packages, you can run the javadoc command again on
a smaller set of changed packages, so that the updated files can be inserted back into the original set.
Examples follow. The -linkoffline option takes two arguments. The first is for the string to be
embedded in the <a href> links, and the second tells the -linkoffline option where to find
package-list:
 The extdocURL value is the absolute or relative URL of the directory that contains the external
Javadoc-generated documentation you want to link to. When relative, the value should be the relative
path from the destination directory (specified with the -d option) to the root of the packages being
linked to. For more information, see extdocURLin the -link option.
 The packagelistLoc value is the path or URL to the directory that contains the package-list file for
the external documentation. This can be a URL (http: or file:) or file path, and can be absolute or
relative. When relative, make it relative to the current directory from where the javadoc command
was run. Do not include the package-list file name.
You can specify multiple -linkoffline options in a specified javadoc command run. Before
Javadoc 1.2.2, the -linkfile options could be specified once.
Absolute Links to External Documents
You might have a situation where you want to link to the java.lang, java.io and other Java SE packages at
http://docs.oracle.com/javase/8/docs/api/index.html
However, your shell does not have web access. In this case, do the following:
1. Open the package-list file in a browser

at http://docs.oracle.com/javase/8/docs/api/package-list
2. Save the file to a local directory, and point to this local copy with the second argument, packagelistLoc. In
this example, the package list file was saved to the current directory (.).
The following command generates documentation for the package c om.mypackage with links to the Java SE
packages. The generated documentation will contain links to the Objectclass, for example, in the class trees.
Other necessary options, such as -sourcepath, are not shown.
javadoc -linkoffline http://docs.oracle.com/javase/8/docs/api/ .

com.mypackage
Relative Links to External Documents
It is not very common to use -linkoffline with relative paths, for the simple reason that the -link option is
usually enough. When you use the -linkoffline option, the package-list file is usually local, and when you use
relative links, the file you are linking to is also local, so it is usually unnecessary to give a different path for the two
arguments to the -linkoffline option When the two arguments are identical, you can use the -link option.
Create a package-list File Manually
If a package-list file does not exist yet, but you know what package names your document will link to, then you can
manually create your own copy of this file and specify its path with packagelistLoc. An example would be the
previous case where the package list for com.spipackage did not exist when com.apipackage was first
generated. This technique is useful when you need to generate documentation that links to new external
documentation whose package names you know, but which is not yet published. This is also a way of creating
package-list files for packages generated with Javadoc 1.0 or 1.1, where package-list files were not generated.
Similarly, two companies can share their unpublished package-list files so they can release their cross-linked
documentation simultaneously.
Link to Multiple Documents

You can include the -linkoffline option once for each generated document you want to refer to:
javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2

packagelistLoc2 ...
Update Documents
You can also use the -linkoffline option when your project has dozens or hundreds of packages. If you have
already run the javadoc command on the entire source tree, then you can quickly make small changes to
documentation comments and rerun the javadoc command on a portion of the source tree. Be aware that the
second run works properly only when your changes are to documentation comments and not to declarations. If you
were to add, remove, or change any declarations from the source code, then broken links could show up in the index,
package tree, inherited member lists, Use page, and other places.
First, create a new destination directory, such as update, for this new small run. In this example, the original
destination directory is named html. In the simplest example, change directory to the parent of html. Set the first
argument of the -linkoffline option to the current directory (.) and set the second argument to the relative path
to html, where it can find package-list and pass in only the package names of the packages you want to update:
javadoc -d update -linkoffline . html com.mypackage

When the javadoc command completes, copy these generated class pages in update\com\package (not the
overview or index) to the original files in html\com\package.
-linksource
Creates an HTML version of each source file (with line numbers) and adds links to them from the standard
HTML documentation. Links are created for classes, interfaces, constructors, methods, and fields whose
declarations are in a source file. Otherwise, links are not created, such as for default constructors and
generated classes.
This option exposes all private implementation details in the included source files, including private classes,
private fields, and the bodies of private methods, regardless of the -public, -package, -protected,
and -private options. Unless you also use the -private option, not all private classes or interfaces
are accessible through links.
Each link appears on the name of the identifier in its declaration. For example, the link to the source code of
the Button class would be on the word Button:
public class Button extends Component implements Accessible

The link to the source code of the getLabel method in the Button class is on the word getLabel:
public String getLabel()

-group groupheading packagepattern:packagepattern
Separates packages on the overview page into whatever groups you specify, one group per table. You
specify each group with a different -group option. The groups appear on the page in the order specified on
the command line. Packages are alphabetized within a group. For a specified -group option, the packages
matching the list of packagepattern expressions appear in a table with the heading groupheading.
 The groupheading can be any text and can include white space. This text is placed in the table
heading for the group.
 The packagepattern value can be any package name at the start of any package name followed
by an asterisk (*). The asterisk is the only wildcard allowed and means match any characters. Multiple
patterns can be included in a group by separating them with colons (:). If you use an asterisk in a
pattern or pattern list, then the pattern list must be inside quotation marks, such
as "java.lang*:java.util".
When you do not supply a -group option, all packages are placed in one group with the
heading Packages and appropriate subheadings. If the subheadings do not include all documented
packages (all groups), then the remaining packages appear in a separate group with the subheading Other
Packages.
For example, the following javadoc command separates the three documented packages
into Core, Extension, and Other Packages. The trailing dot (.) does not appear in java.lang*. Including
the dot, such as java.lang.* omits the java.lang package.
javadoc -group "Core Packages" "java.lang*:java.util"

-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet
java.new
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
-nodeprecated
Prevents the generation of any deprecated API in the documentation. This does what the -
nodeprecatedlist option does, and it does not generate any deprecated API throughout the rest of the
documentation. This is useful when writing code when you do not want to be distracted by the deprecated
code.
-nodeprecatedlist
Prevents the generation of the file that contains the list of deprecated APIs (deprecated-list.html) and the link
in the navigation bar to that page. The javadoc command continues to generate the deprecated API
throughout the rest of the document. This is useful when your source code contains no deprecated APIs,
and you want to make the navigation bar cleaner.
-nosince
Omits from the generated documents the Since sections associated with the @since tags.
-notree
Omits the class/interface hierarchy pages from the generated documents. These are the pages you reach
using the Tree button in the navigation bar. The hierarchy is produced by default.
-noindex
Omits the index from the generated documents. The index is produced by default.
-nohelp
Omits the HELP link in the navigation bars at the top and bottom of each page of output.
-nonavbar
Prevents the generation of the navigation bar, header, and footer, that are usually found at the top and
bottom of the generated pages. The -nonavbar option has no affect on the -bottom option. The -
nonavbar option is useful when you are interested only in the content and have no need for navigation,
such as when you are converting the files to PostScript or PDF for printing only.
-helpfile path\filename
Specifies the path of an alternate help file path\filename that the HELP link in the top and bottom navigation
bars link to. Without this option, the javadoc command creates a help file help-doc.html that is hard-coded
in the javadoc command. This option lets you override the default. The file name can be any name and is
not restricted to help-doc.html. The javadoc command adjusts the links in the navigation bar accordingly,
for example:
javadoc -helpfile C:\user\myhelp.html java.awt.

-stylesheet path\filename
Specifies the path of an alternate HTML stylesheet file. Without this option, the javadoc command
automatically creates a stylesheet file stylesheet.css that is hard-coded in the javadoc command. This
option lets you override the default. The file name can be any name and is not restricted to stylesheet.css,
for example:
javadoc -stylesheet file C:\user\mystylesheet.css com.mypackage

-serialwarn
Generates compile-time warnings for missing @serial tags. By default, Javadoc 1.2.2 and later versions
generate no serial warnings. This is a reversal from earlier releases. Use this option to display the serial
warnings, which helps to properly document default serializable fields and writeExternal methods.
-charset name
Specifies the HTML character set for this document. The name should be a preferred MIME name as
specified in the IANA Registry, Character Sets at
http://www.iana.org/assignments/character-sets
For example, javadoc -charset "iso-8859-1" mypackage inserts the following line in the
head of every generated page:
<META http-equiv="Content-Type" content="text/html; charset=ISO-

8859-1">
This META tag is described in the HTML standard (4197265 and 4137321), HTML Document
Representation, at
http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2
See also the -encoding and -docencoding name options.
-docencoding name
Specifies the encoding of the generated HTML files. The name should be a preferred MIME name as
specified in the IANA Registry, Character Sets at
http://www.iana.org/assignments/character-sets
If you omit the -docencoding option but use the -encoding option, then the encoding of the
generated HTML files is determined by the -encoding option, for example: javadoc -docencoding
"iso-8859-1" mypackage. See also the -encoding and -docencoding name options.
-keywords
Adds HTML keyword <META> tags to the generated file for each class. These tags can help search engines
that look for <META> tags find the pages. Most search engines that search the entire Internet do not look at
<META> tags, because pages can misuse them. Search engines offered by companies that confine their
searches to their own website can benefit by looking at <META> tags. The <META> tags include the fully
qualified name of the class and the unqualified names of the fields and methods. Constructors are not
included because they are identical to the class name. For example, the class String starts with these
keywords:
<META NAME="keywords" CONTENT="java.lang.String class">

<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
<META NAME="keywords" CONTENT="length()">
<META NAME="keywords" CONTENT="charAt()">
-tag tagname:Xaoptcmf:"taghead"
Enables the javadoc command to interpret a simple, one-argument @tagname custom block tag in
documentation comments. For the javadoc command to spell-check tag names, it is important to include
a -tag option for every custom tag that is present in the source code, disabling (with X) those that are not
being output in the current run.The colon (:) is always the separator. The -tag option outputs the tag
heading taghead in bold, followed on the next line by the text from its single argument. Similar to any block
tag, the argument text can contain inline tags, which are also interpreted. The output is similar to standard
one-argument tags, such as the @return and @author tags. Omitting a value
for taghead causes tagname to be the heading.
Placement of tags: The Xaoptcmf arguments determine where in the source code the tag is allowed to
be placed, and whether the tag can be disabled (using X). You can supply either a, to allow the tag in all
places, or any combination of the other letters:
X (disable tag)
a (all)
o (overview)
p (packages)
t (types, that is classes and interfaces)
c (constructors)
m (methods)
f (fields)
Examples of single tags: An example of a tag option for a tag that can be used anywhere in the source
code is: -tag todo:a:"To Do:".
If you want the @todo tag to be used only with constructors, methods, and fields, then you use: -tag
todo:cmf:"To Do:".
Notice the last colon (:) is not a parameter separator, but is part of the heading text. You would use either
tag option for source code that contains the @todo tag, such as: @todo The documentation for
this method needs work.
Colons in tag names: Use a backslash to escape a colon that you want to use in a tag name. Use the -
tag ejb\\:bean:a:"EJB Bean:" option for the following documentation comment:
/**
* @ejb:bean
*/
Spell-checking tag names: Some developers put custom tags in the source code that they do not always
want to output. In these cases, it is important to list all tags that are in the source code, enabling the ones
you want to output and disabling the ones you do not want to output. The presence of X disables the tag,
while its absence enables the tag. This gives the javadoc command enough information to know whether
a tag it encounters is unknown, which is probably the results of a typographical error or a misspelling.
The javadoc command prints a warning in these cases. You can add X to the placement values already
present, so that when you want to enable the tag, you can simply delete the X. For example, if
the @todo tag is a tag that you want to suppress on output, then you would use: -tag
todo:Xcmf:"To Do:". If you would rather keep it simple, then use this: -tag todo:X. The syntax -
tag todo:X works even when the @todo tag is defined by a taglet.
Order of tags: The order of the -tag and -taglet options determines the order the tags are output. You
can mix the custom tags with the standard tags to intersperse them. The tag options for standard tags are
placeholders only for determining the order. They take only the standard tag's name. Subheadings for
standard tags cannot be altered. This is illustrated in the following example.If the -tag option is missing,
then the position of the -taglet option determines its order. If they are both present, then whichever
appears last on the command line determines its order. This happens because the tags and taglets are
processed in the order that they appear on the command line. For example, if the -taglet and -
tag options have the name todo value, then the one that appears last on the command line determines
the order.
Example of a complete set of tags: This example inserts To Do after Parameters and before Throws in the
output. By using X, it also specifies that the @example tag might be encountered in the source code that
should not be output during this run. If you use the @argfile tag, then you can put the tags on separate
lines in an argument file similar to this (no line continuation characters needed):
-tag param
-tag return
-tag todo:a:"To Do:"
-tag throws
-tag see
-tag example:X
When the javadoc command parses the documentation comments, any tag encountered that is neither a
standard tag nor passed in with the -tag or -taglet options is considered unknown, and a warning is
thrown.
The standard tags are initially stored internally in a list in their default order. Whenever the -tag options are
used, those tags get appended to this list. Standard tags are moved from their default position. Therefore, if
a -tag option is omitted for a standard tag, then it remains in its default position.
Avoiding conflicts: If you want to create your own namespace, then you can use a dot-separated naming
convention similar to that used for packages: com.mycompany.todo. Oracle will continue to create
standard tags whose names do not contain dots. Any tag you create will override the behavior of a tag by
the same name defined by Oracle. If you create a @todo tag or taglet, then it always has the same
behavior you define, even when Oracle later creates a standard tag of the same name.
Annotations vs. Javadoc tags: In general, if the markup you want to add is intended to affect or produce
documentation, then it should be a Javadoc tag. Otherwise, it should be an annotation. See Custom Tags
and Annotations in How to Write Doc Comments for the Javadoc Tool at
137868.html#annotations
You can also create more complex block tags or custom inline tags with the -taglet option.
-taglet class
Specifies the class file that starts the taglet used in generating the documentation for that tag. Use the fully
qualified name for the class value. This taglet also defines the number of text arguments that the custom
tag has. The taglet accepts those arguments, processes them, and generates the output. For extensive
documentation with example taglets, see: Taglet Overview at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/ov
erview.html
Taglets are useful for block or inline tags. They can have any number of arguments and implement custom
behavior, such as making text bold, formatting bullets, writing out the text to a file, or starting other
processes. Taglets can only determine where a tag should appear and in what form. All other decisions are
made by the doclet. A taglet cannot do things such as remove a class name from the list of included classes.
However, it can execute side effects, such as printing the tag's text to a file or triggering another process.
Use the -tagletpath option to specify the path to the taglet. The following example inserts the To Do
taglet after Parameters and ahead of Throws in the generated pages. Alternately, you can use the -
taglet option in place of its -tag option, but that might be difficult to read.
-taglet com.sun.tools.doclets.ToDoTaglet
-tagletpath /home/taglets
-tag return
-tag param
-tag todo
-tag throws
-tag see
-tagletpath tagletpathlist
Specifies the search paths for finding taglet class files. The tagletpathlist can contain multiple paths
by separating them with a colon (:). The javadoc command searches all subdirectories of the specified
paths.
-docfilesubdirs
Enables deep copying of doc-files directories. Subdirectories and all contents are recursively copied to the
destination. For example, the directory doc-files/example/images and all of its contents would be copied.
There is also an option to exclude subdirectories.
-excludedocfilessubdir name1:name2
Excludes any doc-files subdirectories with the specified names. This prevents the copying of SCCS and
other source-code-control subdirectories.
-noqualifier all | packagename1:packagename2...
Omits qualifying package names from class names in output. The argument to the -noqualifier option
is either all (all package qualifiers are omitted) or a colon-separate list of packages, with wild cards, to be
removed as qualifiers. The package name is removed from places where class or interface names appear.
See Process Source Files.
The following example omits all package qualifiers: -noqualifier all.

The following example omits java.lang and java.io package qualifiers: -noqualifier
java.lang:java.io.
The following example omits package qualifiers starting with java, and com.sun subpackages, but
not javax: -noqualifier java.*:com.sun.*.
Where a package qualifier would appear due to the previous behavior, the name can be suitably shortened.
See How a Name Appears. This rule is in effect whether or not the -noqualifier option is used.
-notimestamp
Suppresses the time stamp, which is hidden in an HTML comment in the generated HTML near the top of
each page. The -notimestamp option is useful when you want to run the javadoc command on two
source bases and get the differences between diff them, because it prevents time stamps from causing
a diff (which would otherwise be a diff on every page). The time stamp includes
the javadoc command release number, and currently appears similar to this: .
-nocomment
Suppresses the entire comment body, including the main description and all tags, and generate only
declarations. This option lets you reuse source files that were originally intended for a different purpose so
that you can produce skeleton HTML documentation at the early stages of a new project.
-sourcetab tablength
Specifies the number of spaces each tab uses in the source.
Command-Line Argument Files

To shorten or simplify the javadoc command, you can specify one or more files that contain arguments to
the javadoc command (except -J options). This enables you to create javadoc commands of any length on any
operating system.
An argument file can include javac options and source file names in any combination. The arguments within a file
can be space-separated or newline-separated. If a file name contains embedded spaces, then put the whole file
name in double quotation marks.
File Names within an argument file are relative to the current directory, not the location of the argument file. Wild
cards (*) are not allowed in these lists (such as for specifying *.java). Using the at sign (@) to recursively interpret
files is not supported. The -J options are not supported because they are passed to the launcher, which does not
support argument files.
When you run the javadoc command, pass in the path and name of each argument file with the @ leading
character. When the javadoc command encounters an argument beginning with the at sign (@), it expands the
contents of that file into the argument list.
Example 1 - Single Argument File
You could use a single argument file named argfile to hold all javadoc command
arguments: javadoc @argfile. The argument file contains the contents of both files, as shown in the
next example.
Example 2 - Two Argument Files

You can create two argument files: One for the javadoc command options and the other for the package
names or source file names. Notice the following lists have no line-continuation characters.
Create a file named options that contains:
-d docs-filelist
-use
-splitindex
-windowtitle 'Java SE 7 API Specification'
-doctitle 'Java SE 7 API Specification'
-header 'Java SE 7'
-bottom 'Copyright © 1993-2011 Oracle and/or its affiliates.
All rights reserved.'
-group "Core Packages" "java.*"
-overview \java\pubs\ws\1.7.0\src\share\classes\overview-core.html
-sourcepath \java\pubs\ws\1.7.0\src\share\classes
Create a file named packages that contains:
com.mypackage1
com.mypackage2
com.mypackage3
Run the javadoc command as follows:
javadoc @options @packages

Example 3 - Argument Files with Paths
The argument files can have paths, but any file names inside the files are relative to the current working
directory (not path1 or path2):
javadoc @path1\options @path2\packages

Example 4 - Option Arguments
The following example saves an argument to a javadoc command option in an argument file. The -
bottom option is used because it can have a lengthy argument. You could create a file named bottom to
contain the text argument:

<a href="http://bugreport.sun.com/bugreport/">Submit a bug or
feature</a> 
Copyright © 1993, 2011, Oracle and/or its affiliates. All
rights reserved. 
Oracle is a registered trademark of Oracle Corporation and/or
its affiliates.
Other names may be trademarks of their respective
owners.
Run the javadoc command as follows: javadoc -bottom @bottom @packages.
You can also include the -bottom option at the start of the argument file and run the javadoc command
as follows: javadoc @bottom @packages.
Running the Javadoc Command

The release number of the javadoc command can be determined with the javadoc -J-version option. The
release number of the standard doclet appears in the output stream. It can be turned off with the -quiet option.
Use the public programmatic interface to call the javadoc command from within programs written in the Java
language. This interface is in com.sun.tools.javadoc.Main (and the javadoc command is reentrant). For
more information, see The Standard Doclet at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/standard-
doclet.html#runningprogrammatically
The following instructions call the standard HTML doclet. To call a custom doclet, use the -doclet and -
docletpath options. See Doclet Overview at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview
.html
Simple Examples
You can run the javadoc command on entire packages or individual source files. Each package name has a
corresponding directory name.
In the following examples, the source files are located at C:\home\src\java\awt\*java. The destination directory is
C:\home\html.
Document One or More Packages
To document a package, the source files for that package must be located in a directory that has the same name as
the package.
If a package name has several identifiers (separated by dots, such as java.awt.color), then each subsequent
identifier must correspond to a deeper subdirectory (such as java\awt\color).
You can split the source files for a single package among two such directory trees located at different places, as long
as -sourcepath points to them both. For example, src1\java\awt\color and src2\java\awt\color.
You can run the javadoc command either by changing directories (with the cd command) or by using the -
sourcepath option. The following examples illustrate both alternatives.
Example 1 - Recursive Run from One or More Packages
This example uses -sourcepath so the javadoc command can be run from any directory and -
subpackages (a new 1.4 option) for recursion. It traverses the subpackages of the java directory
excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a
subpackage of java.lang. To also traverse down other package trees, append their names to the -
subpackages argument, such as java:javax:org.xml.sax.
javadoc -d /home/html -sourcepath /home/src -subpackages java -

exclude
Example 2 - Change to Root and Run Explicit Packages
Change to the parent directory of the fully qualified package. Then, run the javadoc command with the
names of one or more packages that you want to document:
cd C:\home\src\
javadoc -d C:\home\html java.awt java.awt.event
To also traverse down other package trees, append their names to the -subpackages argument, such as
java:javax:org.xml.sax.
Example 3 - Run from Any Directory on Explicit Packages in One Tree

In this case, it does not matter what the current directory is. Run the javadoc command and use the -
sourcepath option with the parent directory of the top-level package. Provide the names of one or more
packages that you want to document:
javadoc -d C:\home\html -sourcepath C:\home\src java.awt

java.awt.event
Example 4 - Run from Any Directory on Explicit Packages in Multiple Trees
Run the javadoc command and use the -sourcepath option with a colon-separated list of the paths to
each tree's root. Provide the names of one or more packages that you want to document. All source files for
a specified package do not need to be located under a single root directory, but they must be found
somewhere along the source path.
javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2

java.awt java.awt.event
The result is that all cases generate HTML-formatted documentation for
the public and protected classes and interfaces in packages java.awt and java.awt.event and
save the HTML files in the specified destination directory. Because two or more packages are being
generated, the document has three HTML frames: one for the list of packages, another for the list of classes,
and the third for the main class pages.
Document One or More Classes
The second way to run the javadoc command is to pass one or more source files. You can run javadoc either of
the following two ways: by changing directories (with the cdcommand) or by fully specifying the path to the source
files. Relative paths are relative to the current directory. The -sourcepath option is ignored when passing source
files. You can use command-line wild cards, such as an asterisk (*), to specify groups of classes.
Example 1 - Change to the Source Directory
Change to the directory that holds the source files. Then run the javadoc command with the names of one
or more source files you want to document.
This example generates HTML-formatted documentation for the classes Button, Canvas, and classes
that begin with Graphics. Because source files rather than package names were passed in as arguments
to the javadoc command, the document has two frames: one for the list of classes and the other for the
main page.
cd C:\home\src\java\awt
javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
Example 2 - Change to the Root Directory of the Package
This is useful for documenting individual source files from different subpackages off of the same root.
Change to the package root directory, and supply the source files with paths from the root.
cd C:\home\src
javadoc -d \home\html java\awt\Button.java java\applet\Applet.java
Example 3 - Document Files from Any Directory
In this case, it does not matter what the current directory is. Run the javadoc command with the absolute
path (or path relative to the current directory) to the source files you want to document.
javadoc -d C:\home\html C:\home\src\java\awt\Button.java

C:\home\src\java\awt\Graphics*.java
Document Packages and Classes
You can document entire packages and individual classes at the same time. Here is an example that mixes two of the
previous examples. You can use the -sourcepath option for the path to the packages but not for the path to the
individual classes.
javadoc -d C:\home\html -sourcepath C:\home\src java.awt

C:\home\src\java\applet\Applet.java
Real-World Examples
The following command-line and makefile versions of the javadoc command run on the Java platform APIs. It
uses 180 MB of memory to generate the documentation for the 1500 (approximately) public and protected classes in
the Java SE 1.2. Both examples use absolute paths in the option arguments, so that the same javadoc command
can be run from any directory.
Command-Line Example
The following command might be too long for some shells. You can use a command-line argument file (or write a
shell script) to overcome this limitation.
In the example, packages is the name of a file that contains the packages to process, such
as java.applet java.lang. None of the options should contain any newline characters between the single
quotation marks. For example, if you copy and paste this example, then delete the newline characters from the -
bottom option.
javadoc -sourcepath \java\jdk\src\share\classes ^

-overview \java\jdk\src\share\classes\overview.html ^
-d \java\jdk\build\api ^
-use ^
-splitIndex ^
-windowtitle 'Java Platform, Standard Edition 7 API Specification' ^
-doctitle 'Java Platform, Standard Edition 7 API Specification' ^
-header 'Java SE 7' ^
-bottom '
feature</a> 
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights
reserved. 
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates.
Other names may be trademarks of their respective owners.'
-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" ^
-group "Extension Packages" "javax.*" ^
-J-Xmx180m ^
@packages
Programmatic Interface
The Javadoc Access API enables the user to invoke the Javadoc tool directly from a Java application without
executing a new process.
For example, the following statements are equivalent to the command javadoc -d /home/html -
sourcepath /home/src -subpackages java -exclude java.net:java.lang
com.example:
import javax.tools.DocumentationTool;
import javax.tools.ToolProvider;
public class JavaAccessSample{

public static void main(String[] args){
DocumentationTool javadoc =
ToolProvider.getSystemDocumentationTool();
int rc = javadoc.run( null, null, null,
"-d", "/home/html",
"-sourcepath", "home/src",
"-subpackages", "java",
"-exclude", "java.net:java.lang",
"com.example");
}
}
The first three arguments of the run method specify input, standard output, and standard error streams. Null is the
default value for System.in, System.out, and System.err, respectively.
The makefile Example

This is an example of a GNU makefile. Single quotation marks surround makefile arguments. For an example
of a Windows makefile, see the makefiles section of the Javadoc FAQ at
137483.html#makefiles
javadoc -sourcepath $(SRCDIR) ^ /* Sets path for source

files */
-overview $(SRCDIR)\overview.html ^ /* Sets file for overview
text */
-d \java\jdk\build\api ^ /* Sets destination
directory */
-use ^ /* Adds "Use" files
*/
-splitIndex ^ /* Splits index A-Z
*/
-windowtitle $(WINDOWTITLE) ^ /* Adds a window title
*/
-doctitle $(DOCTITLE) ^ /* Adds a doc title
*/
-header $(HEADER) ^ /* Adds running header
text */
-bottom $(BOTTOM) ^ /* Adds text at bottom
*/
-group $(GROUPCORE) ^ /* 1st subhead on
overview page */
-group $(GROUPEXT) ^ /* 2nd subhead on
overview page */
-J-Xmx180m ^ /* Sets memory to 180MB
*/
java.lang java.lang.reflect ^ /* Sets packages to
document */
java.util java.io java.net ^
java.applet
WINDOWTITLE = 'Java Platform, Standard Edition 6 API Specification'

DOCTITLE = 'Java Platform, Standard Edition 6 API Specification'
HEADER = 'Java Platform, Standard Edition 6'
BOTTOM = '
feature</a> 
Copyright © 1993, 2011, Oracle and/or its affiliates. All
rights reserved. 
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates.
Other names may be trademarks of their respective owners.'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'
Notes
 If you omit the -windowtitle option, then the javadoc command copies the document title to the window
title. The -windowtitle option text is similar to the the -doctitleoption, but without HTML tags to
prevent those tags from appearing as raw text in the window title.
 If you omit the -footer option, then the javadoc command copies the header text to the footer.
 Other important options you might want to use, but were not needed in the previous example, are the -
classpath and -link options.
General Troubleshooting
 The javadoc command reads only files that contain valid class names. If the javadoc command is not
correctly reading the contents of a file, then verify that the class names are valid. See Process Source Files.
 See the Javadoc FAQ for information about common bugs and for troubleshooting tips at
137483.html
Errors and Warnings

Error and warning messages contain the file name and line number to the declaration line rather than to the particular
line in the documentation comment.
For example, this message error: cannot read: Class1.java means that the javadoc command is
trying to load Class1.java in the current directory. The class name is shown with its path (absolute or relative).
Environment
CLASSPATH
CLASSPATH is the environment variable that provides the path that the javadoc command uses to find
user class files. This environment variable is overridden by the -classpath option. Separate directories
with a semicolon for Windows or a colon for Oracle Solaris.
Windows example: .;C:\classes;C:\home\java\classes
Oracle Solaris example: .:/home/classes:/usr/local/java/classes.
See Also
 javac(1)
 java(1)
 jdb(1)
 javah(1)
 javap(1)
Related Documents
 Javadoc Technology at
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
 How Classes Are Found

http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html
 How to Write Doc Comments for the Javadoc Tool

137868.html
 URL Memo, Uniform Resource Locators

http://www.ietf.org/rfc/rfc1738.txt
 HTML standard, HTML Document Representation (4197265 and 4137321)

http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2
Contents Previous Next
Copyright © 1993, 2018, Oracle and/or its affiliates. All rights reserved.
Contact Us
appletviewer
Note: You use the appletviewer command to launch the AppletViewer and run applets outside of a web
browser. Although available and supported in JDK 9, the Applet API is marked as deprecated in preparation
for removal in a future release. Instead of applets, consider alternatives such as Java Web Start or self-
contained applications.
Synopsis
appletviewer [options] url...
options
Specifies the command-line options separated by spaces. See Options for appletviewer.
url
Specifies the location of the documents or resources to be displayed. You can specify multiple URLs
separated by spaces.
Description
The appletviewer command connects to the documents or resources designated by url and displays each
applet referenced by the documents in its own AppletViewer window. If the documents referred to
by url don’t reference any applets with the OBJECT, EMBED, or APPLET tag, then
the appletviewer command does nothing. The OBJECT, EMBED, and APPLETtags are described
in AppletViewer Tags.
The appletviewer command requires encoded URLs according to the escaping mechanism defined in
RFC2396. Only encoded URLs are supported. However, file names must be unencoded, as specified in
RFC2396.
Note:
The appletviewer command is intended for development purposes only.
Options for appletviewer
-encoding encoding-name
Specifies the input HTML file encoding name.
-Jjavaoption
Passes the string javaoption as a single argument to the Java interpreter, which runs the
AppletViewer. The argument shouldn’t contain spaces. Multiple argument words must all begin with
the prefix -J. This is useful for adjusting the compiler's execution environment or memory usage.
Seejava command documentation for more information about JVM options.
AppletViewer Tags
The AppletViewer makes it possible to run a Java applet without using a browser.
The AppletViewer ignores any HTML that isn’t immediately relevant to launching an applet. However, it
recognizes a wide variety of applet-launching syntax. The HTML code that the AppletViewer recognizes is
described in this section. All other HTML code is ignored.
object
The object tag is the HTML 4.0 tag for embedding applets and multmedia objects into an HTML page. It’s
also an Internet Explorer 4.n extension to HTML 3.2 which enables IE to run a Java applet using the latest Java
plug-in.
<object
width="pixelWidth"
height="pixelHeight"
>
<param name="code" value="yourClass.class">
<param name="object" value="serializedObjectOrJavaBean">
<param name="codebase" value="classFileDirectory">
...alternate-text
</object>
Note:
 The AppletViewer ignores the classID attribute, on the assumption that it’spointing to the Java
plug-in, with the value:
 classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
 The AppletViewer also ignores the codebase attribute that’s usually included as part of
the object tag, assuming that it points to a Java plug-in in a network cab file with a value like:
 codebase="http://java.sun.com/products/plugin/1.1/jinstall-11-
win32.cab#Version=1,1,0,0"
 The optional codebase parameter tag supplies a relative URL that specifies the location of the applet
class.
 Either code or object is specified, not both.
 The type parameter tag isn’t used by AppletViewer, but should be present so that browsers load the
plug-in properly. For an applet, the value should be similar to:
 <param name="type" value="application/x-java-applet;version=1.1">
or
<param name="type__1" value="application/x-java-applet">
For a serialized object or JavaBean, the type parameter value should be similar to:
<param name="type__2" value="application/x-java-bean;version=1.1">
or
<param name="type__3" value="application/x-java-bean">
 Other parameter tags are argument values supplied to the applet.

 The object tag recognized by IE4.n and the embed tag recognized by Netscape 4.n can be combined
so that an applet can use the latest Java plug-in, regardless of the browser that downloads the applet.
 The AppletViewer doesn’t recognize the java_code, java_codebase, java_object,
or java_type param tags. These tags are needed only when the applet defines parameters with the
names code, codebase, object, or type, respectively. In that situation, the plug-in recognizes
and uses the java_ versionoption in preference to the version is be used by the applet. If the
applet requires a parameter with one of these four names, then it might not run in the AppletViewer.
embed
The embed tag is the Netscape extension to HTML 3.2 that allows embedding an applet or a multimedia
object in an HTML page. It allows a Netscape 4.n browser (which supports HTML 3.2) to run a Java applet
using the Java plug-in.
<embed
code="yourClass.class"
object="serializedObjectOrJavaBean"
codebase="classFileDirectory"
width="pixelWidth"
>
...
</embed>
Note:
 The object and embed tags can be combined so that an applet can use the latest Java plug-in,
regardless of the browser that downloads the applet.
 Unlike the object tag, all values specified in an embed tag are attributes (part of the tag) rather than
parameters (between the start tag and end tag), specified with a param tag.
 To supply argument values for applet parameters, you add additional attributes to the embedtag.
 The AppletViewer ignores the src attribute that’s usually part of an embed tag.
 The optional codebase attribute supplies a relative URL that specifies the location of the applet
class.
 The type attribute isn’t used by the AppletViewer, but should be present so that browsers load the
plug-in properly.
For an applet, the value should be similar to:

<type="application/x-java-applet;version=1.1">...
or
<type="application/x-java-applet">...
For a serialized object or JavaBean, the type parameter value should be similar to:
<type="application/x-java-bean;version=1.1">...
or
<type="application/x-java-bean">...
 The pluginspage attribute isn’t used by the AppletViewer, but should be present so that browsers
load the plug-in properly. It should point to a Java plug-in in a network cab file with a value like:
 pluginspage="http://java.sun.com/products/plugin/1.1/jinstall-11-
win32.cab#Version=1,1,0,0"
applet
The applet tag is the original HTML 3.2 tag for embedding an applet in an HTML page. Applets loaded
using the applet tag are run by the browser, which may not be using the latest version of the Java platform. To
ensure that the applet runs with the latest version, use the object tag to load the Java plug-in into the
browser. The plug-in then runs the applet.
<applet
code="yourClass.class"
object="serializedObjectOrJavaBean"
codebase="classFileDirectory"
width="pixelWidth"
>
<param name="..." value="...">
...alternate-text
</applet>
Note:
 The optional codebase attribute supplies a relative URL that specifies the location of the applet
class.
 The param tags supply argument values for applet parameters.
app
The app tag was a short-lived abbreviation for applet that’s no longer supported. The AppletViewer translates
the tag and prints an equivalent tag that’s supported.
<app
class="classFileName" (without a .class suffix)
src="classFileDirectory"
width="pixelWidth"
>
<param name="..." value="...">
...
</app>
javac
You can use the javac tool and its options to read Java class and interface definitions and compile them into
bytecode and class files.
Synopsis
javac [ options ] [ sourcefiles ]
options
Command-line options. See Overview of javac Options.
sourcefiles
One or more source files to be compiled (such as MyClass.java) or processed for annotations (such
as MyPackage.MyClass).
Description
The javac command reads class and interface definitions, written in the Java programming language, and
compiles them into bytecode class files. The javac command can also process annotations in Java source files
and classes.
In JDK 9, a new launcher environment variable, JDK_JAVAC_OPTIONS, has been introduced that prepends its
content to the command line to javac . See Using JDK_JAVAC_OPTIONS Environment Variable.
There are two ways to pass source code file names to javac.
 For a small number of source files, you can list the file names on the command line.
 For a large number of source files, you can use the @filename option on the javac command line to
include a file that lists the source file names. See Standard Options for javac for a description of the
option and javac Command-Line Argument Files for a description of javac argument files.
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 that combine the inner and
outer class names, such as MyClass$MyInnerClass.class.
You should arrange the source files in a directory tree that reflects their package tree. For example:
 Oracle Solaris, Linux, and OS X: If all of your source files are in /workspace, then put the source
code
for com.mysoft.mypack.MyClass in /workspace/com/mysoft/mypack/MyClass.java.
 Windows: If all of your source files are in \workspace, then put the source code
for com.mysoft.mypack.MyClass 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 the -d option described in Standard Options for javac.
Programmatic Interface
The javac command supports the new Java Compiler API defined by the classes and interfaces in
the javax.tools package.
Implicitly Loaded Source Files

To compile a set of source files, the compiler might need to implicitly load additional source files.
See Searching for Types. Such files are currently not subject to annotation processing. By default, the compiler
gives a warning when annotation processing occurs and any implicitly loaded source files are compiled. The -
implicit option provides a way to suppress the warning.
Using JDK_JAVAC_OPTIONS Environment Variable

The content of the JDK_JAVAC_OPTIONS environment variable, separated by white-spaces ( ) or white-space
characters (\n, \t, \r, or \f) is prepended to the command line arguments passed to javac as a list of
arguments.
The encoding requirement for the environment variable is the same as the javac command line on the
system. JDK_JAVAC_OPTIONS environment variable content is treated in the same manner as that specified
in the command line.
Single (') or double (") quotes can be used to enclose arguments that contain whitespace characters. All
content between the open quote and the first matching close quote are preserved by simply removing the pair
of quotes. In case a matching quote is not found, the launcher will abort with an error message. @files are
supported as they are specified in the command line. However, as in @files, use of a wildcard is not supported.
Examples of quoting arguments containing white spaces:
export JDK_JAVAC_OPTIONS=‘@"C:\white spaces\argfile”'
export JDK_JAVAC_OPTIONS=‘"@C:\white spaces\argfile”'
export JDK_JAVAC_OPTIONS='@C:\"white spaces"\argfile'
Overview of javac Options

The compiler has sets of standard options, and cross-compilation options that are supported on the current
development environment. The compiler also has a set of nonstandard options that are specific to the current
virtual machine and compiler implementations but are subject to change in the future. The nonstandard options
begin with -X . The different sets of javac options are described in the following sections:
 Standard Options for javac

 Cross-Compilation Options for javac
 Extra Options for javac
Standard Options for javac
@filename
Reads options and file names from a file. To shorten or simplify the javac command, you can
specify one or more files that contain arguments to the javac command (except -J options). This
let’s you to create javaccommands of any length on any operating system. See javac Command-Line
Argument Files.
-Akey[=value]
Specifies options to pass to annotation processors. These options aren’t interpreted by javac directly,
but are made available for use by individual processors. The key value should be one or more
identifiers separated by a dot (.).
--add-modules module , module

Specifies root modules to resolve in addition to the initial modules, or all modules on the module path
if module is ALL-MODULE-PATH.
--boot-class-path path or -bootclasspath path
Overrides the location of the bootstrap class files.
Note:
This option is not supported when using --release release to compile for JDK 9. See the
description of --release release for details about compiling for versions other than JDK 9.
--class-path path , -classpath path, or -cp path
Specifies where to find user class files and annotation processors. This class path overrides the user
class path in the CLASSPATH environment variable.
 If --class-path, -classpath, or -cp aren’t specified, then the user class path is the
current directory.
 If the -sourcepath option isn’t specified, then the user class path is also searched for
source files.
 If the -processorpath option isn’t specified, then the class path is also searched for
annotation processors.
-d directory
Sets the destination directory for class files. If a class is part of a package, then javac puts the class
file in a subdirectory that reflects the package name and creates directories as needed. For example:
 Oracle Solaris, Linux, and OS X: If you specify -d /home/myclasses and the class is
called com.mypackage.MyClass, then the class file
is /home/myclasses/com/mypackage/MyClass.class.
 Windows: If you specify -d C:\myclasses and the class is
called com.mypackage.MyClass, then the class file
is C:\myclasses\com\mypackage\MyClass.class.
If the -d option isn’t specified, then javac puts each class file in the same directory as the source file
from which it was generated.
Note:
The directory specified by the -d option isn’t automatically added to your user class path.
-deprecation
Shows a description of each use or override of a deprecated member or class. Without the -
deprecationoption, javac shows a summary of the source files that use or override deprecated
members or classes. The -deprecation option is shorthand for -Xlint:deprecation.
-encoding encoding
Specifies character encoding used by source files, such as EUC-JP and UTF-8. If the -
encoding option isn’t specified, then the platform default converter is used.
-endorseddirs directories
Overrides the location of the endorsed standards path.
Note:
-extdirs directories
Overrides the location of the installed extensions. The directories variable is a colon-separated list of
directories. Each JAR file in the specified directories is searched for class files. All JAR files found
become part of the class path.
If you are cross-compiling, then this option specifies the directories that contain the extension classes.
See Cross-Compilation Options for javac.
Note:
-g
Generates all debugging information, including local variables. By default, only line number and
source file information is generated.
-g:[lines, vars, source],[lines, vars, source],[lines, vars, source]
Generates only the kinds of debugging information specified by the comma-separated list of
keywords. Valid keywords are:
lines
Line number debugging information.
vars
Local variable debugging information.
source
Source file debugging information.
-g:none
Doesn’t generate any debugging information.
-h directory
Specifies where to place generated native header files.
When you specify this option, a native header file is generated for each class that contains native
methods or that has one or more constants annotated with
the java.lang.annotation.Native annotation. If the class is part of a package, then the
compiler puts the native header file in a subdirectory that reflects the package name and creates
directories as needed.
--help or –help
Prints a synopsis of the standard options.
--help-extra or -X
Prints the help for extra options.
-implicit:{[none, class],[none, class]}
Specifies whether or not to generate class files for implicitly referenced files:
 -implicit:class — Automatically generates class files.

 -implicit:none — Suppresses class file generation.
If this option isn’t specified, then the default automatically generates class files. In this case, the
compiler issues a warning if any class files are generated when also doing annotation processing. The
warning isn’t issued when the -implicit option is explicitly set. See Searching for Types.
-Joption
Passes option to the runtime system, where option is one of the Java options described
on javacommand. For example, -J-Xms48m sets the startup memory to 48 MB.
Note:
The CLASSPATH environment variable, -classpath option, -bootclasspath option, and -
extdirsoption don’t specify the classes used to run javac. Trying to customize the compiler
implementation with these options and variables is risky and often doesn’t accomplish what you want.
If you must customize the complier implementation, then use the -J option to pass options through to
the underlying Java launcher.
--limit-modules module , module*

Limits the universe of observable modules.
--module module-name or -m module-name
Compiles only the specified module and checks time stamps.
--module-path path or -p path
Specifies where to find application modules.
--module-source-path module-source-path
Specifies where to find input source files for multiple modules.
--module-version version
Specifies the version of modules that are being compiled.
-nowarn
Disables warning messages. This option operates the same as the -Xlint:none option.
-parameters
Generates metadata for reflection on method parameters. Stores formal parameter names of
constructors and methods in the generated class file so that the
method java.lang.reflect.Executable.getParametersfrom the Reflection API can
retrieve them.
-proc: [none, only] , [none, only]
Controls whether annotation processing and compilation are done. -proc:none means that
compilation takes place without annotation processing. -proc:only means that only annotation
processing is done, without any subsequent compilation.
-processor class1 [,class2,class3...]
Names of the annotation processors to run. This bypasses the default discovery process.
--processor-module—path path or -p module-path
Specifies the module path used for finding annotation processors.
--processor—path path or -processorpath path
Specifies where to find annotation processors. If this option isn’t used, then the class path is searched
for processors.
-profile profile
Checks that the API used is available in the specified profile.

Note:
Not supported when using --release release to compile for JDK 9. See the description of --
release release for details about compiling for versions other than JDK 9.
--release release
Compiles against the public, supported and documented API for a specific VM version.
Supported releasetargets are 6, 7, 8, and 9.
Note:
When using --release for a version of the Java Platform that supports modules, you can’t use --
add-modules to access internal JDK modules, nor can you use --add-exports to access internal
JDK APIs in the modules.
-s directory
Specifies the directory used to place the generated source files. If a class is part of a package, then the
compiler puts the source file in a subdirectory that reflects the package name and creates directories as
needed. For example:
 Oracle Solaris, Linux, and OS X:: If you specify -s /home/mysrc and the class is
called com.mypackage.MyClass, then the source file is put
in /home/mysrc/com/mypackage/MyClass.java.
 Windows: If you specify -s C:\mysrc and the class is
called com.mypackage.MyClass, then the source file is put
in C:\mysrc\com\mypackage\MyClass.java.
-source release
Specifies the version of source code accepted. The following values for release are allowed:
Note:
As of JDK 9, the javac doesn’t support -source release settings less than or equal to 5. If settings
less than or equal to 5 are used, then the javac command behaves as if -source 6 were specified.
1.6
No language changes were introduced in Java SE 6. However, encoding errors in source files are now
reported as errors instead of warnings as was done in earlier releases of Java Platform, Standard
Edition.
Synonym for 1.6.

1.7
The compiler accepts code with features introduced in Java SE 7.
Synonym for 1.7.
1.8
The compiler accepts code with features introduced in Java SE 8.
Synonym for 1.8.
The default value. The compiler accepts code with features introduced in Java SE 9.
--source-path path or -sourcepath path
Specifies where to find input source files. This is the source code path used to search for class or
interface definitions. As with the user class path, source path entries are separated by colons (:) on
Oracle Solaris and semicolons(;) on Windows. They can be directories, JAR archives, or ZIP archives.
If packages are used, then the local path name within the directory or archive must reflect the package
name.
Note:
Classes found through the class path might be recompiled when their source files are also found.
See Searching for Types.
--system jdk | none
Overrides the location of system modules.
-target release
Generates class files for a specific VM version.
--upgrade-module—path path
Overrides the location of upgradeable modules.
-verbose
Outputs messages about what the compiler is doing. Messages include information about each class
loaded and each source file compiled.
--version or -version
Prints version information.
-Werror
Terminates compilation when warnings occur.
Cross-Compilation Options for javac

By default, for releases prior to JDK 9, classes were compiled against the bootstrap classes of the platform that
shipped with thejavac command. But javac also supports cross-compiling, in which classes are compiled
against bootstrap classes of a different Java platform implementation. It’s important to use the -
bootclasspathand -extdirs options when cross-compiling.
Note:
Extra Options for javac
--add-exports module/package=other-module(,other-module)*
Specifies a package to be considered as exported from its defining module to additional modules or to
all unnamed modules when the value of other-module is ALL-UNNAMED.
--add-reads module=other-module(,other-module)*
Specifies additional modules to be considered as required by a given module.
-Djava.endorsed.dirs=dirs
Overrides the location of the endorsed standards path.
Note:
-Djava.ext.dirs=dirs
Overrides the location of installed extensions.
Note:
--doclint-format [html4|html5]
Specifies the format for documentation comments.
--patch-module module=file(:file)*
Overrides or augments a module with classes and resources in JAR files or directories.
-Xbootclasspath:path
Overrides the location of the bootstrap class files.
Note:
-Xbootclasspath/a:path
Adds a suffix to the bootstrap class path.
Note:
-Xbootclasspath/p:path
Adds a prefix to the bootstrap class path.
Note:
-Xdiags:[compact, verbose]
Selects a diagnostic mode.
-Xdoclint
Enables recommended checks for problems in javadoc comments
-Xdoclint:(all|none|[-]group) [/access]
Enables or disables specific groups of checks, where group is one of the following values:
 accessibility
 html
 missing
 reference
 syntax
For more information about these groups of checks, see the -Xdoclint option of
the javadoc command. The -Xdoclint option is disabled by default in the javac command.
The variable access specifies the minimum visibility level of classes and members that the -
Xdoclint option checks. It can have one of the following values (in order of most to least visible:)
 public
 protected
 package
 private
The default access level is private.
For example, the following option checks classes and members (with all groups of checks) that have
the access level of protected and higher (which includes protected and public):
-Xdoclint:all/protected
The following option enables all groups of checks for all access levels, except it won’t check for
HTML errors for classes and members that have the access level of package and higher (which
includes package, protected and public :)
-Xdoclint:all,-html/package
Xdoclint/package:[-]packages(,[-]package)*
Enables or disables checks in specific packages. Each package is either the qualified name of a
package or a package name prefix followed by .*, which expands to all sub-packages of the given
package. Each packagecan be prefixed with - to disable checks for a specified package or packages.
-Xlint
Enables all recommended warnings. In this release, enabling all available warnings is recommended.
-Xlint:key(,key)*
Supplies warnings to enable or disable, separated by comma. Precede a key by a hypen (-) to disable
the specified warning.
Supported values for key are:
 all — Enables all warnings.

 auxiliaryclass — Warns about an auxiliary class that’s hidden in a source file, and is
used from other files.
 cast — Warns about the use of unnecessary casts.
 classfile — Warns about the issues related to classfile contents.
 deprecation — Warns about the use of deprecated items.
 dep-ann — Warns about the items marked as deprecated in javadoc but without
the @Deprecatedannotation.
 divzero — Warns about the division by the constant integer 0.
 empty — Warns about an empty statement after if.
 exports — Warns about the issues regarding module exports.
 fallthrough — Warns about the falling through from one case of a switch statement to the
next.
 finally — Warns about finally clauses that don’t terminate normally.
 module — Warns about the module system-related issues.
 opens — Warns about the issues related to module opens.
 options — Warns about the issues relating to use of command line options.
 overloads — Warns about the issues related to method overloads.
 overrides — Warns about the issues related to method overrides.
 path — Warns about the invalid path elements on the command l ine.
 processing — Warns about the issues related to annotation processing.
 rawtypes — Warns about the use of raw types.
 removal — Warns about the use of an API that has been marked for removal.
 serial — Warns about the serializable classes that don’t provide a serial version ID. Also
warns about access to non-public members from a serializable element.
 static — Warns about the accessing a static member using an instance.
 try — Warns about the issues relating to the use of try blocks ( that is, try-with-resources).
 unchecked — Warns about the unchecked operations.
 varargs — Warns about the potentially unsafe vararg methods.
 none — Disables all warnings.
See Examples of Using -Xlint keys.
-Xmaxerrs number
Sets the maximum number of errors to print.
-Xmaxwarns number
Sets the maximum number of warnings to print.
-Xpkginfo:[always, legacy, nonempty]
Specifies when and how the javac command generates package-info.class files
from package-info.java files using one of the following options:
always
Generates a package-info.class file for every package-info.java file. This option may be
useful if you use a build system such as Ant, which checks that each .java file has a
corresponding .class file.
legacy
Generates a package-info.class file only if package-info.java contains annotations. This

option doesn't generate a package-info.class file if package-info.java contains only
comments.
Note:
A package-info.class file might be generated but be empty if all the annotations in
the package-info.java file have RetentionPolicy.SOURCE.
nonempty
Generates a package-info.class file only if package-info.java contains annotations

with RetentionPolicy.CLASS or RetentionPolicy.RUNTIME.
-Xplugin:name args
Specifies the name and optional arguments for a plug-in to be run.
-Xprefer:[source or newer]
Specifies which file to read when both a source file and class file are found for an implicitly compiled
class using one of the following options. See Searching for Types.
 -Xprefer:newer — Reads the newer of the source or class files for a type (default).
 -Xprefer:source — Reads the source file. Use -Xprefer:source when you want to
be sure that any annotation processors can access annotations declared with a retention policy
of SOURCE.
-Xprint
Prints a textual representation of specified types for debugging purposes. This doesn’t perform
annotation processing or compilation. The format of the output could change.
-XprintProcessorInfo
Prints information about which annotations a processor is asked to process.
-XprintRounds
Prints information about initial and subsequent annotation processing rounds.
-Xstdout filename
Sends compiler messages to the named file. By default, compiler messages go to System.err.
javac Command-Line Argument Files

An argument file can include javac options and source file names in any combination. The arguments within
a file can be separated by spaces or new line characters. If a file name contains embedded spaces, then put the
whole file name in double quotation marks.
File names within an argument file are relative to the current directory, not to the location of the argument file.
Wildcards (*) aren’t allowed in these lists (such as for specifying *.java). Use of the at sign (@) to
recursively interpret files isn’t supported. The -J options aren’t supported because they’re passed to the
launcher, which doesn’t support argument files.
When executing the javac command, pass in the path and name of each argument file with the at sign (@)
leading character. When the javac command encounters an argument beginning with the at sign (@), it
expands the contents of that file into the argument list.
Examples of Using javac @filename

Single Argument File
You could use a single argument file named argfile to hold all javac arguments:
javac @argfile
This argument file could contain the contents of both files shown in Example 2.
Two Argument Files
You can create two argument files: one for the javac options and the other for the source file names.
Note that the following lists have no line-continuation characters.
Create a file named options that contains the following:
Oracle Solaris, Linux, and OS X::
-d classes
-g
-sourcepath /java/pubs/ws/1.3/src/share/classes
Windows:
-d classes
-g
-sourcepath C:\java\pubs\ws\1.3\src\share\classes
Create a file named classes that contains the following:
MyClass1.java
MyClass2.java
MyClass3.java
Then, run the javac command as follows:
javac @options @classes
Argument Files with Paths
The argument files can have paths, but any file names inside the files are relative to the current
working directory (not path1 or path2):
javac @path1/options @path2/classes
Examples of Using -Xlint keys

cast
Warns about unnecessary and redundant casts, for example:
String s = (String) "Hello!"
classfile
Warns about issues related to class file contents.
deprecation
Warns about the use of deprecated items. For example:
java.util.Date myDate = new java.util.Date();
int currentDay = myDate.getDay();
The method java.util.Date.getDay has been deprecated since JDK 1.1.
dep-ann
Warns about items that are documented with the @deprecated Javadoc comment, but don’t have
the @Deprecated annotation, for example:
/**
* @deprecated As of Java SE 7, replaced by {@link #newMethod()}
*/
public static void deprecatedMethod() { }
public static void newMethod() { }
divzero
Warns about division by the constant integer 0, for example:
int divideByZero = 42 / 0;
empty
Warns about empty statements after if statements, for example:
class E {
void m() {
if (true) ;
fallthrough
Checks the switch blocks for fall-through cases and provides a warning message for any that are
found. Fall-through cases are cases in a switch block, other than the last case in the block, whose code
doesn’t include a break statement, allowing code execution to fall through from that case to the next
case. For example, the code following the case 1 label in this switch block doesn’t end with a break
statement:
switch (x) {
case 1:
// No break statement here.
case 2:
If the -Xlint:fallthrough option was used when compiling this code, then the compiler emits a
warning about possible fall-through into case, with the line number of the case in question.
finally
Warns about finally clauses that can’t be completed normally, for example:
public static int m() {
try {
throw new NullPointerException();
} catch (NullPointerException(); {
System.err.println("Caught NullPointerException.");
return 1;
} finally {
return 0;
The compiler generates a warning for the finally block in this example. When the int method is
called, it returns a value of 0. A finally block executes when the try block exits. In this example,
when control is transferred to the catch block, the int method exits. However, the finally block
must execute, so it’s executed, even though control was transferred outside the method.
options
Warns about issues that related to the use of command-line options. See Cross-Compilation Options
for javac.
overrides
Warns about issues related to method overrides. For example, consider the following two classes:
public class ClassWithVarargsMethod {
void varargsMethod(String... s) { }
}
public class ClassWithOverridingMethod extends ClassWithVarargsMethod {
@Override
void varargsMethod(String[] s) { }
The compiler generates a warning similar to the following:.
warning: [override] varargsMethod(String[]) in

ClassWithOverridingMethod
overrides varargsMethod(String...) in ClassWithVarargsMethod;

overriding
method is missing '...'
When the compiler encounters a varargs method, it translates the varargs formal parameter into
an array. In the method ClassWithVarargsMethod.varargsMethod, the compiler translates
the varargs formal parameter String... s to the formal parameter String[] s, an array that
matches the formal parameter of the method ClassWithOverridingMethod.varargsMethod.
Consequently, this example compiles.
path
Warns about invalid path elements and nonexistent path directories on the command line (with regard
to the class path, the source path, and other paths). Such warnings can’t be suppressed with
the @SuppressWarnings annotation. For example:
 Oracle Solaris, Linux, and OS X:: javac -Xlint:path -classpath

/nonexistentpath Example.java
 Windows: javac -Xlint:path -classpath C:\nonexistentpath
Example.java
processing
Warns about issues related to annotation processing. The compiler generates this warning when you
have a class that has an annotation, and you use an annotation processor that can’t handle that type of
exception. For example, the following is a simple annotation processor:
Source file AnnocProc.java:
import java.util.*;
import javax.annotation.processing.*;
import javax.lang.model.*;
import.javaz.lang.model.element.*;
@SupportedAnnotationTypes("NotAnno")
public class AnnoProc extends AbstractProcessor {
public boolean process(Set<? extends TypeElement> elems,

RoundEnvironment renv){
return true;
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.latest();
Source file AnnosWithoutProcessors.java:
@interface Anno { }
@Anno
class AnnosWithoutProcessors { }
The following commands compile the annotation processor AnnoProc, then run this annotation
processor against the source file AnnosWithoutProcessors.java:
javac AnnoProc.java
javac -cp . -Xlint:processing -processor AnnoProc -proc:only

AnnosWithoutProcessors.java
When the compiler runs the annotation processor against the source
file AnnosWithoutProcessors.java, it generates the following warning:
warning: [processing] No processor claimed any of these annotations:

Anno
To resolve this issue, you can rename the annotation defined and used in the
class AnnosWithoutProcessors from Anno to NotAnno.
rawtypes
Warns about unchecked operations on raw types. The following statement generates
a rawtypes warning:
void countElements(List l) { ... }
The following example doesn’t generate a rawtypes warning:
void countElements(List<?> l) { ... }
List is a raw type. However, List<?> is an unbounded wildcard parameterized type.

Because List is a parameterized interface, always specify its type argument. In this example,
the List formal argument is specified with an unbounded wildcard (?) as its formal type parameter,
which means that the countElementsmethod can accept any instantiation of the List interface.
serial
Warns about missing serialVersionUID definitions on serializable classes, for example:
public class PersistentTime implements Serializable
private Date time;
public PersistentTime() {
time = Calendar.getInstance().getTime();
public Date getTime() {
return time;

warning: [serial] serializable class PersistentTime has no definition
of
serialVersionUID
If a serializable class doesn’t explicitly declare a field named serialVersionUID, then the
serialization runtime environment calculates a default serialVersionUID value for that class
based on various aspects of the class, as described in the Java Object Serialization Specification.
However, it’s strongly recommended that all serializable classes explicitly
declare serialVersionUID values because the default process of
computing serialVersionUID values is highly sensitive to class details that can vary depending on
compiler implementations. As a result, might cause an
unexpected InvalidClassExceptions during deserialization. To guarantee a
consistent serialVersionUID value across different Java compiler implementations, a serializable
class must declare an explicit serialVersionUID value.
static
Warns about issues relating to the use of statics variables, for example:
class XLintStatic {
static void m1() { }
void m2() { this.m1(); }
warning: [static] static method should be qualified by type name,
XLintStatic, instead of by an expression
To resolve this issue, you can call the static method m1 as follows:
XLintStatic.m1();
Alternately, you can remove the static keyword from the declaration of the method m1.
try
Warns about issues relating to the use of try blocks, including try-with-resources statements. For
example, a warning is generated for the following statement because the resource ac declared in
the try block isn’t used:
try ( AutoCloseable ac = getResource() ) { // do nothing}

unchecked
Gives more detail for unchecked conversion warnings that are mandated by the Java Language
Specification, for example:
List l = new ArrayList<Number>();
List<String> ls = l; // unchecked warning
During type erasure, the

types ArrayList<Number> and List<String> become ArrayList and List, respectively.
The ls command has the parameterized type List<String>. When the List referenced by l is
assigned to ls, the compiler generates an unchecked warning. At compile time, the compiler and JVM
can’t determine whether l refers to a List<String> type. In this case, l doesn’t refer to
a List<String> type. As a result, heap pollution occurs.
A heap pollution situation occurs when the List object l, whose static type is List<Number>, is
assigned to another List object, ls, that has a different static type, List<String>. However, the
compiler still allows this assignment. It must allow this assignment to preserve backward
compatibility with releases of Java SE that don’t support generics. Because of type
erasure, List<Number> and List<String> both become List. Consequently, the compiler
allows the assignment of the object l, which has a raw type of List, to the object ls.
varargs
Warns about unsafe use of variable arguments (varargs) methods, in particular, those that contain
non-reifiable arguments, for example:
public class ArrayBuilder {
public static <T> void addToList (List<T> listArg, T... elements) {
for (T x : elements) {
listArg.add(x);
A non-reifiable type is a type whose type information isn’t fully available at runtime.
The compiler generates the following warning for the definition of the
method ArrayBuilder.addToList:
warning: [varargs] Possible heap pollution from parameterized vararg
type T
When the compiler encounters a varargs method, it translates the varargs formal parameter into an
array. However, the Java programming language doesn’t permit the creation of arrays of
parameterized types. In the method ArrayBuilder.addToList, the compiler translates
the varargs formal parameter T... elements to the formal parameter T[] elements, an array.
However, because of type erasure, the compiler converts the varargs formal parameter
to Object[] elements. Consequently, there’s a possibility of heap pollution.
Example of Compiling by Providing Command-Line Arguments

To compile as though providing command-line arguments, use the following syntax:
JavaCompiler javac = ToolProvider.getSystemJavaCompiler();
The example writes diagnostics to the standard output stream and returns the exit code that javac command
would give when called from the command line.
You can use other methods in the javax.tools.JavaCompiler interface to handle diagnostics, control
where files are read from and written to, and more.
Old Interface
Note:
This API is retained for backward compatibility only. All new code should use the Java Compiler API.
The com.sun.tools.javac.Main class provides two static methods to call the compiler from a program:
public static int compile(String[] args);
public static int compile(String[] args, PrintWriter out);
The args parameter represents any of the command-line arguments that would typically be passed to the
compiler.
The out parameter indicates where the compiler diagnostic output is directed.
The return value is equivalent to the exit value from javac.
Note:
All other classes and methods found in a package with names that start
with com.sun.tools.javac(subpackages of com.sun.tools.javac) are strictly internal and subject to
change at any time.
Example of Compiling Multiple Source Files
This example compiles the Aloha.java, GutenTag.java, Hello.java, and Hi.java source files in
the greetings package.
% javac greetings/*.java
% ls greetings
Aloha.class GutenTag.class Hello.class Hi.class
Aloha.java GutenTag.java Hello.java Hi.java
Windows:
C:\>javac greetings\*.java
C:\>dir greetings
Aloha.class GutenTag.class Hello.class Hi.class
Aloha.java GutenTag.java Hello.java Hi.java
Example of Specifying a User Class Path

After changing one of the source files in the previous example, recompile it:
pwd
/examples
javac greetings/Hi.java
Windows:
C:\>cd
\examples
C:\>javac greetings\Hi.java
Because greetings.Hi refers to other classes in the greetings package, the compiler needs to find these
other classes. The previous example works because the default user class path is the directory that contains the
package directory. If you want to recompile this file without concern for which directory you are in, then add
the examples directory to the user class path by setting CLASSPATH. This example uses the -
classpath option.
javac -classpath /examples /examples/greetings/Hi.java
Windows:
C:\>javac -classpath \examples \examples\greetings\Hi.java
If you change greetings.Hi to use a banner utility, then that utility also needs to be accessible through the
user class path.
javac -classpath /examples:/lib/Banners.jar \
/examples/greetings/Hi.java
Windows:
C:\>javac -classpath \examples;\lib\Banners.jar ^
\examples\greetings\Hi.java
To execute a class in the greetings package, the program needs access to the greetings package, and to
the classes that the greetings classes use.
java -classpath /examples:/lib/Banners.jar greetings.Hi
Windows:
C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi
The -source 1.7 option specifies that release 1.7 (or 7) of the Java programming language must be used to
compile OldCode.java. The -target 1.7 option ensures that the generated class files are compatible with
JVM 1.7.
Annotation Processing
The javac command provides direct support for annotation processing, superseding the need for the separate
annotation processing command, apt.
The API for annotation processors is defined in
the javax.annotation.processing and javax.lang.modelpackages and subpackages.
How Annotation Processing Works
Unless annotation processing is disabled with the -proc:none option, the compiler searches for any
annotation processors that are available. The search path can be specified with the -processorpath option.
If no path is specified, then the user class path is used. Processors are located by means of service provider-
configuration files named META-INF/services/javax.annotation.processing. Processor on the
search path. Such files should contain the names of any annotation processors to be used, listed one per line.
Alternatively, processors can be specified explicitly, using the -processor option.
After scanning the source files and classes on the command line to determine what annotations are present, the
compiler queries the processors to determine what annotations they process. When a match is found, the
processor is called. A processor can claim the annotations it processes, in which case no further attempt is
made to find any processors for those annotations. After all of the annotations are claimed, the compiler does
not search for additional processors.
If any processors generate new source files, then another round of annotation processing occurs: Any newly
generated source files are scanned, and the annotations processed as before. Any processors called on previous
rounds are also called on all subsequent rounds. This continues until no new source files are generated.
After a round occurs where no new source files are generated, the annotation processors are called one last
time, to give them a chance to complete any remaining work. Finally, unless the -proc:only option is used,
the compiler compiles the original and all generated source files.
Searching for Types

To compile a source file, the compiler often needs information about a type, but the type definition is not in the
source files specified on the command line.
To compile a source file, the compiler often needs information about a type, but the type definition is not in the
source files specified on the command line. 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 that provide information through inheritance.
For example, when you create a subclass of java.awt.Window, you are also using the ancestor classes
of Window: java.awt.Container, java.awt.Component, and java.lang.Object.
When the compiler needs type information, it searches for a source file or class file that defines the type. The
compiler searches for class files first in the bootstrap and extension classes, then in the user class path (which
by default is the current directory). The user class path is defined by setting the CLASSPATH environment
variable or by using the -classpath option.
If you set the -sourcepath option, then the compiler searches the indicated path for source files. Otherwise,
the compiler searches the user class path for both class files and source files.
You can specify different bootstrap or extension classes with the -bootclasspath and the -
extdirs options. See Cross-Compilation Options for javac.
A successful type search may produce a class file, a source file, or both. If both are found, then you can use
the -Xprefer option to instruct the compiler which to use. If newer is specified, then the compiler uses the
newer of the two files. If source is specified, the compiler uses the source file. The default is newer.
If a type search finds a source file for a required type, either by itself, or as a result of the setting for the -
Xprefer option, then the compiler reads the source file to get the information it needs. By default the
compiler also compiles the source file. You can use the -implicit option to specify the behavior. If none is
specified, then no class files are generated for the source file. If class is specified, then class files are
generated for the source file.
The compiler might not discover the need for some type information until after annotation processing
completes. When the type information is found in a source file and no -implicit option is specified, the
compiler gives a warning that the file is being compiled without being subject to annotation processing. To
disable the warning, either specify the file on the command line (so that it will be subject to annotation
processing) or use the -implicit option to specify whether or not class files should be generated for such
source files.

Core Java

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Core Java

Încărcat de

Drepturi de autor:

Formate disponibile

https://docs.oracle.com/javase/9/tools/javac.

Java Platform Standard Edition 8 Documentation

About the Java Technology

The Java Programming Language

 Simple  Architecture neutral

An overview of the software development process.

The Java Platform

The Java platform has two components:

 The Java Virtual Machine

What Can Java Technology Do?

How Will Java Technology Change My Life?

Lesson: The "Hello World!" Application

"Hello World!" for Microsoft Windows

To write your first program, you'll need:

1. The Java SE Development Kit 8 (JDK 8)

Creating Your First Application

 Create a source file

 Compile the source file into a .class file

 Run the program

Create a Source File

To create a source file, you have two options:

Be Careful When You Type

HelloWorldApp is not the same as helloworldapp.

The Save As dialog just before you click Save.

Now click Save, and exit Notepad.

Now the prompt should change to C:\myapplication>.

2014-04-24 01:34 PM <DIR> .

2014-04-24 02:07 PM <DIR> .

Run the Program

In the same directory, enter the following command at the prompt:

java -cp . HelloWorldApp

You should see the following on your screen:

C:\myapplication>java -cp . HelloWorldApp

Congratulations! Your program works!

A list of most important features of Java language is given below.

Object-oriented programming (OOPs) is a methodology that simplifies software

Basic concepts of OOPs are:

o Classloader: Classloader in Java is a part of the Java Runtime Environment(JRE)

Java supports dynamic compilation and automatic memory management (garbage

JDK Environment and tools

Tool Name Brief Description

javac The compiler for the Java programming language.

java The launcher for Java applications. In this release, a single

javadoc API documentation generator.

apt Annotation processing tool.

appletviewer Run and debug applets without a web browser.

jar Create and manage Java Archive (JAR) files.

javah C header and stub generator. Used to write native methods.

javap Class file disassembler

extcheck Utility to detect Jar conflicts.

apt: It is an annotation-processing tool.

extcheck: it is a utility that detects JAR file conflicts.

idlj: An IDL-to-Java compiler. This utility generates Java bindings from

jabswitch: It is a Java Access Bridge. Exposes assistive technologies on

javafxpackager: It is a tool to package and sign JavaFX applications.

jarsigner: the jar signing and verification tool.

javap: the class file disassembler.

javaws: the Java Web Start launcher for JNLP applications.

JConsole: Java Monitoring and Management Console.

jdb: the debugger.

jhat: Java Heap Analysis Tool (experimental).

jinfo: This utility gets configuration information from a running Java

jmc: Java Mission Control