# Chapter 9

# Introducing the Java API

### CONTENTS

- The Java API Packages
- The Structure of the API Packages
  - java.lang
  - java.util
  - java.io
  - java.net
  - java.awt.image
  - java.awt.peer
  - java.applet
  - sun.tools.debug
- Using the Java API
- API Web Reference Structure
  - Package Documentation
  - Interface Documentation
  - Class Documentation
  - Exception Documentation
- Constructing Code with Documentation Information
- Summary

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 `array`s
`RemoteBoolean` | Methods for debugging `boolean`s
`RemoteByte` | Methods for debugging `byte`s
`RemoteChar` | Methods for debugging `char`s
`RemoteClass` | Methods for accessing a class from a debugger
`RemoteDebugger` | Methods for instantiating a debugger
`RemoteDouble` | Methods for debugging `double`s
`RemoteField` | Methods for accessing variables or methods via a debugger
`RemoteFloat` | Methods for debugging `float`s
`RemoteInt` | Methods for debugging `int`s
`RemoteLong` | Methods for debugging `long`s
`RemoteObject` | Methods for accessing objects via a debugger
`RemoteShort` | Methods for debugging `short`s
`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 `threadgroup`s
`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.