2.3 The Java API Documentation

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.

java.awt Class Point java.lang.Object | +--java.awt.geom.Point2D | +--java.awt.Point All Implemented Interfaces: java.lang.Objectjava.awt.geom.Point2D Cloneable, Serializable CloneableSerializable

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

Inner classes inherited from class java.awt.geom.Point2DPoint2D Point2D.DoublePoint2D.Double, Point2D.FloatPoint2D.Float

Inner classes inherited from class java.awt.geom.Point2DPoint2D Point2D.Double Point2D.Double, Point2D.Float Point2D.Float Field Summary int x x The x coordinate. int y y The y coordinate.

Constructor Summary PointPoint() Constructs and initializes a point at the origin (0, 0) of the coordinate space. PointPoint(int x, int y) Constructs and initializes a point at the specified (x, y) location in the coordinate space. PointPoint(Point p) Constructs and initializes a point with the same location as the specified Point object.Point

Method Summary boolean equalsequals(Object obj) Determines whether an instance of Point2D is equal to this point.Object Point getLocationgetLocation() Returns the location of this point. double getXgetX() Returns the X coordinate of the point in double precision. double getYgetY() Returns the Y coordinate of the point in double precision. void movemove(int x, int y) Moves this point to the specificed location in the (x, y) coordinate plane.

void setLocationsetLocation(double x, double y) Sets the location of this point to the specified float coordinates. void setLocationsetLocation(int x, int y) Changes the point to have the specificed location. void setLocationsetLocation(Point p) Sets the location of the point to the specificed location.Point String toStringtoString() Returns a string representation of this point and its location in the (x, y) coordinate space. void translatetranslate(int x, int y) Translates this point, at location (x, y), by dx along the x axis and dy along the y axis so that it now represents the point ( x + dx, y + dy ).

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.

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.*;

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.

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.

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”.

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.

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.