The Java Package Tutorial
This is a Java Package tutorial. It provides examples of importing classes from existing
Java Packages, creating new Java Packages and adding
to existing Java Packages.
For a detailed description of packages, see the
Java Language Specification.
See our Java Package Quick Reference which provides
a brief reference on how to build and use Java packages.
This tutorial also provides some insight on how to use the Java Compiler:
javac,
the Java Documentation Generator:
javadoc,
and the Java Disassembler:
javap.
The Package Tutorial addresses the following subjects:
- 1 - Java Package Names and Directory Structure
- 2 - Importing a Class from an Existing Java Package
- 3 - Setting CLASSPATH to Point to Java Classes & Packages
- 4 - Adding a Class to an Existing Java Package
- 5 - Creating a New Java Package
- 7 - javac Compiler Errors Relating to Java Packages
- 8 - Generating Java Package Documentation Using javadoc
- 9 - javadoc Undocumented Options
- 10 - Disassembling Java Class Files Using javap
The
Java Language Specification
defines Packages as groups of Java classes and Java interfaces.
Packages are a tool for managing a large namespace and avoiding conflicts.
Every Java class and interface name is contained in some package.
1. Java Package Names and Directory Structure
The Java Package name consists of words separated by periods. The first part of the name represents the organization
which created the package. The remaining words of the Java Package name reflect the contents of the package.
The Java Package name also reflects its directory structure.
Take, for example, the Java-supplied package "java.awt".
The first part of that package name "java" represents the organization that developed the package (Sun's Java group).
The second part of the package name "awt" stands for the contents of the package, in this case the Abstract
Window Toolkit. The "java.awt" package resides in a directory structure which reflects the package name:
<path>/classes/java/awt/*.class
All classes contained in the java.awt package reside in the above directory.
For this tutorial, we will be working with three packages. The organization name "v2k" in the
Java Package names stands for
Hubble Space Telescope Vision 2000 GUI group.
The three Java Package names are given below:
Directory Package
========================= =======
/GUI/java/classes/v2k/awt v2k.awt // Abstract Window Toolkit
/GUI/java/classes/v2k/ddo v2k.ddo // Realtime Data Driven Objects
/GUI/java/classes/v2k/p3d v2k.p3d // Three Dimensional
All classes for the Package v2k.awt reside in the above directories. The Java source for these classes
reside in the following directories:
Source Directory
=========================
/GUI/java/src/v2k/awt // Abstract Window Toolkit
/GUI/java/src/v2k/ddo // Realtime Data Driven Objects
/GUI/java/src/v2k/p3d // Three Dimensional
2. Importing a Class from an Existing Java Package
To import a Java Class, for example v2k.awt.RGBColorSelector, from an existing Java Package
simply add either of the following statements to the top of your Java source file:
import v2k.awt.RGBColorSelector; // imports the RGBColorSelector class only
or
import v2k.awt.*; // imports all classes in awt package
If you use "import v2k.awt.*" , ALL classes in the awt
package will be imported. We recommend importing only the classes you need.
Bringing in an entire Package does not alter the size of the class file, but
does lengthen the compile time. Wildcarding also increases the chances of namespace
conflict as new classes are added to the package over time.
3. Setting CLASSPATH to Point to Java Classes & Packages
The CLASSPATH environment variable must be set to point to any directories that contain
Java classes that you want to import. To point to specific Java Packages, you
must set the CLASSPATH to point to the directory ABOVE the package:
% setenv CLASSPATH ".:/GUI/java/classes"
You can add as many directories as you like to the path (separated by ":"), but remember that order is
important. The directories will be searched in the left-to-right order. In the above example,
your current directory would be searched first, then the "/GUI/java/classes" directory. If the
same class exists in both directories, the class in the current directory will be used.
Note: The window in which you invoke Netscape MUST NOT have the CLASSPATH set! The use of
CLASSPATH will conflict with Netscape accessing the Java classes in its own installation directory.
% unsetenv CLASSPATH
% netscape
4. Adding a Class to an Existing Java Package
To add a Class to an existing Java Package do the following:
To add the class MyClass to the Java Package v2k.awt, add the following statement
to the MyClass.java source file. (It must be the first non-comment statement of the file):
MyClass.java:
package v2k.awt;
Move the Java source file MyClass.java to the source directory for Package v2k.awt:
UNIX example:
% mv MyClass.java /GUI/java/src/v2k/awt/.
You are ready to compile the new class and make it part of the v2k.awt Java Package.
If the CLASSPATH environment variable is set (the path to search for classes being imported by MyClass.java),
do the following :
% javac -d /GUI/java/classes /GUI/java/src/v2k/awt/MyClass.java
The -d option tells the compiler to place the MyClass.class file in the
directory: /GUI/java/classes/v2k/awt.
If the CLASSPATH environment is not set, do the following :
% javac -d /GUI/java/classes -classpath .:/GUI/java/classes:/usr/java/classes
/GUI/java/src/v2k/awt/MyClass.java
The -d option tells the compiler to place the MyClass.class file in the
directory: /GUI/java/classes/v2k/awt.
The -classpath option tells the compiler to search for classes being imported by MyClass.java
in the path: .:/GUI/java/classes/.
If you have compiler errors, see javac Compiler Errors Relating to Java Packages.
The class "MyClass" is now part of the Java Package v2k.awt. You can now import this class using
the statement import v2k.awt.MyClass.
5. Creating a New Java Package
To create a new Java Package do the following.
To create a new Java Package, for example v2k.NEW, first create a directory which will
contain the Package's class files. Give the directory the same name as the package, ex. "NEW":
UNIX example:
% cd /GUI/java/classes/v2k // change directory under the
// main organization directory
% mkdir NEW // create a new directory with
// new Package name
Now create a directory which will
contain the Package's source files. Give the directory the same name as the package, ex. "NEW":
UNIX example:
% cd /GUI/java/src/v2k // change directory under the
// main organization directory
% mkdir NEW // create a new directory with
// new Package name
Copy the Java source files for the Package to the NEW source directory:
UNIX example:
% cp *.java /GUI/java/src/v2k/NEW/.
Add the following statement to the top of ALL java source files in
the v2k.NEW Java Package (/GUI/java/src/v2k/NEW/*.java). Important:
It must be the first non-comment statement of the file):
package v2k.NEW;
Now compile the NEW source and create the v2k.NEW Java Package.
If the CLASSPATH environment variable is set (the path to search for classes
being imported by MyClass.java), do the following :
% javac -d /GUI/java/classes /GUI/java/src/v2k/NEW/*.java
The -d option tells the compiler to place the MyClass.class file in the
directory: /GUI/java/classes/v2k/NEW.
If the CLASSPATH environment is not set, do the following :
% javac -d /GUI/java/classes -classpath .:/GUI/java/classes:/usr/java/classes
/GUI/java/src/v2k/NEW/*.java
The -d option tells the compiler to place the MyClass.class file in the
directory: /GUI/java/classes/v2k/NEW.
The -classpath option tells the compiler to search for imported classes
in the path: .:/GUI/java/classes/.
If you have compiler errors, see javac Compiler Errors Relating to Java Packages.
The Java Package v2k.NEW has been created. You can now import classes from
this package using
the statement import v2k.NEW.*.
When first moving a class into a Java Package, you may encounter errors similar to the one shown below:
test/b/Dummy.java:30: No constructor matching RGBColorSelector(test.b.Dummy)
found in class v2k.NEW.RGBColorSelector.
cs = new RGBColorSelector( this );
^
1 error
The problem is that even though a constructor RGBColorSelector(test.b.Dummy) does exist, it
is not declared public, and therefore not accessible to a class outside of the package.
The Document generating tool
javadoc
generates API documentation from Java source files. To generate API documentation from
a Java Package, do the following.
First modify all java source files to add
Documentation Tags
which will be translated to the output documentation.
Important: The developer is allowed to use HTML tags ex.<br> inside of their comments.
However, these will be properly interpreted by javadoc only if
they are lowercase - uppercase tags are silently ignored.
Create a directory which will contain the package html documentation files.
Name the directory whatever you prefer, ex. "doc":
UNIX example:
% cd /GUI/java/ // already at this level are directories:
// GUI/java/classes
// GUI/java/src
% mkdir doc // create a new directory for documentation
To generate documentation from the example Java Package v2k.NEW,
You must first change into the source directory which is the level above
the organization name of the Java Package. Remember, documentation
is generated using the source files, not the class files.
UNIX example:
% cd /GUI/java/src // source for NEW package is in /GUI/java/src/NEW/*.java
Then type the following javadoc command.
The -d option tells the compiler to place the .html documentation files in the
directory: /GUI/java/doc):
UNIX example:
% javadoc -d /GUI/java/doc v2k.NEW
Loading source files for v2k.NEW
Generating packages.html
generating documentation for interface v2k.NEW.Colorable
generating documentation for interface v2k.NEW.SliderClient
generating documentation for class v2k.NEW.ColorSlider
.
.
.
Generating index
Sorting 76 items . . . done
Generating tree
We found that the following
javadoc
options were not defined in the
Java Language Specification.
- -author
- -authors
-
Use either of these options to display author information in the generated documentation.
To see documentation which resulted from using the -author javadoc option, go to
v2k.awt API documentation.
Multiple
@author tags will generate a comma-separated list.
An example of a comment containing a single @author tag:
/**
* @author Joe Smith
**/
An example of a comment containing multiple @author tags:
/**
* @author Joe Smith
* @author Bill Smith
* @author Gene Smith
**/
-debug
This option generates command line output demonstrating the parsing of the input java
source file by javadoc.
This option
was probably used by the developer of the javadoc tool and will not be of much
use to others.
-depend
Use this option to understand dependencies on other Java Packages when generating documentation.
UNIX example:
% javadoc -d directory_name -version -depend v2k.p3d v2k.awt v2k.ddo
This allows the dependencies between Java Packages to be built in to the generated
API documentation for more than one related Package at a time (ex. provides a hyperlink
to a class in Package
v2k.awt which is related to a class in package v2k.ddo).
It also provides a
merged index
(of all fields and methods) and
class heirarchy
of all dependent Packages.
In addition, this option provides a
main package index
(in packages.html) with hyperlinks to all dependent packages.
-noindex
This option allows user to execute the javadoc command without producing an index file.
-notree
This option allows user to execute the javadoc command without producing an class heirarchy.
-nowrite
This option allows user to execute the javadoc command without producing any output.
-sourcepath
Specifies the path javadoc uses to look up the .java files.
Directories are separated by colons, for example:
This option allows user to execute the javadoc command without producing an class heirarchy.
.:/GUI/java/src/
-version
Use this option to display source code version information in the generated documentation.
UNIX example:
% javadoc -d directory_name -version v2k.p3d v2k.awt v2k.ddo
The Java Class File Disassembler
javap
dissasembles Java class files. The javap command has different arguments
depending upon whether or not the Java Class file is in a non-default Package.
Following is an example of how to disassemble a class file which is in
a non-default Java Package v2k.awt.
First change into the directory where the Java class file resides. Remember, the
disassembler reads Java class files, not source files.
UNIX example:
% cd /GUI/java/classes/v2k/awt
If the target class file is ColorSlider.class and is in a Java Package v2k.awt,
type the following:.
UNIX example:
% javap v2k.awt.ColorSlider
Compiled from ColorSlider.java
public class v2k.awt.ColorSlider extends java.awt.Canvas {
protected v2k.awt.SliderClient client;
protected double min;
protected double max;
protected double value;
To disassemble a class file which is not in a Package (actually all classes by default
are in a default Java Package which has no name),
first change into the directory where the Java class file resides. Remember, the
disassembler reads Java class files, not source files.
UNIX example:
% cd /home/jsmith/javaclasses
If the target class file is MyButton.class type the following:.
UNIX example:
% javap MyButton
Compiled from MyButton.java
public class MyButton extends java.awt.Button {
protected double min;
protected double max;
protected double value;
Last updated February 22, 1996 by Mary Smiley:
msmiley@v2mc01.gsfc.nasa.gov