The package-info.java File

1. Overview

In this tutorial, we're going to understand the purpose of package-info.java and how it is useful. Simply put, package-info is a Java file that can be added to any Java package.

2. Purposes of package-info

The package-info.java file currently serves two purposes:

• A place for package-level documentation
• Home for package-level annotations

Other than the aforementioned, the use-cases can be extended as required. In the future, if it's required to add any package-level feature, this file will be a perfect place.

Let's examine the current use cases in detail.

3. Package Documentation

Prior to Java version 5, the documentation related to a package was placed in an HTML file, package.html. This is just a normal HTML file with Javadoc comments placed inside the body tag.

As JDK 5 arrived on the scene, package.html gave way to a new option, package-info.java, which is now preferred over package.html.

Let's see an example of the package documentation in a package-info.java file:

/**
 * This module is about impact of the final keyword on performance
 * <p>
 * This module explores  if there are any performance benefits from
 * using the final keyword in our code. This module examines the performance
 * implications of using final on a variable, method, and class level.
 * </p>
 *
 * @since 1.0
 * @author baeldung
 * @version 1.1
 */
package com.baeldung.finalkeyword;

The above package-info.java will generate the Javadoc:

So, just as we write a Javadoc in other places, we can place the package Javadoc in a Java source file.

4. Package Annotations

Suppose we have to apply an annotation to the entire package. In this case, package-info.java can come to our aid.

Consider a situation where we need to declare fields, parameters, and return values as non-null by default. We can achieve this goal by simply including the @NonNullApi annotation for non-null parameters and return values, and the @NonNullFields annotation for non-null fields, in our package-info.java file.

@NonNullFields and @NonNullApi will mark fields, parameters, and return values as non-null unless they are explicitly marked as @Nullable:

@NonNullApi
@NonNullFields
package com.baeldung.nullibility;
import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;

There are various annotations available to be used at the package level. For example, in the Hibernate project, we have a category of annotations, and the JAXB project also has package-level annotations.

5. How to Create a package-info File

Creating a package-info file is fairly simple: we can create it manually or seek IDE help for generating the same.

In IntelliJ IDEA, we can right-click on the package and select New-> package-info.java:

Eclipse's New Java Package option allows us to generate a package-info.java:

The above method works for existing packages also. Select the existing package, New-> Package option, and tick the Create package-info.java option.

It's always a good practice to make the mandatory inclusion of package-info.java in our project coding guidelines. Tools like Sonar or Checkstyle can be of help in achieving this.

6. Conclusion

The main difference between the HTML and Java file usage is that, with a Java file, we have an additional possibility of using Java annotations. So the package-info java file isn't just a home for package Javadocs but also package-wide annotations. Also, this list of use-cases can be extended in the future.

As always, the code is available over on GitHub.