What’s package-info.java for?

In some recent classes, my students have encountered a package-info.java file tucked inside of some of the sample code we get from courseware providers.  「What’s that thing?」, they usually ask.

package-info.java’s purpose

The package-info.java is a Java file that can be added to any Java source package.  Its purpose is to provide a home for package level documentation and package level annotations. Simply create the package-info.java file and add the package declaration that it relates to in the file.  In fact, the only thing the package-info.java file must contain is the package declaration.

Java

package com.intertech.services;

1	package com . intertech . services ;

The package-info.java file above must sit in the com.intertech.services package.

Package Documentation

Prior to Java 5, package level documentation (the documentation shown in Javadocs for a package) was placed in package.html.  Today, the description and other related documentation for a package can be written up in the package-info.java file and it gets used in the production of the Javadocs.  As a demonstration, the example package-info.java…

Java

/** * Domain classes used to produce the JSON and XML output for the RESTful services. * <p> * These classes contain the JAXB annotations. * * @since 1.0 * @author jwhite * @version 1.1 */ package com.intertech.cms.domain;

1 2 3 4 5 6 7 8 9 10

/** * Domain classes used to produce the JSON and XML output for the RESTful services. * <p> * These classes contain the JAXB annotations. * * @since 1.0 * @author jwhite * @version 1.1 */ package com . intertech . cms . domain ;

… results in the following Javadocs.

Package Annotations

Perhaps more importantly to today’s annotation driven programmer, the package-info.java file contains package level annotations. An annotation with ElementType.PACKAGE as one of its targets is a package-level annotation and there are many of them.  Using your favorite IDE’s code assistant (shown in Eclipse below) in a package-info.java file and you will find a number package annotation options.

For example, perhaps you want to deprecate all the types in a package. You could annotate each individual type (the classes, interfaces, enums, etc. defined in their .java files) with @Deprecated (as shown below).

Java

@Deprecated public class Contact { }

1 2 3

@Deprecated public class Contact { }

Or, you could use the @Deprecated on the package declaration in package-info.java.  This has the effect of deprecating everything in the package in one fell swoop.

Java

@Deprecated package com.intertech.cms.domain;

1 2	@Deprecated package com . intertech . cms . domain ;

Help adding package-info.java to your packages

While you can add the package-info.java file to your packages by hand (just as you can create Java classes by hand), IDE’s often offer you the option to include a package-info.java file each time you create a new package.  Eclipse, shown below, offers a simple (and often overlooked) checkbox in the New Java Package creation wizard.

Wrap Up
So now you know what that package-info.java file is all about and you know how to use it. Like to learn more about Java or other Java related topic? Sign up for one of our many classes today.