Historical Context & Motivation
As software projects grew from a few hundred lines to millions of lines of code throughout the 1980s and 1990s, developers faced a serious organizational problem. Imagine writing a school essay where every paragraph, heading, and footnote lived in a single document with no folders or file structure — finding anything would become nearly impossible. Early programming languages like C let you group code into separate files, but there was no built-in system for preventing two files from accidentally using the same name. When James Gosling and the team at Sun Microsystems designed Java in the mid-1990s, they solved this problem by building packages directly into the language.
java.lang and java.io, demonstrating the convention of grouping related classes together.com.sun.java) becomes standard to prevent naming conflicts across organizations worldwide.The central question that packages answer is straightforward: How do you organize thousands of classes so that names don't collide and developers can find what they need? This lesson will teach you how to create packages, import classes from them, and follow the naming conventions that professional Java developers use every day.
Core Principles & Definitions
A package in Java is a named group of related classes and interfaces that provides a separate namespace — a way to guarantee that class names don't conflict. Think of a package like a folder on your computer. You can have a file called notes.txt in your English folder and another notes.txt in your History folder without any confusion, because the folder path makes each file unique. Packages work the same way for Java classes.
Namespace Separation
Date class in java.util is entirely separate from a Date class in java.sql.Logical Organization
java.io.Access Control
Reverse-Domain Convention
com.google.maps) to ensure global uniqueness.com.myschool.projects.Calculator uniquely identifies your Calculator class even if a thousand other developers also wrote one. The package is the "full address" that makes each class name globally unique.Visual Explanation — Package Hierarchy
package declaration at the top of each Java file. Notice that com.myschool.math maps to the folder path com/myschool/math/.The diagram above reveals the most important rule of Java packages: the package name must exactly match the folder path where the source file lives. If you declare package com.myschool.math; at the top of a file, that file must be saved inside the folder com/myschool/math/. If there is a mismatch, the Java compiler will throw an error. This tight coupling between folders and packages is what keeps large codebases navigable.
package statement must be the very first line of code in your Java file (comments and blank lines above it are fine). Only one package declaration is allowed per file, and every class in that file belongs to that package.How Packages Work — Syntax & Import Statements
Declaring a Package
Every Java source file can begin with a package declaration, which tells the compiler which package the file belongs to. The syntax is simple:
package com.myschool.math;Importing Classes from Other Packages
When you want to use a class from a different package, you have three options. The most common is the import statement, which appears after the package declaration and before the class definition. You can import a single class or use a wildcard to import all classes from a package.
com.myschool.math package. Convenient but can make it harder to see which classes are actually being used.java.util.Date and java.sql.Date.java.lang package is automatically imported into every Java program. That's why you can use String, System, Math, and other fundamental classes without writing an import statement.Package Naming Conventions in Detail
Java's naming conventions aren't enforced by the compiler — you won't get an error for using uppercase letters in a package name. However, following these conventions is considered essential in professional development because they prevent naming collisions and make code instantly readable to other developers. The key convention is the reverse internet domain name pattern.
| Convention | Good Example | Bad Example |
|---|---|---|
| All lowercase | com.myschool.math | Com.MySchool.Math |
| Reverse domain name | org.apache.commons | commons.apache.org |
| No hyphens (use underscores) | com.my_school.app | com.my-school.app |
| Avoid Java keywords | com.example.my_int | com.example.int |
| Meaningful names | com.school.gradebook | com.school.stuff |
Worked Example — Building a School Project with Packages
Let's walk through creating a complete project that uses packages. Imagine you're building a grade calculator application for your school. You want to separate the math logic from the user interface code.
com.school.grades.logic for calculation classes and com.school.grades.ui for the user interface. This means we need two sets of folders.src/com/school/grades/logic/ and src/com/school/grades/ui/GradeCalculator.java inside src/com/school/grades/logic/. The first line must declare the package:package com.school.grades.logic;
public class GradeCalculator {
public double average(double[] scores) {
double sum = 0;
for (double s : scores) {
sum += s;
}
return sum / scores.length;
}
}App.java inside src/com/school/grades/ui/. This class needs to import GradeCalculator from the other package:package com.school.grades.ui;
import com.school.grades.logic.GradeCalculator;
public class App {
public static void main(String[] args) {
GradeCalculator calc = new GradeCalculator();
double[] scores = {92, 85, 78, 96, 88};
System.out.println("Average: " + calc.average(scores));
}
}src directory and compile both files. The compiler needs to be able to find all referenced packages from this root directory.javac com/school/grades/logic/GradeCalculator.java
javac com/school/grades/ui/App.java.class file.java com.school.grades.ui.App
Output: Average: 87.8Package Types — Built-in vs. User-Defined
Java packages fall into two broad categories. The built-in packages ship with the Java Development Kit (JDK) and provide ready-made functionality. The user-defined packages are the ones you create yourself to organize your own code. Understanding both types is essential for writing well-structured Java programs.
| Feature | Built-in Packages | User-Defined Packages |
|---|---|---|
| Source | Included with the JDK | Created by the developer |
| Examples | java.util, java.io, java.lang | com.school.grades, org.club.roster |
| Import needed? | Yes (except java.lang) | Yes, when accessing from other packages |
| Naming | Starts with java. or javax. | Starts with reversed domain (e.g., com.) |
| Purpose | Standard functionality: data structures, I/O, networking | Custom application logic specific to your project |
Connection to Modules and Advanced Organization
Packages are the foundation of code organization in Java, but as applications scale to millions of lines, even packages can become difficult to manage. Java 9 introduced the module system (also called Project Jigsaw), which groups related packages together into a higher-level unit. Think of it this way: if packages are folders, modules are like labeled boxes that hold multiple folders and explicitly list which folders are visible to the outside world.
| Concept | Package | Module (Java 9+) |
|---|---|---|
| Granularity | Groups related classes | Groups related packages |
| Defined by | package declaration in each file | module-info.java descriptor file |
| Access control | Package-private (default) or public | Exports specific packages; hides internal ones |
| Required to learn first? | Yes — fundamental | No — typically covered in advanced courses |
For now, focus on mastering packages. Once you're comfortable with them, modules will feel like a natural extension. The good news is that packages you create today will work perfectly inside modules later — nothing about the package system changes when modules are added on top.
Practice Problems
Timer without causing a conflict, as long as they are in different packages. What mechanism makes this possible?coolprojects.org. They are building a chess game with separate packages for the board logic and the AI. Write the correct package declarations and the folder paths (from the source root) for a class called Board.java in the board package and MoveGenerator.java in the AI package.import com.school.utils.StringHelper;
package com.school.app;
public class Main {
public static void main(String[] args) {
StringHelper helper = new StringHelper();
}
}Book, Member, Checkout, DatabaseConnection, and SearchService. Your school's domain is lincoln-high.edu. Design a package structure by grouping related classes, writing the package name for each group, and explaining why you chose that grouping.import java.util.*; to bring in all classes from a package. However, most professional style guides (like Google's Java Style Guide) discourage wildcard imports. What problems could wildcard imports cause, especially as a project grows? Consider what happens when a new class is added to a package you're wildcard-importing.Lesson Summary
Java packages are named groups of related classes that provide namespace separation, logical organization, and access control. Every package name must match its folder path on disk, and the package declaration must be the first line of code in each Java file. To use classes from other packages, you write import statements — either single-class imports (preferred) or wildcard imports.
The standard naming convention uses a reversed internet domain name followed by project and module segments, all in lowercase letters separated by dots (e.g., com.myschool.math). Built-in packages like java.util and java.io ship with the JDK, while user-defined packages let you organize your own code. As projects grow, Java 9's module system adds an additional layer above packages for even larger-scale organization.