CSCI 241 Labs: PreLab 7

CSCI 241 Labs: PreLab 7
On-Line Java Documentation

Introduction

The three most fundamental levels of abstraction that Java provides are classes, objects, and methods. Understanding these three abstractions is key to being a good Java programmer. The Java Development Kit provides us with literally thousands of classes to use. If we search the Internet, we can find millions of other classes that programmers have written. If we are to use any of these effectively, we need to know what they are meant to do and how to invoke their methods. Fortunately, Java has a standard way of supplying documentation that is readily accessible via a web browser. This document explains how to navigate and hopefully make sense of the documentation. For purposes of this document, we will concentrate on static (i.e., class-level) information.

Online Documentation

Java Packages

Java organizes classes into packages. A package is simply a collection of related classes and maybe some sub-packages. If our program is going to use one class from a package, there is a good chance that it will use others, so we generally import all the classes in a package at the same time by using the wild card (*) at the end of the package name. As you may remember, programmers use import statements in Java to refer to classes without using the full class names.

Java documentation is also organized around the same package structure.

Java 11 API Specification

We can reach the general Java documentation from our course web page. The link on the course web page, Java Platform Standard Edition & Java Development Kit version 11 API Specification takes you to the source of Java's documentation. Here you will find information about all the classes available for you to use in your own programs.

This document is the API (Application Programming Interface) specification for the Java Platform, Standard Edition, version 11.0, which is the version of the language that we are using. It is sometimes referred to as "version 1.11" as well.

When you open this link to the API documentation, it looks like:

The window you see begins with a summary describing the categories of modules available. Once you choose a module from the table, you see an alphabetical list of packages within that module. You also see other things listed in that window such as Interfaces, Enums and Exceptions. These are topics we cover in CSCI-242.

The java.base module

The list of modules includes java.base, which contains the fundamental building blocks of the language. That is where to start!

The java.lang package

The most frequent classes we use are located in the java.lang package. Chapter 4 of your textbook introduces you to many of the methods available in Java's Math class, located in this package. Here the beginning of its page:

Here is a screen shot of some of the classes included:

If you click the Math class, its documentation appears in the window:

After an initial descriptive area, you see the constants and methods the class contains. You will see the method signature as well as the return type, as shown here:

The Math class contains many more methods than are shown in this snapshot. Once you click a method, the display will jump to show you more details about that method, including its parameters and return value. For example, when you click the sqrt method, you will see:

NaN means not a number, which is the type of value you would get if you try to take the square root of a negative number.

Documenting Other Classes

Using javadoc-style comments, it is possible to document any Java packages you write. In chapter 9, we will learn how to recognize and use other parts of the documentation for other types of classes; ones from which we instantiate objects.