1.7 Application Program Interface (API) and Libraries

1. Libraries, APIs and packages

You do not write every class yourself. A library is a collection of classes. An application programming interface (API) specification informs the programmer how to use those classes. To understand what attributes and behaviors a class in the API has, you read its documentation 1.7.A.1.

• A class defines a specific reference type. String is a class, so String is a reference type 1.7.A.1.
• Classes in APIs and libraries are grouped into packages 1.7.A.1.
• Existing classes and class libraries can be used to create objects 1.7.A.1.

Example: String and Math are classes in the java.lang package, part of the library that comes with Java. The Java Quick Reference tables in topics 1.11 and 1.15 are short extracts of their API documentation.

2. Using a class you did not write

You can use a library class by reading its documentation. You do not need to see its code.

String city = "Lisbon";
System.out.println(city.length());
System.out.println(Math.sqrt(81.0));

Output:

6
9.0

The String documentation says length() returns the number of characters. The Math documentation says sqrt returns a square root. Neither class was written by you.

3. Attributes and behaviors

Attributes are the data that belong to a class; they are kept in variables. Behaviors are the actions an instance of the class can do, or that can be done to it; methods define them 1.7.A.2.

Example: a Plant class might have the attributes name and height and the behaviors grow, getName and getHeight. Its documentation could look like this:

Documentation entry	Attribute or behavior?
String name: the plant’s name	attribute (data in a variable)
int height: the height in centimeters	attribute (data in a variable)
void grow(int cm): adds cm to the height	behavior (defined by a method)
int getHeight(): returns the height	behavior (defined by a method)
String getName(): returns the name	behavior (defined by a method)

Using the behaviors changes or reports the attributes:

Plant fern = new Plant("Fern", 30);
fern.grow(5);
System.out.println(fern.getName() + " is " + fern.getHeight() + " cm");

Output:

Fern is 35 cm

Watch out: attribute = noun stored in a variable (height); behavior = verb defined by a method (grow). In documentation, a method name is followed by parentheses.