An Introduction to the Java API

Steven Zeil

Last modified: Aug 19, 2016

Contents:

The Java API is the collection of classes provided as part of the Java compilation and runtime environment. These are classes that you can exploit in almost any program you write. That Java API is the equivalent of the C++ standard library, std..

1 What is an API?

API stands for Application Programming Interface, which is a description of a programming interface that let’s you build new applications from a library of already-implemented functions.

APIs can describe many different kinds of programming interfaces. They can describe commands that you can issue to an interactive system, messages that you can send across the network to a server, or a collection of functions that you can call.

There are all kinds of APIs of all different sizes and complexities. For example, many word processors and spreadsheets provide an API by which you can construct new documents or manipulate spreadsheets from other programs.

2 The Java API

The Java API is the collection of classes that are provided by any compiler and runtime environment for Java. It is, in fact, Java’s equivalent to the C++ std library. Many of the functionalities that you are used to obtaining from the C++ std will have direct equivalences in the Java API.

You’ve already caught on to the fact that Java and C++ are very similar at the level of language syntax. In a sense, you already know most of the Java language itself. Most of what you really need to do is to get familiar with the Java API so that you can actually be productive in the language.

When the Java API was introduced (v1.0, c. 1996), this would not have been too difficult. The Java API was smaller than std, and many things that C++ programmers took for granted in the way of support for basic data structures and algorithms were missing from the Java API. (To be fair, though, a large portion of the Java API was concerned with allowing you to build GUIs (Graphic User Interfaces) with windows, menus, buttons, etc. C++ will probably never have that in std.)

But, in the intervening years, the C++ library has remained unchanged. (One disadvantage of C++ being an international standard is that changes have to be approved by many different international groups, so change occurs rarely and in large chunks. On the other hand, an advantage of C++ being an international standard is that it is stable and your code does not go out of date with every new release of a compiler.)

In that same time period, the Java API has exploded. It’s now large enough and complicated enough that most Java programmers never touch upon more than a small fraction of it.

2.1 Structure of the Java API

Luckily the API is very well documented. (Click on the Java symbol above. You will probably want to bookmark that page.)

The page you are looking at is typical of Java documentation. It’s produced by a program called javadoc, which is part of the Java compiler suite. You can use this to document your own programs in the same way.

The Java API is divided into multiple packages, which you can see listed in the main area and, once you navigate away from there, in the upper left-hand corner. Many of these packages are sub-divided into smaller packages. Some of the packages you will use most often are:

java.lang: The most basic components of the language, including String, System, and Math. The classes in this package are always available to your program You don’t have to import them or include “java.lang.” in their names.
By contrast, for each of the other packages, you will need to give the full name of a class (e.g., java.io.File) or import the class (covered elsewhere) in order to use the short name.

java.util: This package collects most of the general-purpose utilities that could be used in any program. This includes many classes that correspond to the common data structures from the C++ std library:

Corresponding Data structures
C++ std	Java API
vector	ArrayList (or Vector)
list	LinkedList
deque	ArrayDeque
set	TreeSet
unordered_set	HashSet
map	TreeMap
unordered_map	HashMap
iterators	Iterator or Enumeration
stack	Stack
queue	ArrayQueue
priorityqueue	PriorityQueue

Java does not have an equivalent to the C++ multiset and multimap types.

In addition to data structures, java.util provides utilities for formatting I/O, random number generation, calendars and dates, and currency.

java.io: Classes for reading and writing from streams that, in turn, can be connected to I/O devices, files, Strings, etc.

java.awt: Classes for building GUIs (graphic user interfaces). Many, though not all of the classes in this package, are considered outdated and are replaced by newer classes in…

javax.swing: The newer library for GUI manipulation.

3 Reading the Java API

You can select any package that you are interested in by clicking its name in the upper-left section of the javadoc documentation. For example, locate java.util and click on it.

The lower left column will list all classes in the package that you have selected. You can then select a specific class that you wish to explore further. Try clicking on ArrayList.

The main panel on the right will display information about the3 selected class. Scroll down through the information on ArrayList. You will see an opening overview describing the class. Then, eventually, summary lists of all the functions that are provided by this class. Try clicking on the contains function name. Notice that this takes you to a more detailed description of the function.

Note also that the parameter types and return types of many listed functions are actually hyperlinks. Try clicking on the “Object” parameter of the contains function. You can see that this jumps you to the documentation for the Object class.