Java packages, imports and modules

Packages group classes and interfaces under a common name; modules (Java 9) group packages and say which of them other modules may use. Both are declared at the top of a compilation unit, and imports let a file use their types by simple names (JLS chapter 7).

Packages

PackageDeclaration:
    {PackageModifier} package Identifier {. Identifier} ;

PackageModifier:
    Annotation

The members of a package are its top-level classes and interfaces and its subpackages. A package cannot have a subpackage and a type with the same name.
The hierarchy is only in the names: java.util and java.util.concurrent are unrelated for access control, and importing one does not import the other.
A compilation unit with no package declaration belongs to an unnamed package. Its types cannot be imported, so it suits only small programs and tests. A compact source file is always in the unnamed package.
Package annotations are allowed only in one compilation unit per package, normally package-info.java.
Packages whose names start with java. belong to the platform; class loaders refuse to define classes in them.

Imports

Imports come after the package declaration and before the first type. They change nothing at run time; they only let names be written shorter in that one compilation unit. There are five kinds (JLS 7.5):

Form	Name	Imports	Since
`import java.util.List;`	Single-type import	One type, by its canonical name (also a nested type: `import java.util.Map.Entry;`)	1.0
`import java.util.*;`	Type import on demand	Every accessible type in a package, or every member type of a type, as needed	1.0
`import static java.lang.Math.PI;`	Single static import	Every accessible static member of a type with that name: fields, methods (all overloads) and member types	5
`import static java.lang.Math.*;`	Static import on demand	Every accessible static member of a type, as needed	5
`import module java.sql;`	Single module import	Every public top-level type of every package the module exports to this module, and of the packages exported by the modules it `requires transitive`	25

Every compilation unit behaves as if it had import java.lang.*;. A compact source file also behaves as if it had import module java.base;.
An on-demand import never imports subpackages: import java.util.*; does not import java.util.function.Function.
Importing a type from the file’s own package, or from java.lang, is allowed and has no effect. Importing the same thing twice is allowed.
A module import can be used in code in any module, including the unnamed module of the class path. The module named must be one the current module reads.

Which import wins

When a simple type name could come from more than one place, the more specific declaration shadows the less specific (JLS 6.4.1 and 7.5):

A type declared in the compilation unit, or a single-type import. The two cannot clash: importing a type with the same simple name as one declared in the file is an error, as are two single-type imports of different types with the same simple name.
A type declared in another compilation unit of the same package.
Types imported on demand, from packages (including the implicit java.lang.*) or by static on-demand imports.
Types imported by module imports.

Two declarations at the same level with the same simple name are allowed until the name is used; then it is ambiguous and an error. The usual fix is a single-type import:

import module java.base;      // exports java.util, with java.util.List
import module java.desktop;   // exports java.awt, with java.awt.List
import java.util.List;        // single-type import: List now means java.util.List

List<String> names = new ArrayList<>();

Static imports follow the same idea for fields and methods: a single static import shadows a static-on-demand one, and a member declared or inherited in the class shadows both. An imported method name is shadowed by any method of the same name in the class, whatever its parameters.

Module declarations

ModuleDeclaration:
    {Annotation} [open] module Identifier {. Identifier} { {ModuleDirective} }

ModuleDirective:
    requires {RequiresModifier} ModuleName ;
    exports PackageName [to ModuleName {, ModuleName}] ;
    opens PackageName [to ModuleName {, ModuleName}] ;
    uses TypeName ;
    provides TypeName with TypeName {, TypeName} ;

RequiresModifier:
    transitive | static

Directive	Meaning
`requires M;`	This module depends on `M` and can read it, at compile time and run time
`requires transitive M;`	Also any module that requires this one reads `M`; use it when `M`’s types appear in this module’s exported API
`requires static M;`	`M` is needed at compile time, optional at run time
`exports p;`	The public types of package `p`, and their public and protected members, are accessible to every module that reads this one
`exports p to A, B;`	A qualified export: only to modules `A` and `B`
`opens p;`	All types and members of `p`, private ones included, are open to deep reflection at run time; nothing extra at compile time
`opens p to A;`	Opened to module `A` only
`uses S;`	This module looks up implementations of service `S` with `ServiceLoader`
`provides S with I1, I2;`	This module supplies implementations of service `S`

Every module except java.base implicitly requires java.base. Writing requires java.base; is allowed, but static may not be used with it. Before Java 25 no modifier at all was allowed there; since Java 25, requires transitive java.base; is allowed.
An open module opens every package and may not contain opens directives.
A module name may not be required twice, a package may not be exported or opened twice, and the exported and opened packages must exist in the module (an empty package is an error).
A service provider named in provides must be a public top-level or nested static class with a public constructor without parameters, or have a public static method provider() with no parameters.
The module’s own packages need not be listed; only exports and opens are.

Named, automatic and unnamed modules

Kind	Where it comes from	Reads	Exports
Named (explicit) module	A `module-info.class` on the module path	What it requires	What it exports
Automatic module	A JAR without `module-info.class` on the module path; named from `Automatic-Module-Name` in its manifest or from the file name	Every module	Every package
Unnamed module	Everything on the class path	Every module	Every package, but named modules cannot require it

A program that never uses modules runs entirely in the unnamed module, as before Java 9, except that it cannot use the packages the JDK’s own modules keep internal by not exporting them, such as sun.security.util.

.JAVA File Format – Packages and modules

Packages

Imports

Which import wins

Module declarations

Named, automatic and unnamed modules