JAVA package-info文件【轉】

翻看之前的筆記，看到一個特殊的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提供便利

     首先定義一個包類型的註解，它只能放置的一個包上：

 

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

 

 

 

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

 

@PkgAnnotation
package com.company;

      很簡單，就這麼個文件，裏面啥都沒有，就這兩句話，沒有class類，沒有常變量聲明。接着寫一個模擬交易類，代碼以下：

 

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 ,which is be placed on package!");
                /*
                 * 註解操做
                 * MyAnnotation myAnn = (PkgAnnotation)an;
                 * 還能夠操做該註解包下的全部類，好比初始化，檢查等等
                 * 相似Struts的@Namespace，能夠放到包名上，標明一個包的namespace路徑
                 */
            }
        }
    }
}

      運行結果以下所示：

 

 

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

 

 

聲明友好類和包常量

     這個比較簡單，並且很實用，好比一個包中有不少的內部訪問的類或常量，就能夠統一的放到package-info類中，這樣就方便，並且集中管理，減小friendly類處處遊走的狀況，看例子：

 

@PkgAnnotation
package com.company;
 //這裏是包類，聲明一個包使用的公共類，強調的是包訪問權限
class PkgClass{
    public void test(){
    }
}
//包常量，只運行包內訪問，適用於分「包」開發
class PkgConst{
    static final String PACAKGE_CONST="ABC";
}

 

 

 

  提供包的總體註釋說明

     若是是分「包」開發，也就是說一個包實現一個業務邏輯或功能點、或模塊、或組件，則須要對一個包有很好的說明，說明這個包是幹啥的，有啥做用，版本變遷，特別說明等等，以下：

 

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