Understanding Java Packages: A Comprehensive Guide with Examples

1. What is a Package?

In Java, projects often include numerous classes, making it inconvenient to keep them all in one directory. Additionally, conflicts may arise if two programmers create classes with the same name. Java offers a solution with packages. Packages act like directories in the file system and must align with it.

2. Adding a Class to a Package

How do you add a class to a package? There are two main steps:

• First, use the package keyword as the first line in your file to specify the package name.
• Second, ensure the class resides in a directory named after the package.

Here’s an example of adding the MyFirstApp class to the lesson1 package:

package lesson1;

public class MyFirstApp {
    public static void main(String[] args)  {
        System.out.println("Hello world!");
    }
}

3. Naming Rules for Packages

There are specific naming rules for packages. For commercial projects, start the package name with com, followed by the organization name and project name. Functional descriptors usually follow this hierarchy. For example, a project from examclouds.com could have packages like com.examclouds.examples.code.lesson1. Use lowercase letters for package names.

Packages not only organize classes but also control access. Classes within a package can share detailed information while restricting it from external code.

A package can also declare members that are accessible only to other members of the same package, so classes can share details with each other without exposing them to the outside world.

4. Compiling and Running Package Files

To compile a package file, consider the following project structure: a root directory project1, with src and classes subdirectories. Place the MyFirstApp.java file in the lesson1 package inside src.

cd project1/src
javac -d ../classes lesson1/MyFirstApp.java

After compilation, the class file is stored in classes/lesson1. To run the program:

cd project1/classes 
java lesson1.MyFirstApp

5. Example of a Multi-Level Package

Here’s an example of a multi-level package com.company.lesson1. The class will be located in the directory com/company/lesson1:

package com.company.lesson1;

public class MyFirstApp {
    public static void main(String[] args) {
        System.out.println("Hello world!");
    }
}

6. Importing Packages

To access a class from another package, you can refer to it by its fully qualified name. Consider two classes in different packages, first.Example1 and second.Example2:

package first;

public class Example1 {
    public static void main(String[] args) {
        second.Example2 example2 = new second.Example2();
        System.out.println("Done!");
    }
}

package second;

public class Example2 {
}

Writing the full name every time is inconvenient, especially for multi-level packages. The import statement lets you refer to the class by its short name. Import statements come after the package declaration and before any class definitions:

package first;

import second.Example2;

public class Example1 {
    public static void main(String[] args) {
        Example2 example2 = new Example2();
        System.out.println("Done!");
    }
}

You can import a single class or a whole package:

import java.util.regex.Matcher;
import java.time.*;

One package is imported automatically into every program: java.lang, which holds the most commonly used classes such as String, System and Object.

If you import two packages that contain classes with the same name, the compiler cannot tell which one you mean, so referring to such a class by its short name is an error — you must use the fully qualified name.

When you import a whole package, only its public classes are accessible. In the example below, MyClass imports package p1 but can use only AClass; BClass is not public, so it stays hidden:

package p1;

public class AClass {
}

class BClass {
}

package p2;

import p1.*;

public class MyClass {
    public static void main(String[] args) {
        AClass aClass = new AClass();
        BClass bClass = new BClass(); // compile error: BClass is not public
    }
}

If the package statement is omitted, classes go into the unnamed default package. This is fine for learning and demos, but real projects should always use named packages.

7. Key Points

1. Use the package keyword to declare a package, always as the first line in the file.
2. If no package keyword is present, the classes are added to the default unnamed package.
3. A class must reside in a directory matching its package name.
4. Create package hierarchies using dots as separators.
5. A package can contain multiple classes.
6. A class’s full name includes its package name.
7. Packages help manage object accessibility.
8. The import statements follow the package declaration but precede class definitions.
9. Classes in the java.lang package are implicitly imported.

Frequently Asked Questions