2.3 The Java API Documentation

1. 2.3 The Java API Documentation

2. What follows are the contents of the Java Application Programming Interface (API) Documentation for the system supplied class Point. • The complete online Java API documentation can easily be found through a Web search. • This is a comprehensive reference for questions about programming in Java. • An explanation of the excerpt from the documentation is given following it.

3. java.awtClass Point • java.lang.Object | +--java.awt.geom.Point2D | +--java.awt.PointAll Implemented Interfaces: • Cloneable, Serializable

4. public class Point • extends Point2D • implements Serializable • A point representing a location in (x, y) coordinate space, specified in integer precision. • Since: • JDK1.0 • See Also: • Serialized Form

10. The information given at the top of the documentation concerns the naming of the class and where it is located. • System supplied classes are arranged in packages. • If you scan through the information at the top you will eventually find this: • java.awt.Point. • “awt” stands for “abstract windowing toolkit”. • This is the name of a package in Java which includes classes related to doing graphical things.

11. Point is one of those classes. If a program uses a system supplied class, a line like this is put at the top of the code: • import java.awt.Point; • The idea is that this will make the class available for use in the program. • This will be done in the example programs. • It is possible to import all classes in a package at once. • If you chose to do this, you would use the * as a wildcard: • import java.awt.*;

12. The next segment of interest in the documentation is entitled “Field Summary”. • In the documentation, what are referred to in these notes as instance variables are referred to as fields. • In other words, you discover from this documentation that an object created from the Point class will have two instance variables, an x coordinate and a y coordinate. • These instance variables are given the type “int”, which signifies that these coordinates can take on integer values.

13. The next segment in the documentation is entitled “Constructor Summary”. • Constructors are special pieces of code used for creating instances of classes. • Constructors have a form reminiscent of methods—they have a name followed by a set of parentheses which may or may not contain parameters.

14. Constructors are not methods. • Their name is the same as the class they belong to. • As you can see, a single class may have more than one constructor. • The system can tell them apart because they have different parameter lists. • In the documentation the types of the parameters are shown. • For the time being we will restrict our attention to examples with parameters of the type “int”.

15. The last segment of the documentation is the “Method Summary”. • This gives all of the methods by name and all of their parameters by name, including their types. • There can be different methods with the same name. • The system tells them apart by their parameter lists. • It is only through these methods that a program can affect the instance variables, the x and y coordinates, of a Point object that has been created.

16. As you can see, int and double are two different numeric types. • The meaning of types will be covered in the next unit. • For the time being, examples will be restricted to the int, or integer type. • This type can hold whole number values.