Hello World

Goals

Compile and execute a Java program, with appropriate comments and documentation.

Concepts

Application Programming Interface (API)
Don't Repeat Yourself (DRY)
Java Development Kit (JDK)
Java Runtime Environment (JRE)
Java Virtual Machine (JVM)
bytecode
class
command prompt
default package
execute
imperative programming
method
object code
OpenJDK
package
procedural programming
project root directory
refactor
source code
TODO

Preview

package com.example;

public class HelloWorld
{
  public static void main(String[] args)
  {
    System.out.println("Hello, World!");
  }
}

Preparation

Download and install the latest version of the Java Development Kit (JDK). This course is based on Java 11.
- Make sure the download says “JDK” and not “JRE”.
- Unpack the archive contents into the directory of your choice. 7-Zip is recommended.
- Don't forget to set the JAVA_HOME environment variable to indicate the root directory where you unpacked the download file.
- You will want to add the Java …/bin subdirectory to your system path.
Install a good text editor that supports the UTF-8 encoding.

Visual Studio Code (recommended)

Modern, extensible, and supports other user interface languages in addition to English.

Atom

Modern and extensible, but can be buggy and unstable.

Notepad++

Has localizations for other user interface languages.

This course assumes you understand the basics of working with the command prompt (sometimes called the “terminal” or “shell”) of your computer's operating system. The basic commands for creating and changing directories are slightly different but similar across operating systems. Here are the important commands you will use in these lessons:

ls (Linux) or dir (Windows): Lists the files in the current directory.
mkdir directoryname (Linux) or md directoryname (Windows): Creates a directory with the given name.
cd directoryname: Changes to the directory with a given name. The special directory name . indicates the current directory, while the name .. indicates the directory above the current level.

For a more in-depth explanation for using the command line on Linux, see How do you open a command line? and A Quick Guide To Get Started With The Linux Command Line.

For a more information on using the command line on Windows, see 10 Ways to Open the Command Prompt in Windows 10 and Introduction to the Windows Command Prompt.

This lesson includes separate examples for Linux and Windows, except when the commands would be identical on both platforms.

You can verify you have correctly installed the JDK by entering the following at the command prompt; you must have version 1.8.0 or higher:

java --version

You should see something similar to the following:

openjdk 11 2018-09-25
OpenJDK Runtime Environment 18.9 (build 11+28)
OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode)

This same command may be used on Linux or Windows. The details output for these platforms may vary slightly.

Lesson

The Java programming language became available in 1995. It was primarily created by James Gosling at Sun Microsystems, which was later sold to Oracle Corporation. Nowadays Oracle provides a distribution of Java that requires a license for commercial use, but the open-source version of Java used in this course, the OpenJDK, can be used without restrictions.

Java is object-oriented and runs on the Java Virtual Machine (JVM). The Java compiler javac takes source code, stored in .java files, and compiles them into object code, stored in .class files. Java prefers to call its object code bytecode.

Java compile workflow — Compiling Java source code to bytecode and deploying it on different platforms.

For Java to run on a platform there must therefore exist a JVM implementation for that CPU. Usually the JVM will function together with libraries and tools, collectively known as the Java Runtime Environment (JRE).

Project

It is best to create a separate directory for each project you will working on. For now, this project root directory will contain a simple subdirectory named src for storing the source code. Create a directory structure named helloworld/src.

Creating a helloworld project directory on Linux.

mkdir helloworld
cd helloworld
mkdir src
cd src

Creating a helloworld project directory on Windows.

md helloworld
cd helloworld
md src
cd src

Source Code

Packages of Classes

Generally speaking, each .java file contains code for a Java class, which is a bundle of program logic. The Java class will indicate a package, which is a way to group related classes. You need to choose a package name that is unique.

Because the Internet domain system ensures uniqueness, the package name is usually a domain owned by the author, in reverse order of the domain components. For example, the company that owns the example.com domain would use a package name of com.example.

In the src directory, place the source code in a series of subdirectories that match the package structure, considering each component of the package to be a directory. For example a package of com.example would result in the directory structure com/example. The example below assumes you have changed to the src directory, continuing the steps above.

Creating com/example directories inside src on Linux.

cd src
mkdir com/example

Creating com/example directories inside src on Windows.

cd src
md com\example

Note that Linux uses the forward slash / character to separate directory names, while Windows uses the backslash \ character for the same purpose, although Windows also accepts the forward slash / character when changing directories. These lessons will use the forward slash / character in the examples and figures.

Now using your editor, create the source code file inside the helloworld/src/com/example directory. The .java source code file should have the same name as the class.

Source code for helloworld/src/com/example/HelloWorld.java.

/*
 * Copyright © 2015-2018 GlobalMentor, Inc. (http://www.globalmentor.com/)
 */

package com.example;

/**
 * "Hello world" sample Java program.
 *
 * <p>This application prints a greeting to the standard output.</p>
 *
 * @author Garret Wilson
 *
 * @see <a href="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">"Hello, World!" program</a>
 */
public class HelloWorld
{

  /**
   * Main program entry point; called by the Java Runtime Engine (JRE).
   * @param args The array of arguments passed on the command line.
   */
  public static void main(String[] args)
  {
    System.out.println("Hello, World!"); //this is the only line to execute
    //TODO make the program do something more interesting
  }

}

Each statement must end in a semicolon ; character.
A single-line comment uses //.
A multi-line comment uses /* … */.
A special multi-line comment /** … */ is used to indicate documentation, which is recognized and prepared by a tool named Javadoc. You can include basic HTML in such comments.
The @see tag is a special Javadoc tag to create a link to some related site or content.
A class gathers together values and logic. A package is used to group similar classes, usually by subject or domain. Java requires that the location of the Java class source code (the .java file) reflect the package structure.
System.out.println method is part of the Java library. Don't worry about what that means right now. Just note that you put what you want to print inside quotes, which in turn go inside parentheses.
Comments that start with TODO indicate a note to developers that something needs to be fixed or improved; it is a reminder “to do” something later. TODO comments are recommended. Modern tools recognize these notes to assist in making lists of tasks.

Methods

Java is based on an imperative programming paradigm: each line in the source code is an instruction telling Java to perform some action. The JVM will read the codes in the .class file representing the instructions you originally placed in your source code, and execute the commands, one at a time. You could modify the above program to print more information by adding more lines containing the command System.out.println(…).

Adding more instructions to the HelloWorld.java program.

…
public static void main(String[] args)
{
  System.out.println("Welcome!");  //welcome the students
  System.out.println("Good luck in the course.");
  System.out.println("Don't hesitate to ask the teacher if you have any questions.");
  System.out.println("Welcome!");  //welcome the students again
  System.out.println("Good luck in the course.");
}
…

The JVM would then execute each of these five instructions, one after the other. You'll note that the first two instructions are exactly the same as the last two instructions. Java doesn't care how many whether instructions are duplicated—it will execute them as provided. But from the perspective of program design, duplication of code or data makes the program larger and harder to maintain.

The main(…) section in your first program is in fact a method—a special method that tells Java where the program should begin execution.

Java additionally allows for procedural programming, allowing you to group together multiple instructions into a “procedure” to prevent repeating the individual instructions yourself in the code. Java calls these procedures methods, and they will appear outside the main(…) section. The simplest method begins with the words static void and is followed by parentheses (), as you saw above.

In order to reduce the number of repeated instructions in the above code, you can place the instructions inside a method named printWelcome. In each of the original locations of the duplicated code, you “call” the method using the method name followed by parentheses: printWelcome(). A method therefore acts as a single instruction representing several instructions. Don't forget to add Javadoc documentation to your new method!

Adding a method to the HelloWorld.java program.

…
public static void main(String[] args)
{
  printWelcome();
  System.out.println("Don't hesitate to ask the teacher if you have any questions.");
  printWelcome();
}

/**
 * Prints a welcome to the students in the course.
 */
static void printWelcome()
{
  System.out.println("Welcome!");  //welcome the students
  System.out.println("Good luck in the course.");
}
…

A method name in Java must be one word with no spaces; it should use beginning lowercase camelCase. It should usually include a verb in the name, indicating what the method does. Examples include startExperiment(), calculate(), and getResult().

Compiling the Source Code

From the source code root directory src, use javac to compile the source code. It will produce a .class file containing bytecode in the same directory as the source code.

Compiling source code on Linux or Windows.

cd helloworld/src
javac com/example/HelloWorld.java -encoding UTF-8

The -encoding UTF-8 option is necessary if you are using characters with accents on systems such as Windows which use a limited encoding by default.

Running the Bytecode

From the source code root directory src, use java to run the compiled class, making sure to indicate the entire package name. Don't indicate the name of the .class file; Java will find it automatically based upon the package and class name.

Running bytecode on Linux or Windows.

cd helloworld/src
java com.example.HelloWorld

The javac command expects you to indicate a the path to a class source file to compile, such as com/example/HelloWorld.java. The java command, on the other hand, expects the full package and name of a class, such as com.example.HelloWorld. The java command will know how to find the appropriate class file automatically.

Generating Documentation

The javadoc tool will examine all your source code for some package(s) and generate HTML documentation for you automatically, based upon the Javadoc tags you have included. This documentation can be distributed to other developers to quickly and easily communicate how to interact with your program. Correct and thorough Javadoc documentation is therefore very important within the code.

From the project root directory, create a separate directory such as apidocs for the documentation. Then from the source code root directory src, use javadoc to create documentation for all classes in the com.example package. With this form of the Javadoc comment, don't specify the individual filenames, just the name of the package to be included in the documentation.

Generating Javadoc documentation on Linux.

mkdir apidocs
cd src
javadoc -d ../apidocs com.example -encoding UTF-8

Generating Javadoc documentation on Windows.

md apidocs
cd src
javadoc -d ..\apidocs com.example -encoding UTF-8

The documentation will be generated and placed in the helloworld/apidocs directory. You can view it by loading helloworld/apidocs/index.html in a web browser.

The -encoding UTF-8 option is necessary if you are using characters with accents on systems such as Windows which use a limited encoding by default.

The Javadoc documentation explains the Application Programming Interface (API) of your program; hence the directory name apidocs.

Review

Gotchas

In Java, all code must be part of some class. Java will not accept simply a file containing “bare” code or methods.
If you leave off the package indication, your Java classes will be placed in the default package, which is not recommended.
Make sure the directory structure for each class matches the components of its package.
Make sure each statement ends in a semicolon. A missing ; can cause all sorts of grief.
Javadoc comments, as opposed to normal comments, should be associated with something, such as a class or a method; they should not stand alone.
The javac command expects a path to a source file, but and java command expects a package and class name, and will figure out the path itself from the current directory.
If you don't include the -encoding UTF-8 option with the javac and the javadoc commands, you have no guarantee that your program will support international characters on your systems.

In the Real World

Don't put your classes in the default package, or they won't play well with other programs and libraries. No one uses the default package in real life.
Some people line up the braces { and } vertically, as in the Preview section above. Some people put the first brace at the end of the previous line, as in the Source Code in the Lesson. Which you prefer may be a matter of personal taste, but above all should match what your team has agreed to use for a project.
System.out.println() is great for example programs, but you will seldom use it in real life unless you are writing a command-line program (which is hardly ever). Don't get in the habit of using it. Usually a logging facility is better, even for testing values.
The main method is only included if you want to run a program. Usually each application will only have one class with a main method. Avoid the temptation to add main methods to other classes to test them; usually a unit testing framework is better.
Good developers will add plenty of comments to the source code, using TODO notations to indicate where improvements need to be made.

Think About It

Did I include documentation for the class?
Did I include an @author tag?
Did I include documentation for the methods?

Self Evaluation

How is Java different from a compiled language such as C/C++ or Fortran?
What is a “virtual machine”?
What are the differences among the terms JDK, JVM, and JRE?
The Wildlife Conservation Network (WCN) owns the domain wildnet.org. What might be an appropriate package name for a WCN application called “animal tracker”?

Task

Create your own “Hello World” program from scratch. Type it all in manually; don't copy and paste.

Choose an appropriate package name.
Add your own copyright comment at the top.
Add your own Javadoc description of the class.
Indicate that you are the author of the class.
Provide Javadoc documentation for the main method.
Make the program print out your name in the main method.
Call a separate method that prints something else.
Provide Javadoc documentation for your other method.
Generate API documentation in the project's apidocs directory.

Put your entire project directory and contained files into an archive such as .zip or .7z and send it to your teacher. The 7-Zip application, indicated in the Resources, uses an especially efficient, open-source .7z file format and is recommended for homework submission.