651.288.7000 info@intertech.com

What’s package-info.java for?

by | Jul 3, 2013

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.

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…

… results in the following Javadocs.

package descrption

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

package annotations

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

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.

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.
new package
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 topics? Take a look at the Java Training courses that we provide.

Intertech also provides Java Consulting for those looking for some help with development projects. See what we can do for you!


Java Consutling
Free Tutorial: Spring Batch Admin
Free Guide: Tips For A Virtual Development Environment
Java Course Finder
Spring Training

Like What You've Read?

Subscribe to the Blog.

Every Friday we send that week's content from our Developers via email. Try it out!

Some ad blockers can block the form below.

You have Successfully Subscribed!