java註釋指導手冊

時間 2019-11-12

標籤 java 註釋指導手冊欄目 Java 简体版

原文原文鏈接

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

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

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

咱們也有些文章是關於註解在不一樣類庫中的應用，包括 Make your Spring Security @Secured annotations more DRY和 Java Annotations & A Real World Spring Example.程序員

如今，是時候彙總這些和註解相關的信息到一篇文章了，祝你們閱讀愉快。spring

在這篇文章中咱們將闡述什麼是Java註解，它們如何工做，怎麼使用它們。數據庫

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

最後，咱們將實現自定義的註解，編寫一個使用註解的處理程序（消費器），它經過java反射使用註解。數組

咱們還會列出一些基於註解，知名且被普遍應用的第三方類庫如：Junit，JAXB，Spring，Hibernate。安全

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

Eclipse Luna 4.4
JRE Update 8.20
Junit 4
Hibernate 4.3.6
FindBugs 3.0.0

1.什麼是註解？

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

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

其它因素也促成了這個決定：當時不一樣類型的應用程序使用XML做爲標準的代碼配置機制，這其實並非最佳方式，由於代碼和XML的解耦以及將來對這種解耦應用的維護並不低廉。另外，因爲非保留字的使用，例如「@deprecated」自從Java1.4便開始在Java文檔中使用。我很是肯定這是一個如今在註解中使用「@」緣由。

包含註解的設計和開發的Java規範主要有如下兩篇：

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）等等。

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

7. 內建註解

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

如下討論到的註解中有一些被稱之爲Meta註解，它們的目的註解其餘註解，而且包含關於其它註解的信息。

@Retention：這個註解注在其餘註解上，並用來講明如何存儲已被標記的註解。這是一種元註解，用來標記註解並提供註解的信息。可能的值是：
- SOURCE：代表這個註解會被編譯器忽略，並只會保留在源代碼中。
- CLASS:代表這個註解會經過編譯駐留在CLASS文件，但會被JVM在運行時忽略,正由於如此,其在運行時不可見。
- RUNTIME：表示這個註解會被JVM獲取，並在運行時經過反射獲取。

咱們會在稍後展開幾個例子。

@Target：這個註解用於限制某個元素能夠被註解的類型。例如：@Documented：被註解的元素將會做爲Javadoc產生的文檔中的內容。註解都默認不會成爲成爲文檔中的內容。這個註解能夠對其它註解使用。
- ANNOTATION_TYPE 表示該註解能夠應用到其餘註解上
- CONSTRUCTOR 表示可使用到構造器上
- FIELD 表示可使用到域或屬性上
- LOCAL_VARIABLE表示可使用到局部變量上。
- METHOD可使用到方法級別的註解上。
- PACKAGE可使用到包聲明上。
- PARAMETER可使用到方法的參數上
- TYPE可使用到一個類的任何元素上。
@Inherited：在默認狀況下，註解不會被子類繼承。被此註解標記的註解會被全部子類繼承。這個註解能夠對類使用。
@Deprecated：說明被標記的元素不該該再度使用。這個註解會讓編譯器產生警告消息。可使用到方法，類和域上。相應的解釋和緣由，包括另外一個可取代的方法應該同時和這個註解使用。
@SuppressWarnings：說明編譯器不會針對指定的一個或多個緣由產生警告。例如：若是咱們不想由於存在還沒有使用的私有方法而獲得警告能夠這樣作：

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

一般,編譯器會由於沒調用該方而產生警告; 用了註解抑制了這種行爲。該註解須要一個或多個參數來指定抑制的警告類型。

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

8. Java 8 與註解

Java8帶來了一些優點，一樣註解框架的能力也獲得了提高。在本章咱們將會闡述，並就java8帶來的3個註解作專題說明和舉例：

@Repeatable註解，關於類型註解的聲明，函數式接口註解@FunctionalInterface（與Lambdas結合使用）。

@Repeatable：說明該註解標識的註解能夠屢次使用到同一個元素的聲明上。

看一個使用的例子。首先咱們創造一個能容納重複的註解的容器：

/** * Container for the {@link CanBeRepeated} Annotation containing a list of values */ @Retention( RetentionPolicy.RUNTIME ) @Target( ElementType.TYPE_USE ) public @interface RepeatedValues { CanBeRepeated[] value(); }

接着，建立註解自己，而後標記@Repeatable

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

最後，咱們能夠這樣重複地使用：

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

若是咱們嘗試去掉@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 { }

咱們會獲得編譯器的錯誤信息：

Duplicate annotation of non-repeatable type

自Java8開始，咱們能夠在類型上使用註解。因爲咱們在任何地方均可以使用類型，包括 new操做符，casting，implements，throw等等。註解能夠改善對Java代碼的分析而且保證更加健壯的類型檢查。這個例子說明了這一點：

@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" ); }

全部的這些在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 ); }

這個註解能夠被使用到類，接口，枚舉和註解自己。它的被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 CustomAnnotationMetho

在保留策略中 RUNTIME 告訴編譯器這個註解應該被被JVM保留，而且能經過反射在運行時分析。經過 TYPE 咱們又設置該註解能夠被使用到任何類的元素上。

以後，咱們定義兩個註解的成員：

@Retention( RetentionPolicy.RUNTIME ) @Target( ElementType.TYPE ) public @interface CustomAnnotationClass { public String author() default "danibuiza"; public String date(); }

以上咱們僅定義了默認值爲「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(); }

這種註解可使用在方法聲明上：

@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"; }

有不少其它屬性能夠用在自定義註解上，可是目標（Target）和保留策略（Retention Policy）是最重要的兩個。

10. 獲取註解

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

getAnnotations(): 返回該元素的全部註解，包括沒有顯式定義該元素上的註解。
isAnnotationPresent(annotation): 檢查傳入的註解是否存在於當前元素。
getAnnotation(class): 按照傳入的參數獲取指定類型的註解。返回null說明當前元素不帶有此註解。

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 ); } } }

輸出以下：

@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)

在這個程序中，咱們能夠看到 getAnnotations()方法來獲取全部某個對象（方法，類）上的全部註解的用法。展現了怎樣使用isAnnotationPresent()方法和getAnnotation()方法檢查是否存在特定的註解，和如何獲取它。

11. 註解中的繼承

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

若是一個註解在Java中被標識成繼承，使用了保留註解@Inherited，說明它註解的這個類將自動地把這個註解傳遞到全部子類中而不用在子類中聲明。一般，一個類繼承了父類，並不繼承父類的註解。這徹底和使用註解的目的一致的：提供關於被註解的代碼的信息而不修改它們的行爲。

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

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

有一個父類名爲：AnnotatedSuperClass，已經被自定義的註解給註解上了：

@InheritedAnnotation public class AnnotatedSuperClass { public void oneMethod() { } }

一個子類繼承父類：

@InheritedAnnotation public class AnnotatedSuperClass { public void oneMethod() { } }

子類 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>

輸出以下：

is true: true is true: true

咱們能夠看到子類雖然並無聲明註解，但仍是被自動地註解上了。

若是咱們嘗試註解在一個接口中：

@InheritedAnnotation public interface AnnotatedInterface { public void oneMethod(); }

一個實現了該接口的類：

public class AnnotatedImplementedClass implements AnnotatedInterface { @Override public void oneMethod() { } }

通過 isAnnotationPresent() 方法測試：

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

結果以下：

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處理程序負責它按照徹底隨機的沒法預知的順序執行。當全部的測試方法都相互獨立的時候，不推薦使用這個註解。可是，當測試的場景須要測試方法按照必定規則的時候，這個註解就派上用場了。

還有一些測試套件和類庫使用了註解，例如Mockito和JMock，使用註解來建立測試對象和預期值。

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; } }

在次代碼片斷中咱們能夠找到兩個使用在了類和方法上的註解。

@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 ); } }

這個類已經重現了 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 );

程序產生的輸入以下：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 02 <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中一種分析元數據的強大機制，能夠在不一樣的程序中擔任不一樣的做用，例如校驗，依賴注入，單元測試。