The package-info.java file

-

Remember the javadocs are written within the class (or interface, or enum files). There are no files to document the package information (or package javadoc). This file (package-info.java) is precisely used for that. It (which must always be named as package-info.java) contains the information about the package under which it is created. 

Apart from the javadoc it also serves as a placeholder for package level annotations. Instead of say deprecating the classes one by one, the annotation could be applied to this file, and the processor deprecates the entire package. This is the place where the annotation with @Target(ElementType.PACKAGE)can be placed. In fact, the Annotation with ElementType.PACKAGE
cannot be placed on any other file, except package-info.java. The file can just contain the package name and the annotation. A sample code for package-info.java is  below. The comments can be generated as Javadocs. Also notice the import statement below the package declaration for the annotation. It was introduced in Java 5, and replaces package.html file, to make it consistent with javadoc style.


/**
 *
 * This is an annotation which can be used only at package level.
 * Note the package cannot be annotated on a class declaration but only on the file
 * package-info.java
 *
 * This package declaration is also used as an example for Target-ElementType.PACKAGE
 * example
 * Note the import statement for PackageAnnotation below the package declaration
 *
 * @author Gaurav Vishal
 *
 */
@PackageAnnotation
package in.gvbooks.annotation.pkg;
import in.gvbooks.annotation.pkg.PackageAnnotation;

The annotation file (PackageAnnotation.java) looks like this


package in.gvbooks.annotation.pkg;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;


/**
 * Refer to package-info.java file in this package and check the usage
 */
@Target(ElementType.PACKAGE)
@Retention(RetentionPolicy.RUNTIME)
public @interface PackageAnnotation {

}

Programmers usually ignore this file. Do not ignore them. Use them especially to create javadocs

Comments

Post a Comment

Popular posts from this blog

Java Generics - 7. Upper and Lower Bounds

-
Image
This is part 7 of the 9 part series on Java Generics  Prev Topic Typed Classes as method parameters Topics 1. Introduction 2. Bounding 3. Multiple bounding 4. Generic Methods 5. Wildcards 6. Typed Classes as method parameters 7. Upper and Lower Bounds 8. Target Types 9. Type Erasure Next Topic Target Types Java Generics - Upper and Lower Bounds This is going to be a really long blog, so please bear with me. Declaring Generic Variables You can also use generics to declare the variables. In other work you can choose which types can be assigned to a variable. The rules are more or less the same as for methods. You cannot define a type variable, like you could for the methods. Thus the declaration below makes no sense.         // invalid        private <E extends Fruit> E var1 = null ;      ...
Read more

Java Functional Programming : 3. The java.util.function Library

-
Image
This is the multi part series on Java Functional Programming 3. The java.util.function Library In most cases you might not need to declare your own functional interface as Java gives you a standard set of interfaces to save your time. In case you’d like to work with a function of two parameters of the same type, you could probably use the interface java.util.function.BinaryOperator<T> for the same activity. (More on the package java.util.function is to follow). As a shortcut, you’d probably prefer to keep things simple without the need of an extra interface declaration. Lets look at the constructs below:        BinaryOperator<Integer> binAdd = ( a , b ) -> a + b ;        System. out .println( "Bin Add 2, 3 = " + binAdd .apply(2, 3)); The lambda expressions can be passed as a parameter into the methods. Let us define a method which doubles the value given by the lambda ex...
Read more

Java Generics - 3. Multiple bounding

-
Image
This is part 3 of the 9 part series on Java Generics  Prev Topic Bounding Topics 1. Introduction 2. Bounding 3. Multiple bounding 4. Generic Methods 5. Wildcards 6. Typed Classes as method parameters 7. Upper and Lower Bounds 8. Target Types 9. Type Erasure Next Topic Generic Methods Java Generics - Multiple bounding Refer back to out Fruit and Grain hierarchy. Remember few of the Grains and Fruits also implement the interface Exportable . What if you wanted the generic class to be used only with the type Exportable? We already discussed that earlier. The declaration extends makes no distinction whether the F extends a class or an interface. The generics give us even more flexibility. Say you wanted you generic class to be used with a type Fruit which is Exportable ? Here the class to be used with the Generic types should be both – Fruit & Exportable . Is that possible with generics? Yes of cou...
Read more