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.
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.
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.
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.
Clonable | Indicates object can be copied or cloned |
Runnable | Indicates object can implement threads |
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 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.
Enumeration | Indicates object can implement methods to count through a set of values |
Observer | Indicates object can be tracked with class Observer |
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 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.
DataInput | Template for classes implementing input stream methods |
DataOutput | Template for classes implementing output stream methods |
FilenameFilter | Template for classes implementing filename-filtering methods |
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 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.
ContentHandlerFactory | Template for classes implementing content handlers |
SocketImplFactory | Template for classes implementing socket handlers |
URLStreamHandlerFactory | Template for classes implementing URL handlers |
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 |
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.
LayoutManager | Template for classes implementing layout containers |
MenuContainer | Template for classes implementing menu containers |
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 |
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.
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 |
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 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.
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 |
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.
AppletContext | Template for obtaining information about an applet's environment |
AppletStub | Template used to implement an applet viewer |
AudioClip | Template for implementing audio objects |
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.
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 |
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
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
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.
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.
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
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.
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);
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.