Java Development Environments

Packages are named containers for related Java classes and interfaces.

Programming

Every Java Class Has a Home

When you open an unfamiliar Java class, a useful first question is not what the class does but where it belongs. Java places every class inside a package. Before you can judge whether one file can use another file's class, you need to know which package each class is stated to belong to.

What do you think happens?

A .java file has no package line at the top. Which package does Java place its class in?

A package named after the file
The default package
The java.lang package
No package at all, so the class cannot be used elsewhere

Reveal answer

Answer:

The default package

If a class is not explicitly placed into a named package, Java puts it in the default package. Omitting the package declaration is what sends the class there, so no package name has to appear at the start of the file.

What a Package Contains

Definition

A package is a named container for related Java classes and interfaces. It gives Java types an organizational home that has a name.

The key idea is that a package is not an action performed on a class later. It is the class's stated organizational home. Once you know that home, you can decide whether another Java file needs an import directive to use the class. Grouping related types together in one named container is what lets the rest of the program refer to them by a known location.

Java's standard classes follow the same pattern. String and System are standard classes stored in the named package java.lang. Your own code is organized the same way: a package holds the classes and interfaces that belong together, and the package name tells a reader where to look for them.

Named Packages and the Default Package

There are two situations you will encounter. In the first, a class declares a package name at the top of its file, so it is placed in a named package. In the second, the class has no package declaration, so Java places it in the default package. The two cases differ in whether the class has a name-based home.

How do classes that declare a package name differ from classes with no package declaration? The diagram groups the two cases side by side.

The default package can make very small beginner exercises feel simpler, because no package name has to be introduced at the start of the source file. However, official Java style guidelines discourage using it. The practical reason becomes clearer once you see how imports work: an import directive points to a class by its package name, and the default package has no name to point to.

Where the Package Declaration Goes

A package declaration identifies the package that the current class belongs to. It is a single line that names the package. In a Java source file, the package declaration comes first, before any import directives and before the class declaration. The import directives follow, and then the class itself.

Where does the package declaration appear relative to import directives and the class declaration in a .java file? Read the tokens from left to right in file order.

java

// File: com/example/shapes/Circle.java
package com.example.shapes;

public class Circle {
    private double radius;

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

    public double getRadius() {
        return radius;
    }
}

// File: com/example/shapes/Circle.java
package com.example.shapes;

public class Circle {
    private double radius;

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

    public double getRadius() {
        return radius;
    }
}

Notes on the code

The package line names the package this class belongs to.
The class Circle is placed inside com.example.shapes.
No import directive is needed here, because the class does not use any type from another package.

Why Another Package Needs an Import Directive

A package declaration tells you which package the current class is in. An import directive is what lets the current class use a class from a different package. Without it, the compiler has no stated link from the current file to the class in the other package. The import directive is the connection, and it names the class by its package path.

When code in one package uses a class from a different package, how does the import directive connect the two? The App class in one package reaches Circle in another through the import.

java

// File: com/example/app/App.java
package com.example.app;

import com.example.shapes.Circle;

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

// File: com/example/app/App.java
package com.example.app;

import com.example.shapes.Circle;

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

Notes on the code

The package line places App in com.example.app.
The import directive lets App refer to Circle, which lives in com.example.shapes.
System is not imported, because classes in java.lang are imported automatically into every Java file.

Worked example

Deciding whether an import is needed

A class in package com.example.app uses the class String and the class Circle from com.example.shapes. Which of these needs an import directive?

1
Identify where String lives
String is a standard class stored in java.lang, which is an exception: classes in java.lang are automatically imported into every Java file.
2
Identify where Circle lives
Circle is in the named package com.example.shapes, a different package from com.example.app.
3
Apply the general rule
A class from another package must be brought in with an import directive. Circle therefore needs one.

Result

Circle needs an import directive. String does not, because java.lang is imported automatically.

Edge case

The java.lang exception is the one place where you can use a class from another package without writing an import. It applies to classes stored in java.lang, such as String and System. For any other package, the import directive is what makes the class usable by name.

Mistakes Beginners Make with Packages

Common mistake
Assuming a class with no package line belongs to a named package
What it looks like
A file starts with public class Circle and no package line.
Why it fails
Omitting the package declaration places the class in the default package. No package name has been stated.
Do this instead
Add a package declaration such as package com.example.shapes; at the top of the file when the class belongs to a named package.
Common mistake
Using the default package for real code
Why it fails
Official Java style guidelines discourage the default package.
Common mistake
Writing an import for a class that already sits in java.lang
What it looks like
```
import java.lang.String; added above a class that uses String.
```
Why it fails
Classes in java.lang are imported automatically into every Java file, so the import is not needed for them.
Do this instead
Use String and System directly, and add imports only for classes in other packages.
Common mistake
Treating the package declaration as something that connects two files
Why it fails
A package declaration identifies the current class's package. Linking a class from another package is the job of an import directive.
Do this instead
Use the package line to state where this class lives, and an import directive to use a class from elsewhere.

Sorting Classes into Packages

EASY

A file Invoice.java contains a class Invoice that uses the class Customer, which is stored in package com.example.sales. Invoice should belong to com.example.billing. Write the package declaration for Invoice.java, then write the import directive it needs to use Customer. State whether an import is also needed for String if the class uses String.

Hints

The package declaration goes first, and it names the package the current class belongs to.
The import directive names the class by its full package path, such as com.example.sales.Customer.
Think about which package String is stored in, and what the java.lang exception says about it.

Your attempt (not saved)

Key Takeaways

A package is a named container for related Java classes and interfaces, and it gives every class a stated organizational home.
A class with no package declaration is placed in the default package, which official Java style guidelines discourage for real code.
The package declaration names the current class's package and comes first in the source file, before any import directives and the class declaration.
A class from another package generally needs an import directive, except for classes in java.lang such as String and System, which are imported automatically.