Java 注解指導手冊 – 終極向導

jopen 9年前發布 | 38K 次閱讀 Java 注解 Java開發

譯文出處： Toien Liu   原文出處：Dani Buiza

編者的話：注解是java的一個主要特性且每個java開發者都應該知道如何使用它。

我們已經在Java Code Geeks提供了豐富的教程, 如Creating Your Own Java Annotations, Java Annotations Tutorial with Custom Annotation 和 Java Annotations: Explored & Explained.

我們也有些文章是關于注解在不同類庫中的應用，包括 Make your Spring Security @Secured annotations more DRY和 Java Annotations & A Real World Spring Example.

現在，是時候匯總這些和注解相關的信息到一篇文章了，祝大家閱讀愉快。

目錄

  1. 什么是注解

  2. 介紹

  3. 消費器

  4. 注解語法和注解元素

  5. 在什么地方使用

  6. 使用案例

  7. 內建注解

  8. Java 8 與注解

  9. 自定義注解

  10. 提取注解

  11. 注解集成

  12. 使用注解的知名類庫

  13. 小結

  14. 下載

  15. 資料
    16. </ol>

     

    在這篇文章中我們將闡述什么是Java注解，它們如何工作，怎么使用它們。

    我們將揭開Java注解的面紗，包括內建注解或稱元注解，還將討論Java8中與之相關的的新特性。

    最后，我們將實現自定義的注解，編寫一個使用注解的處理程序（消費器），它通過java反射使用注解。

    我們還會列出一些基于注解，知名且被廣泛應用的第三方類庫如：Junit，JAXB，Spring，Hibernate。

    在文章的最后，會有一個壓縮文件包含了文章中的所有示例，實現這些例子使用的軟件版本如下所示：

    • Eclipse Luna 4.4

    • JRE Update 8.20

    • Junit 4

    • Hibernate 4.3.6

    • FindBugs 3.0.0
      • </ul>

      1.什么是注解？

      注解早在J2SE1.5就被引入到Java中，主要提供一種機制，這種機制允許程序員在編寫代碼的同時可以直接編寫元數據。

      在引入注解之前，程序員們描述其代碼的形式尚未標準化，每個人的做法各異：transient關鍵字、注釋、接口等。這顯然不是一種優雅的方式，隨之而來的一種嶄新的記錄元數據的形式——注解被引入到Java中。

      其它因素也促成了這個決定：當時不同類型的應用程序使用XML作為標準的代碼配置機制，這其實并不是最佳方式，因為代碼和XML的解耦以及未來對這種解耦應用的維護并不低廉。另外，由于非保留字的使用，例如“@deprecated”自從Java1.4便開始在Java文檔中使用。我非常確定這是一個現在在注解中使用“@”原因。

      包含注解的設計和開發的Java規范主要有以下兩篇：

      • JSR 175 A metadata facility for the Java programming Language

      • JSR 250 Common Annotations for the Java Platform
        • </ul>

        2. 介紹

        解釋何為注解的最佳方式就是元數據這個詞：描述數據自身的數據。注解就是代碼的元數據，他們包含了代碼自身的信息。

        注解可以被用在包，類，方法，變量，參數上。自Java8起，有一種注解幾乎可以被放在代碼的任何位置，叫做類型注解。我們將會在后面談到具體用法。

        被注解的代碼并不會直接被注解影響。這只會向第三系統提供關于自己的信息以用于不同的需求。

        注解會被編譯至class文件中，而且會在運行時被處理程序提取出來用于業務邏輯。當然，創建在運行時不可用的注解也是可能的，甚至可以創建只在源文件中可用，在編譯時不可用的注解。

        3.消費器

        理解注解的目的以及如何使用它都會帶來困難，因為注解本身并不包含任何功能邏輯，它們也不會影響自己注解的代碼，那么，它們到底為什么而存在呢？

        這個問題的解釋就是我所稱的注解消費器。它們是利用被注解代碼并根據注解信息產生不同行為的系統或者應用程序。

        例如，在Java自帶的內建注解（元注解）中，消費器是執行被注解代碼的JVM。還有其他稍后談到的其他例子，例如JUnit，消費器是讀取，分析被注解代碼的JUnit處理程序，它還可以決定測試單元和方法執行順序。我們會在JUnit章節更深入。

        消費器使用Java中的反射機制來讀取和分析被注解的源代碼。使用的主要的包有：java.lang, java.lang.reflect。我們將會在本篇指南中介紹如何用反射從頭開始創建一個自定義的消費器。

        4. 注解語法和元素

        聲明一個注解需要使用“@”作為前綴，這便向編譯器說明，該元素為注解。例如：

        @Annotation
public void annotatedMehod() {
...
 }

        上述的注解名稱為Annotation，它正在注解annotatedMethod方法。編譯器會處理它。注解可以以鍵值對的形式持有有很多元素，即注解的屬性。

        @Annotation(
 info = "I am an annotation",
 counter = "55"
)
public void annotatedMehod() {
...
 }

        如果注解只包含一個元素（或者只需要指定一個元素的值，其它則使用默認值），可以像這樣聲明：

        @Annotation("I am an annotation")
public void annotatedMehod() {
...
 }

        就像我們看到的一樣，如果沒有元素需要被指定，則不需要括號。多個注解可以使用在同一代碼上，例如類：

        @ Annotation (info = "U a u O")
@ Annotation2
class AnnotatedClass { ... }

        一些java本身提供的開箱即用的注解，我們稱之為內建注解。也可以定義你自己的注解，稱之為子定義注解。我們會在下一章討論。

        5. 在什么地方使用

        注解基本上可以在Java程序的每一個元素上使用：類，域，方法，包，變量，等等。

        自Java8，誕生了通過類型注解的理念。在此之前，注解是限于在前面討論的元素的聲明上使用。從此，無論是類型還是聲明都可以使用注解，就像：

        @MyAnnotation String str = "danibuiza";

        我們將會在Java8關聯章節看到這種機制的更多細節。

        6. 使用案例

        注解可以滿足許多要求，最普遍的是：

        • 向編譯器提供信息：注解可以被編譯器用來根據不同的規則產生警告，甚至錯誤。一個例子是Java8中@FunctionalInterface注解，這個注解使得編譯器校驗被注解的類，檢查它是否是一個正確的函數式接口。

        • 文檔：注解可以被軟件應用程序計算代碼的質量例如：FindBugs，PMD或者自動生成報告，例如：用來Jenkins, Jira，Teamcity。

        • 代碼生成：注解可以使用代碼中展現的元數據信息來自動生成代碼或者XML文件，一個不錯的例子是JAXB。

        • 運行時處理：在運行時檢查的注解可以用做不同的目的，像單元測試（JUnit），依賴注入（Spring），校驗，日志（Log4j），數據訪問（Hibernate）等等。
          • </ul>

          在這篇手冊中我們將展現幾種注解可能的用法，包括流行的Java類庫是如何使用它們的。

          7. 內建注解

          Java語言自帶了一系列的注解。在本章中我們將闡述最重要的一部分。這個清單只涉及了Java語言最核心的包，未包含標準JRE中所有包和庫如JAXB或Servlet規范。

          以下討論到的注解中有一些被稱之為Meta注解，它們的目的注解其他注解，并且包含關于其它注解的信息。

            <li>@Retention：這個注解注在其他注解上，并用來說明如何存儲已被標記的注解。這是一種元注解，用來標記注解并提供注解的信息。可能的值是：

            • SOURCE：表明這個注解會被編譯器忽略，并只會保留在源代碼中。

            • CLASS:表明這個注解會通過編譯駐留在CLASS文件，但會被JVM在運行時忽略,正因為如此,其在運行時不可見。

            • RUNTIME：表示這個注解會被JVM獲取，并在運行時通過反射獲取。
              • </ul> </li> </ul>

              我們會在稍后展開幾個例子。

                <li>@Target：這個注解用于限制某個元素可以被注解的類型。例如：

                • ANNOTATION_TYPE 表示該注解可以應用到其他注解上

                • CONSTRUCTOR 表示可以使用到構造器上

                • FIELD 表示可以使用到域或屬性上

                • LOCAL_VARIABLE表示可以使用到局部變量上。

                • METHOD可以使用到方法級別的注解上。

                • PACKAGE可以使用到包聲明上。

                • PARAMETER可以使用到方法的參數上

                • TYPE可以使用到一個類的任何元素上。
                  • </ul> </li> <li>@Documented：被注解的元素將會作為Javadoc產生的文檔中的內容。注解都默認不會成為成為文檔中的內容。這個注解可以對其它注解使用。</li> <li>@Inherited：在默認情況下，注解不會被子類繼承。被此注解標記的注解會被所有子類繼承。這個注解可以對類使用。</li> <li>@Deprecated：說明被標記的元素不應該再度使用。這個注解會讓編譯器產生警告消息。可以使用到方法，類和域上。相應的解釋和原因，包括另一個可取代的方法應該同時和這個注解使用。</li> <li>@SuppressWarnings：說明編譯器不會針對指定的一個或多個原因產生警告。例如：如果我們不想因為存在尚未使用的私有方法而得到警告可以這樣做：</li> </ul>

                  @SuppressWarnings( "unused")
private String myNotUsedMethod(){
 ...
}

                  通常,編譯器會因為沒調用該方而產生警告; 用了注解抑制了這種行為。該注解需要一個或多個參數來指定抑制的警告類型。

                  • @Override：向編譯器說明被注解元素是重寫的父類的一個元素。在重寫父類元素的時候此注解并非強制性的，不過可以在重寫錯誤時幫助編譯器產生錯誤以提醒我們。比如子類方法的參數和父類不匹配，或返回值類型不同。
                  • @SafeVarargs：斷言方法或者構造器的代碼不會對參數進行不安全的操作。在Java的后續版本中，使用這個注解時將會令編譯器產生一個錯誤在編譯期間防止潛在的不安全操作。

                  更多信息請參考：http://docs.oracle.com/javase/7/docs/api/java/lang/SafeVarargs.html

                  8. Java 8 與注解

                  Java8帶來了一些優勢，同樣注解框架的能力也得到了提升。在本章我們將會闡述，并就java8帶來的3個注解做專題說明和舉例：

                  <p>@Repeatable注解，關于類型注解的聲明，函數式接口注解@FunctionalInterface（與Lambdas結合使用）。</p>

                  • @Repeatable：說明該注解標識的注解可以多次使用到同一個元素的聲明上。

                  看一個使用的例子。首先我們創造一個能容納重復的注解的容器：

                  /**
                  

                    

                  • Container for the {@link CanBeRepeated} Annotation containing a list of values
*/
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE_USE )
public @interface RepeatedValues
{
CanBeRepeated[] value();
}</pre> 
                    接著，創建注解本身，然后標記@Repeatable
                    

                    @Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE_USE )
@Repeatable( RepeatedValues.class )
public @interface CanBeRepeated
{
                    

                    String value();
}</pre> 
                    最后，我們可以這樣重復地使用：
                    

                    @CanBeRepeated( "the color is green" )
@CanBeRepeated( "the color is red" )
@CanBeRepeated( "the color is blue" )
public class RepeatableAnnotated
{
                    

                    • 

                  

                  }</pre> 
                  如果我們嘗試去掉@Repeatable
                  

                  @Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE_USE )
public @interface CannotBeRepeated
{
                  

                  String value();
}
                  

                  @CannotBeRepeated( "info" )
/*
                  

                    

                  • if we try repeat the annotation we will get an error: Duplicate annotation of non-repeatable type
*
                    • 

                  • @CannotBeRepeated. Only annotation types marked
*
                    • 

                  • @Repeatable can be used multiple times at one target.
*/
// @CannotBeRepeated( "more info" )
public class RepeatableAnnotatedWrong
{
                    • 

                  

                  }</pre> 
                  我們會得到編譯器的錯誤信息：
                  

                  Duplicate annotation of non-repeatable type
                   
                    

                  • 自Java8開始，我們可以在類型上使用注解。由于我們在任何地方都可以使用類型，包括 new操作符，casting，implements，throw等等。注解可以改善對Java代碼的分析并且保證更加健壯的類型檢查。這個例子說明了這一點：
                    • 
</ul>
                    

                    @SuppressWarnings( "unused" )
public static void main( String[] args )
{
 // type def
 @TypeAnnotated
 String cannotBeEmpty = null;
                    

                    // type
 List<@TypeAnnotated String> myList = new ArrayList<String>();
                    

                    // values
 String myString = new @TypeAnnotated String( "this is annotated in java 8" );
                    

                    }
                    

                    // in method params
public void methodAnnotated( @TypeAnnotated int parameter )
{
 System.out.println( "do nothing" );
}</pre> 
                    所有的這些在Java8之前都是不可能的。
                    

                      

                    • @FunctionalInterface：這個注解表示一個函數式接口元素。函數式接口是一種只有一個抽象方法（非默認）的接口。編譯器會檢查被注解元素，如果不符，就會產生錯誤。例子如下：
                      • 

                    

                    // implementing its methods
@SuppressWarnings( "unused" )
MyCustomInterface myFuncInterface = new MyCustomInterface()
{
                    

                    @Override
 public int doSomething( int param )
 {
 return param * 10;
 }
};
                    

                    // using lambdas
@SuppressWarnings( "unused" )
 MyCustomInterface myFuncInterfaceLambdas = ( x ) -> ( x * 10 );
}
                    

                    @FunctionalInterface
interface MyCustomInterface
{
/*
                    

                      

                    • more abstract methods will cause the interface not to be a valid functional interface and
                      • 

                    • the compiler will thrown an error:Invalid '@FunctionalInterface' annotation;
                      • 

                    • FunctionalInterfaceAnnotation.MyCustomInterface is not a functional interface
*/
// boolean isFunctionalInterface();
                      

                      int doSomething( int param );
}</pre> 
                      這個注解可以被使用到類，接口，枚舉和注解本身。它的被JVM保留并在runtime可見，這個是它的聲明：
                      

                       @Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface FunctionalInterface
                       
                      9. 自定義注解
                      

                      正如我們之前多次提及的，可以定義和實現自定義注解。本章我們即將探討。
                      
首先，定義一個注解：
                      

                      public @interface CustomAnnotationClass
                       
                      這樣創建了一個新的注解類型名為 CustomAnnotationClass。關鍵字：@interface說明這是一個自定義注解的定義。
                      

                      之后，你需要為此注解定義一對強制性的屬性，保留策略和目標。還有一些其他屬性可以定義，不過這兩個是最基本和重要的。它們在第8章，描述注解的注解時討論過，它們同樣也是Java內建的注解。
                      

                      所以，我們為自定義的注解設置屬性：
                      

                      @Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE )
public @interface CustomAnnotationClass implements CustomAnnotationMethod
                       
                      在保留策略中 RUNTIME 告訴編譯器這個注解應該被被JVM保留，并且能通過反射在運行時分析。通過 TYPE 我們又設置該注解可以被使用到任何類的元素上。
                      

                      之后，我們定義兩個注解的成員：
                      

                      @Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE )
public @interface CustomAnnotationClass
{
                      

                      public String author() default "danibuiza";
                      

                      public String date();
                      

                      • 

                    

                    }</pre> 
                    以上我們僅定義了默認值為“danibuiza”的 author 屬性和沒有默認值的date屬性。我們應強調所有的方法聲明都不能有參數和throw子句。這個返回值的類型被限制為之前提過的字符串，類，枚舉，注解和存儲這些類型的數組。
                    

                    現在我們可以像這樣使用剛創建的自定義注解：
                    

                    @CustomAnnotationClass( date = "2014-05-05" )
public class AnnotatedClass
{
...
}
                     
                    在另一種類似的用法中我們可以創建一種注解方法的注解，使用Target METHOD：
                    

                    @Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.METHOD )
public @interface CustomAnnotationMethod
{
                    

                    public String author() default "danibuiza";
                    

                    public String date();
                    

                    public String description();
                    

                    }</pre> 
                    這種注解可以使用在方法聲明上：
                    

                    @CustomAnnotationMethod( date = "2014-06-05", description = "annotated method" )
public String annotatedMethod()
 {
 return "nothing niente";
}
                    

                    @CustomAnnotationMethod( author = "friend of mine", date = "2014-06-05", description = "annotated method" )
public String annotatedMethodFromAFriend()
{
 return "nothing niente";
}</pre> 
                    有很多其它屬性可以用在自定義注解上，但是 目標 （Target）和 保留策略（Retention Policy）是最重要的兩個。
                    

                    10. 獲取注解
                    

                    Java反射API包含了許多方法來在運行時從類，方法或者其它元素獲取注解。接口AnnotatedElement包含了大部分重要的方法，如下：
                    

                      

                    • getAnnotations(): 返回該元素的所有注解，包括沒有顯式定義該元素上的注解。
                      • 

                    • isAnnotationPresent(annotation): 檢查傳入的注解是否存在于當前元素。
                      • 

                    • getAnnotation(class): 按照傳入的參數獲取指定類型的注解。返回null說明當前元素不帶有此注解。
                      • 
</ul>
                      

                      class 通過java.lang.Class被實現，java.lang.reflect.Method 和 java.lang.reflect.Field，所以可以基本上被和任何Java元素使用。
                      

                      現在，我們將看一個怎么讀取注解的例子：
                      
我們寫一個程序，從一個類和它的方法中讀取所有的存在的注解：
                      

                      public static void main( String[] args ) throws Exception
{
                      

                      Class<AnnotatedClass> object = AnnotatedClass.class;
 // Retrieve all annotations from the class
 Annotation[] annotations = object.getAnnotations();
 for( Annotation annotation : annotations )
 {
 System.out.println( annotation );
 }
                      

                      // Checks if an annotation is present
 if( object.isAnnotationPresent( CustomAnnotationClass.class ) )
 {
                      

                      // Gets the desired annotation
 Annotation annotation = object.getAnnotation( CustomAnnotationClass.class );
                      

                      System.out.println( annotation );
                      

                      }
 // the same for all methods of the class
 for( Method method : object.getDeclaredMethods() )
 {
                      

                      if( method.isAnnotationPresent( CustomAnnotationMethod.class ) )
 {
                      

                      Annotation annotation = method.getAnnotation( CustomAnnotationMethod.class );
                      

                      System.out.println( annotation );
                      

                      }
                      

                      }
}</pre> 
                      輸出如下：
                      

                      @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
                      

                      @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
                      

                      @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=friend of mine, date=2014-06-05, description=annotated method)
@com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=danibuiza, date=2014-06-05, description=annotated method)</pre> 
                      在這個程序中，我們可以看到 getAnnotations()方法來獲取所有某個對象（方法，類）上的所有注解的用法。展示了怎樣使用isAnnotationPresent()方法和getAnnotation()方法檢查是否存在特定的注解，和如何獲取它。
                      

                      11. 注解中的繼承
                      

                      注解在Java中可以使用繼承。這種繼承和普通的面向對象繼承幾乎沒有共同點。
                      

                      如果一個注解在Java中被標識成繼承，使用了保留注解@Inherited，說明它注解的這個類將自動地把這個注解傳遞到所有子類中而不用在子類中聲明。通常，一個類繼承了父類，并不繼承父類的注解。這完全和使用注解的目的一致的：提供關于被注解的代碼的信息而不修改它們的行為。
                      

                      我們通過一個例子更清楚地說明。首先，我們定義一個自動繼承的自定義注解。
                      

                      @Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface InheritedAnnotation
{
                      

                      }</pre> 
                      有一個父類名為：AnnotatedSuperClass，已經被自定義的注解給注解上了：
                      

                      @InheritedAnnotation
public class AnnotatedSuperClass
{
                      

                      public void oneMethod()
 {
                      

                      }
                      

                      }</pre> 
                      一個子類繼承父類：
                      

                      @InheritedAnnotation
public class AnnotatedSuperClass
{
                      

                      public void oneMethod()
 {
                      

                      }
                      

                      }</pre> 
                      子類 AnnotatedSubClass 展示了自動繼承的注解 @InheritedAnnotation。我們看到下面的代碼通過 isAnnotationPresent() 方法測試出了當前注解。
                      

                      <pre>System.out.println( "is true: " + AnnotatedSuperClass.class.isAnnotationPresent( InheritedAnnotation.class ) );
                      

                      System.out.println( "is true: " + AnnotatedSubClass.class.isAnnotationPresent( InheritedAnnotation.class ) );</pre>
<pre></pre> 
                      輸出如下：
                      

                      is true: true
is true: true
                       
                      我們可以看到子類雖然并沒有聲明注解，但還是被自動地注解上了。
                      

                      如果我們嘗試注解在一個接口中：
                      

                      @InheritedAnnotation
public interface AnnotatedInterface
{
                      

                      public void oneMethod();
                      

                      }</pre> 
                      一個實現了該接口的類：
                      

                      public class AnnotatedImplementedClass implements AnnotatedInterface
{
                      

                      @Override
 public void oneMethod()
 {
                      

                      }
                      

                      }</pre> 
                      經過 isAnnotationPresent() 方法測試：
                      

                      System.out.println( "is true: " + AnnotatedInterface.class.isAnnotationPresent( InheritedAnnotation.class ) );
                      

                      System.out.println( "is true: " + AnnotatedImplementedClass.class.isAnnotationPresent( InheritedAnnotation.class ) );</pre> 
                      結果如下：
                      

                      is true: true
is true: false
                       
                      這個結果說明繼承注解和接口在一起使用時，接口中的注解在實現類中：僅僅被忽略。實現類并不繼承接口的注解；接口繼承僅僅適用于類繼承。正如 AnnotatedSubClass。
                      
@Inheriated注解僅在存在繼承關系的類上產生效果，在接口和實現類上并不工作。這條同樣也適用在方法，變量，包等等。只有類才和這個注解連用。
                      

                      一條關于@Inheriated注解的很好的解釋在Javadoc中：http://docs.oracle.com/javase/7/docs/api/java/lang/annotation/Inherited.html.
                      

                      注解不能繼承注解，如果你嘗試這么做了，就會得到編譯器拋出的錯誤：
                      

                      Annotation type declaration cannot have explicit superinterfaces
                       
                      12. 使用注解的知名類庫
                      

                      在這一章我們將展示知名類庫是如何利用注解的。一些類庫如：JAXB, Spring Framework, Findbugs, Log4j, Hibernate, Junit。它們使用注解來完成代碼質量分析，單元測試，XML解析，依賴注入和許多其它的工作。
                      

                      在這篇手冊中我們將討論以下類庫的部分內容：
                      

                      12.1. Junit
                      

                      這個框架用于完成Java中的單元測試。自JUnit4開始，注解被廣泛應用，成為Junit的設計的主干之一。
                      

                      基本上，JUnit處理程序通過反射讀取類和測試套件，按照在方法上，類上的注解順序地執行它們。當然還有一些用來修改測試執行的注解。其它注解都用來執行測試，阻止執行，改變執行順序等等。
                      

                      用到的注解相當多，但是我們將會看到最重要的幾個：
                      

                        

                      • @Test：這個注解向JUnit說明這個被注解的方法一定是一個可執行的測試方法。這個注解只能標識在方法上，并且被JVM保留至運行時。
                        @Test
public void testMe()
{
 //test assertions
 assertEquals(1,1);
}
                         
                        從這個例子可以看到我們如何在JUnit中使用這類注解。
                        

                        • 

                      • @Before：這個注解用來向JUnit說明被標記的方法應該在所有測試方法之前被執行。這對于在測試之前設置測試環境和初始化非常有用。同樣只適用于方法上：
                        @Before
public void setUp()
 {
 // initializing variables
 count = 0;
 init();
}
                        • 

                      • @After：這個注解用來向JUnit說明被注解的方法應該在所有單元測試之后執行。這個注解通常用來銷毀資源，關閉，釋放資源或者清理，重置等工作。
                        @After
public void destroy()
{
 // closing input stream
 stream.close();
}
                        • 

                      • @Ignore：這個方法用來向JUnit說明被注解的方法應該不被當作測試單元執行。即使它被注解成為一個測試方法，也只能被忽略。
                        @Ignore
@Test
public void donotTestMe()
{
 count = -22;
 System.out.println( "donotTestMe(): " + count );
}
                         
                        這個方法可能在在開發調試階段使用，但一旦開始進入發布階段變需要將被忽略的代碼去掉。
                        

                        • 

                      • @FixMethodOrder：指定執行的順序，正常情況下Junit處理程序負責它按照完全隨機的無法預知的順序執行。當所有的測試方法都相互獨立的時候，不推薦使用這個注解。但是，當測試的場景需要測試方法按照一定規則的時候，這個注解就派上用場了。
                        @FixMethodOrder( MethodSorters.NAME_ASCENDING )
public class JunitAnnotated
                        還有一些測試套件和類庫使用了注解，例如Mockito和JMock，使用注解來創建測試對象和預期值。
查看JUnit中所有注解請參考：https://github.com/junit-team/junit/wiki/Getting-started
                        • 

                      

                      12.2. Hibernate ORM
                      

                      Hibernate可能是一個用得最廣泛的對象關系映射類庫。它提供了對象模型和關系型數據庫的映射框架。使用注解作為設計的一部分。
                      

                      在本章我們將討論一兩個由Hibernate提供的注解并解釋它的處理程序如何處理它們。
                      

                      下面的代碼段使用了@Entity和@Table。這兩個是用來向消費器（Hibernate處理程序）說明被注解的類是一個實體類，以及它映射的SQL表名。實際上，這個注解僅僅是指明了主表，還可以有說明字表的注解。
                      

                      @Entity
@Table( name = "hibernate_annotated" )
public class HibernateAnnotated
                       
                      接下來的代碼段展示了如何向Hibernate處理程序說明被標記的元素是表的主鍵，并映射名為“id”的列，并且主鍵是自動生成的。
                      

                      @Id
@GeneratedValue
@Column( name = "id" )
private int id;
                       
                      為了指定標準的SQL表列名，我們可以寫如下注解：
                      

                      @Column( name = "description" )
private String description;
                       
                      這說明被標記的元素映射的是這個類所對應的表中名為“description”的一列。
                      

                      這些注解都來自 http://docs.oracle.com/javaee/6/api/javax/persistence/package-summary.html 企業級Java的包。它們幾乎涵蓋了所有 Hibernate 所有可用的注解。
                      

                      12.3. Spring MVC
                      

                      Spring是個被廣泛使用的Java企業級應用框架。其一項重要的特性就是在Java程序使用依賴注入。
                      

                      Spring使用注解作為XML（Spring的早期版本使用的基于XML配置）的一種替代方式。現在兩者都是可行的。你可以使用XML文件或者注解配置你的項目。在我看來兩者都各有優勢。
                      

                      我們將在下例中展示兩個可用注解：
                      

                      @Component
public class DependencyInjectionAnnotation
{
                      

                      private String description;
                      

                      public String getDescription()
 {
 return description;
 }
                      

                      @Autowired
 public void setDescription( String description )
 {
 this.description = description;
 }
                      

                      }</pre> 
                      在次代碼片段中我們可以找到兩個使用在了類和方法上的注解。
                      

                        

                      • @Component：說明被標記的元素，在本例中是一個類，是一個自動檢測的目標。這意味著被注解的類，將會被Spring容器實例化并管理。
                        • 

                      • @Autowired：Spring容器將會嘗試通過類型（這是一種元素匹配機制）使用這個set方法來自動裝配。此注解也可以使用在構造器和屬性上，Spring也會根據注解的地方不同采取不同的操作。
                        • 

                      

                      更多關于依賴注入和Spring框架的細節請參考：http://projects.spring.io/spring-framework/.
                      

                      12.4. Findbugs
                      

                      這是一個用來測量代碼質量，并提供一系列可能提高它的工具。它會根據預定義（或者自定義）的違反規則來檢查代碼。Findbugs提供一系列注解來允許開發者來改變默認行為。
                      

                      它主要使用反射讀取代碼（和包含的注解）并決定基于它們，應該采取什么行為。
                      

                      一個列子是 edu.umd.cs.findbugs.annotations.SuppressFBWarnings 注解期待一種違反規定的鍵值并把它當作參數。這非常像 java.lang.SuppressWarnings。被用來向 Findbugs 說明當執行代碼分析的時候，忽略指定的違反規則。
                      

                      這是一個例子：
                      

                      @SuppressFBWarnings( "HE_EQUALS_USE_HASHCODE" )
public class FindBugsAnnotated
{
                      

                      @Override
 public boolean equals( Object arg0 )
 {
 return super.equals( arg0 );
 }
                      

                      }</pre> 
                      這個類已經重現了 Object 的 equals 方法，但是并沒有重寫 hashCode 方法。這通常會導致問題，因為 hashCode 和 equals 兩者應該被同時重寫，否則在使用這個對象作為 HashMap 的key值的時候會導致錯誤。所以，Findbugs會在違反規則報告中創造一個錯誤條目。
                      

                      如果注解 @SuppressFBWarnings 設置了 HE_EQUALS_USE_HASHCODE 值以后，處理程序就不會在拋出這類型的錯誤了。
                      

                      Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and uses Object.hashCode()
Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and uses Object.hashCode()
                       
                      這個類重寫了 equals 方法，但是沒有重寫 hashCode 方法，繼承自 java.lang.Object 的 hashCode 方法（返回每個對象被JVM賦予的特定值）。因此，這個類幾乎違反了相同的對象必須 hashcode 相同的一致性。
                      

                      如果你認為這個類的實例不會插入到哈希表，推薦的做法是像這樣實現 hashCode 方法：
                      

                      public int hashCode() {
 assert false : "hashCode not designed";
 return 42; // any arbitrary constant will do
 }
                      Rank: Troubling (14), confidence: High
Pattern: HE_EQUALS_USE_HASHCODE
Type: HE, Category: BAD_PRACTICE (Bad practice)
                       
                      這個錯誤包含了該問題的一種解釋并且提示如何處理它。在這種情況下，解決方案應該是實現 hashCode 方法。
                      

                      想知道FindBugs在 SuppressFBWarnings 注解所有可用的違反規則設置，請參考：http://findbugs.sourceforge.net/bugDescriptions.html.
                      

                      12.5. JAXB
                      

                      JAXB是一個用來相互轉換和映射XML文件與Java對象的類庫。實際上，這個類庫與標準JRE一起提供，不需要任何額外的下載和配置。可以直接通過引入 java.xml.bind.annotation 包下的類直接使用。
                      

                      JAXB使用注解來告知處理程序（或者是JVM）XML文件與代碼的相互轉化。例如，注解可以用來在代碼上標記XML節點，XMl屬性，值等等。我們將看到一個例子：
                      

                      首先，我們聲明一個類說明它應該是XML文件中的一個節點：
                      

                      import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
@XmlType( propOrder = { "brand", "model", "year", "km" } )
@XmlRootElement( name = "Car" )
class Car
...
                       
                      使用注解@XmlType，@XmlRoootElement。它們用來告知 JAXB 處理程序 Car 這個類在轉換后，將會轉換成為XML中的一個節點。這個@XmlType說明了屬性在XML中的順序。JAXB將會基于這些注解執行合適的操作。
                      

                      除了分離的 getter 和 setter 屬性，再也不需要向這個類中添加其它東西來完成轉換。現在我們需要一個消費器程序來執行轉換成XML：
                      

                      Car car = new Car();
car.setBrand( "Mercedes" );
car.setModel( "SLK" );
car.setYear( 2011 );
car.setKm( 15000 );
                      

                      Car carVW = new Car();
carVW.setBrand( "VW" );
carVW.setModel( "Touran" );
carVW.setYear( 2005 );
carVW.setKm( 150000 );
                      

                      / init jaxb marshaler /
JAXBContext jaxbContext = JAXBContext.newInstance( Car.class );
Marshaller jaxbMarshaller = jaxbContext.createMarshaller();
                      

                      / set this flag to true to format the output /
jaxbMarshaller.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, true );
                      

                      / marshaling of java objects in xml (output to standard output) /
jaxbMarshaller.marshal( car, System.out );
jaxbMarshaller.marshal( carVW, System.out );</pre> 
                      程序產生的輸入如下：
                      

                      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Car>
 <brand>Mercedes</brand>
 <model>SLK</model>
 <year>2011</year>
 <km>15000</km>
</Car>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Car>
 <brand>VW</brand>
 <model>Touran</model>
 <year>2005</year>
 <km>150000</km>
</Car>
                       
                      更多關于JAXB XML和Java 的轉換信息請參考：https://jaxb.java.net/
                      

                      13. 總結
                      

                      在這篇文檔中，我們解釋了Java注解是Java1.5開始一個非常重要的特性。基本上，注解都是作為包含代碼信息的元數據而被標記到代碼中。它們不會改變或者影響代碼的任何意義，而是被第三方稱為消費器的程序通過反射的方式使用。
                      

                      我們列出了Java默認的內建注解，一些稱為元注解例如：@Target或者 @Retention，又有@Override，@SuppressWarnings，還有一些Java8相關的注解，比如：@Repeatable，@FunctionalInterface和類型注解。我們還展現了一兩個結合使用反射的例子，并描述了一些使用注解的類庫例如Spring， Junit，Hibernate。
                      

                      注解是Java中一種分析元數據的強大機制，可以在不同的程序中擔任不同的作用，例如校驗，依賴注入，單元測試。
                      

                      14. 下載
                      

                      這是一個java注解的教程。
                      

                      你可以從這里下載本教程所有代碼: customAnnotations
                      

                      15. 資料
                      

                      這是一些非常有用的關于Java注解的資料：
                      

                      官方Java注解地址：http://docs.oracle.com/javase/tutorial/java/annotations/
                      
維基百科中關于Java注解的解釋：http://en.wikipedia.org/wiki/Java_annotation
                      
Java規范請求250：http://en.wikipedia.org/wiki/JSR_250
                      
Oracle 注解白皮書：http://www.oracle.com/technetwork/articles/hunter-meta-096020.html
                      
注解API：http://docs.oracle.com/javase/7/docs/api/java/lang/annotation/package-summary.html
 本文由用戶 jopen 自行上傳分享，僅供網友學習交流。所有權歸原作者，若您的權利被侵害，請聯系管理員。
 轉載本站原創文章，請注明出處，并保留原始鏈接、圖片水印。
 本站是一個以用戶分享為主的開源技術平臺，歡迎各類分享！