另類的package-info.java檔案探討

     翻看以前的筆記，看到一個特殊的java檔案：pacakge-info.java，雖然有記錄，但是不全，就嘗試著追蹤一下該問題， 分享一下流水賬式的結果。

首先，它不能隨便被建立。在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代碼  

1. /** 
2.  * 定義只能標註在package上的註解 
3. */  
4. @Target(ElementType.PACKAGE)  
5. @Retention(RetentionPolicy.RUNTIME)  
6. public @interface PkgAnnotation {  
7. }  

 

 

 

     再定義一個package-info類，這個是一個特殊的類，先看代碼：

 

Java代碼  

1. @PkgAnnotation  
2. package com.company;  

      很簡單，就這麼個檔案，裡面啥都沒有，就這兩句話，沒有class類，沒有常變數聲明。接著寫一個類比交易類，代碼如下：

 

Java代碼  

1. public class Client {     
2.     public static void main(String[] args) {  
3.         //可以通過I/O操作或配置項獲得包名  
4.         String pkgName = "com.company";       
5.         Package pkg = Package.getPackage(pkgName);  
6.         //獲得包上的註解  
7.         Annotation[] annotations = pkg.getAnnotations();  
8.         //遍曆註解數組  
9.         for(Annotation an:annotations){  
10.             if(an instanceof PkgAnnotation){  
11.                 System.out.println("Hi,I'm the PkgAnnotation ,which is be placed on package!");  
12.                 /* 
13.                  * 註解操作 
14.                  * MyAnnotation myAnn = (PkgAnnotation)an; 
15.                  * 還可以操作該註解包下的所有類，比如初始化，檢查等等 
16.                  * 類似Struts的@Namespace，可以放到包名上，標明一個包的namespace路徑 
17.                  */           
18.             }  
19.         }  
20.     }  
21. }  

      運行結果如下所示：

 

 

Hi,I'm the PkgAnnotation ,which is be placed on package!

 

 

聲明友好類和包常量

     這個比較簡單，而且很實用，比如一個包中有很多的內部訪問的類或常量，就可以統一的放到package-info類中，這樣就方便，而且集中管理，減少friendly類到處遊走的情況，看例子：

 

Java代碼  

1. @PkgAnnotation  
2. package com.company;  
3.  //這裡是包類，聲明一個包使用的公用類，強調的是包存取權限  
4. class PkgClass{  
5.     public void test(){  
6.     }  
7. }  
8. //包常量，只運行包內訪問，適用於分“包”開發  
9. class PkgConst{  
10.     static final String PACAKGE_CONST="ABC";  
11. }  

 

 

 

  提供包的整體注釋說明

     如果是分“包”開發，也就是說一個包實現一個商務邏輯或功能點、或模組、或組件，則需要對一個包有很好的說明，說明這個包是幹啥的，有啥作用，版本變遷，特別說明等等，如下：

 

Java代碼  

1. /** 
2.  * <b>package-info不是平常類，其作用有三個:</b><br> 
3.  * 1、為標註在包上Annotation提供便利；<br> 
4.  * 2、聲明包的私人類和常量；<br> 
5.  * 3、提供包的整體注釋說明。<br>  
6. */  
7. 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檔案惹的禍，在各個包下建立一個即可。

 

 

轉自：http://strong-life-126-com.iteye.com/blog/806246