> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Java 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.
```java theme={"dark"}
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.
```java theme={"dark"}
/**
* 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:
```bash theme={"dark"}
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:
```bash theme={"dark"}
java com.example.project.module.MyClass
```
Tired of Poor Java Skills? Fix That With Deep Grasping!
Learn More
