Packages and the classpath
A class has a name and a package, and the two together are its full name: Main in the package demo is demo.Main. The package keeps two classes with the same simple name apart, and it maps to a folder under the output folder. The class path then says where the root of that folder tree is.
A package is a folder
The first statement of a source file may declare its package. It comes before any import and before the class, and the name is one or more words joined by dots. By convention the words are a domain in reverse, as in com.example.app, which keeps a published library from colliding with another one.
The compiler writes the class file into a folder path made from the package: demo.Main becomes demo/Main.class under the output folder. The source file itself may sit anywhere, but keeping it in the matching folder is the convention every build tool expects.
Building into out
The file Main.java declares the package demo:
package demo;
public class Main {
public static void main(String[] args) {
System.out.println("from package demo");
}
}
javac -Xlint:all -d out Main.java
ls out
ls out/demo
java -cp out demo.Main
demo
Main.class
from package demo
The compiler created out/demo because the package says so, and -d out made out the root of the tree. The run names the class by its full name, package first, and -cp out says where the root is.
The class path
The class path is a list of roots. The JVM turns the class name into a relative path, demo/Main.class, and looks for it under each root in turn. The default root is the current folder, which is why the same class runs from inside out with no -cp at all. From the folder that holds the source, the default root is wrong and the JVM says so:
java demo.Main
Error: Could not find or load main class demo.Main
Caused by: java.lang.ClassNotFoundException: demo.Main
The first line is the launcher, the second is the cause, and both name the class the same way. A class path with several entries separates them with a colon on Linux and macOS and a semicolon on Windows: -cp out:lib/util.jar. A jar is a zip of class files with the same folder tree inside it, so a jar is a root like a folder.
import
A class from another package is usable by its full name, or by its simple name after an import. The import does not copy anything and does not load the class at run time; it only lets the compiler read ArrayList as java.util.ArrayList.
import java.util.ArrayList;
import java.util.List;
public class Imports {
public static void main(String[] args) {
List<String> names = new ArrayList<>();
names.add("Ada");
names.add("Grace");
System.out.println(names);
System.out.println("size: " + names.size());
}
}
javac -Xlint:all Imports.java
java Imports
[Ada, Grace]
size: 2
java.util.* imports every class of the package and is legal, but a list of single classes says what the file uses and does not collide with a class of the same name in another package. The import page has the same rule for a static import, which imports a static member rather than a class.
The unnamed package
A file with no package statement belongs to the unnamed package. Every lesson so far used it, and it is fine for one file that is compiled and run by hand. The unnamed package cannot be imported from a named one, so the first time two files need each other, both get a package.
The file name rule still applies, and the error names both the class and the file the compiler expected. A file named Other.java that declares public class Main does not build:
public class Main {
public static void main(String[] args) {
System.out.println("wrong file name");
}
}
javac -Xlint:all Other.java
Other.java:1: error: class Main is public, should be declared in a file named Main.java
public class Main {
^
1 error
A package adds one more rule to the same idea: the class file goes into the folder of its package under the output root. A public class whose file name is wrong is refused before the compiler reads the members, so the caret sits on the class name and nothing else is reported.
Exercises
- Change the package in Main.java to demo.app, build with -d out and find the class file. What is its full name now?
- Run java -cp out:out demo.Main. Does a repeated root change anything?
- Remove the two imports from Imports.java and use the full names java.util.List and java.util.ArrayList. Does it still build?
- Put a class with no package statement into a file that also has a packaged class. What does the compiler say?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does
package demo;decide about the class file?Answer
It goes into the folder demo under the output root
The package becomes a folder path under the -d root; the class file keeps the class name.
-
Which command runs the class
Mainof the packagedemowith the classes inout?Answer
java -cp out demo.Main
The class path names the root, and the class is named by its package and simple name.
-
What does an
importstatement do?Answer
It lets the compiler use a simple name for a class of another package
An import is a compile-time name binding; loading happens later, when the class is first used.
-
What does this program print?
package demo; public class Q1 { public static void main(String[] args) { System.out.println("packaged"); } }Answer
packaged
The package changes the class name and its folder, not the output of the program.
-
What does this program print?
import java.util.ArrayList; import java.util.List; public class Q2 { public static void main(String[] args) { List<String> names = new ArrayList<>(); names.add("Ada"); names.add("Grace"); System.out.println(names.size()); } }Answer
2
Two strings were added, so size returns 2.
-
What does
-cp out:lib/util.jarmean?Answer
The JVM searches out and the jar for classes
A class path is a list of roots, and both a folder and a jar can be a root.
-
A source file is named Other.java and declares
public class Main. What does javac print?Answer
error: class Main is public, should be declared in a file named Main.java
A public class must be declared in a file with its own name, whatever the package.
-
What does this program print?
public class Q3 { public static void main(String[] args) { java.util.List<String> list = new java.util.ArrayList<>(); list.add("x"); System.out.println(list); } }Answer
[x]
A full name works without an import; the list holds one string and prints it in brackets.
-
Can a class in the unnamed package be imported by a class in a named package?
Answer
No: the unnamed package cannot be imported
There is no name for the unnamed package to import, which is why two files that need each other get packages.
-
What does this program print?
public class Q4 { public static void main(String[] args) { Helper helper = new Helper(); System.out.println(helper.text()); } } class Helper { String text() { return "helper"; } }Answer
helper
A file may hold several classes; only the public one has to match the file name, and main can use the other.
The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.
Article author: Arthur Isaev