PACKAGE-INFO.JAVA 做用及用法详解

package-info.java对于常用外部包的程序员来讲应该是熟悉陌生人。由于不是专门开发包的程序员不多须要关注它，而又常在其余包中看到他，眼很熟。它到底有哪些特性和做用及如何使用呢？程序员讲究动口不如动手，何不建立一个试试。打开Eclipse,new class,哦！建立失败，‘-’ 做为特殊字符不容许在类名称里出现，什么状况。原来它原本就是个特例固然得用特别方法建立，记事本上，好了成功了。我喜欢追根问底，还什么特殊的，google 吧，果真有先辈，转过来收藏了。

原文地址：http://strong-life-126-com.iteye.com/blog/806246

特色：

• 首先，它不能随便被建立。在Eclipse中，package-info文件不能随便被建立，会报“Type name is notvalid”错误，类名无效，Java变量定义规范是：字母、数字、下划线，还有那个不怎么经常使用的$符号（顺带说下，Java是支持中文名称的变量，习惯挑战的同窗能够尝试下，分享一下这方面的经验）。

• 其次，服务的对象很特殊。一个类是一类或一组事物的描述，好比Dog这个类，就是描述旺财的，那package-info这个类是描述啥的呢？它总要有一个被描述或被陈述的对象，它是描述和记录本包信息。

• 最后，类不能带有public、private访问权限。package-info.java再怎么特殊，也是一个类文件，也会被编译成package-info.class，可是在package-info.java中只能声明默认访问权限的类，也就是友好类。

其实还有几个特殊的地方，好比不能够继承，没有接口，没有类间关系（关联、组合、聚合等等）等。

这个文件的特殊性说完了，那再说说它有什么做用，它有三个做用：

1. 为标注在包上Annotation提供便利；
2. 声明友好类和包常量；
3. 提供包的总体注释说明。

    咱们来创建一个项目演示这三个做用，创建一个package-info的Java Project，在com.company包三个类:package-info.java是咱们重点关注的，PkgAnnotation.java是一个标注在包上的注解定义，Client.java模拟业务操做类。其结构以下图：

 

为标注在包上Annotation提供便利

     首先定义一个包类型的注解，它只能放置的一个包上：

Java代码    

/**  
 * 定义只能标注在package上的注解  
 */  
 @Target(ElementType.PACKAGE)  
 @Retention(RetentionPolicy.RUNTIME)  
 public @interface PkgAnnotation {  
 }

 再定义一个package-info类，这个是一个特殊的类，先看代码：

@PkgAnnotation  
package com.company;

 很简单，就这么个文件，里面啥都没有，就这两句话，没有class类，没有常变量声明。接着写一个模拟交易类，代码以下

Java代码：

public class Client {  
 public static void main(String[] args) {  
 //能够经过I/O操做或配置项得到包名  
 String pkgName = "com.company";  
 Package pkg = Package.getPackage(pkgName);  
 //得到包上的注解  
 Annotation[] annotations = pkg.getAnnotations();  
 //遍历注解数组  
 for(Annotation an:annotations){  
 if(an instanceof PkgAnnotation){  
 System.out.println("Hi,I'm the PkgAnnotation");  
 /*  
 * 注解操做  
 * MyAnnotation myAnn = (PkgAnnotation)an;  
 * 还能够操做该注解包下的全部类，好比初始化，检查等等  
 * 相似Struts的@Namespace，能够放到包名上，标明一个包的namespace路径  
 */  
 }  
 }  
 }  
 }

      运行结果以下所示：

Hi,I'm the PkgAnnotation!

声明友好类和包常量

     这个比较简单，并且很实用，好比一个包中有不少的内部访问的类或常量，就能够统一的放到package-info类中，这样就方便，并且集中管理，减小friendly类处处游走的状况，看例子：

Java代码：

@PkgAnnotation  
package com.company;  
 //这里是包类，声明一个包使用的公共类，强调的是包访问权限  
class PkgClass{  
 public void test(){  
 }  
}  
//包常量，只运行包内访问，适用于分“包”开发  
class PkgConst{  
 static final String PACAKGE_CONST="ABC";  
}

提供包的总体注释说明

     若是是分“包”开发，也就是说一个包实现一个业务逻辑或功能点、或模块、或组件，则须要对一个包有很好的说明，说明这个包是干啥的，有啥做用，版本变迁，特别说明等等，以下：

Java代码：

/**  
 * <b>package-info不是日常类，其做用有三个:</b><br>  
 * 一、为标注在包上Annotation提供便利；<br>  
 * 二、声明包的私有类和常量；<br>  
 * 三、提供包的总体注释说明。<br>  
 */  
 package com.company;

      经过javadoc生成的API文档以下：

 

     这与包下放置package.htm没啥区别，只是package-info能够更好的在代码中维护文档的完整性，而且能够实现代码与文档同步更新，package.htm也能够作到，不争论，建议是Java 1.5以上版本都使用package-info.java来注释。

 

     与package-info相关的问题

     在项目开发中，能够放置在包上的经常使用注解有：Struts的@namespace、Hibernate的@FilterDef和@TypeDef等等。在包下，随便一个类中的包名前加这些注解，Eclipse会提示“Package annotations must be in file package-info.java”,在该包下创建package-info.java文件，把注解移到这里便可。

    使用Checkstyle插件作代码检查时，会报一个警告“Missing package-info.java file.”也是这个package-info文件惹的祸，在各个包下建立一个便可。