Packages

This tutorial is an abbreviated version of http://java.sun.com/docs/books/tutorial/java/interpack/packages.html.

Programmers bundle groups of related classes and interfaces into packages to:

make classes easier to find and to use
avoid naming conflicts
control access.

Definition: A package is a collection of related classes and interfaces providing access protection and namespace management.

The classes and interfaces that are part of the Java platform are members of various packages that bundle classes by function:

fundamental classes are in java.lang,

classes for reading and writing (input and output) are in java.io,

and so on.

Why put them in a package?

Suppose that you write:

a group of classes that represent a collection of graphic objects, such as circles, rectangles, lines, and points
an interface, Draggable, that classes implement if they can be dragged with the mouse by the user:

//in the Graphic.java file
public abstract class Graphic {
    . . .
}

//in the Circle.java file
public class Circle extends Graphic implements Draggable {
    . . .
}

//in the Rectangle.java file
public class Rectangle extends Graphic implements Draggable {
    . . .
}

//in the Draggable.java file
public interface Draggable {
    . . .
}
You should bundle these classes and the interface in a package for several reasons:

You and other programmers can:

easily determine that these classes and interfaces are related

know where to find classes and interfaces that provide graphics-related functions.

The names of your classes wont conflict with class names in other packages, because the package creates a new namespace.

Classes within the package can have (package) access to one another yet restrict access from classes outside the package.

Creating a Package

To create a package, you put a class or an interface in it:
Put a package statement at the top of the source file in which the class or the interface is defined.
For example, the following code appears in the source file Circle.java and puts the Circle class in the graphics package:

package graphics;

public class Circle extends Graphic implements Draggable {
    . . .
}

The Circle class is a public member of the graphics package.
Include a package statement at the top of every source file that defines a class or an interface that is to be a member of the graphics package.

Include the statement in Rectangle.java and so on:

package graphics;

public class Rectangle extends Graphic implements Draggable {
    . . .
}

The scope of the package statement is the entire source file:

All classes and interfaces defined in Circle.java and Rectangle.java are also members of the graphics package.

If you put multiple classes in a single source file, only one may be public, and it must share the name of the source files base name.
Only public package members are accessible from outside the package.

If you do not use a package statement, your class or interface ends up in the default package, which is a package that has no name.
The default package is only for small/temporary applications.
Your project classes and interfaces belong in named packages.

Naming a Package

With programmers all over the world writing classes and interfaces using the Java programming language, it is likely that two programmers will use the same name for two different classes.
The previous example, we define a Rectangle class when there is already a Rectangle class in the java.awt package.
Yet the compiler allows both classes to have the same name because they are in different packages, and the fully qualified name of each class includes the package name:

The fully qualified name of the Rectangle class in the graphics package is graphics.Rectangle
The fully qualified name of the Rectangle class in the java.awt package is java.awt.Rectangle.

This works just fine unless 2 independent programmers use the same name for their packages. What prevents this problem? Convention.

By Convention: Companies use their reversed Internet domain name in their package names, e.g., com.company.package.
Some companies now drop the first element com. in this example from their package names.
In this course, your team name is analgous to company name.

Use <team name>.<project name> as the top 2 components of your project's package name.

Using Package Members

Only public package members are accessible outside the package in which they are defined.
To use a public package member from outside its package:

Refer to the member by its long (qualified) name

Import the package member

Import the members entire package

Each is appropriate for different situations, as explained in the following sections.

Referring to a Package Member by Name

Use a package member's simple name, if the code you are writing is in the same package as that member or if the member's package has been imported.
To use a member from a different package and that package has not been imported, use the member's qualified name, which includes the package name.

This is the qualified name for the Rectangle class declared in the graphics package in the previous example:

graphics.Rectangle
You could use this long name to create an instance of graphics.Rectangle:
graphics.Rectangle myRect = new graphics.Rectangle();
This sometimes is done for 1-time use of a member. For example,

public class FancyObject implements java.io.Serializable { ... }

Importing a Package Member

To import a member into the file, put an import statement at the beginning of your file before any class or interface definitions but after the package statement.

To import the Circle class from the graphics package created in the previous section:

import graphics.Circle;
Now you can refer to the Circle class by its simple name:
Circle myCircle = new Circle();

Importing an Entire Package

To import all the classes and interfaces contained in a particular package, use the import statement with the asterisk (*) wildcard character:
import graphics.*;
Now you can refer to any class or interface in the graphics package by its short name:
Circle myCircle = new Circle();
Rectangle myRectangle = new Rectangle();
The asterisk in the import statement can be used only to specify all the classes within a package.

It cannot be used to match a subset of the classes in a package. For example, the following does not match all the classes in the graphics package that begin with A:
import graphics.A*;	// does not work
    
The * is not recursive: It does not import any classes in subpackages.

Java runtime system automatically imports the java.lang package.

Disambiguating a Name

If a member in one package shares the same name with a member in another package and both packages are imported, you must refer to each member by its qualified name.

For example, the previous example defined a class named Rectangle in the graphics package.
The java.awt package also contains a Rectangle class.

graphics

java.awt

Rectangle rect;

In such a situation, use the member's qualified name to indicate exactly which Rectangle class you want:

graphics.Rectangle rect;

Managing Source and Class Files

Put the source code for a class or an interface in a file whose name is the simple name of the class or the interface and whose extension is .java.
Then, put the source file in a directory whose name reflects the name of the package to which the class or the interface belongs.
For example, the source code for the Rectangle class is in a file named Rectangle.java, which is in a directory named graphics.
The graphics directory can be anywhere in the file system. The figure below illustrates how this.

The qualified name of the package member and the path name to the file are parallel, assuming the UNIX file name separator slash (/):

class name graphics.Rectangle

pathname to file graphics/Rectangle.java

The company whose Internet domain name is taranis.com precedes all its package names with com.taranis.
Each component of the package name corresponds to a subdirectory.
If Taranis had a graphics package that contained a Rectangle.java source file, it is in a directory as shown below.

When you compile a source file, the compiler creates a different output file for each class and interface defined in it.
The base name of the output file is the name of the class or the interface, and its extension is .class, as shown in the following figure.

Like a .java file, a .class file should be in a series of directories that reflect the package name.
It does not have to be in the same directory as its source.
In this course, class files are in a parallel directory structure, as illustrated below.

You thus can give the classes directory to your customoers without [readily] revealing your source code.

Definition: A class path is an ordered list of directories or ZIP files in which to search for class files.

Each directory listed in the class path is a top-level directory in which package directories appear.
From the top-level directory, the compiler and the interpreter construct the rest of the path, based on the package and the class name for the class.
For example, the class path entry for the directory structure shown in the previous diagram would include classes but not com or any of the directories below com.
Both the compiler and the interpreter construct the path name to a .class file with its full package name.

Summary of Creating and Using Packages

To create a package, put a class or an interface in it.
To put a class or an interface into a package, put a package statement as the first statement in the source file for the class or the interface.
The path name of the source and class file of a class or an interface mirrors the name of the package.

To use a class or an interface that's in a different package, you have 3 choices:

Use the fully qualified name of the class or the interface.

Import the class or the interface.

Import the entire package of which the class or the interface is a member.

In this course, set your class path so the compiler and interpreter can find your source and class files for your classes and interfaces.

class name	`graphics.Rectangle`
pathname to file	`graphics/Rectangle.java`