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.
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.