Package Declaration

A package declaration in Java is a construct that establishes the hierarchical namespace for the types (classes, interfaces, enums, records, or annotations) defined within a source file. It dictates the Fully Qualified Class Name (FQCN) of the compiled types and defines a fundamental encapsulation boundary for Java’s access control model.

Syntax

The declaration uses the package keyword followed by a dot-separated namespace and terminated by a semicolon.

package com.example.project.module;

public class MyClass {
    // Class implementation
}

Structural and Syntactic Rules

• Positioning: The package declaration must be the exact first non-comment, non-whitespace construct in the .java source file. A file can contain a maximum of one package declaration.
• Valid Identifiers: The package name must consist of valid Java identifiers separated by dots. Each component of the package name cannot be a reserved Java keyword (e.g., package com.new.project; is invalid because new is a keyword) and cannot begin with a digit.
• Access Control Boundary: Packages define a core level of encapsulation. Types and members declared without an explicit access modifier (public, protected, or private) possess default (package-private) visibility. These elements are accessible only to other types declared within the exact same package.
• Bytecode Resolution: Standard ClassLoader implementations map package names to hierarchical paths (e.g., com/example/core/). However, the JVM does not strictly require .class files to reside in a physical directory structure on the host file system. Class loaders frequently supply bytecode from virtual paths inside archive files (.jar, .jmod), network streams, or memory.
• Naming Conventions: By convention, package names are written entirely in lowercase to avoid conflict with the names of classes or interfaces. The standard approach utilizes a reversed Internet domain name as a unique prefix (e.g., org.apache.commons).
• Default Package: If a source file omits the package declaration, its types are placed into an unnamed, default package. Types in the default package cannot be imported by types residing in named packages.

Package-Level Metadata (package-info.java)

A package declaration can exist in isolation within a specialized file named package-info.java. This file is used to apply package-level annotations and to generate package-level Javadoc documentation. It contains no class or interface definitions.

/**
 * Provides core module functionality.
 */
@Deprecated
package com.example.project.module;

Compilation Mechanics

When compiling a Java file with a package declaration, the compiler embeds the package information into the resulting .class bytecode file. The FQCN of the class is formed by concatenating the package name and the class name, separated by a dot (.) (e.g., com.example.project.module.MyClass).

To automatically generate the corresponding directory structure for the .class files during compilation, the -d (directory) flag is used:

javac -d . MyClass.java

This command instructs the compiler to read the package declaration and create the com/example/project/module/ directory tree in the specified output directory (.), placing MyClass.class at the leaf, regardless of where the original MyClass.java file is physically located.

Execution Mechanics

When executing a packaged class, the JVM’s class loader must be able to resolve the package hierarchy from the classpath, and the exact FQCN must be provided to the java command:

java com.example.project.module.MyClass

Master Java with Deep Grasping Methodology!

Learn More