Package: the library unit

package: the library unit

A package is what you get when you use the import keyword to bring in an entire library, such as

This brings in the entire utility library that's part of the standard Java distribution. Since Vector is in java.util, you can now either specify the full name java.util.Vector (which you can do without the import statement), or you can simply say Vector (because of the import).

If you want to bring in a single class, you can name that class in the import statement

Now you can use Vector with no qualification. However, none of the other classes in java.util are available.

The reason for all this importing is to provide a mechanism to manage "name spaces." The names of all your class members are insulated from each other. A method f( ) inside a class A will not clash with an f( ) that has the same signature (argument list) in class B. But what about the class names? Suppose you create a stack class that is installed on a machine that already has a stack class that's written by someone else? With Java on the Internet, this can happen without the user knowing it since classes can get downloaded automatically in the process of running a Java program.

This potential clashing of names is why it's important to have complete control over the name spaces in Java, and to be able to create a completely unique name regardless of the constraints of the Internet.

So far, most of the examples in this book have existed in a single file and have been designed for local use, and haven't bothered with package names. (In this case the class name is placed in the "default package.") This is certainly an option, and for simplicity's sake this approach will be used whenever possible throughout the rest of the book. If you're planning to create a program that is "Internet friendly," however, you must think about preventing class name clashes.

When you create a source-code file for Java, it's commonly called a compilation unit (sometimes a translation unit). Each compilation unit must have a name ending in .java, and inside the compilation unit there can be a public class that must have the same name as the file (including capitalization, but excluding the .java filename extension). If you don't do this, the compiler will complain. There can be only one public class in each compilation unit (again, the compiler will complain). The rest of the classes in that compilation unit, if there are any, are hidden from the world outside that package because they're not public, and they comprise "support" classes for the main public class.

When you compile a .java file you get an output file with exactly the same name but an extension of .class for each class in the .java file. Thus you can end up with quite a few .class files from a small number of .java files. If you've programmed with a compiled language, you might be used to the compiler spitting out an intermediate form (usually an "obj" file) that is then packaged together with others of its kind using a linker (to create an executable file) or a librarian (to create a library). That's not how Java works. A working program is a bunch of .class files, which can be packaged and compressed into a JAR file (using the jar utility in Java 1.1). The Java interpreter is responsible for finding, loading and interpreting these files.

A library is also a bunch of these class files. Each file has one class that is public (you're not forced to have a public class, but it's typical), so there's one component for each file. If you want to say that all these components (that are in their own separate .java and .class files) belong together, that's where the package keyword comes in.

When you say:

at the beginning of a file, where the package statement must appear as the first non-comment in the file, you're stating that this compilation unit is part of a library named mypackage. Or, put another way, you're saying that the public class name within this compilation unit is under the umbrella of the name mypackage, and if anyone wants to use the name they must either fully specify the name or use the import keyword in combination with mypackage (using the choices given previously). Note that the convention for Java packages is to use all lowercase letters, even for intermediate words.

For example, suppose the name of the file is MyClass.java. This means there can be one and only one public class in that file, and the name of that class must be MyClass (including the capitalization):

Now, if someone wants to use MyClass or, for that matter, any of the other public classes in mypackage, they must use the import keyword to make the name or names in mypackage available. The alternative is to give the fully-qualified name:

The import keyword can make this much cleaner:

It's worth keeping in mind that what the package and import keywords allow you to do, as a library designer, is to divide up the single global name space so you won't have clashing names, no matter how many people get on the Internet and start writing classes in Java.