Chapter 9

Introducing the Java API


CONTENTS


For those of you impatiently waiting to put Java to use, this chapter will probably help with the frustration level a great deal. Java structure is presented in Part III, "Anatomy of the Java Language." Part IV, "The Java Application Programming Interface," begins the fun part. Now it is time to fill in the structure with some pretty fancy stuff, such as mouse clicks and graphics. This chapter and the next four explore in detail the capabilities of the prebuilt objects available in Java.

The Application Programming Interface (API) packages contain classes and interfaces for building applets and applications. This chapter provides an overview of all the packages available at this writing.

Another key skill presented here is how to read the Java API documentation online and know what to do with it. This chapter discusses how to create a library call using the documentation and how to interpret what the library call will do.

The Java API Packages

Java libraries are groups of prewritten classes available for programming. In other languages these procedures are called system service calls, system calls, or library calls and are used to access system time or date or to query the input device as to its type. Java libraries function as a rich resource of functionality for the programmer.

These libraries are gathered in packages-collections of class libraries or, sometimes, of other packages. (See Chapter 7, "Building Objects," for a discussion of packages and class libraries.)

This chapter presents the overall concept of the Java libraries and gives some idea of their use. Read on to get the details of each library in the next four chapters.

Think of this aspect of Java as a pyramid. The pyramid itself is the package, and the blocks that build it are libraries and classes.

The top block of the pyramid package is the Object class. This class is the superclass to all other classes. So we have a pyramid with the Object class at the top, and beneath it, side by side, are the class libraries that support the functionality of Java.

Java is designed to have great flexibility and to produce results quickly. Someone else has gone to the work of coding classes and interfaces to perform many feats of functionality, so why reinvent the wheel? In fact, you can create applications in which all the programmer needs to do is create variables and program logic through control flow. All other aspects of the application are performed by library calls, including painting the screen, performing input and output, manipulating data, and closing links.

Use library calls as much as possible to guarantee results across platforms. These classes and interfaces have been tested and, if not completely bulletproof, are close to it.

The Structure of the API Packages

Java packages are made up of class libraries. Java is made up of the following packages:

java.applet
java.lang
java.io
java.net
java.awt
java.awt.image
java.awt.peer
java.util

Recently, a new API has been added: The Java Database Connectivity API. This API can be used to connect to databases using SQL queries. It is not included in the base Java Developer's Kit (JDK) but can be downloaded from Sun's Web site. At the time of this writing this API was located at http://www.javasoft.com/jdbc/.

Packages are imported into program code using the following command:

import java.awt.*;   //imports the.package java.awt and all of its sub-packages

Java evaluates the import statements and the code. Only the libraries, classes, and interfaces used in the code are imported. Therefore, it is no waste of overhead if more classes are imported than are used. However, it is confusing to the programmer who must maintain the code later. Importing more packages or libraries than are needed also slows down the compile.

A brief description of the packages of Java and lists of the interfaces and classes from each package are in the following sections. The lists are included to give you a better understanding of the contents of the package. The rest of Part IV gives specifics of each package, including many examples of class usage.

java.lang

The java.lang package is imported by default into each class at compile time. There is no need to import it explicitly.

java.lang contains the classes that define the fundamental elements of Java. (These elements are covered in Chapter 6, "Fundamentals of the Java Language.") The lists of interfaces and classes shown in Tables 9.1 and 9.2 may look familiar after learning about primitive data types in Chapter 6.

Table 9.1. java.lang interfaces.
Interface
Usage
Clonable Indicates object can be copied or cloned
Runnable Indicates object can implement threads

Table 9.2. java.lang classes.
Class Name
Description
Boolean Object wrapper for the primitive type boolean
Character Object wrapper for the primitive type character
Class Contains runtime representations of all class types
ClassLoader Abstract class specifying how classes are loaded at runtime
Double Object wrapper for the primitive type double
Float Object wrapper for the primitive type float
Integer Object wrapper for the primitive type integer
Long Object wrapper for the primitive type long
Math Library of standard mathematical functions
Number Abstract superclass to all number types
Object Superclass to all other class types
Process Library of process control methods
Runtime Library of runtime access methods
SecurityManager Abstract class containing security policy method templates
String Superclass for all string objects
StringBuffer Superclass for all growable string objects
System Library of system interface methods
Thread Superclass for all thread objects and methods
ThreadGroup Superclass for grouping multiple threads together
Throwable Superclass for all exception-handling objects and methods

java.util

java.util is the library that contains objects used for system utilities. The Date class with its many methods is found here, as well as Random, a random number generator, and Vector, used to provide a growable array of objects. Tables 9.3 and 9.4 present a list of interfaces and classes found in java.util.

Table 9.3. java.util interfaces.
Interface
Usage
Enumeration Indicates object can implement methods to count through a set of values
Observer Indicates object can be tracked with class Observer

Table 9.4. java.util classes.
Class Name
Description
BitSet Bit-manipulation library
Date Date-manipulation library
Dictionary Abstract parent to class hash table
Hashtable Hash table-manipulation library
Observable Observer-manipulation library
Properties Persistent properties class
Random Random number-manipulation library
Stack Stack-manipulation library
StringTokenizer String token-manipulation library
Vector Vector-manipulation library

java.io

java.io is the library that contains objects useful in handling the input/output between Java and the keyboard, screen, printer, disk files, or network. It also provides interfaces for streams and files. Tables 9.5 and 9.6 present a list of java.io interfaces and classes.

Table 9.5. java.io interfaces.
Interface
Usage
DataInput Template for classes implementing input stream methods
DataOutput Template for classes implementing output stream methods
FilenameFilter Template for classes implementing filename-filtering methods

Table 9.6. java.io classes.
Class Name
Description
BufferedInputStream Buffered input stream allowing faster reads
BufferedOutputStream Buffered output stream allowing faster writes
ByteArrayInputStream Stream read from an array of bytes
ByteArrayOutputStream Stream written to an array of bytes
DataInputStream Generic byte-input stream
DataOutputStream Generic byte-output stream
File Platform-independent representations of filenames
FileDescriptor Stream read from a file descriptor
FileInputStream Stream read from a file
FileOutputStream Stream written to a file
FilterInputStream Abstract class for filtered input streams
FilterOutputStream Abstract class for filtered output streams
InputStream Superclass to all input stream classes
LineNumberInputStream Input stream that is aware of line numbers
OutputStream Superclass to all output stream classes
PipedInputStream Stream for reading data from another process
PipedOutputStream Stream for writing data to another process
PrintStream Output stream for sending formatted data to output devices
PushbackInputStream Input stream allowing a single byte to be pushed back onto the stream
RandomAccessFile Input stream allowing random access to a file
SequenceInputStream Input stream allowing multiple input streams to read in sequence
StreamTokenizer Methods for converting an input stream into tokens
StringBufferInputStream Stream read from a StringBuffer

java.net

java.net libraries contain routines that interact with network protocols. These objects interface with such protocols as sockets, Telnet, FTP, NNTP, and HTTP. Tables 9.7 and 9.8 present a list of java.net interfaces and classes.

Table 9.7. java.net interfaces.
Interface
Usage
ContentHandlerFactory Template for classes implementing content handlers
SocketImplFactory Template for classes implementing socket handlers
URLStreamHandlerFactory Template for classes implementing URL handlers

Table 9.8. java.net classes.
Class Name
Description
ContentHandler Class for creating objects from URLs
DatagramPacket Class for representing network packets
DatagramSocket Class for representing network sockets
InetAddress Internet address-manipulation library
ServerSocket Server socket-implementation library
Socket Client socket-implementation library
SocketImpl Abstract superclass for all socket classes
URL URL-manipulation library
URLConnection Abstract class for manipulating URL connections
URLEncoder Methods for tokenizing URL strings
URLStreamHandler Abstract class for opening URL connection streams

java.awt

AWT stands for Abstract Windowing Toolkit. As its name suggests, AWT libraries involve the GUI (graphical user interface) parts of Java, including such elements as boxes, buttons, borders, and menus. Tables 9.9 and 9.10 present a list of java.awt interfaces and classes.

Table 9.9. java.awt interfaces.
Interface
Usage
LayoutManager Template for classes implementing layout containers
MenuContainer Template for classes implementing menu containers

Table 9.10. java.awt classes.
Class Name
Description
BorderLayout Methods for handling border layouts
Button Methods for manipulating Button objects
Canvas Generic template for implementing canvases
CardLayout Methods for manipulating Rolodex-style card objects
Checkbox Methods for manipulating Checkbox objects
CheckboxGroup Methods for manipulating groups of Checkbox objects
CheckboxMenuItem Methods for manipulating Checkbox-style menus
Choice Methods for manipulating pop-up choice options
Color Methods for manipulating colors
Component Generic class for implementing AWT components
Container Generic class for implementing AWT containers
Dialog Methods for manipulating a pop-up dialog box
Dimension Wrapper for representing width and height
Event Methods for manipulating user input events
FileDialog Methods for manipulating a file dialog box
FlowLayout Methods for manipulating flow of Window objects
Font Methods for manipulating fonts
FontMetrics Methods for manipulating font characteristics
Frame Methods for handling frames
Graphics Abstract superclass to all Graphics objects
GridBagConstraints Methods for placing restraints on GridBag layouts
GridBagLayout Methods for placing objects in a window in a specified way
GridLayout Methods for manipulating grid layout containers
Image Abstract class for implementing platform-specific images
Insets Methods for manipulating insets in containers
Label Methods for manipulating labels
List Methods for manipulating lists
MediaTracker Methods for tracking media objects
Menu Methods for manipulating menus
MenuBar Methods for manipulating menu bars
MenuComponent Superclass to all menu objects
MenuItem Methods for manipulating menu items
Panel Generic class for implementing panel containers
Point Wrapper for representing points
Polygon Wrapper for representing polygons
Rectangle Wrapper for representing rectangles
Scrollbar Methods for manipulating scrollbars
TextArea Methods for manipulating text areas
TextComponent Superclass to all text objects
TextField Methods for manipulating single lines of text
Toolkit Class used to bind the AWT to a specific implementation
Window Methods for manipulating a Window object

java.awt.image

As is evident from the package title, java.awt.image is a subpackage of java.awt. java.awt.image's classes primarily involve the screen image as a whole, in contrast to java.awt, which involves the individual elements of a screen image. Tables 9.11 and 9.12 present the interfaces and classes found in java.awt.image.

Table 9.11. java.awt.image interfaces.
Interface
Usage
ImageConsumer Template for receiving images from an image producer
ImageObserver Template for receiving image-update information
ImageProducer Template for producing images for an image consumer

Table 9.12. java.awt.image classes.
Class Name
Description
ColorModel Abstract class for converting among color models
CropImageFilter Methods for cropping images
DirectColorModel Methods for translating color models
FilteredImageSource Methods for applying filters to an image
ImageFilter Methods for implementing an image filter
IndexColorModel Methods for translating color models
MemoryImageSource Methods for creating images using arrays of pixels
PixelGrabber Methods to extract a subset of an image
RGBImageFilter Methods for implementing an RGB filter

java.awt.peer

java.awt.peer is also a subpackage of java.awt. java.awt.peer consists only of interfaces. (See Table 9.13.) It is used in conjunction with java.awt to provide platform-dependent graphics for the window. The Java interpreter handles the call on a platform-specific basis.

Table 9.13. java.awt.peer interfaces.
Interface
Usage
ButtonPeer Native template for manipulating Button objects
CanvasPeer Native template for implementing canvases
CheckboxPeer Native template for manipulating Checkbox objects
CheckboxMenuItemPeer Native template for manipulating Checkbox-style menus
ChoicePeer Native template for manipulating pop-up choice options
ComponentPeer Native template for implementing AWT components
ContainerPeer Native template for implementing AWT containers
DialogPeer Native template for manipulating a pop-up dialog box
FileDialogPeer Native template for manipulating a file dialog box
FramePeer Native template for handling frames
LabelPeer Native template for manipulating labels
ListPeer Native template for manipulating lists
MenuBarPeer Native template for manipulating menu bars
MenuComponentPeer Superclass to all menu objects
MenuPeer Native template for manipulating menus
MenuItemPeer Native template for manipulating menu items
PanelPeer Native template for implementing panel containers
ScrollbarPeer Native template for manipulating scrollbars
TextAreaPeer Native template for manipulating text areas
TextComponentPeer Superclass to all text objects
TextFieldPeer Native template for manipulating single lines of text
WindowPeer Native template for manipulating a Window object

java.applet

The java.applet package contains an applet-specific class-Applet-and several interfaces. The Applet class contains the methods init, start, stop, and destroy (covered in Chapter 7). In other words, the java.applet package is used to control the structure and use of applets. Table 9.14 lists the interfaces for this package.

Table 9.14. java.applet interfaces.
Interface
Usage
AppletContext Template for obtaining information about an applet's environment
AppletStub Template used to implement an applet viewer
AudioClip Template for implementing audio objects

sun.tools.debug

The sun.tools.debug libraries are used in conjunction with the debug-enabled Java binaries such as javac_g. These are used for debugging Java programs with tools such as the Java Debugger (jdb). The sun.tools.debug interface, DebuggerCallback, is a template for implementing communications between an application and a debugger. The classes in this package are listed in Table 9.15 for your reference.

Table 9.15. sun.tools.debug classes.
Class Name
Description
RemoteArray Methods for debugging arrays
RemoteBoolean Methods for debugging booleans
RemoteByte Methods for debugging bytes
RemoteChar Methods for debugging chars
RemoteClass Methods for accessing a class from a debugger
RemoteDebugger Methods for instantiating a debugger
RemoteDouble Methods for debugging doubles
RemoteField Methods for accessing variables or methods via a debugger
RemoteFloat Methods for debugging floats
RemoteInt Methods for debugging ints
RemoteLong Methods for debugging longs
RemoteObject Methods for accessing objects via a debugger
RemoteShort Methods for debugging shorts
RemoteStackFrame Methods for accessing the stack frame of a suspended thread
RemoteStackVariable Methods for accessing stack variables via a debugger
RemoteString Methods for debugging strings
RemoteThread Methods for debugging threads
RemoteThreadGroup Methods for debugging threadgroups
RemoteValue Methods for accessing variable values via a debugger
StackFrame Wrapper for the stack frame of a suspended thread

Using the Java API

Now that we have flown over the packages at 30,000 feet, let's talk about ways these packages are useful to programmers. The Java class libraries provide a basis for most of the work that needs to be accomplished in an application. This includes painting a screen, getting information from the user, displaying it, allowing corrections, manipulating the input data, perhaps storing the data, and so on. It is up to the programmer to decide which class to use to get the job done.

It may appear to the Java beginner that it is easier to do all the coding, or to learn a few of the classes and ignore the rest, than to become familiar with the huge number of classes available in Java. This would be a very self-limiting course of action-part of learning Java classes is learning about constructors, methods, and variables.

Sun Microsystems's Web sites have a complete set of documentation covering Java's API. They are located at

http://java.sun.com

and

http://www.javasoft.com

The documentation is available as either browsable Web pages or PostScript files, which are simply screen shots of the Web pages. The browsable API documentation provides a fast way to look up specific information. (This section makes a lot more sense if you are looking at the appropriate online documentation at the same time you are reading the description.) The documentation is also available for downloading in a variety of formats, including PostScript, HTML, and PDF. At the time of this writing, this documentation could be found at

http://www.javasoft.com/java.sun.com/newdocs.html

API Web Reference Structure

This section is a short tutorial on how to use the Sun Web page based on Sun's Web site at this writing. Web sites change constantly, so do not be surprised if these instructions are less than correct when you read this. As always, your mileage may vary.

The first part of this section covers the structure of the package documentation. Just looking at the structure of the documentation can be very confusing the first few times. Still, it is important to understand where to look for information in the API documentation.

The second part of this section is a step-by-step instruction on getting information from Web pages and what to do with it. Code constructed from the examples demonstrates the implementation of this information.

The documentation is divided into packages:

java.lang
java.util
java.io
java.net
java.applet
java.awt
java.awt.image
java.awt.peer
sun.tools.debug

Package Documentation

The package page contains the interface index, the variable index, and the class index (see Figure 9.1). Some packages also have an exception index or an error index.

Figure 9.1 : The java.awt packagereference page.

The interface index is a list of the interface names contained in the package. The class index is a list of class names contained in the package. The exception index is a list of exception names accessed by the classes in the package; the exceptions themselves are contained in the java.lang package. The error index is a list of error names accessed by the classes in the package.

Interface Documentation

The interface section contains the actual reference information for each interface in the package. Multiple interfaces are broken out separately into an interface definition, a method index, and method definitions. Interfaces can also have a variable index. Remember, interfaces do not contain code (see Chapter 7); they are the structure of what must be implemented in either Sun- or programmer-written methods.

The interface definition contains basic information about the interface. It shows the interface declaration and a description of the interface's purpose. The declaration can include an extends keyword that shows other interfaces on which this interface is based. The interface definition also includes, in the declaration section, the declaration used to define the interface and a description of the possible uses of the interface.

There is usually a method index, which gives a brief index of all methods contained in the interface. (See Figure 9.2.) This includes the name of the method, the method parameter list, and a brief description of the method. The sections method name and parameter list list the method name and the parameter types the method accepts. It also includes a short description of the method's purpose.

Figure 9.2 : The method index from Java.applet.AppletContext.

The methods definition section of the interface is a more detailed description of each method in the interface. It includes a section on method name, which contains the name of the method and the declaration used in the interface to declare the method. This is the declaration that must be used when implementing the interface. Finally, it includes a description of the use of the interface.

The interface documentation also can contain a variable index. The variable index is a list of variables defined in the interface as well as a short definition of the variable. (See java.awt.image.ImageConsumer for an interface that uses several variables.)

The variables section gives more detail on the variables defined in the interface. Figure 9.3 is an example from interface java.awt.image.ImageConsumer.

Figure 9.3 : The variable index from java.awt.image.ImageConsumer.

Class Documentation

The classes section contains the reference information for each class in the package. If a package contains multiple classes, each is broken out separately into inheritance, structure of class, class definition, the variable index, the constructor index, the method index, variables, constructors, and methods. (Some of these sections may be missing if the class does not use them.)

The inheritance class structure appears at the top of the page in classes. It is a visual and textual explanation of the inheritance structure of the class. An example of this structure is shown in Fig-ure 9.4.

Figure 9.4 : Class documentation from java.applet.Applet.

The visual reference shows the class and each of its superclasses until the top of the hierarchy is reached. Directly beneath this is a section that gives a brief definition of the class and possibly additional information such as cross-references. An example of the definition is

public class Button
   extends Component.
   A class that produces a labeled button component.

This is basic information showing how the class is declared and a description of its purpose. The declaration also can include an extends keyword that shows other classes on which this class may be based.

The variable index is list of appropriate variables for the class. For example, in the java.awt.image.ColorModel class, you will find this:

Variable Index

pixel bits

The constructor index is a list of the constructors for the method. It also contains a brief description of the constructor, as in the following example from java.awt.Button:

Button()
    Constructs a Button with no label.
Button(String)
   Constructs a Button with a string label.

Remember, constructors are used to create new objects.

The method index is a list of methods in the class. It also contains a brief description of the method, as in the following example from the java.awt.Button class:

addNotify()
   Creates the peer of the button.
getLabel()
   Gets the label of the button.
paramString()
   Returns the parameter String of this button.
setLabel(String)
   Sets the button with the specified label.

The variable section contains more detailed information about variables declared in the class. The following code fragment is from the java.awt.image.ColorModel class:

Variables
pixel_bits
protected int pixel_bits

pixel_bits is a variable that has access security of protected, is of primitive data type int, and is named pixel_bits. Therefore, any time this class is imported in a Java program, the pixel_bits variable is available.

The constructors section of the class lists the constructors contained in the library. This is shown in the following code fragment from java.awt.Button:

Button
   public Button()
   Constructs a Button with no label.
Button
   public Button(String label)
   Constructs a Button with a string label.
   Parameter:
     label - the button label.

The methods definition section lists the methods contained in the class and contains detailed information about their use. It lists the methods alphabetically and gives declaration syntax. The methods section also gives a detailed definition of the method, lists parameter information, lists overrides, and includes a "See Also" section. Each method may have a part or all of these elements, depending on applicability. Following is the addNotify method from java.awt.Button:

addNotify
   public synchronzed void addNotify()
   Creates the peer of the button. This peer allows us to change the look of the
   button without changing its functionality.
   Overrides:
      addNotify is class Component

This method definition contains information about overrides. The following is the getLabel method from java.awt.Button:

getLabel
   public String getLabel()
   Gets the label of the button.
   See Also:
      setLabel

This definition has information about other methods in the class to cross-reference, in this case setLabel. The setLabel definition includes information on parameters, like this:

setLabel
   public void setLabel(String label)
   Set the button with the specified label.
   Parameters:
      Label - the label to set the button with
   See Also:
      getLabel

Exception Documentation

The exception index contains a list of exceptions used in a package. These exceptions are usually part of package java.lang, which is part of every Java program by default.

The exception definition shows the access security, the exact declaration of the exception, and other information such as cross references. The following example is from AWTException, which is called in java.awt:

AWTException
   public class AWTException
   extends Exception
   Signals that an Abstract Window Toolkit exception has occurred.

Exceptions are part of java.lang and are explicitly called as java.lang.Exception.

Constructing Code with Documentation Information

The previous section has given you an overview of the parts of the Java API documentation and what they mean. That is all well and good, but the larger issue is what to do with the information. This section constructs code using the information provided in the documentation.

Suppose you had a question about the method necessary to destroy an applet after its use.

Access to the Java API documentation is available at http://www.javasoft.com. This will bring up the home page for Sun's Java language. See Figure 9.5 for an example of this page as of this writing. Next, click API documentation.

Figure 9.5 : The www.javasoft.com home page.

Now click Documentation. Now click Documentation for the n.n Release.

In Package information, click java.applet. This is the proper place to look for methods that control applets. In Class information, click Applet. Class information is displayed. See Figure 9.6 for an example of this page.

Figure 9.6 : The reference page for java.applet.Applet.

In the Method Index, click destroy. This will bring up the reference page for the destroy method.

The following information is displayed:

destroy
   public void destroy()
   Cleans up whatever resources are being held. If the applet is active it is
   stopped.
   See Also:
      init, start, stop

This is all the information you need to code the command. Following is a code fragment that creates and destroys an instance of an applet:

import java.applet.*;             //imports the java.applet library
public class MyApplet extends Applet {
   Applet anApplet;
   public void start() {
      anApplet = new Applet();    //create a new instance of MyApplet
      anApplet.destroy();         //stops the applet from executing
   }
}

The command that suits our purposes here is anApplet.destroy();. The method destroy is called from class Applet by the syntax

objectname.methodname;

Do not declare the destroy method, as in public void destroy. This part of the documentation just shows how the method is declared internally to class Applet and is provided for informational purposes only. In this case, the documentation shows that the method is void; therefore no information is returned from the method call. All the information about the methods in class Applet is imported with the import statement.

The next example is a bit more complex. This example is also from class java.applet.Applet, so get back into that online documentation. The method to look at this time is getAppletInfo. The online documentation looks like this:

getAppletInfo
   public String getAppletInfo()
   Returns a string containing information about the author, version and
   copyright of the applet.

This method should be defined in programs. The default applet returns null.

A code fragment using getAppletInfo follows:

import java.applet.*;                      //imports the java.applet library
public class MyApplet extends Applet {
   String owner;
   Applet anApplet;
   public void start() {
      anApplet = new Applet();             //create a new instance of MyClass
      owner = anApplet.getAppletInfo();    //returns applet information
   }
}

The information returned from the call to getAppletInfo is placed in variable owner. This information can now be displayed or manipulated in other ways.

This following example passes information to a method: resize, once again from java.applet.Applet. The online documentation is

resize
   public void resize(int width, int height)
   Requests that the applet be resized.
   Overrides:
      resize in class Component

resize is type void, so no information is returned from the method. It is necessary to supply the information width and height to the method to get it to do anything. This is how it could look:

String owner;
int howTall = 3, howWide = 7;
anApplet.resize(howTall, howWide);    //resizes the applet window
owner = anApplet.getAppletInfo();     //returns applet information
System.out.println("Applet information is "+owner);

Summary

This chapter introduces the Java API packages and demonstrates the process of retrieving API information from Sun's Web pages. When you know where to look for information and what to do with it, many, many things become possible with Java. The next four chapters go over the packages in more detail and give more examples on how to use the Java API.