Application Program Interface (API) and Libraries

Suppose a program needs the length of one side of a square garden whose area is 144 square feet. You need a square root. With only +, -, *, /, and %, there is no direct way to get one; you would have to invent an algorithm that guesses and improves its guess over and over. That is a lot of work for one small calculation, and if you made a mistake, every program that used your code would inherit it.

Programmers almost never start from nothing. Someone has already written, tested, and fixed code for the jobs that nearly every program needs: printing, reading input, working with text, doing math. You reuse their work instead of rewriting it.

To see how that work is packaged, recall something from Topic 1.1. Every program you have written starts with a line such as public class Greeting, and all of its code sits inside the braces that follow. That wrapper is a class: a named unit of Java code that groups related data together with the actions that work on that data. (Read past the word public for now; a later topic explains it.) Your programs have each been one small class. The ready-made code that comes with Java is organized the same way, into classes, but there are thousands of them.

A library is a collection of classes that were written to be used by other programs. Java comes with a large standard library, and you have been using it all along:

None of these words is part of the Java language itself the way int and double are. They are names of classes that other programmers wrote and that come with every Java installation.

public class GardenPlan
{
    public static void main(String[] args)
    {
        String plant = "tomatoes";
        double side = Math.sqrt(144.0);
        System.out.print("Plant: ");
        System.out.println(plant);
        System.out.print("Side length in feet: ");
        System.out.println(side);
    }
}

Plant: tomatoes
Side length in feet: 12.0

Now vary it. Here is a different program with the same shape:

public class ScoreBoard
{
    public static void main(String[] args)
    {
        String team = "Hawks";
        int lead = Math.abs(-12);
        System.out.println(team);
        System.out.println(lead);
    }
}

Hawks
12

This time the program’s own class is ScoreBoard, and the Math calculation it uses is abs, which gives the distance of a number from zero, so Math.abs(-12) is 12. The library classes are still String, Math, and System. The lesson does not depend on which calculation you do: one class is yours, and every other capitalized class name came from the library.

public class LowercaseClass
{
    public static void main(String[] args)
    {
        double side = math.sqrt(144.0);
        System.out.println(side);
    }
}

LowercaseClass.java:5: error: cannot find symbol
        double side = math.sqrt(144.0);
                      ^
  symbol:   variable math

Java’s standard library has thousands of classes. If they were all in one giant pile, two problems would appear. Finding the class you need would be hard, and two programmers could not give different classes the same short name without a clash. Java solves both problems the way a school organizes its library: books are grouped on labeled shelves.

A package is a named group of related classes. The package name is written in lowercase words joined by dots. Two packages matter in this course:

A class’s full name is its package name, a dot, and its class name. Scanner’s full name is java.util.Scanner: the class Scanner in the package java.util. String’s full name is java.lang.String.

Typing full names everywhere would be tiring, so Java lets you name a class once at the top of the file and then use its short name. That is what an import statement does. In Topic 1.4 you wrote

import java.util.Scanner;

at the top of a program before using Scanner. Now you can read that line: “In this file, when I write Scanner, I mean the class Scanner from the package java.util.” An import line goes above the class, ends with a semicolon, and does not run anything; it only tells the compiler where to find a name.

Why do String and Math never need an import line? The java.lang package holds the classes nearly every program needs, so Java makes all of its classes available by default: every program can use them by their short names without importing them. Every other package, including java.util, must be imported.

import java.util.Scanner;

public class TicketCount
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("12 7");
        int adults = reader.nextInt();
        int children = reader.nextInt();
        int total = adults + children;
        System.out.print("Tickets: ");
        System.out.println(total);
    }
}

Tickets: 19

To see that the import line is only a shortcut, here is the same program with no import line at all. It uses Scanner’s full name instead:

public class FullName
{
    public static void main(String[] args)
    {
        java.util.Scanner reader = new java.util.Scanner("12 7");
        int adults = reader.nextInt();
        int children = reader.nextInt();
        int total = adults + children;
        System.out.print("Tickets: ");
        System.out.println(total);
    }
}

Tickets: 19

The output is identical. Writing java.util.Scanner every time tells the compiler exactly where the class lives, so no import is needed. Programmers rarely write code this way, because it is long and hard to read, but it shows what the import line really does: it lets you shorten the full name to Scanner.

public class MissingImport
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("12 7");
        int adults = reader.nextInt();
        int children = reader.nextInt();
        int total = adults + children;
        System.out.print("Tickets: ");
        System.out.println(total);
    }
}

MissingImport.java:5: error: cannot find symbol
        Scanner reader = new Scanner("12 7");
        ^
  symbol:   class Scanner

You now know that Math holds square-root code. But how would you know that in the first place? And once you know, how would you find out its exact name, what to give it, and what it gives back? You cannot open the library’s code and read thousands of lines; even if you could, that would defeat the point of reusing it.

Think of a microwave. You do not need to understand its wiring to use it. You need to know what the buttons are and what each one does. The buttons are the microwave’s interface: the part meant for users.

A library class works the same way. An application programming interface (API) is the set of classes, and the parts of those classes, that a library offers for other programs to use. (The College Board calls this topic “Application Program Interface”; both names mean the same thing.) The API specification, usually called the documentation, is the written description of the API: which classes exist, which package each one is in, what each one is for, and how to use each part. Java’s documentation is free online, with one page per class. Reading it is how programmers learn what a class can do without reading its code.

Here is a simplified version of the Math documentation page, written in our own words. The real page has more lines and many more methods, arranged in tables.

Package java.lang
Class Math

java.lang.Object
    java.lang.Math

Math holds methods for common number work, such as
absolute values, powers, and square roots.

Method Summary
  static int     abs(int a)               the absolute value of a
  static double  pow(double a, double b)  a raised to the power b
  static double  sqrt(double a)           the nonnegative square root of a

Take it apart from the top:

• Package says where the class lives. java.lang means no import is needed (1.7.2).
• The two indented lines show where Math sits in a family tree of classes. Read past them for now; Topic 1.12 explains them.
• The description says what the class is for, in plain words.
• Method Summary lists the class’s methods: named pieces of code that each do one job. Each row gives the method’s name, what it needs in the parentheses, and what kind of value it gives back, shown just before the name. sqrt needs one double and gives back a double. (Read past the word static for now; Topic 1.10 explains it. Topic 1.9 teaches these method headers in full.)

int morning = 58;
int afternoon = 71;
int swing = Math.abs(morning - afternoon);
System.out.println(swing);

13

Now vary it. The documentation matters most when a method needs more than one value, because the order of the values is part of what the documentation tells you. The pow row says the result is “a raised to the power b”, so the first value is the base and the second is the exponent.

double first = Math.pow(2.0, 10.0);
double second = Math.pow(10.0, 2.0);
System.out.println(first);
System.out.println(second);

1024.0
100.0

Math.pow(2.0, 10.0) is 2 multiplied by itself 10 times, 1024.0. Swapping the values gives 10 squared, 100.0. Same method, same two numbers, different answers; only the documentation tells you which order means what.

public class GuessedName
{
    public static void main(String[] args)
    {
        double side = Math.squareRoot(144.0);
        System.out.println(side);
    }
}

GuessedName.java:5: error: cannot find symbol
        double side = Math.squareRoot(144.0);
                          ^
  symbol:   method squareRoot(double)

double area = Math.pow(3.0, 2.0);
double volume = Math.pow(2.0, 3.0);
System.out.println(area);
System.out.println(volume);

9.0
8.0

A documentation page can list dozens of entries. To make sense of them, it helps to know that everything a class offers falls into two kinds. Think of describing a phone. Some things are facts about it: its battery level, its phone number. Other things are actions: it can make a call, take a photo. Facts and actions are different kinds of information, and classes are described the same way.

• An attribute is a piece of data that belongs with a class. Attributes are stored in variables.
• A behavior is something the class’s objects can do, or something that can be done with them. Behaviors are defined by methods.

(An object is one particular thing made from a class, such as one particular piece of text; 1.7.5 explains this.) A handy test is to ask whether the entry is a fact or an action: a noun such as “the largest value” is an attribute, and a verb phrase such as “give back the square root” is a behavior.

You have already used an attribute. In Topic 1.5, the constant Integer.MAX_VALUE held the largest possible int; a constant is an attribute whose value never changes. The Integer class’s documentation lists it in a section called Field Summary, which is where a documentation page lists the attributes that programs are allowed to use. (A field is Java’s name for a variable that belongs to a class.) The behaviors, as you saw in 1.7.3, are in the Method Summary. Here is a simplified excerpt; the real page lists more entries.

Package java.lang
Class Integer

Field Summary
  static int  MAX_VALUE        the largest value an int can hold
  static int  MIN_VALUE        the smallest value an int can hold

Method Summary
  static int  parseInt(String s)   the int written in the text s

Not every attribute is listed. A String object must store its characters somewhere, but that variable is kept hidden inside the class, so the documentation describes it in words (“a String holds a sequence of characters”) rather than listing it. You use the attribute through the class’s behaviors instead.

int biggest = Integer.MAX_VALUE;
int smallest = Integer.MIN_VALUE;
System.out.println(biggest);
System.out.println(smallest);

2147483647
-2147483648

Now vary it: use a behavior instead of an attribute. Here is a simplified excerpt of the String documentation page. It has the same layout as the Math page, including the two indented lines near the top, which Topic 1.12 explains.

Package java.lang
Class String

java.lang.Object
    java.lang.String

A String object holds a sequence of characters (text).
Every string literal, such as "abc", is a String object.

Method Summary
  int  length()   the number of characters in this string

The description mentions the attribute every string has, its characters, without listing a variable for it. The Method Summary lists the behavior length(). Every String object has this behavior, and each one answers with its own count.

String home = "Denver";
String trip = "Kansas City";
System.out.println(home.length());
System.out.println(trip.length());

6
11

home.length() asks the text "Denver" for its length, which is 6. trip.length() asks "Kansas City", which has 11 characters because the space counts. (The rules for calls like home.length() are taught fully in Topic 1.14.) Two differences from the attribute example are worth noticing. A behavior is an action, so it is written with parentheses, even when nothing goes inside them. And the result depends on which object performs it, because each string holds different characters.

public class AttributeParens
{
    public static void main(String[] args)
    {
        int biggest = Integer.MAX_VALUE();
        System.out.println(biggest);
    }
}

AttributeParens.java:5: error: cannot find symbol
        int biggest = Integer.MAX_VALUE();
                             ^
  symbol:   method MAX_VALUE()

In Topic 1.2 you learned that data types come in two groups: primitive types such as int, double, and boolean, and reference types. Since then you have written String and Scanner as types of variables. You may have wondered why String is capitalized while int is not. Now there is an answer: String is the name of a class, and every class is a type.

A class does two jobs for your program.

A class defines a type. When you write a class name in a declaration, such as String city or Scanner reader, you are saying what kind of value the variable can hold. Each class defines its own reference type: String variables hold text objects, Scanner variables hold scanner objects, and a variable of one type cannot hold the other. (What a reference variable actually stores is explained in Topic 1.12.)

A class is used to create objects. Think of a class as a blueprint. A blueprint for a house says how every house built from it will be laid out, but you cannot live in a blueprint; you live in a house built from it. In the same way, the String class describes what every piece of text has and can do, while "Denver" is one actual piece of text. One particular thing made from a class is an object, also called an instance of the class. Each object has its own values for the class’s attributes: "Denver" and "Kansas City" are both String objects, each holding its own characters. The analogy has a limit: a house can be repainted or have rooms added beyond the plan, but an object can only have the attributes and behaviors its class defines.

So the library gives you more than ready-made calculations. It gives you ready-made blueprints, and your program can create objects from them.

import java.util.Scanner;

public class TripInfo
{
    public static void main(String[] args)
    {
        int miles = 412;
        String city = "Denver";
        Scanner reader = new Scanner("3");
        int days = reader.nextInt();
        System.out.print("Driving to ");
        System.out.println(city);
        System.out.print("Miles: ");
        System.out.println(miles);
        System.out.print("Days: ");
        System.out.println(days);
    }
}

Driving to Denver
Miles: 412
Days: 3

Compare this with Math. You have used Math in every subsection, yet the program above never declares a Math variable or creates a Math object. Its behaviors, such as sqrt, do not belong to any particular object, so you use them through the class name itself. Topic 1.10 explains this kind of method. A class can be a blueprint for objects, a holder of behaviors you use directly, or both.

public class TextInInt
{
    public static void main(String[] args)
    {
        int city = "Denver";
        System.out.println(city);
    }
}

TextInInt.java:5: error: incompatible types: String cannot be converted to int
        int city = "Denver";
                   ^

public class LowercaseString
{
    public static void main(String[] args)
    {
        string pet = "Biscuit";
        System.out.println(pet);
    }
}

public class LowercaseStringFixed
{
    public static void main(String[] args)
    {
        String pet = "Biscuit";
        System.out.println(pet);
    }
}

Biscuit

This program decides how far a word’s length is from a goal length. Before reading the trace, find every library class and decide what the program uses each one for.

import java.util.Scanner;

public class WordGoal
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("9");
        int goal = reader.nextInt();
        String word = "planet";
        int letters = word.length();
        int off = Math.abs(goal - letters);
        System.out.print("Letters: ");
        System.out.println(letters);
        System.out.print("Letters away from goal: ");
        System.out.println(off);
    }
}

Line by line:

Letters: 6
Letters away from goal: 3

The library classes, through this chapter’s ideas:

Every behavior the program uses, nextInt, length, abs, print, and println, is listed in its class’s documentation. The program’s author wrote nine lines of instructions and borrowed the hard parts from four library classes.

Four of this chapter’s mistakes produce the same message, cannot find symbol. The symbol: line under it tells you which mistake you made.

• A library is a collection of classes that someone else wrote and tested. String, Math, Scanner, Integer, and System all come from Java’s standard library.
• Library classes are grouped into packages. Classes in java.lang are available by default; classes from other packages, such as java.util.Scanner, need an import line to be used by their short names.
• An API’s documentation describes each class: its package, its purpose, and how to use each part. Reading it, rather than guessing, is how you find a method’s exact name, what it needs, and what it gives back.
• A class offers attributes, which are data stored in variables, and behaviors, which are actions defined by methods. Documentation lists usable attributes under Field Summary and behaviors under Method Summary.
• Every class defines a reference type, and a class is a blueprint used to create objects, also called instances.

Package java.lang
Class Integer

Field Summary
  static int  MAX_VALUE        the largest value an int can hold
  static int  MIN_VALUE        the smallest value an int can hold

Method Summary
  static int  parseInt(String s)   the int written in the text s

import java.lang.Scanner;

public class WrongPackage
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("40 25");
        int first = reader.nextInt();
        int second = reader.nextInt();
        System.out.println(first - second);
    }
}

import java.util.Scanner;

public class WrongPackageFixed
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("40 25");
        int first = reader.nextInt();
        int second = reader.nextInt();
        System.out.println(first - second);
    }
}

15

String word = "library";
int letters = word.length();
int gap = Math.abs(letters - 10);
System.out.print(letters);
System.out.print(" ");
System.out.println(gap);

7 3

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can explain what a library is and pick out the library classes in a program. Reread
• I can name the package of String, Math, and Scanner and say which ones need an import line. Reread
• I can use a documentation page to find a method and learn what it needs and gives back. Reread
• I can sort what a class offers into attributes and behaviors. Reread
• I can explain that a class is a type and a blueprint for objects. Reread