Packages and imports

Every program in this course so far has fit in one file. A real Java project has hundreds of classes, written by different people, and now and then two of them want the same name. Java keeps them apart by sorting classes into named groups called packages. You have used packages since your first ArrayList, through the import lines at the top of your programs. This lesson explains what those lines do, how to put your own classes into packages, and how Java finds a class while a program runs.

Start with the clutter#

Picture a banking application. It has a class for a customer, a class for an account, a class for a transaction, a class that prints reports, a class that talks to the database, and dozens more. Now imagine all of those sitting loose in a single folder, every .java file shoulder to shoulder with no grouping. Finding the one you want means scrolling through a wall of names. Worse, two different parts of the project might both want a class called Reader: one that reads bank records, one that reads a file. With everything in one pile, those two names collide and the language has no way to tell them apart.

Key idea

A package is a named group of related classes. It works like a folder, with one twist: the package name is written into the code itself, so Java always knows which group a class belongs to.

Declaring a package#

To put a class into a package, you write one line at the very top of its file, above everything except comments. It names the package the class belongs to.

That first line, package com.bank.model;, says “this class lives in the package com.bank.model”. Each dot in the name is one step deeper into a folder, so the package com.bank.model matches the folder path com/bank/model, and the file Customer.java sits inside that last folder. When Java needs a class, it turns the dots of its package into folders and looks there. A file in the wrong folder is a file Java cannot find, and the compiler reports package com.bank.model does not exist.

Here is how the bank's classes lay out on disk. The dotted names become nested folders under src, the folder that holds the source code.

The full name of a class#

Once a class lives in a package, its complete name includes the package. The class above is Customer for short, and its full name is com.bank.model.Customer: the package, a dot, then the class. That long form is called the fully qualified name. It names one class and no other, anywhere in the world, because the package pins down which Customer you mean.

Nobody wants to type com.bank.model.Customer every time, so Java lets you use the short name, Customer, as long as the compiler can tell which class you mean. Inside the same package it can tell on its own. From another package you have to say, and that is what import is for.

An import line is a convenience, never a requirement. You can always skip it and write the full name in place. This program uses three classes from java.util and imports none of them. It reads two names from the keyboard input box and prints them in alphabetical order:

It prints [Ada, Grace]. It also shows why hardly anyone writes Java like this: every class name drags its package along with it.

Bringing a class into scope with import#

An importline tells the compiler: “when I write this short name, I mean the class from that package”. Here is the same program with three imports at the top.

The output is the same. Read the top of the file as the list of classes it borrows. After import java.util.Scanner;, writing Scanner is enough, because you said which one you meant. An import copies no code into your file and loads nothing while the program runs. It only tells the compiler how to read a short name. The compiled .class file refers to every class by its full name, so the import lines are gone once compiling is done.

Importing a whole package#

You write one import per class. When a file uses many classes from one package, a star imports them all: import java.util.*; makes every public class in java.util available by its short name. This is called an on-demand import, because the compiler only looks in java.util when it meets a short name it does not otherwise know.

A star brings in classes, never other packages. Package names look nested, as in java.util and java.util.function, but Java treats them as two unrelated packages that happen to share the start of their names. So import java.util.*; does not cover Function, which lives in java.util.function. Here is javac's answer to a file that imports java.util.* and then uses Function:

The fix is one more line: import java.util.function.Function;.

java.lang: the package you never import#

You have used String, System and Math since your very first program, and you never wrote an import for them. They live in a package called java.lang, and Java imports it into every file for you, as if each one began with import java.lang.*;. It holds the classes almost every program needs, so the language spares you the line.

It prints HELLO 5. Every class in it, String, Math and System, comes from java.lang. Anything outside java.lang must be imported or written out in full. These are the packages you have met so far, and some you will meet soon:

Static imports#

A normal import brings in a class. A static import brings in the static members of a class, its static methods and constants, so you can use them with no class name in front. You met one in testing with JUnit: import static org.junit.jupiter.api.Assertions.assertEquals; is why a test can say assertEquals(...) where it would otherwise need Assertions.assertEquals(...). Math works the same way.

It prints Area: 28.27, Best score: 91 and Square root of 49: 7.0. Each line at the top names one member: PI is a constant, and max and sqrt are methods. import static java.lang.Math.*; would bring in every static member of Math at once. Math itself needs no import, since it is in java.lang. The static imports only save you writing Math. in front of each member.

1import static java.lang.Math.PI;
2// TODO: add a static import for sqrt
3 
4public class Main {
5    public static void main(String[] args) {
6        System.out.printf("Table top: %.2f square metres%n", tableArea(0.6));
7        System.out.printf("Rug diagonal: %.2f metres%n", diagonal(1.2, 1.6));
8    }
9 
10    static double tableArea(double radius) {
11        return 0; // TODO: PI times the radius times the radius
12    }
13 
14    static double diagonal(double width, double length) {
15        return 0; // TODO: the square root of width squared plus length squared
16    }
17}

When two classes share a short name#

Packages exist so that two classes can share a short name, and now and then two of them meet in one file. Java decides which one a short name means with a few rules:

• A class declared in your own file, or elsewhere in your own package, beats a class that a star import offers. Java does not warn you.
• An import that names one class beats a star import.
• If two star imports both offer the name, javac refuses to guess, and using the short name is an error.
• A fully qualified name always means exactly one class, whatever the imports say.

It prints [4, 4, 4] on every run. The class Random at the bottom of the file beats the Random that the star import offers, so dieis the program's own loaded die, and each roll is 3 plus 1. Java gives no warning. With import java.util.Random; at the top instead, javac would refuse the file with Random is already defined in this compilation unit, which at least tells you about the clash.

The third rule shows up with two star imports. java.awt, Java's older toolkit for windows and buttons, has a class called List too: a list box drawn on the screen. Import both packages with stars, and javac cannot tell which List you mean.

Either of two fixes works. Add import java.util.List; below the star imports, and the single-class import wins the short name. Or write the full name, java.util.List<String> names, and leave the short name out of it. With either change the program compiles and prints [Ada].

One import for all of java.base#

Java 25 adds a wider import still. A moduleis a named group of packages that ship together. Modules arrived in Java 9, and the core of Java's library is a module called java.base, which holds java.lang, java.util, java.util.function, java.io, java.time, java.math and dozens more. The line import module java.base; imports every public class of every one of those packages.

One line, and List, Map, LocalDate and Function all work, from four different packages. The wider an import, the more names it can clash on, and a single-class import settles a clash here just as it does for star imports. Most projects still list their classes one by one, so import module suits small programs and experiments best. It also explains something from your first Java program: a compact source file, the kind that starts with void main(), gets import module java.base; automatically, so it can use List or Scanner without a single import line.

The classpath: where Java goes looking#

There is a gap to close. When your program says new Account("Maya"), the running Java machine has to find the compiled Accountcode somewhere on the computer and load it. Java's own classes, such as Scanner, come with the JDK, and Java always knows where they are. For every other class, your own and those of any library you use, Java searches the classpath: the list of places where it looks for compiled classes.

Remember that the Java machine runs bytecode, not source code. javac compiles each .java file into a .class file, and the .class files are what run. When the program needs the class com.bank.model.Account, Java goes through each place on the classpath and looks for com/bank/model/Account.class inside it. It is the same mirror-the-folders rule, used again while the program runs.

Here is the whole trip for a two-file version of the bank. The account lives in one package and the program that uses it in another.

From the folder that holds src, two commands compile the program and run it:

-d out tells javac to put the compiled files in a folder called out, and it builds the package folders inside it for you:

-cp out, short for classpath, makes out the one place Java searches. And java takes the class's full name, com.bank.app.Main, never a file name. It turns the dots into folders and loads out/com/bank/app/Main.class. When main first uses Account, Java finds out/com/bank/model/Account.class the same way.

Key idea

The classpath is the list of folders and JAR files Java searches when a running program needs a class that is not part of Java itself. In each one, Java looks for the folders that match the class's package.

When Java cannot find a class#

Give java a short name, or leave out the classpath, and it cannot find your program at all:

The first command asks for a class called Main in no package, so Java looks for out/Main.class, which does not exist. The second command has no -cp, so Java searches the default classpath: the folder you are standing in. There is no com/bank/app/Main.class directly inside it.

JAR files#

Projects rarely hand around folders of .class files. They pack them into a JAR file (short for Java ARchive): a single zip file holding .class files in their package folders. The jar tool that comes with the JDK makes one. Here the model package goes into a JAR, its loose class files are deleted, and the program runs twice:

Read the first run closely. The program starts, then crashes on line 7, the first line that uses Account. Java loads each class the first time it is needed, and Account is no longer in out. A NoClassDefFoundError means a class that was there when the code was compiled is missing while it runs. (The line numbers inside java.base depend on your Java version.) Put the JAR on the classpath after a colon, and the program works again: Java searches a JAR exactly as if it were a folder. On Windows the entries are separated by a semicolon instead, as in out;lib\bank-model.jar.

Reaching across a package boundary#

Packages do more than tidy your files. They draw a boundary that the access modifiers from encapsulation and inheritance respect. In a one-file program every class shares the unnamed package, so the boundary never showed. Split the bank into packages and it does.

A class with no modifier in front of the word class has package access, also called package-private: only classes in the same package can use it. To use a class from another package, it must be public. Fields and methods follow the same rule, and protected opens one more door: a protected member can also be used inside a subclass in another package. Here is an account with one field of each kind, a program that uses it, and a savings account that extends it. Main and SavingsAccount are both in com.bank.app.

Walk the boundary one field at a time. owner is public, so line 8 of Main is fine. balance is protected: Main is neither in com.bank.model nor a subclass, so line 9 fails, while line 11 of SavingsAccount, which uses balance inside a subclass, compiles without complaint. branch has package access, so only classes in com.bank.model may touch it. Both other classes fail on it, and extending Account does not help.

Putting the whole picture together#

Here is the full life of a name, from the file that defines it to the program that uses it, in four steps.

1. 1A class declares its package on the first line: package com.bank.model;. On disk it sits in the matching folder, com/bank/model.
2. 2That gives the class a fully qualified name, com.bank.model.Account, which no other class in the world shares.
3. 3A class in another package writes import com.bank.model.Account; so it can use the short name Account. For that to be allowed, Account must be public.
4. 4When the program runs, Java searches the classpath for com/bank/model/Account.class and loads it. The folders mirror the package name once more.

The same correspondence shows up three times: in the folders that hold the source files, in the fully qualified name, and on the classpath while the program runs. Hold onto it and packages stop being mysterious. They are folders whose names the language keeps track of.

Further reading#

• Packages on dev.java, the official Java learning site, with naming conventions, imports and static imports
• Packages and modules in the Java Language Specification, chapter 7, the exact rules for package and import declarations
• The java command in the JDK 25 documentation, including --class-path and running a program from source files
• JEP 511: Module Import Declarations, the proposal behind import module, final in Java 25