Package-private: the forgotten modifier

Written Explanation

The rule

A declaration with no access modifier has package access. The Java Language Specification says that, absent a modifier, most declarations have package access, meaning they can be used anywhere inside the package that holds them. The Oracle tutorial's access table agrees. For a top-level class with no modifier, "visible only within its own package". For a member with no modifier, the same package, but not subclasses in other packages and not the world.

Notice that package-private is the first level that reaches other classes, but only those in the same drawer.

The word "forgotten" in the title has two meanings. Beginners forget it exists, and they also forget to write a modifier and get package-private by accident. Both are worth fixing: use it on purpose, and read a missing modifier as a decision, not an omission.

The public surface

The public surface of a package is the set of classes (and their public members) that code outside the package may use. Everything else is internal. A good package has a small public surface: only what other packages truly need.

Why small is better:

• Freedom to change. You may rename, rewrite or delete a package-private class at will. No code outside the package can depend on it, so nothing outside can break.
• Less to learn. A teammate reading the package sees two public classes, not twelve, and knows where to start.
• Fewer wrong uses. Other code cannot bypass your rules by calling an internal helper directly.

This is the same idea as private fields, applied one level up: classes and packages get a "front desk" just as objects get methods.

Hiding a helper class

Suppose savings accounts compute interest, and the formula lives in its own helper class. Only the accounts need it:

package com.example.bank;

class InterestCalculator {                    // no modifier: package-private
    double monthlyInterest(double balance) {  // also package-private
        return balance * 0.02 / 12;
    }
}

package com.example.bank;

public class SavingsAccount {
    private double balance;
    private final InterestCalculator calculator = new InterestCalculator();

    public SavingsAccount(double balance) {
        this.balance = balance;
    }

    public void addMonthlyInterest() {
        balance += calculator.monthlyInterest(balance);
    }

    public double balance() {
        return balance;
    }
}

SavingsAccount is public: it is the front desk. InterestCalculator is a working note. Because both are in com.example.bank, SavingsAccount uses the calculator with no import. Even though SavingsAccount is public, its field of type InterestCalculator is private, so the helper does not leak.

Package-private members

The same rule applies to fields, methods and constructors. Even inside a public class, a member without a modifier is invisible to other packages. Two common uses:

• A method that sibling classes in the package need but the outside world should not call.
• A constructor that only the package may use, while a public static factory method hands out instances. The tutorial advice, "use the most restrictive access level that makes sense", leads here naturally.

The compiler's message differs slightly. For a hidden class:

error: InterestCalculator is not public in com.example.bank; cannot be accessed from outside package

For a hidden member:

error: rate is not public in Fee; cannot be accessed from outside package
error: Fee() is not public in Fee; cannot be accessed from outside package

Both messages say "not public ... outside package", which is the compiler's name for "package-private and you are in another package".

A choosing rule for top-level classes

A top-level class can be only public or package-private (the private and protected levels apply to members). Ask:

1. Do classes in other packages need to create or call it? If yes, public.
2. Is it only a helper for classes in its own package? If so, package-private.
3. Unsure? Start package-private. Opening it later (adding public) cannot break anyone. Hiding a class that others already use can.

One public class per file

A file may contain at most one public top-level class, and the file must carry that class's name. In our test, declaring public class Three inside Two.java produced:

error: class Three is public, should be declared in a file named Three.java

Package-private classes have no such limit, but keeping one class per file is the habit that keeps projects easy to navigate. In this course, one class per file.

Why an import cannot help

Visibility and imports are separate checks. In Example 3 below, Bad imports InterestCalculator and the compiler still refuses, three times: once on the import line and twice on the usage. The import resolves the name. The visibility check then fails.

The default package, once more

Package-private means "same package". In the default package, every class is in the same package, so nothing is hidden from anything else. Dropping classes in one unnamed package therefore removes the protection this lesson is about. Named packages are what give you drawers to hide things in.