Java package

Short description: Package of Java software

A Java package organizes Java classes into namespaces, providing a unique namespace for each type it contains. Classes in the same package can access each other's package-private and protected members.

In general, a package can contain the following kinds of types: classes, interfaces, enumerations, records and annotation types. A package allows a developer to group classes (and interfaces) together. These classes will all be related in some way – they might all have to do with a specific application or perform a specific set of tasks. Programmers also typically use packages to organize classes belonging to the same category or providing similar functionality.

Using packages

In a Java source file, the package that this file's class or classes belong to is specified with the package keyword. This keyword is usually the first keyword in the source file. At most one package declaration can appear in a source file.

package java.awt.event;

To use a package's classes inside a Java source file, it is convenient to import the classes from the package with an import declaration, which dequalifies the namespaces of the class into scope. The following declaration

import java.awt.event.*;

imports all classes from the java.awt.event package, while the next declaration

import java.awt.event.ActionEvent;

imports only the ActionEvent class from the package. After either of these import declarations, the ActionEvent class can be referenced using its simple class name:

ActionEvent myEvent = new ActionEvent();

Classes can also be used directly without an import declaration by using the fully qualified name of the class. For example,

java.awt.event.ActionEvent myEvent = new java.awt.event.ActionEvent();

does not require a preceding import declaration.

Package-wide Javadoc & annotations

Documentation explaining the package as a whole is written as Javadoc in a file named exactly package-info.java. That file is also the place for annotations to be used across all classes of the package.

The unnamed package

If a package declaration is not used, classes are placed in an unnamed package. Classes in an unnamed package cannot be imported by classes in any other package. The official Java Tutorial advises against this:

Generally speaking, an unnamed package is only for small or temporary applications or when you are just beginning the development process. Otherwise, classes and interfaces belong in named packages.

Package access protection

Public members and classes are visible everywhere and private members are visible only in the same class. Classes within a package can access classes and members declared with default (package-private) access as well as class members declared with the protected access modifier. Default (package-private) access is enforced when a class or member has not been declared as public, protected or private. By contrast, classes in other packages cannot access classes and members declared with default access. However, class members declared as protected can be accessed from the classes in the same package as well as classes in other packages that are subclasses of the declaring class.

Creation of JAR files

JAR files are created with the jar command-line utility. The command

jar cf myPackage.jar *.class

compresses all .class files into the JAR file myPackage.jar. The 'c' option on the command line tells the jar command to "create new archive." The ' f ' option tells it to create a file. The file's name comes next before the contents of the JAR file.

Package naming conventions

Packages are usually defined using a hierarchical naming pattern, with some levels in the hierarchy separated by periods (., pronounced "dot"). Although packages lower in the naming hierarchy are often referred to as "subpackages" of the corresponding packages higher in the hierarchy, there is almost no semantic relationship between packages. The Java Language Specification establishes package naming conventions to avoid the possibility of two published packages having the same name. The naming conventions describe how to create unique package names, so that packages that are widely distributed will have unique namespaces. This allows packages to be separately, easily and automatically installed and catalogued.

In general, a package name begins with the top level domain name of the organization and then the organization's domain and then any subdomains, listed in reverse order. The organization can then choose a specific name for its package. Subsequent components of the package name vary according to an organization's own internal naming conventions.

For example, if an organization in Canada called MySoft creates a package to deal with fractions, naming the package ca.mysoft.fractions distinguishes the fractions package from another similar package created by another company. If a German company named MySoft also creates a fractions package, but names it de.mysoft.fractions, then the classes in these two packages are defined in a unique and separate namespace. There is no requirement that the TLD must be the name of the country of the company. For instance, many packages also use other TLDs such as org, com, etc. The Java standard library puts all symbols in the java.*, javax.*, or jdk.* namespace, though some classes associated with other technologies may reside in other namespaces. Some projects, such as Project Lombok, may not use TLDs at all (all symbols are located in namespace lombok).

Using TLDs in package names is a convention primarily associated with Java, but seldom used in other languages. In other languages such as C++ and C# it is sufficient to just prefix package/namespace names with the company name.

Complete conventions for disambiguating package names and rules for naming packages when the Internet domain name cannot be directly used as a package name are described in section 7.7 of the Java Language Specification.

Core packages in Java SE 8

Main article: Java Platform, Standard Edition

java.lang	Basic language functionality and fundamental types. Implicitly imported by every program.
java.util	Collection data structure classes
java.io	File operations
java.math	Multiprecision arithmetics
java.nio	The Non-blocking I/O framework for Java
java.net	Networking operations, sockets, DNS lookups, ...
java.security	Key generation, encryption and decryption
java.sql	Java Database Connectivity (JDBC) to access databases
java.awt	Basic hierarchy of packages for native GUI components
java.text	Provides classes and interfaces for handling text, dates, numbers, and messages in a manner independent of natural languages.
java.rmi	Provides the RMI package.
java.time	The main API for dates, times, instants, and durations.
java.beans	The java.beans package contains classes and interfaces related to JavaBeans components.
java.applet	This package provides classes and methods to create and communicate with the applets.

Modules

Further information: Java Platform Module System

In Java 9 (released on September 21, 2017) support for "modules", a kind of collection of packages, was implemented as a result of the development effort of Project Jigsaw. The "modules" were earlier called "superpackages" and originally planned for Java 7.

Modules describe their dependencies in a declaration placed in a file named module-info.java at the root of the module's source-file hierarchy. Since Java 9, the JDK is able to check the module dependencies both at compile time and runtime. The JDK itself is modularized for Java 9. For example, the majority of the Java standard library is exported by the module java.base.

As an example, the following module declaration declares that the module com.foo.bar depends on another com.foo.baz module, and exports the following packages: com.foo.bar.alpha and com.foo.bar.beta:

module com.foo.bar {
    requires com.foo.baz;

    exports com.foo.bar.alpha;
    exports com.foo.bar.beta;
}

See also

• Translation unit (programming)
• Modules (C++)

External links

• Java SE 10 API Javadocs