What does Java's `import module M` bring into scope, how does it differ from a wildcard package import, and how are simple-name ambiguities resolved?
answer
- whole module, not one package
- exports plus implied readability
- public top-level types only
- clash reported at the use site
- single-type, then on-demand, then module
basics
~20 simport module M makes every public top-level type in M's exported packages, plus those of modules M requires transitively, usable by simple name. Clashing names fail only when used; a single-type or wildcard import settles them.
solid answer
~50 s`import module M;`, final since Java 25 after previews in 23 and 24, imports on demand every public top-level class and interface in the packages `M` exports to the current module, plus the packages exported by modules the current module reads because it reads `M`, which means following `requires transitive`. A wildcard like `import java.util.*;` covers one package, or a type's member types. A module import spans many packages, skips nested types, and needs `M` to be read already, though the file need not belong to a module. Ambiguity appears only at a use: `import module java.base; import module java.sql;` compiles until you write `Date`. Resolve it with something more specific: a single-type import shadows on-demand and module imports, an on-demand import shadows module imports, and a module import shadows nothing. A same-package type and `java.lang` also beat it.
code
java · 12 linesimport module java.base; // java.util.Date, java.util.List, java.time.LocalDate, ...
import module java.sql; // java.sql.Date, javax.sql.DataSource, and via requires transitive:
// java.util.logging.Logger, javax.xml.xpath.XPath, ...
import java.sql.Date; // single-type import: shadows both module imports for Date
class Report {
Date day; // java.sql.Date
List<String> lines; // java.util.List, from java.base
DataSource source; // javax.sql.DataSource, from java.sql
Logger log; // java.util.logging.Logger, java.sql requires java.logging transitively
}go deeper
Recall the form import module M, that it is final since Java 25, and that it saves writing one wildcard per package. Know that a clash shows up only when you use the name.
Explain the two clauses of what gets imported, exports to the current module and implied readability, then state the shadowing ladder and show one line settling java.util.Date against java.sql.Date.
Be ready to say where it belongs: scripts and exploration versus long-lived sources, where a new public type in any imported package can turn a compiling file ambiguous on upgrade.
The decision is a team's import style: whether production sources may use module imports and what review or formatting enforces. Weigh shorter headers against brittleness and readers who can no longer see a type's package.
## What a module import is A **module import declaration**, written `import module M;`, lets a source file use the **simple names** (`List` rather than the fully qualified `java.util.List`) of types from a whole module instead of from one package. The Java Language Specification calls it a *single-module-import declaration* (§7.5.5). It previewed in JDK 23 (JEP 476) and JDK 24 (JEP 494, which added on-demand shadowing and `java.se`'s transitive requirement on `java.base`), and became final in Java 25 (JEP 511). The outcomes below hold on javac 27 and javac 25. The import works **on demand**: nothing is listed, and a name is picked up only if the code uses it. ## What it brings into scope It imports every **public top-level** class and interface in two sets of packages: - the packages `M` exports to the current module, which counts a qualified `exports p to ...` that names the current module; - the packages exported by modules the current module reads *because* it reads `M`, which in practice means following `requires transitive`. So `import module java.sql;` covers `java.sql` and `javax.sql`, plus what `java.logging`, `java.xml` and `java.transaction.xa` export, because `java.sql` requires those three transitively. `Logger` and `XPath` work by simple name after that one line. `List` does not: `java.sql` does not require `java.base` transitively, so `java.util` stays out. `java.se` exports nothing itself but requires the rest of the platform transitively, `java.base` included, which is why importing it reaches the whole Java SE API. What stays out: - **Unexported packages**, and packages exported only to other modules. - **Modules `M` requires without `transitive`.** - **Nested types**: `Map.Entry` is usable after `import module java.base;`, but `Entry` alone is not. - **Static members**: `PI` still needs `Math.PI` or a static import. ## How it differs from a wildcard package import | | `import java.util.*;` | `import module java.base;` | |---|---|---| | Names | one package, or a class or interface | one module | | Reach | that package's types, not its subpackages; or a type's member types | every package the module exports to you, plus implied readability | | Imports | accessible classes and interfaces | public top-level classes and interfaces | | Fails when | the package is not uniquely visible | the module is not found or not read | | Shadows | same-named types from module imports | nothing | `import java.util.*;` leaves `Stream` unresolved, because `java.util.stream` is a different package. `import module java.base;` resolves `Stream`, `Path` and `Map` with one line. The source file does not have to belong to a module: class-path code can write `import module java.sql;`. But the import adds no dependency. In an explicit module, javac rejects it with `module m does not read: java.sql` when resolution did not make that module readable. On the class path, code sits in the unnamed module, and `java.se` is outside its default root modules, so `import module java.se;` fails with `unnamed module does not read: java.se` unless you compile with `--add-modules java.se`. Since the declaration takes a module name, it also cannot import from a JAR on the class path. ## How ambiguities arise and resolve A module spans packages, so two imported types can share a simple name, even inside a single module. That is not an error at the import line. javac reports `reference to Date is ambiguous` only where the name is used, so a file with `import module java.base;` and `import module java.sql;` compiles until something says `Date`. The rule that settles it is **shadowing** (§6.4.1): one declaration makes another unusable by simple name in that file. It follows specificity: | Declaration | Shadows a same-named type from | |---|---| | Single-type import, `import java.sql.Date;` | same-package types in other files, on-demand imports, module imports | | Type-import-on-demand, `import java.util.*;`, including the implicit `java.lang.*` | module imports | | Module import | nothing | A top-level type in the file's own package also wins over a module import, and static imports of a nested type sit on the same rungs as their non-static forms. The order of the import lines plays no part. JEP 511's suggested grouping, module imports first and single-type imports last, is a readability convention that mirrors the ladder. The ways out: - **Single-type import** settles one name: `import java.sql.Date;`. - **Wildcard package import** settles every clashing name in that package: `import java.util.*;` makes `List` mean `java.util.List` beside `import module java.desktop;`. - **Fully qualified name** sidesteps the question at one use site: `java.sql.Date`. Two traps follow. A wildcard import can redirect a name silently: with `import module java.base;` alone, `List` means `java.util.List`, and adding `import java.awt.*;` makes it mean `java.awt.List`. And two wildcards still clash with each other: `import java.util.*;` with `import java.awt.*;` leaves `List` ambiguous, module imports or not. ## Where it fits JEP 511's motivation leans on early-stage work, such as prototyping, exploring an API and learning, and it notes that many developers prefer single-type imports in large, mature codebases. Its risk section warns that managing these ambiguities can lead to brittle code. One consequence: a new public type in any imported package can make a name ambiguous after an upgrade. Every compact source file already behaves as if it began with `import module java.base;` (§7.3).
- Can `import module` pick up types from a JAR on the class path?No. The declaration takes a module name, and the class path is the unnamed module, which has no name, the same limit a `requires` directive has. Types from such a JAR still need a single-type or wildcard package import.
- Why does `import module java.sql` leave `Map` unresolved, while `import module java.se` in a module requiring `java.se` resolves it?`java.sql` depends on `java.base` only through the mandated requirement, not transitively, so `java.util` is not among the packages imported. `java.se` declares `requires transitive java.base`, a change JEP 494 made so that importing it reaches the whole Java SE API. `List` stays ambiguous there, because `java.se` also brings in `java.awt` through `java.desktop`.
- Can a wildcard package import change what a name means in a file that already uses module imports?Yes. Type-import-on-demand declarations shadow module imports, so adding `import java.awt.*;` beside `import module java.base;` turns `List` into `java.awt.List`. A single-type import is the narrower fix, because it names one type rather than taking every name in a package.
- import module adds the module as a dependency, the way a requires directive does.
- You can only use import module in code that has its own module-info.java.
- It imports every public type in the module, including packages the module does not export.
- Two modules exporting the same simple name fail the build at the import line.
- The import listed first in the file wins when two modules clash.
- Only a single-type import can resolve a clash; a wildcard package import cannot shadow a module import.
- Module import declarations
- Java 25pre-release 23
Assumes Java 27; module import declarations are final since Java 25, previewed in 23 and 24, and the compile outcomes here match at 25.
context
- JEP 511: Module Import Declarationsopenjdk.org
- Chapter 7. Packages and Modulesdocs.oracle.com
- Chapter 6. Namesdocs.oracle.com