The Java Programming Language:
Packages and the Java Namespace

There have been a number of translations of this page, the authors of which have requested that links to their home pages as well as to the translation be included here. The situation (and the translations) were getting out of hand, and all have now been removed as I am not supposed to place what appear to be "sponsoring" links on my personal website here at the university. Thanks again to all those who supplied the translations.

What is a Java package?

Here are some things various authors have said about Java packages:

1. A package is a collection of related classes and interfaces providing access privileges and namespace management. [Campione, Walrath and Huml in The Java Tutorial]
2. The package is Java's mechanism for managing namespaces. [A paraphrase of Eckel]
3. A package is a convenient way of grouping together many different classes that have a common purpose. [Holmes]
4. A package is a unique named collection of classes. [Horton]
5. Packages, which comprise many classes, interfaces, or other packages, support hierarchical organization, and are used to organize large programs into logical and manageable units. [A paraphrase of Jia]
6. Java packages are namespaces. They allow programmers to create small private areas in which to declare classes. The names of those classes will not collide with identically named classes in different packages. [Martin]

How is a Java package named, created and stored?

• The names of Java packages should be all lower case and consist of one or more identifiers, separated by dots (periods), such as one.two.three.
• If you want the contents of several Java source code files to be part of a package called one.two.three, then the following line of code must be the first non-comment line in each of those files:

  package one.two.three;
  

• All files in a given package must be located in a single subdirectory corresponding to the package name, and the package name will be "translated" to a directory path on the local system (with each dot becoming a separator character beween portions of the path). For example, on a Unix or Linux system the class files of the package one.two.three must be stored at a location like this

  /rest_of_path/one/two/three
  

  while on a Windows system it might be

  C:\rest_of_path\one\two\three
  

  In addition, the part of the path down to one/two/three (or one\two\three) must be part of the classpath for the given system.
• If you plan to make your Java classes available to the world at large, it is recommended that you register an Internet domain name, and begin the name of each of your packages with your domain name reversed. This will guarantee a globally unique name for each of your packages. And this really does mean "globally", in the sense of "anywhere in the world".

How is a Java package used?

• You get access to all the classes in a package with an import statement like this:

  import one.two.three.*;
  

• You can also import just one specific class, as in

  import one.two.three.SomeClass;
  

• When you have access to a class via an import statement, you use its unqualified name like this:

SomeClass myObject = new SomeClass();

• You can even use a specific class without an import statement, inconvenient and longwinded though that might be, as in

  one.two.three.SomeClass myObject = new one.two.three.SomeClass();
  

What about the standard Java packages?

• The standard class libraries in Java are contained in packages whose names start with either java or javax. These packages themselves contain smaller packages (java.io, for example). These classes are guaranteed to be available in all implementations.
• Your classes have access by default to all classes in java.lang, so you never have to explicitly import this package. It contains classes like String, Math, and the "wrapper classes" for the primitive types, for example.
• Many Java packages are imported more frequently than others, so you will often see one or more of the following import statements.

  import java.io.*;
  import java.awt.*;
  import java.awt.event.*;
  import javax.swing.*
  

Some things to remember about Java packages ...

• Classes not placed in a named package belong to the (anonymous) "default package" associated with the current directory, and when writing small programs, we generally just leave everything in the "default package" for simplicity. However, packages are there to help us keep our sanity when writing medium to large programs, and we should make use of them.
• Members of classes in a given package that have the protected qualifier are available anywhere within the same package, and also from any subclass of a class in the given package that appears in another package.
• Members of classes in a given package that have the "default access" (no specific access qualifier) are available only within the given package.
• Note that packages don't really "contain" other packages, even though the hierarchical naming scheme may imply that they do. For example, using the import statement

  import java.awt.*;
  

  does not mean that you also get what is in the part of the library that you get by using this statement:

  import java.awt.event.*;
  

  This should be clear if you just think for a moment about how package names relate to the directory structure used to store package files, but it is easy to make wrong assumptions about the package relationships when the package names are closely related.

List of All Topics