Java Import Directives

Packages are named containers for related Java classes and interfaces.

Programming

Asking Where a Class Belongs

When you look at a Java class, a useful first question is where the class belongs, before you ask what the class does. Java places every class inside a package. This article follows one question through a small example: when code in one file uses a class name, how does Java know which class that name refers to, and when does the file need an import directive to make the name usable?

Key point

A package is a named container for related Java classes and interfaces. It is the class's stated organizational home, and knowing that home is the first step in deciding whether another file needs an import directive to use the class.

Tracing a Class Name Through One File

Start with a single source file. Its first meaningful line may be a package declaration. That line states the package of the class defined in the file. If the file has no package declaration at all, the class is placed in the default package. The package declaration therefore answers the question of where the current class lives.

java

package shapes.geometry;

public class Circle {
    private double radius;

    public Circle(double radius) {
        this.radius = radius;
    }

    public double getRadius() {
        return radius;
    }
}

package shapes.geometry;

public class Circle {
    private double radius;

    public Circle(double radius) {
        this.radius = radius;
    }

    public double getRadius() {
        return radius;
    }
}

Notes on the code

The package declaration states that Circle lives in the package shapes.geometry.
The class body is ordinary Java; the package line does not change how Circle is written.
Any other file that wants to use Circle from this package must refer to it in a way Java can resolve, as explained below.

1
Read the package declaration at the top of the file to learn which package the current class belongs to.
2
When the file uses a class name, check whether that name is a class in the same package or a class the file has been given access to.
3
If the class is in a different package, look for an import directive in the file that names that class.
4
If there is an import directive, the short class name can be used in the code.
5
If there is no import directive and the class is not one that Java imports automatically, the class must be referred to by its full package path, or the import must be added.

Follow one class name used in a file. The answer depends on whether the class belongs to java.lang, whether the file imports it, or whether it must be written with its full package path.

What a Package Contains

Definition

A package is a named container for related Java classes and interfaces. It gives Java types an organizational home and a name that other code can refer to.

Java's standard classes are also stored in named packages. String and System are standard classes that live in the package java.lang. Your own classes are placed in packages too, either by a package declaration you write or, if you write none, by Java's default package.

A package is not an action performed on a class later. It is part of the class's declared identity. Because of this, you can read a class's package before you read its methods and already know whether another file will need an import to use it.

The Package Declaration in a Source File

The package declaration is a single statement that names the package of the classes in the file. It is written at the top of the file and ends with a semicolon. Each part of the anatomy below does a specific job.

Each token of the package declaration and what it contributes to the file.

Named Packages Versus the Default Package

The two kinds of package differ in how a class is placed and in whether its name can be referred to from elsewhere through a package name. The table compares them using only what the source establishes.

Feature	Named package	Default package
How the class is placed	A package declaration names the package explicitly	Omitting the package declaration places the class here
Typical use	Organizing real code and related classes	Very small beginner exercises
Official style guidance	Recommended for organizing code	Discouraged by official Java style guidelines
Can its name be referred to through a package path	Yes, using the package name	The source pack does not describe a package path for it, so avoid relying on one

Named packages and the default package, as established by the source.

Why a Class in Another Package Needs an Import

A package declaration identifies the current class's package. An import directive is the separate statement that enables a file to use a class from another package. The two statements do different jobs, and confusing them is one of the most common beginner errors.

Worked example

Using Circle from a Different Package

Class Circle lives in the package shapes.geometry. A second file, placed in the package app, needs to create a Circle. How does that file make the name Circle usable?

1
Identify the current package
The second file declares package app, so its own class belongs to app.
2
Identify the other package
Circle belongs to shapes.geometry, which is a different package from app.
3
Add an import directive
The import directive names the class by its full path, shapes.geometry.Circle, so the file can use the short name Circle.
4
Use the short name
After the import, the code can write Circle directly.

Result

The file needs an import directive for shapes.geometry.Circle before it can use the short name Circle.

java

package app;

import shapes.geometry.Circle;

public class Main {
    public static void main(String[] args) {
        Circle c = new Circle(2.0);
        System.out.println(c.getRadius());
    }
}

package app;

import shapes.geometry.Circle;

public class Main {
    public static void main(String[] args) {
        Circle c = new Circle(2.0);
        System.out.println(c.getRadius());
    }
}

Notes on the code

package app; states that Main lives in the app package.
import shapes.geometry.Circle; tells Java that this file uses the class Circle from another package.
System appears without an import, because classes in java.lang are imported automatically into every Java file.

Full Package Path Versus the Short Name

The same class can be referred to two ways: by its full package path, or by its short name after an import directive has been written. Compare the two versions below. The class and the behavior are identical; only the way the name is written changes.

Before

package app;

public class Main {
    public static void main(String[] args) {
        shapes.geometry.Circle c = new shapes.geometry.Circle(2.0);
        System.out.println(c.getRadius());
    }
}

The full package path is written at every use of Circle.

After

package app;

import shapes.geometry.Circle;

public class Main {
    public static void main(String[] args) {
        Circle c = new Circle(2.0);
        System.out.println(c.getRadius());
    }
}

The import directive names the class once, and the short name Circle is used in the code.

What do you think happens?

Does a file need an import directive to use the class String?

Reveal answer

Answer:

No. String lives in java.lang, and classes in java.lang are automatically imported into every Java file.

This is the exception to the general rule. A class in another package usually needs an import directive, but java.lang classes such as String and System do not.

Mistakes Beginners Make with Packages and Imports

Common mistake
Treating the package declaration as if it imports a class
What it looks like
Writing package shapes.geometry; in a file that needs to use Circle from another package, and expecting that to make Circle usable.
Why it fails
The package declaration identifies the current class's package. It does not enable use of a class from a different package.
Do this instead
Use an import directive, such as import shapes.geometry.Circle;, to use a class from another package.
Common mistake
Assuming every class needs an import
What it looks like
Adding an import for String and wondering why the file still works without it.
Why it fails
Classes in java.lang are automatically imported into every Java file.
Do this instead
Import classes from other packages, but do not import java.lang classes such as String or System.
Common mistake
Leaving classes in the default package in a larger project
What it looks like
Omitting the package declaration from every class in a growing application.
Why it fails
The default package is discouraged by official Java style guidelines, and it is intended for very small beginner exercises.
Do this instead
Give classes a named package once the code grows beyond a small exercise.

Practice: Reading a File's Package and Imports

MEDIUM

A file begins with package report; and then uses the class Scanner from another package without any import directive. Explain what the package declaration tells Java and what is missing from the file. Then say what line would make the short name usable.

Hints

Ask first which package the current file belongs to, using the package declaration.
Then ask whether the other class is in java.lang, which is imported automatically, or in a different package that needs an import.
The import line names the class by its full path and ends with a semicolon.

Your attempt (not saved)

EASY

Without running any code, sort these names into two groups: those that need an import directive in a file in the package app, and those that do not. Names: String, System, and Circle, where Circle lives in shapes.geometry. Explain how you decided for each name.