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文件惹的禍，在各個包下建立一個便可。