Previous | Next | Trail Map | Writing Java Programs | Objects, Classes, and Interfaces

Roll Your Own Packages

Packages are groups of related classes and interfaces. Packages provide a convenient mechanism for managing a large set of classes and interfaces and avoiding naming conflicts. In addition to the Java packages, you can create your own package and put class and interface definitions in it using Java's package statement.

Suppose that you are implementing a group of classes that represent a collection of graphic objects such as circles, rectangles, lines, and points. In addition to these classes you also have written an interface Draggable that classes implement if they can be dragged with the mouse by the user. If you want to make these classes available to other programmers, you bundle them together into a package called graphics and give the package to the programmers, along with some reference documentation as to what the classes and interfaces do and what their public programming interfaces are.

In this way, other programmers can easily determine what your group of classes are for, how to use them, and how they relate to one another and to other classes and packages. Also, the names of your classes won't conflict with class names in other packages because the classes and interfaces within a package are referenced in terms of their package (Technically, a package creates a new name space.)

You create a package using the package statement:

package graphics;

interface Draggable {
    . . .

class Circle {
    . . .

class Rectangle {
    . . .
The first line in the preceding code sample creates a package called graphics.

Note: For simplicity, we've named the package graphics. However, this does not circumvent the name collision problem, as two different projects can conceivably use the same package name. This problem is solved by convention only. By convention, companies use their name in their package names like this: COM.MyCompany.PackageName.

All the classes and interfaces defined in the file containing this statement in it are members of the graphics package. So, Draggable, Circle, and Rectangle are all members of the new graphics package.

The .class files generated by the compiler when you compile the file that contains the source for Draggable, Circle, and Rectangle must be placed in a directory (or folder) named graphics somewhere in your CLASSPATH. Your CLASSPATH is a list of directories that indicate where on the file system you've installed various compiled Java classes and interfaces. When looking for a class, the Java interpreter searches your CLASSPATH for a directory whose name matches the package name of which the class is a member. The .class files for all classes and interfaces defined in the package must be in that package directory.

Your package names can have multiple components, separated by periods. In fact, the Java package names have multiple components: java.util, java.lang, and so on. Each component of the package name represents a diretory on the file system. So, the .class files for java.util are in a directory named util in a directory named java somewhere in your CLASSPATH.

Note: All classes and interfaces belong to a package even if you don't specify one with the package statement. If you don't specify a package explicitly using package, your classes and interfaces become members of the default package, which has no name and which is always imported.


To run a stand-alone Java application, specify the name of the Java application that you wish to execute to the Java interpreter. The application that you are running could be anywhere on your system or on the network. In addition, the application might use other classes or objects that are in the same or different location.

Because your classes could be anywhere, you must indicate to the Java interpreter where it can find the classes that you are trying to run. You do this with the CLASSPATH environment variable. The CLASSPATH environment variable is comprised of a list of directory names that contain compiled Java classes. The actual construct of CLASSPATH depends on the system you are running.

When the interpreter gets a classname, it searches each directory in the CLASSPATH until it finds the class it's looking for.

You should put the top-level directory that contains your Java classes in your CLASSPATH. By convention, many people have a classes directory in their home directory where they put all of the Java code. If you have such a directory, you should put that directory in your CLASSPATH. It's often convenient to put the current directory in the CLASSPATH as well.

The classes included with the Java development environment are automatically available to you because the interpreter automatically appends the correct directory to your CLASSPATH when it starts up.

Note that order is important. When the Java interpreter is looking for a class, it searches the directories indicated by your CLASSPATH in order until it finds a class with the correct name. The Java interpreter runs the first class with the correct name that it encounters and does not search the remaining directories. Normally, it's best to give your classes unique names, but if you can't avoid it, make sure that your CLASSPATH searches your classes in the proper order. Keep this in mind when setting up your CLASSPATH and your source code hierarchy.

Note: If you load an applet into a Java application such as HotJavaTM or the applet viewer and the loaded class is in the class path, the applet doesn't have the restrictions that applets loaded over the network do, and it can never be reloaded. We recommend never starting an application such as HotJava in the same directory as an applet class because the current directory "." is usually part of the class path.

Previous | Next | Trail Map | Writing Java Programs | Objects, Classes, and Interfaces