When you're just writing a few programs for your personal use, you can put the classes in any old directory and use any old names. When you have a team of twenty programmers working on five different software products that interact, you need a better way to organize your files than “putting them in any old directory.”

Java uses the term package to mean a collection of related classes that form a library, and which are kept together in the same directory. Strictly speaking, packages and classes do not have to be directories and files. The Java Language Specification is written to allow implementations to store code in a database or any other kind of repository, and some IDEs do just that. However, “package equals directory” and “class equals file” is the simplest implementation, and the best way to understand the topic.

A package name needs to match the directory name where the source and class files are stored. So a package called “java.lang” must have its class files in a directory where the last part of the pathname is javalang (on Windows) or java/lang (on Unix, Linux, the Mac, etc). Java uses the computer's filesystem to organize and locate packages.

The requirement means that if you know the name of a class, you also know where to find it (as long as you know where to begin looking). Classes that are part of the same package will be in the same directory. It simplifies things for the compiler-writer, and gives the programmer less to remember.

How do you tell the compiler that a class D is part of some package, like a.b.c ? It's simplicity itself—just put the source in file a/b/c/D.java and write the first few lines in the file like this:

Class D will go in file D.java and the byte code output by the compiler will go in D.class. Package names are hierarchical, and the packages can be nested arbitrarily deep. The prize in the Java API currently goes to

That package contains half-a-dozen classes relating to parsing HTML within Text components that belong to the Swing GUI package in the Javax API. Classes in this package are in directory $JAVAHOME/javax/swing/text/html/parser.

A class's package name is used as a prefix to create the full name of the class. If a class was identified only by classname and nothing else, we'd need some scheme to distinguish between duplicate names. If I wrote a class called ReadData that was in a library installed on a customer's system, and you wrote a class called ReadData that was in another library installed on the same customer's system, the JVM wouldn't know which of the two classes to load when it hit a reference to ReadData.

All the compiler tools recognize classes that are qualified by package name. In the case of class a.b.c.D, if you are in the parent directory of “a”, you can compile with:

and if D has a public main method, you can run it with:

When your source code doesn't explicitly mention a package, the class is compiled into an unnamed package in the current directory. This is fine for toy programs and examples, but professional software always uses packages.

The JLS tells you how to form package names that are distinct from everyone else's. Within a given organization, start with its Internet domain name, and reverse it, so the most general part appears first. In IBM's workstation division, the package names would start with com.ibm.wkstn. How, and how far, they subdivide it further is totally up to them. They'll probably want to add, at a minimum,“product within division.”

Since domain names are unique across the entire Internet, you can also easily create package names that have this quality. It allows different vendors to provide class libraries with no danger of namespace collisions. There are thus three purposes to packages:

Picking up on these points, the next section, ow the JDK Finds Classes, explains how the JDK uses packages to locate the classes to load. Access Modifiers on page 103 describes the keywords that make classes more visible or less.