System, but they may not be reproduced for publication

pkg.class#member specifies the name of the item, and text is the text displayed for that
item. The text parameter is optional, and if not used, then the item specified by
pkg.class#member is displayed. The member name, too, is optional. Thus, you can
specify a reference to a package, class, or interface in addition to a reference to a
specific method or field. The name can be fully qualified or partially qualified. However,
the dot that precedes the member name (if it exists) must be replaced by a hash
character.
@since
The @since tag states that an element was introduced in a specific release. It has the
following syntax:
@since release
Here, release is a string that designates the release or version in which this feature
became available.
{@summary}

---

The {@summary} tag explicitly specifies a summary for an item. It must be the first
tag in the documentation for the item. It has the following syntax:
@summary explanation
Here, explanation provides a summary of the tagged item, which can span multiple
lines. This tag was added by JDK 10. Without the use of {@summary}, the first line in
an item’s documentation comment is used as the summary.
@throws
The @throws tag has the same meaning as the @exception tag.
@uses
The @uses tag documents a service provider needed by a module. It has the following
syntax:
@uses type explanation
Here, type specifies a service provider type and explanation describes the service.
{@value}
{@value} has two forms. The first displays the value of the constant that it precedes,
which must be a static field. It has this form:
{@value}
The second form displays the value of a specified static field. It has this form:
{@value pkg.class#field}
Here, pkg.class#field specifies the name of the static field.
@version
The @version tag specifies the version of a program element. It has the following
syntax:
@version info

---

Here, info is a string that contains version information, typically a version number,
such as 2.2. You will need to specify the ­version option when executing javadoc in
order for the @version field to be included in the HTML documentation.
THE GENERAL FORM OF A DOCUMENTATION
COMMENT
After the beginning /**, the first line or lines become the main description of your class,
interface, field, constructor, method, or module. After that, you can include one or more
of the various @ tags. Each @ tag must start at the beginning of a new line or follow
one or more asterisks (*) that are at the start of a line. Multiple tags of the same type
should be grouped together. For example, if you have three @see tags, put them one
after the other. In­line tags (those that begin with a brace) can be used within any
description.
Here is an example of a documentation comment for a class:
WHAT JAVADOC OUTPUTS
The javadoc program takes as input your Java program’s source file and outputs
several HTML files that contain the program’s documentation. Information about each
class will be in its own HTML file. javadoc will also output an index and a hierarchy
tree. Other HTML files can be generated. Beginning with JDK 9, a search box feature is
also included.
AN EXAMPLE THAT USES DOCUMENTATION
COMMENTS
Following is a sample program that uses documentation comments. Notice the way
each comment immediately precedes the item that it describes. After being processed
by javadoc, the documentation about the SquareNum class will be found in
SquareNum.html.

---

---

---

I
Appendix C
Compile and Run Simple Single-File Programs
in One Step
n 
Chapter 1
, you were shown how to compile a Java program into bytecode using the
javac compiler and then run the resulting .class file(s) using the Java launcher java.
This is how Java programs have been compiled and run since Java’s beginning, and it is
the method that you will use when developing applications. However, beginning with
JDK 11, it is possible to compile and run some types of simple Java programs directly
from the source file without having to first invoke javac. To do this, pass the name of
the source file, using the .java file extension, to java. This causes java to automatically
invoke the compiler and execute the program.
y
History
opics
utorials
Offers & Deals
Highlights
ettings
Support
Sign Out

---

For example, the following automatically compiles and runs the first example in this
book:
In this case, the Example class is compiled and then run in a single step. There is no
need to use javac. Be aware, however, that no .class file is created. Instead, the
compilation is done behind the scenes. As a result, to rerun the program, you must
execute the source file again. You can’t execute its .class file, because one wasn’t
created. One other point: if you have already used javac to compile Example.java,
then you must erase the resulting .class file Example.class before trying the source­
file launch feature. When running a source file, there cannot already be a .class file
with the same name as the class containing main( ) in the source file.
One use of the source­file launch capability is to facilitate the use of Java programs in
script files. It can also be useful for short one­time­use programs. In some cases, it
makes it a little easier to run simple example programs when you are experimenting
with Java. It is not, however, a general­purpose substitute for Java’s normal
compilation/execution process.
Although this new ability to launch a Java program directly from its source file is
appealing, it comes with several restrictions. First, the entire program must be
contained in a single source file. However, most real­world programs use multiple
source files. Second, it will always execute the first class it finds in the file, and that
class must contain a main( ) method. If the first class in the file does not contain a
main( ) method, the launch will fail. This means that you must follow a strict
organization for your code, even if you would prefer to organize it otherwise. Third,
because no .class files are created, using java to run a single­file program does not
result in a class file that can be reused, possibly by other programs. Finally, as a general
rule, if there is already a .class file that has the same name as a class in the source file,
then the single­file launch will fail. As a result of these restrictions, using java to run a
single­file source program can be useful, but it constitutes what is, essentially, a special­
case technique.
As it relates to this book, it is possible to use the single source­file launch feature to try
many of the examples; just be sure that the class with the main( ) method is first in
your file. That said, it is not, however, applicable or appropriate in all cases.
Furthermore, the discussions (and many of the examples) in the book assume that you
are using the normal compilation process of invoking javac to compile a source file
into bytecode and then using java to run that bytecode. This is the mechanism that is

---

used for real­world development, and understanding this process is an important part
of learning Java. It is imperative that you are thoroughly familiar with it. For these
reasons, when trying the examples in this book, it is strongly recommended that in all
cases you use the normal approach to compiling and running a Java program. Doing so
ensures that you have a solid foundation in the way Java works. Of course, you might
find it fun to experiment with the single source­file launch option!

---

B
Appendix D
Introducing JShell
eginning with JDK 9, Java has included a tool called JShell. It provides an interactive
environment that enables you to quickly and easily experiment with Java code. JShell
implements what is referred to as read­evaluate­print loop (REPL) execution. Using
this mechanism, you are prompted to enter a fragment of code. This fragment is then
read and evaluated. Next, JShell displays output related to the code, such as the output
produced by a println( ) statement, the result of an expression, or the current value of
a variable. JShell then prompts for the next piece of code, and the process continues
(i.e., loops). In the language of JShell, each code sequence you enter is called a snippet.
A key point to understand about JShell is that you do not need to enter a complete Java
History
Topics
Tutorials
Offers & Deals
Highlights
Settings
Support
Sign Out

---

program to use it. Each snippet you enter is simply evaluated as you enter it. This is
possible because JShell handles many of the details associated with a Java program for
you automatically. This lets you concentrate on a specific feature without having to
write a complete program, which makes JShell especially helpful when you are first
learning Java.
As you might expect, JShell can also be useful to experienced programmers. Because
JShell stores state information, it is possible to enter multiline code sequences and run
them inside JShell. This makes JShell quite useful when you need to prototype a
concept because it lets you interactively experiment with your code without having to
develop and compile a complete program.
This appendix introduces JShell and explores several of its key features, with the
primary focus being on those features most useful to beginning Java programmers.
JSHELL BASICS
JShell is a command­line tool. Thus, it runs in a command­prompt window. To start a
JShell session, execute jshell from the command line. After doing so, you will see the
JShell prompt:
When this prompt is displayed, you can enter a code snippet or a JShell command.
In its simplest form, JShell lets you enter an individual statement and immediately see
the result. To begin, think back to the first example Java program in this book. It is
shown again here.
In this program, only the println( ) statement actually performs an action, which is
displaying its message on the screen. The rest of the code simply provides the required
class and method declarations. In JShell, it is not necessary to explicitly specify the
class or method in order to execute the println( ) statement. JShell can execute it
directly on its own. To see how, enter the following line at the JShell prompt:

---

Then, press 
ENTER
. This output is displayed:
As you can see, the call to println( ) is evaluated and its string argument is output.
Then, the prompt is redisplayed.
Before moving on it is useful to explain why JShell can execute a single statement, such
as the call to println( ), when the Java compiler, javac, requires a complete program.
JShell is able to evaluate a single statement because JShell automatically provides the
necessary program framework for you, behind the scenes. This consists of a synthetic