Packages

When you start creating a large number of classes for a program, having a way to organize them becomes important. A clutter of class files is not unlike how your hard drive would look without subdirectories or folders. Imagine if all the files on your hard drive were placed in a single folder. You would have thousands of files without any obvious associations among them and you would have to make sure that no two files had the same name .

Class files without any organization cause similar problems. To overcome this, Java has a system called packages. A package contains a group of classes just as a subdirectory contains a group of files. You have already seen how a number of packages are used in the Java API. For example, java.awt and java.lang are commonly used packages. The java. prefix is reserved by Sun to indicate packages that are part of the SDK. When you create your own packages, the recommended naming convention is to use the reverse of your Internet domain name. For example if you work at a company whose Web site is http://www.mycompany.com, you would start your package names with com.mycompany.

A package should contain classes that are related in some way. For example, you might have a package called com.mycompany.Transportation that contains classes such as Car, Boat, Airplane, and Train. Programmers of applications that deal with modes of transportation could easily access classes of interest to them by using this package.

Packages create namespaces so that duplicate class names can be resolved.

Obviously more than one person will write a Car class at some point. However, placing a class in a package is equivalent to prepending the package name to the name of the class. With this, com.mycompany.Transportation.Car is easily distinguishable from any other Car class.

To make a class a member of a package, you must declare it using the package statement:

package Transportation;

If you declare a class without a package statement, it is placed in a default package. Use of the package statement is restricted as follows :

• For a class to be included in a package, its source code must be in the same directory as the rest of the package files.

• The package statement must be the first statement in a source file, appearing before any import statements and the first line of any class declaration. You can have comments and whitespace before the package statement, but nothing else.

Using Packages to Organize Your Code

Packages are a way of keeping things organized. You could never navigate the large number of classes that are provided with Java if they were not organized into packages. Table 7.1 summarizes some of the top-level packages included with SDK 1.3.

Table 7.1. Standard Java Package Examples

Package	Description
java.applet	Classes needed to create Java applets that run under Java-compatible browsers.
java.awt	Classes helpful in writing platform-independent graphic user interface (GUI) applications.
java.beans	Classes that support JavaBeans development.
java.io	Classes such as streams for performing input and output.
java.lang	Contains the essential Java classes, such as Object and System.
java.net	Classes used for creating network applications. These are used in tandem with java.io for reading and writing data from a network.
java.rmi	The root package of classes used in remote method invocation.
java.security	Classes needed to build upon Java's security framework.
java.sql	Classes used for accessing a database.
java.text	Classes helpful for supporting language- independent applications.
java.util	Contains other tools and data structures, such as encoding, decoding, vectors, stacks, and more.

When you separate your classes into packages, you make it easier for other programmers to understand and reuse what you have developed. You could nevertheless place every class developed for a program into a single package. This is allowed and, for sufficiently small programs, perhaps even preferable. It is more likely, however, that you will want to use packages. Nearly every program you develop will require some classes that are useful to other programs also. Separating these classes into packages simplifies their reuse, just like what has been done with the standard Java packages.

Packages and Your File System

When you place the classes you develop into packages, you must store the source files using a subdirectory structure that matches the elements of the package name. For example, the classes in the example Transportation package should be stored in a com/mycompany/Transportation subdirectory located underneath your working directory or in a path relative to the CLASSPATH.

Troubleshooting Tip

If you have trouble compiling classes in a package. See "Compiler Unable to Locate Source Files," in the "Troubleshooting" section at the end of this chapter.

Importing a Class from Another Package

Packages play a key role in how the compiler locates the other classes referenced by a class you create. When the compiler encounters a reference to another class, it checks to see if that class can be found within the same package as the class being compiled. If you declare a class that references only classes within the same package, you do not have to do anything to help the compiler locate them. If, however, you reference classes outside the package, you have to help the compiler by using the import statement. A programmer working in another package could reference your Car class by including the following statement in a source file:

import com.mycompany.Transportation.Car;

This import statement tells the compiler what package to look in to locate the Car class. A source file can include any number of import statements but they must appear after the package statement if there is one, and before the first line of any class declaration.

Importing an Entire Package

It is also possible to import all the classes in a package with a single import statement. You have probably already seen this done with some of the SDK classes such as those in java.awt. To import an entire package, replace the individual class name with an asterisk:

 import java.awt.*; This is a convenient replacement for multiple imports from the same package, such as import java.awt.Graphics; import java.awt.Image; import java.awt.Button; import java.awt.Canvas; 

Importing an entire package is simple, but it does havea slight drawback. When you import using a wildcard, class dependencies are not as obvious to others reading your code. If a class makes use of only a few classes in another package, explicit imports of those individual classes make the dependencies immediately evident. Similarly, when a class from another package is referenced, an explicit import makes it easier for someone reading the code to locate the source file or documentation for that class because the package assignment for it is stated as part of the import.

Note

An import of java.awt does not also import java.awt.event because package imports are not recursive.

Using a Class Without Importing It

It is actually not necessary to import a class before you use it. You can instead use the full class name when declaring the instance. If you want to declare an instance of your Car class in another package without using an import, you can declare the instance as a com.mycompany. Transportation.Car.

Implicit Import of java.lang

You might have noticed from reading the code examples throughout this book that there are certain classes within the SDK that you can use without importing them or referring to them using their full names. The classes in the java.lang package are used so frequently that the compiler implicitly imports them for you. This means that you can directly use the java.lang.System class in statements like this:

 System.out.println("System can be used without an import statement"); 

This is convenient, but it can be confusing until you become familiar with the classes defined in the java.lang package.