APIs, Packages, and Modules in Java

A specific import names one class using its fully qualified name, in the form import package_name.ClassName;

Programming

Why a Short Class Name Needs an Import

Java programs are built from classes, and many of those classes live in packages that are not part of the file you are writing. When your code writes a short name such as ArrayList, the compiler has to know which class that name refers to. The source material is direct about the consequence: without a matching import, a short class name such as ArrayList cannot be resolved, and compilation fails.

This article follows the same order you would use when debugging an import problem. First you trace how a short name is matched against the import lines at the top of a file. Then you learn the two forms of import, a specific import and a wildcard import. Last, you practice finding the exact line where an import-related result stops matching your prediction.

Tracing a Short Name to Its Import

Read the diagram from top to bottom. The short name is the word your code actually writes. The import lines are the statements at the top of the file that tell the compiler where that name's class is defined. The compiler compares the short name against those import lines. If a matching import is present, the name resolves to a class and the file can use it. If no matching import is present, the source says compilation fails.

When the code writes ArrayList, which import does the compiler check, and what happens when no matching import exists?

Notice that the import lines are not part of the code that runs. They are declarations that the compiler reads before it checks the body of the file. This is why an import problem often shows up as a compile error on a line that uses the class name, even though the real fix belongs at the top of the file.

Specific Imports by Full Name

Definition

A specific import names one class using its fully qualified name, which is the package name, a dot, and the class name. The general form is import package_name.ClassName; The source gives import java.awt.Color; as its example. Here java.awt is the package and Color is the class being imported.

java

import java.util.ArrayList;

public class ShoppingList {
    public static void main(String[] args) {
        ArrayList items = new ArrayList();
        items.add("bread");
        System.out.println(items);
    }
}

import java.util.ArrayList;

public class ShoppingList {
    public static void main(String[] args) {
        ArrayList items = new ArrayList();
        items.add("bread");
        System.out.println(items);
    }
}

Notes on the code

The import line names one class, ArrayList, from the package java.util
The body uses the short name ArrayList, which the import makes resolvable
A reader can see at the top of the file that this file depends on ArrayList

The import line in this example records one dependency exactly. The short name ArrayList in the body refers to the class named in the import. If you delete the import line, the body still contains the same short name, and the source's rule applies: the name cannot be resolved and compilation fails.

Reading a Fully Qualified Name

A fully qualified name carries its own address. Reading java.awt.Color from left to right, the parts before the final dot identify the package, and the part after the final dot identifies the class. The diagram separates these two parts so you can see what each one contributes.

How does the name java.awt.Color break into its package part and its class part?

Once you can split a name this way, an import line becomes easy to read. The package part tells you where to look, and the class part tells you which class the file is taking from that package.

Wildcard Imports and What They Bring In

A wildcard import uses an asterisk in place of a class name. The source describes it as the import statement followed by the package name and a wildcard, in the form import package_name followed by a dot and the asterisk, ending with a semicolon. Instead of naming one class, the line makes all the classes in that package available to the file.

java

import java.util.*;

public class ShoppingList {
    public static void main(String[] args) {
        ArrayList items = new ArrayList();
        items.add("bread");
        System.out.println(items);
    }
}

import java.util.*;

public class ShoppingList {
    public static void main(String[] args) {
        ArrayList items = new ArrayList();
        items.add("bread");
        System.out.println(items);
    }
}

Notes on the code

The wildcard line names only the package java.util, not any single class
The body uses the short name ArrayList, which the wildcard makes available
The import lines alone no longer say which classes this file depends on

Compare this file with the specific-import version. The body is identical, but the top of the file now says less. A wildcard import records only the package, so a reader has to look through the rest of the file to discover which classes are actually used.

Choosing Between Specific and Wildcard Imports

Both forms make a class's short name usable in the file. They differ in two ways: how much they bring in, and how clearly the file states its dependencies. A specific import records exactly which classes the file uses. A wildcard import records only the package. The table summarizes this difference.

Feature	Specific import	Wildcard import
Form	import package_name.ClassName;	import package_name followed by a dot and an asterisk, then a semicolon
What it names	Exactly one class	All classes in the named package
What the top of the file shows	Each dependency, one per line	Only the package
Reader effort to find used classes	Read the import lines	Read the rest of the file
Typical reason to choose it	When the file should state each dependency exactly	When the file uses many classes from one package and listing each would be repetitive

Specific and wildcard imports compared on what they bring in and how clearly they state dependencies

Key point

Choose a specific import when you want the top of the file to be an exact list of the classes it depends on. Choose a wildcard import when you want a shorter header and accept that a reader must check the body to see which classes are used.

Finding Where an Import Result Diverges

When an import-related program does not behave as you expected, the useful question is where the result first differs from your prediction. Walk through the program one line at a time, and at each line write down what you expected to happen. The first line where the expected and actual results disagree is the place to investigate. For an import problem, the source indicates that this is usually the import line itself, or the first line that uses the class name.

Worked example

Locating a missing-import divergence

A file uses the short name ArrayList in its body, but the header contains no import line for it. Find the first line where the expected result and the actual result diverge.

1
Step 1: Predict the first line
Expect the file to compile, since ArrayList is used in the body. Mark the first line that uses the name as the point where a result must be checked.
2
Step 2: Check the import lines
Scan the import lines at the top of the file for any line that names ArrayList or uses a wildcard for its package. None is present in this file.
3
Step 3: Compare expected and actual
The source says that without a matching import, the short name cannot be resolved and compilation fails. The actual result therefore differs from the expected result at the line that uses ArrayList, and the cause is the missing import.
4
Step 4: Apply the fix
Add a specific import such as import java.util.ArrayList; at the top of the file, then repeat the comparison. The divergence should disappear once the import matches the short name.

Result

The divergence is at the first line that uses ArrayList. The fix belongs in the import lines at the top of the file.

Mistakes Beginners Make With Imports

Common mistake
Using a short class name with no matching import
What it looks like
A file writes ArrayList in its body and has no import line that names it.
Why it fails
The source states that without a matching import, a short class name such as ArrayList cannot be resolved, and compilation fails.
Do this instead
Add a specific import for the class, such as import java.util.ArrayList;, or a wildcard import that covers its package.
Common mistake
Believing a wildcard import names one class
What it looks like
A reader sees import java.util.*; and assumes the file uses only one class from java.util.
Why it fails
A wildcard import makes all the classes in the named package available to the file. It names the package, not a single class.
Do this instead
Read the body of the file to see which classes are actually used, since the import line does not list them.
Common mistake
Looking at the error line and not the import lines
Why it fails
The source says that for an import problem, the place to investigate is usually the import line itself or the first line that uses the class name.
Do this instead
Start at the import lines, then check the first line that uses the class name.
Common mistake
Choosing a wildcard import without considering how the file will be read by others

Practice: Pick the Right Import Form

EASY

A file uses only the class ArrayList from the package java.util. Write the import line you would choose if you want the top of the file to name exactly which class it depends on, and then write the import line you would choose if you want a shorter header. Explain which one makes the file's dependencies clearer to a reader.

Hints

A specific import has the form package_name.ClassName with one class named.
A wildcard import replaces the class name with an asterisk, so it names only the package.
Ask which form lets a reader see the dependency without reading the rest of the file.

Your attempt (not saved)

MEDIUM

Before running any program, predict the first line where the actual result would differ from your expectation if the import line for ArrayList were deleted. Then identify which line in the file you would check first to confirm your prediction.