A package declaration in a compilation unit specifies the name (§6.2) of the package to which the compilation unit belongs.

The package name mentioned in a package declaration must be the fully qualified name (§6.7) of the package.

The PackageName in a package declaration ensures there is an observable package with the supplied canonical name, and that it is not subject to the rules in §6.5.3 for determining the meaning of a package name.

The scope and shadowing of a package declaration is specified in §6.3 and §6.4.

The keyword package may optionally be preceded by annotation modifiers. If an annotation a (§9.7) on a package declaration corresponds to an annotation type T (§9.6), and T has a (meta-)annotation m that corresponds to java.lang.annotation.Target, then m must have an element whose value is java.lang.annotation.ElementType.PACKAGE, or a compile-time error occurs.

At most one annotated package declaration is permitted for a given package.

The manner in which this restriction is enforced must, of necessity, vary from implementation to implementation. The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called package-info.java in the directory containing the source files for the package. This file does not contain the source for a class called package-info.java; indeed it would be illegal for it to do so, as package-info is not a legal identifier. Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more package-private (default-access) classes, it would be very bad form.

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

A compilation unit that has no package declaration is part of an unnamed package.

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

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.

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

An implementation of the Java SE 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 SE 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.

A package is observable if and only if either:

The packages java, java.lang, and java.io are always observable.

One can conclude this from the rule above and from the rules of observable compilation units, as follows. The predefined package java.lang declares the class Object, so the compilation unit for Object is always observable (§7.3). Hence, the java.lang package is observable (§7.4.3), and the java package also. Furthermore, since Object is observable, the array type Object[] implicitly exists. Its superinterface java.io.Serializable (§10.1) also exists, hence the java.io package is observable.

A single-type-import declaration imports a single type by giving its canonical name, making it available under a simple name in the class and interface declarations of the compilation unit in which the single-type-import declaration appears.

The TypeName must be the canonical name (§6.7) of a class type, interface type, enum type, or annotation type.

It is a compile-time error if the named type is not accessible (§6.6).

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 the type imported by the single-type-import declaration is declared in the compilation unit that contains the import declaration, the import declaration is ignored.

If a single-type-import declaration imports a type whose simple name is n, and the compilation unit also declares a top level type (§7.6) whose simple name is n, a compile-time error occurs.

If a compilation unit contains both a single-type-import declaration that imports a type whose simple name is n, and a single-static-import declaration (§7.5.3) that imports a type whose simple name is n, a compile-time error occurs.

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

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

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

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

package Vector;
public class Mosquito { int capacity; }

package strange;
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

A type-import-on-demand declaration allows all accessible types of a named package or type to be imported as needed.

The PackageOrTypeName must be the canonical name (§6.7) of a package, a class type, an interface type, an enum type, or an annotation type.

It is a compile-time error if the named package or type is not accessible (§6.6).

It is not a compile-time error to name the current package or java.lang in a type-import-on-demand declaration. The type-import-on-demand declaration is ignored in such cases.

import java.util.*;

Two or more type-import-on-demand declarations in the same compilation unit may name the same type or package. All but one of these declarations are considered redundant; the effect is as if that type was imported only once.

If a compilation unit contains both a type-import-on-demand declaration and a static-import-on-demand declaration (§7.5.4) that name the same type, the effect is as if the static member types of that type (§8.5, §9.5) were imported only once.

A single-static-import declaration imports all accessible static members with a given simple name from a type. This makes these static members available under their simple name in the class and interface declarations of the compilation unit in which the single-static-import declaration appears.

The TypeName must be the canonical name (§6.7) of a class type, interface type, enum type, or annotation type.

It is a compile-time error if the named type is not accessible (§6.6).

The Identifier must name at least one static member of the named type. It is a compile-time error if there is no static member of that name, or if all of the named members are not accessible.

It is permissible for one single-static-import declaration to import several fields or types with the same name, or several methods with the same name and signature.

If a single-static-import declaration imports a type whose simple name is n, and the compilation unit also declares a top level type (§7.6) whose simple name is n, a compile-time error occurs.

If a compilation unit contains both a single-static-import declaration that imports a type whose simple name is n, and a single-type-import declaration (§7.5.1) that imports a type whose simple name is n, a compile-time error occurs.

A static-import-on-demand declaration allows all accessible static members of a named type to be imported as needed.

The TypeName must be the canonical name (§6.7) of a class type, interface type, enum type, or annotation type.

It is a compile-time error if the named type is not accessible (§6.6).

Two or more static-import-on-demand declarations in the same compilation unit may name the same type; the effect is as if there was exactly one such declaration.

Two or more static-import-on-demand declarations in the same compilation unit may name the same member; the effect is as if the member was imported exactly once.

It is permissible for one static-import-on-demand declaration to import several fields or types with the same name, or several methods with the same name and signature.

If a compilation unit contains both a static-import-on-demand declaration and a type-import-on-demand declaration (§7.5.2) that name the same type, the effect is as if the static member types of that type (§8.5, §9.5) were imported only once.