CHAPTER 7

Packages

Programs are organized as sets of packages. Each package has its own set of names for types, which helps to prevent name conflicts. A top level type is accessible (§6.6) outside the package that declares it only if the type is declared public.

The naming structure for packages is hierarchical (§7.1). The members of a package are class and interface types (§7.6), which are declared in compilation units of the package, and subpackages, which may contain compilation units and subpackages of their own.

A package can be stored in a file system (§7.2.1) or in a database (§7.2.2). Packages that are stored in a file system have certain constraints on the organization of their compilation units to allow a simple implementation to find classes easily.

A package consists of a number of compilation units (§7.3). A compilation unit automatically has access to all types declared in its package and also automatically imports all of the public types declared in the predefined package java.lang.

For small programs and casual development, a package can be unnamed (§7.4.2) or have a simple name, but if code is to be widely distributed, unique package names should be chosen (§7.7). This can prevent the conflicts that would otherwise occur if two development groups happened to pick the same package name and these packages were later to be used in a single program.

7.1 Package Members

For example, in the Java Application Programming Interface:

• The package java has subpackages awt, applet, io, lang, net, and util, but no compilation units.
• The package java.awt has a subpackage named image, as well as a number of compilation units containing declarations of class and interface types.

A package may not contain two members of the same name, or a compile-time error results.

Here are some examples:

• Because the package java.awt has a subpackage image, it cannot (and does not) contain a declaration of a class or interface type named image.
• If there is a package named mouse and a member type Button in that package (which then might be referred to as mouse.Button), then there cannot be any package with the fully qualified name mouse.Button or mouse.Button.Click.
• If com.sun.java.jag is the fully qualified name of a type, then there cannot be any package whose fully qualified name is either com.sun.java.jag or com.sun.java.jag.scrabble.

7.2 Host Support for Packages

The observability of compilation units in turn determines which packages are observable, and which packages are in scope.

The packages may be stored in a local file system in simple implementations of the Java platform. Other implementations may use a distributed file system or some form of database to store source and/or binary code.

7.2.1 Storing Packages in a File System

com
gls
jag
java
wnj

Continuing the example, the directory java would contain, among others, the following subdirectories:

applet	
awt
io
lang
net
util

Still continuing the example, if we were to look inside the directory util, we might see the following files:

BitSet.java				Observable.java
BitSet.class				Observable.class
Date.java				Observer.java
Date.class				Observer.class
...

Under this simple organization of packages, an implementation of the Java platform would transform a package name into a pathname by concatenating the components of the package name, placing a file name separator (directory indicator) between adjacent components.

For example, if this simple organization were used on a UNIX system, where the file name separator is /, the package name:

jag.scrabble.board

jag/scrabble/board

com.sun.sunsoft.DOE

com/sun/sunsoft/DOE

children.activities.crafts.papierM\u00e2ch\u00e9

children.activities.crafts.papierMâché

children/activities/crafts/papierM@00e2ch@00e9

7.2.2 Storing Packages in a Database

Such a database must not impose the optional restrictions (§7.6) on compilation units in file-based implementations. For example, a system that uses a database to store packages may not enforce a maximum of one public class or interface per compilation unit.

Systems that use a database must, however, provide an option to convert a program to a form that obeys the restrictions, for purposes of export to file-based implementations.

7.3 Compilation Units

CompilationUnit:
	PackageDeclarationopt ImportDeclarationsopt TypeDeclarationsopt

ImportDeclarations:
	ImportDeclaration
	ImportDeclarations ImportDeclaration

TypeDeclarations:
	TypeDeclaration
	TypeDeclarations TypeDeclaration

A compilation unit consists of three parts, each of which is optional:

• A package declaration (§7.4), giving the fully qualified name (§6.7) of the package to which the compilation unit belongs. A compilation unit that has no package declaration is part of an unnamed package (§7.4.2).
• import declarations (§7.5) that allow types from other packages to be referred to using their simple names
• Top level type declarations (§7.6) of class and interface types

Every compilation unit automatically and implicitly imports every public type name declared by the predefined package java.lang, so that the names of all those types are available as simple names, as described in §7.5.3.

7.4 Package Declarations

7.4.1 Named Packages

PackageDeclaration:
	package PackageName ;

7.4.2 Unnamed Packages

Note that an unnamed package cannot have subpackages, since the syntax of a package declaration always includes a reference to a named top level package.

As an example, the compilation unit:

class FirstCall {
	public static void main(String[] args) {
		System.out.println("Mr. Watson, come here. "
						+ "I want you.");
	}
}

An implementation of the Java platform must support at least one unnamed package; it may support more than one unnamed package but is not required to do so. Which compilation units are in each unnamed package is determined by the host system.

In implementations of the Java platform that use a hierarchical file system for storing packages, one typical strategy is to associate an unnamed package with each directory; only one unnamed package is observable at a time, namely the one that is associated with the "current working directory." The precise meaning of "current working directory" depends on the host system.

Unnamed packages are provided by the Java platform principally for convenience when developing small or temporary applications or when just beginning development.

7.4.3 Observability of a Package

• A compilation unit containing a declaration of the package is observable.
• A subpackage of the package is observable.

7.4.4 Scope of a Package Declaration

It follows that the package java is always in scope (§6.3).

Package declarations never shadow other declarations.

7.5 Import Declarations

ImportDeclaration:
	SingleTypeImportDeclaration
	TypeImportOnDemandDeclaration

The scope of a type imported by a single-type-import declaration (§7.5.1) or type-import-on-demand declaration (§7.5.2) is all the class and interface type declarations (§7.6) in the compilation unit in which the import declaration appears.

An import declaration makes types available by their simple names only within the compilation unit that actually contains the import declaration. The scope of the entities(s) it introduces specifically does not include the package statement, other import declarations in the current compilation unit, or other compilation units in the same package. See §7.5.4 for an illustrative example.

7.5.1 Single-Type-Import Declaration

SingleTypeImportDeclaration:
	import TypeName ;

A single-type-import declaration d in a compilation unit c of package p that imports a type named n shadows the declarations of:

• any top level type named n declared in another compilation unit of p.
• any type named n imported by a type-import-on-demand declaration in c.

The example:

import java.util.Vector;

If two single-type-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored. If another top level type with the same simple name is otherwise declared in the current compilation unit except by a type-import-on-demand declaration (§7.5.2), then a compile-time error occurs.

So the sample program:

import java.util.Vector;
class Vector { Object[] vec; }

import java.util.Vector;
import myVector.Vector;

package myVector;
public class Vector { Object[] vec; }

Note that an import statement cannot import a subpackage, only a type. For example, it does not work to try to import java.util and then use the name util.Random to refer to the type java.util.Random:

import java.util;		// incorrect: compile-time error
class Test { util.Random generator; }

7.5.2 Type-Import-on-Demand Declaration

TypeImportOnDemandDeclaration:
	import PackageOrTypeName . * ;

A type-import-on-demand declaration never causes any other declaration to be shadowed.

The example:

import java.util.*;

7.5.3 Automatic Imports

import java.lang.*;

7.5.4 A Strange Example

package Vector;
public class Mosquito { int capacity; }

package strange.example;
import java.util.Vector;
import Vector.Mosquito;
class Test {
	public static void main(String[] args) {
		System.out.println(new Vector().getClass());
		System.out.println(new Mosquito().getClass());
	}
}

class java.util.Vector
class Vector.Mosquito

7.6 Top Level Type Declarations

TypeDeclaration:
	ClassDeclaration
	InterfaceDeclaration
	;

The scope of a top level type is all type declarations in the package in which the top level type is declared.

If a top level type named T is declared in a compilation unit of a package whose fully qualified name is P, then the fully qualified name of the type is P.T. If the type is declared in an unnamed package (§7.4.2), then the type has the fully qualified name T.

Thus in the example:

package wnj.points;
class Point { int x, y; }

An implementation of the Java platform must keep track of types within packages by their binary names (§13.1). Multiple ways of naming a type must be expanded to binary names to make sure that such names are understood as referring to the same type.

For example, if a compilation unit contains the single-type-import declaration (§7.5.1):

import java.util.Vector;

When packages are stored in a file system (§7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:

• The type is referred to by code in other compilation units of the package in which the type is declared.
• The type is declared public (and therefore is potentially accessible from code in other packages).

When packages are stored in a database (§7.2.2), the host system must not impose such restrictions.

In practice, many programmers choose to put each class or interface type in its own compilation unit, whether or not it is public or is referred to by code in other compilation units. A compile-time error occurs if the name of a top level type appears as the name of any other top level class or interface type declared in the same package (§7.6).

A compile-time error occurs if the name of a top level type is also declared as a type by a single-type-import declaration (§7.5.1) in the compilation unit (§7.3) containing the type declaration.

In the example:

class Point { int x, y; }

package vista;
class Point { int x, y; }

In the example:

package test;
import java.util.Vector;
class Point {
	int x, y;
}
interface Point {			// compile-time error #1
	int getR();
	int getTheta();
}
class Vector { Point[] pts; }		// compile-time error #2

Note, however, that it is not an error for the name of a class to also to name a type that otherwise might be imported by a type-import-on-demand declaration (§7.5.2) in the compilation unit (§7.3) containing the class declaration. In the example:

package test;
import java.util.*;
class Vector { Point[] pts; }		// not a compile-time error

As another example, the compilation unit:

package points;
class Point {
	int x, y;			// coordinates
	PointColor color;		// color of this point
	Point next;			// next point with this color
	static int nPoints;
}
class PointColor {
	Point first;			// first point with this color
	PointColor(int color) {
		this.color = color;
	}
	private int color;		// color components
}

It is a compile-time error if a top level type declaration contains any one of the following access modifiers: protected, private or static.

7.7 Unique Package Names

If unique package names are not used, then package name conflicts may arise far from the point of creation of either of the conflicting packages. This may create a situation that is difficult or impossible for the user or programmer to resolve. The class ClassLoader can be used to isolate packages with the same name from each other in those cases where the packages will have constrained interactions, but not in a way that is transparent to a naïve program.

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as sun.com. You then reverse this name, component by component, to obtain, in this example, com.sun, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names.

In some cases, the internet domain name may not be a valid package name. Here are some suggested conventions for dealing with these situations:

• If the domain name contains a hyphen, or any other special character not allowed in an identifier (§3.8), convert it into an underscore.
• If any of the resulting package name components are keywords (§3.9) then append underscore to them.
• If any of the resulting package name components start with a digit, or any other character that is not allowed as an initial character of an identifier, have an underscore prefixed to the component.

com.sun.sunsoft.DOE
com.sun.java.jag.scrabble
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
gov.whitehouse.socks.mousefinder

The name of a package is not meant to imply where the package is stored within the Internet; for example, a package named edu.cmu.cs.bovik.cheese is not necessarily obtainable from Internet address cmu.edu or from cs.cmu.edu or from bovik.cs.cmu.edu. The suggested convention for generating unique package names is merely a way to piggyback a package naming convention on top of an existing, widely known unique name registry instead of having to create a separate registry for package names.