java指导手册,Java 注解指导手册 – 终极向导
編者的話：注解是java的一個(gè)主要特性且每個(gè)java開發(fā)者都應(yīng)該知道如何使用它。
現(xiàn)在，是時(shí)候匯總這些和注解相關(guān)的信息到一篇文章了，祝大家閱讀愉快。
目錄
什么是注解
介紹
消費(fèi)器
注解語法和注解元素
在什么地方使用
使用案例
內(nèi)建注解
Java 8 與注解
自定義注解
提取注解
注解集成
使用注解的知名類庫
小結(jié)
下載
資料
在這篇文章中我們將闡述什么是Java注解，它們?nèi)绾喂ぷ?#xff0c;怎么使用它們。
我們將揭開Java注解的面紗，包括內(nèi)建注解或稱元注解，還將討論Java8中與之相關(guān)的的新特性。
最后，我們將實(shí)現(xiàn)自定義的注解，編寫一個(gè)使用注解的處理程序(消費(fèi)器)，它通過java反射使用注解。
我們還會(huì)列出一些基于注解，知名且被廣泛應(yīng)用的第三方類庫如：Junit，JAXB，Spring，Hibernate。
在文章的最后，會(huì)有一個(gè)壓縮文件包含了文章中的所有示例，實(shí)現(xiàn)這些例子使用的軟件版本如下所示：
Eclipse Luna 4.4
JRE Update 8.20
Junit 4
Hibernate 4.3.6
FindBugs 3.0.0
1.什么是注解？
注解早在J2SE1.5就被引入到Java中，主要提供一種機(jī)制，這種機(jī)制允許程序員在編寫代碼的同時(shí)可以直接編寫元數(shù)據(jù)。
在引入注解之前，程序員們描述其代碼的形式尚未標(biāo)準(zhǔn)化，每個(gè)人的做法各異：transient關(guān)鍵字、注釋、接口等。這顯然不是一種優(yōu)雅的方式，隨之而來的一種嶄新的記錄元數(shù)據(jù)的形式——注解被引入到Java中。
其它因素也促成了這個(gè)決定：當(dāng)時(shí)不同類型的應(yīng)用程序使用XML作為標(biāo)準(zhǔn)的代碼配置機(jī)制，這其實(shí)并不是最佳方式，因?yàn)榇a和XML的解耦以及未來對(duì)這種解耦應(yīng)用的維護(hù)并不低廉。另外，由于非保留字的使用，例如“@deprecated”自從Java1.4便開始在Java文檔中使用。我非常確定這是一個(gè)現(xiàn)在在注解中使用“@”原因。
包含注解的設(shè)計(jì)和開發(fā)的Java規(guī)范主要有以下兩篇：
2. 介紹
解釋何為注解的最佳方式就是元數(shù)據(jù)這個(gè)詞：描述數(shù)據(jù)自身的數(shù)據(jù)。注解就是代碼的元數(shù)據(jù)，他們包含了代碼自身的信息。
注解可以被用在包，類，方法，變量，參數(shù)上。自Java8起，有一種注解幾乎可以被放在代碼的任何位置，叫做類型注解。我們將會(huì)在后面談到具體用法。
被注解的代碼并不會(huì)直接被注解影響。這只會(huì)向第三系統(tǒng)提供關(guān)于自己的信息以用于不同的需求。
注解會(huì)被編譯至class文件中，而且會(huì)在運(yùn)行時(shí)被處理程序提取出來用于業(yè)務(wù)邏輯。當(dāng)然，創(chuàng)建在運(yùn)行時(shí)不可用的注解也是可能的，甚至可以創(chuàng)建只在源文件中可用，在編譯時(shí)不可用的注解。
3.消費(fèi)器
理解注解的目的以及如何使用它都會(huì)帶來困難，因?yàn)樽⒔獗旧聿⒉话魏喂δ苓壿?#xff0c;它們也不會(huì)影響自己注解的代碼，那么，它們到底為什么而存在呢？
這個(gè)問題的解釋就是我所稱的注解消費(fèi)器。它們是利用被注解代碼并根據(jù)注解信息產(chǎn)生不同行為的系統(tǒng)或者應(yīng)用程序。
例如，在Java自帶的內(nèi)建注解(元注解)中，消費(fèi)器是執(zhí)行被注解代碼的JVM。還有其他稍后談到的其他例子，例如JUnit，消費(fèi)器是讀取，分析被注解代碼的JUnit處理程序，它還可以決定測(cè)試單元和方法執(zhí)行順序。我們會(huì)在JUnit章節(jié)更深入。
消費(fèi)器使用Java中的反射機(jī)制來讀取和分析被注解的源代碼。使用的主要的包有：java.lang, java.lang.reflect。我們將會(huì)在本篇指南中介紹如何用反射從頭開始創(chuàng)建一個(gè)自定義的消費(fèi)器。
4. 注解語法和元素
聲明一個(gè)注解需要使用“@”作為前綴，這便向編譯器說明，該元素為注解。例如：
1
2
3
4@Annotation
public void annotatedMehod() {
...
}
上述的注解名稱為Annotation，它正在注解annotatedMethod方法。編譯器會(huì)處理它。注解可以以鍵值對(duì)的形式持有有很多元素，即注解的屬性。
1
2
3
4
5
6
7@Annotation(
info ="I am an annotation",
counter ="55"
)
public void annotatedMehod() {
...
}
如果注解只包含一個(gè)元素(或者只需要指定一個(gè)元素的值，其它則使用默認(rèn)值)，可以像這樣聲明：
1
2
3
4@Annotation("I am an annotation")
public void annotatedMehod() {
...
}
就像我們看到的一樣，如果沒有元素需要被指定，則不需要括號(hào)。多個(gè)注解可以使用在同一代碼上，例如類：
1
2
3@ Annotation (info ="U a u O")
@ Annotation2
class AnnotatedClass { ... }
一些java本身提供的開箱即用的注解，我們稱之為內(nèi)建注解。也可以定義你自己的注解，稱之為子定義注解。我們會(huì)在下一章討論。
5. 在什么地方使用
注解基本上可以在Java程序的每一個(gè)元素上使用：類，域，方法，包，變量，等等。
自Java8，誕生了通過類型注解的理念。在此之前，注解是限于在前面討論的元素的聲明上使用。從此，無論是類型還是聲明都可以使用注解，就像：
1@MyAnnotation String str ="danibuiza";
我們將會(huì)在Java8關(guān)聯(lián)章節(jié)看到這種機(jī)制的更多細(xì)節(jié)。
6. 使用案例
注解可以滿足許多要求，最普遍的是：
向編譯器提供信息：注解可以被編譯器用來根據(jù)不同的規(guī)則產(chǎn)生警告，甚至錯(cuò)誤。一個(gè)例子是Java8中@FunctionalInterface注解，這個(gè)注解使得編譯器校驗(yàn)被注解的類，檢查它是否是一個(gè)正確的函數(shù)式接口。
文檔：注解可以被軟件應(yīng)用程序計(jì)算代碼的質(zhì)量例如：FindBugs，PMD或者自動(dòng)生成報(bào)告，例如：用來Jenkins, Jira，Teamcity。
代碼生成：注解可以使用代碼中展現(xiàn)的元數(shù)據(jù)信息來自動(dòng)生成代碼或者XML文件，一個(gè)不錯(cuò)的例子是JAXB。
運(yùn)行時(shí)處理：在運(yùn)行時(shí)檢查的注解可以用做不同的目的，像單元測(cè)試(JUnit)，依賴注入(Spring)，校驗(yàn)，日志(Log4j)，數(shù)據(jù)訪問(Hibernate)等等。
在這篇手冊(cè)中我們將展現(xiàn)幾種注解可能的用法，包括流行的Java類庫是如何使用它們的。
7. 內(nèi)建注解
Java語言自帶了一系列的注解。在本章中我們將闡述最重要的一部分。這個(gè)清單只涉及了Java語言最核心的包，未包含標(biāo)準(zhǔn)JRE中所有包和庫如JAXB或Servlet規(guī)范。
以下討論到的注解中有一些被稱之為Meta注解，它們的目的注解其他注解，并且包含關(guān)于其它注解的信息。
@Retention：這個(gè)注解注在其他注解上，并用來說明如何存儲(chǔ)已被標(biāo)記的注解。這是一種元注解，用來標(biāo)記注解并提供注解的信息。可能的值是：
SOURCE：表明這個(gè)注解會(huì)被編譯器忽略，并只會(huì)保留在源代碼中。
CLASS:表明這個(gè)注解會(huì)通過編譯駐留在CLASS文件，但會(huì)被JVM在運(yùn)行時(shí)忽略,正因?yàn)槿绱?其在運(yùn)行時(shí)不可見。
RUNTIME：表示這個(gè)注解會(huì)被JVM獲取，并在運(yùn)行時(shí)通過反射獲取。
我們會(huì)在稍后展開幾個(gè)例子。
@Target：這個(gè)注解用于限制某個(gè)元素可以被注解的類型。例如：
ANNOTATION_TYPE 表示該注解可以應(yīng)用到其他注解上
CONSTRUCTOR 表示可以使用到構(gòu)造器上
FIELD 表示可以使用到域或?qū)傩陨?/p>
LOCAL_VARIABLE表示可以使用到局部變量上。
METHOD可以使用到方法級(jí)別的注解上。
PACKAGE可以使用到包聲明上。
PARAMETER可以使用到方法的參數(shù)上
TYPE可以使用到一個(gè)類的任何元素上。
@Documented：被注解的元素將會(huì)作為Javadoc產(chǎn)生的文檔中的內(nèi)容。注解都默認(rèn)不會(huì)成為成為文檔中的內(nèi)容。這個(gè)注解可以對(duì)其它注解使用。
@Inherited：在默認(rèn)情況下，注解不會(huì)被子類繼承。被此注解標(biāo)記的注解會(huì)被所有子類繼承。這個(gè)注解可以對(duì)類使用。
@Deprecated：說明被標(biāo)記的元素不應(yīng)該再度使用。這個(gè)注解會(huì)讓編譯器產(chǎn)生警告消息。可以使用到方法，類和域上。相應(yīng)的解釋和原因，包括另一個(gè)可取代的方法應(yīng)該同時(shí)和這個(gè)注解使用。
@SuppressWarnings：說明編譯器不會(huì)針對(duì)指定的一個(gè)或多個(gè)原因產(chǎn)生警告。例如：如果我們不想因?yàn)榇嬖谏形词褂玫乃接蟹椒ǘ玫骄婵梢赃@樣做：
1
2
3
4@SuppressWarnings("unused")
private String myNotUsedMethod(){
...
}
通常,編譯器會(huì)因?yàn)闆]調(diào)用該方而產(chǎn)生警告;?用了注解抑制了這種行為。該注解需要一個(gè)或多個(gè)參數(shù)來指定抑制的警告類型。
@Override：向編譯器說明被注解元素是重寫的父類的一個(gè)元素。在重寫父類元素的時(shí)候此注解并非強(qiáng)制性的，不過可以在重寫錯(cuò)誤時(shí)幫助編譯器產(chǎn)生錯(cuò)誤以提醒我們。比如子類方法的參數(shù)和父類不匹配，或返回值類型不同。
@SafeVarargs：斷言方法或者構(gòu)造器的代碼不會(huì)對(duì)參數(shù)進(jìn)行不安全的操作。在Java的后續(xù)版本中，使用這個(gè)注解時(shí)將會(huì)令編譯器產(chǎn)生一個(gè)錯(cuò)誤在編譯期間防止?jié)撛诘牟话踩僮鳌?/p>
8. Java 8 與注解
Java8帶來了一些優(yōu)勢(shì)，同樣注解框架的能力也得到了提升。在本章我們將會(huì)闡述，并就java8帶來的3個(gè)注解做專題說明和舉例：
@Repeatable注解，關(guān)于類型注解的聲明，函數(shù)式接口注解@FunctionalInterface(與Lambdas結(jié)合使用)。
@Repeatable：說明該注解標(biāo)識(shí)的注解可以多次使用到同一個(gè)元素的聲明上。
看一個(gè)使用的例子。首先我們創(chuàng)造一個(gè)能容納重復(fù)的注解的容器：
1
2
3
4
5
6
7
8
9/**
* Container for the {@link CanBeRepeated} Annotation containing a list of values
*/
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE_USE )
public @interface RepeatedValues
{
CanBeRepeated[] value();
}
接著，創(chuàng)建注解本身，然后標(biāo)記@Repeatable
1
2
3
4
5
6
7@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE_USE )
@Repeatable( RepeatedValues.class )
public @interface CanBeRepeated
{
String value();
}
最后，我們可以這樣重復(fù)地使用：
1
2
3
4
5
6
7@CanBeRepeated("the color is green" )
@CanBeRepeated("the color is red" )
@CanBeRepeated("the color is blue" )
public class RepeatableAnnotated
{
}
如果我們嘗試去掉@Repeatable
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21@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
{
}
我們會(huì)得到編譯器的錯(cuò)誤信息：
1Duplicate annotation of non-repeatable type
自Java8開始，我們可以在類型上使用注解。由于我們?cè)谌魏蔚胤蕉伎梢允褂妙愋?#xff0c;包括 new操作符，casting，implements，throw等等。注解可以改善對(duì)Java代碼的分析并且保證更加健壯的類型檢查。這個(gè)例子說明了這一點(diǎn)：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19@SuppressWarnings("unused" )
public static void main(String[] args )
{
// type def
@TypeAnnotated
String cannotBeEmpty =null;
// type
List myList =new ArrayList();
// values
String myString =new @TypeAnnotatedString("this is annotated in java 8" );
}
// in method params
public void methodAnnotated( @TypeAnnotatedint parameter )
{
System.out.println("do nothing" );
}
所有的這些在Java8之前都是不可能的。
@FunctionalInterface：這個(gè)注解表示一個(gè)函數(shù)式接口元素。函數(shù)式接口是一種只有一個(gè)抽象方法(非默認(rèn))的接口。編譯器會(huì)檢查被注解元素，如果不符，就會(huì)產(chǎn)生錯(cuò)誤。例子如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29// 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 );
}
這個(gè)注解可以被使用到類，接口，枚舉和注解本身。它的被JVM保留并在runtime可見，這個(gè)是它的聲明：
1
2
3
4@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface FunctionalInterface
9. 自定義注解
正如我們之前多次提及的，可以定義和實(shí)現(xiàn)自定義注解。本章我們即將探討。
首先，定義一個(gè)注解：
1public @interface CustomAnnotationClass
這樣創(chuàng)建了一個(gè)新的注解類型名為 CustomAnnotationClass。關(guān)鍵字：@interface說明這是一個(gè)自定義注解的定義。
之后，你需要為此注解定義一對(duì)強(qiáng)制性的屬性，保留策略和目標(biāo)。還有一些其他屬性可以定義，不過這兩個(gè)是最基本和重要的。它們?cè)诘?章，描述注解的注解時(shí)討論過，它們同樣也是Java內(nèi)建的注解。
所以，我們?yōu)樽远x的注解設(shè)置屬性：
1
2
3@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE )
public @interface CustomAnnotationClassimplements CustomAnnotationMethod
在保留策略中 RUNTIME 告訴編譯器這個(gè)注解應(yīng)該被被JVM保留，并且能通過反射在運(yùn)行時(shí)分析。通過 TYPE 我們又設(shè)置該注解可以被使用到任何類的元素上。
之后，我們定義兩個(gè)注解的成員：
1
2
3
4
5
6
7
8
9
10@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE )
public @interface CustomAnnotationClass
{
public String author()default "danibuiza";
public String date();
}
以上我們僅定義了默認(rèn)值為“danibuiza”的 author 屬性和沒有默認(rèn)值的date屬性。我們應(yīng)強(qiáng)調(diào)所有的方法聲明都不能有參數(shù)和throw子句。這個(gè)返回值的類型被限制為之前提過的字符串，類，枚舉，注解和存儲(chǔ)這些類型的數(shù)組。
現(xiàn)在我們可以像這樣使用剛創(chuàng)建的自定義注解：
1
2
3
4
5@CustomAnnotationClass( date ="2014-05-05" )
public class AnnotatedClass
{
...
}
在另一種類似的用法中我們可以創(chuàng)建一種注解方法的注解，使用Target METHOD：
1
2
3
4
5
6
7
8
9
10
11
12@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.METHOD )
public @interface CustomAnnotationMethod
{
public String author()default "danibuiza";
public String date();
public String description();
}
這種注解可以使用在方法聲明上：
1
2
3
4
5
6
7
8
9
10
11@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";
}
有很多其它屬性可以用在自定義注解上，但是 目標(biāo) (Target)和 保留策略(Retention Policy)是最重要的兩個(gè)。
10. 獲取注解
Java反射API包含了許多方法來在運(yùn)行時(shí)從類，方法或者其它元素獲取注解。接口AnnotatedElement包含了大部分重要的方法，如下：
getAnnotations(): 返回該元素的所有注解，包括沒有顯式定義該元素上的注解。
isAnnotationPresent(annotation): 檢查傳入的注解是否存在于當(dāng)前元素。
getAnnotation(class): 按照傳入的參數(shù)獲取指定類型的注解。返回null說明當(dāng)前元素不帶有此注解。
class 通過java.lang.Class被實(shí)現(xiàn)，java.lang.reflect.Method 和 java.lang.reflect.Field，所以可以基本上被和任何Java元素使用。
現(xiàn)在，我們將看一個(gè)怎么讀取注解的例子：
我們寫一個(gè)程序，從一個(gè)類和它的方法中讀取所有的存在的注解：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36public static void main(String[] args ) throws Exception
{
Class 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 );
}
}
}
輸出如下：
1
2
3
4
5
6@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)
在這個(gè)程序中，我們可以看到 getAnnotations()方法來獲取所有某個(gè)對(duì)象(方法，類)上的所有注解的用法。展示了怎樣使用isAnnotationPresent()方法和getAnnotation()方法檢查是否存在特定的注解，和如何獲取它。
11. 注解中的繼承
注解在Java中可以使用繼承。這種繼承和普通的面向?qū)ο罄^承幾乎沒有共同點(diǎn)。
如果一個(gè)注解在Java中被標(biāo)識(shí)成繼承，使用了保留注解@Inherited，說明它注解的這個(gè)類將自動(dòng)地把這個(gè)注解傳遞到所有子類中而不用在子類中聲明。通常，一個(gè)類繼承了父類，并不繼承父類的注解。這完全和使用注解的目的一致的：提供關(guān)于被注解的代碼的信息而不修改它們的行為。
我們通過一個(gè)例子更清楚地說明。首先，我們定義一個(gè)自動(dòng)繼承的自定義注解。
1
2
3
4
5
6
7@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface InheritedAnnotation
{
}
有一個(gè)父類名為：AnnotatedSuperClass，已經(jīng)被自定義的注解給注解上了：
1
2
3
4
5
6
7
8
9
10@InheritedAnnotation
public class AnnotatedSuperClass
{
public void oneMethod()
{
}
}
一個(gè)子類繼承父類：
1
2
3
4
5
6
7
8
9
10@InheritedAnnotation
public class AnnotatedSuperClass
{
public void oneMethod()
{
}
}
子類 AnnotatedSubClass 展示了自動(dòng)繼承的注解 @InheritedAnnotation。我們看到下面的代碼通過 isAnnotationPresent() 方法測(cè)試出了當(dāng)前注解。
1
2
3
4
System.out.println("is true: " + AnnotatedSuperClass.class.isAnnotationPresent( InheritedAnnotation.class ) );System.out.println("is true: " + AnnotatedSubClass.class.isAnnotationPresent( InheritedAnnotation.class ) );
輸出如下：
1
2istrue:true
istrue:true
我們可以看到子類雖然并沒有聲明注解，但還是被自動(dòng)地注解上了。
如果我們嘗試注解在一個(gè)接口中：
1
2
3
4
5
6
7@InheritedAnnotation
public interface AnnotatedInterface
{
public void oneMethod();
}
一個(gè)實(shí)現(xiàn)了該接口的類：
1
2
3
4
5
6
7
8
9
10public class AnnotatedImplementedClassimplements AnnotatedInterface
{
@Override
public void oneMethod()
{
}
}
經(jīng)過 isAnnotationPresent() 方法測(cè)試：
1
2
3System.out.println("is true: " + AnnotatedInterface.class.isAnnotationPresent( InheritedAnnotation.class ) );
System.out.println("is true: " + AnnotatedImplementedClass.class.isAnnotationPresent( InheritedAnnotation.class ) );
結(jié)果如下：
1
2is true:true
is true:false
這個(gè)結(jié)果說明繼承注解和接口在一起使用時(shí)，接口中的注解在實(shí)現(xiàn)類中：僅僅被忽略。實(shí)現(xiàn)類并不繼承接口的注解；接口繼承僅僅適用于類繼承。正如 AnnotatedSubClass。
@Inheriated注解僅在存在繼承關(guān)系的類上產(chǎn)生效果，在接口和實(shí)現(xiàn)類上并不工作。這條同樣也適用在方法，變量，包等等。只有類才和這個(gè)注解連用。
注解不能繼承注解，如果你嘗試這么做了，就會(huì)得到編譯器拋出的錯(cuò)誤：
1Annotation type declaration cannot have explicit superinterfaces
12. 使用注解的知名類庫
在這一章我們將展示知名類庫是如何利用注解的。一些類庫如：JAXB, Spring Framework, Findbugs, Log4j, Hibernate, Junit。它們使用注解來完成代碼質(zhì)量分析，單元測(cè)試，XML解析，依賴注入和許多其它的工作。
在這篇手冊(cè)中我們將討論以下類庫的部分內(nèi)容：
12.1. Junit
這個(gè)框架用于完成Java中的單元測(cè)試。自JUnit4開始，注解被廣泛應(yīng)用，成為Junit的設(shè)計(jì)的主干之一。
基本上，JUnit處理程序通過反射讀取類和測(cè)試套件，按照在方法上，類上的注解順序地執(zhí)行它們。當(dāng)然還有一些用來修改測(cè)試執(zhí)行的注解。其它注解都用來執(zhí)行測(cè)試，阻止執(zhí)行，改變執(zhí)行順序等等。
用到的注解相當(dāng)多，但是我們將會(huì)看到最重要的幾個(gè)：
@Test：這個(gè)注解向JUnit說明這個(gè)被注解的方法一定是一個(gè)可執(zhí)行的測(cè)試方法。這個(gè)注解只能標(biāo)識(shí)在方法上，并且被JVM保留至運(yùn)行時(shí)。
1
2
3
4
5
6@Test
public void testMe()
{
//test assertions
assertEquals(1,1);
}
從這個(gè)例子可以看到我們?nèi)绾卧贘Unit中使用這類注解。
@Before：這個(gè)注解用來向JUnit說明被標(biāo)記的方法應(yīng)該在所有測(cè)試方法之前被執(zhí)行。這對(duì)于在測(cè)試之前設(shè)置測(cè)試環(huán)境和初始化非常有用。同樣只適用于方法上：
1
2
3
4
5
6
7@Before
public void setUp()
{
// initializing variables
count =0;
init();
}
@After：這個(gè)注解用來向JUnit說明被注解的方法應(yīng)該在所有單元測(cè)試之后執(zhí)行。這個(gè)注解通常用來銷毀資源，關(guān)閉，釋放資源或者清理，重置等工作。
1
2
3
4
5
6@After
public void destroy()
{
// closing input stream
stream.close();
}
@Ignore：這個(gè)方法用來向JUnit說明被注解的方法應(yīng)該不被當(dāng)作測(cè)試單元執(zhí)行。即使它被注解成為一個(gè)測(cè)試方法，也只能被忽略。
1
2
3
4
5
6
7@Ignore
@Test
public void donotTestMe()
{
count = -22;
System.out.println("donotTestMe(): " + count );
}
這個(gè)方法可能在在開發(fā)調(diào)試階段使用，但一旦開始進(jìn)入發(fā)布階段變需要將被忽略的代碼去掉。
@FixMethodOrder：指定執(zhí)行的順序，正常情況下Junit處理程序負(fù)責(zé)它按照完全隨機(jī)的無法預(yù)知的順序執(zhí)行。當(dāng)所有的測(cè)試方法都相互獨(dú)立的時(shí)候，不推薦使用這個(gè)注解。但是，當(dāng)測(cè)試的場(chǎng)景需要測(cè)試方法按照一定規(guī)則的時(shí)候，這個(gè)注解就派上用場(chǎng)了。
還有一些測(cè)試套件和類庫使用了注解，例如Mockito和JMock，使用注解來創(chuàng)建測(cè)試對(duì)象和預(yù)期值。 查看JUnit中所有注解請(qǐng)參考：https://github.com/junit-team/junit/wiki/Getting-started
12.2. Hibernate ORM
Hibernate可能是一個(gè)用得最廣泛的對(duì)象關(guān)系映射類庫。它提供了對(duì)象模型和關(guān)系型數(shù)據(jù)庫的映射框架。使用注解作為設(shè)計(jì)的一部分。
在本章我們將討論一兩個(gè)由Hibernate提供的注解并解釋它的處理程序如何處理它們。
下面的代碼段使用了@Entity和@Table。這兩個(gè)是用來向消費(fèi)器(Hibernate處理程序)說明被注解的類是一個(gè)實(shí)體類，以及它映射的SQL表名。實(shí)際上，這個(gè)注解僅僅是指明了主表，還可以有說明字表的注解。
1
2
3@Entity
@Table( name ="hibernate_annotated" )
public class HibernateAnnotated
接下來的代碼段展示了如何向Hibernate處理程序說明被標(biāo)記的元素是表的主鍵，并映射名為“id”的列，并且主鍵是自動(dòng)生成的。
1
2
3
4@Id
@GeneratedValue
@Column( name ="id" )
private int id;
為了指定標(biāo)準(zhǔn)的SQL表列名，我們可以寫如下注解：
1
2@Column( name ="description" )
private String description;
這說明被標(biāo)記的元素映射的是這個(gè)類所對(duì)應(yīng)的表中名為“description”的一列。
12.3. Spring MVC
Spring是個(gè)被廣泛使用的Java企業(yè)級(jí)應(yīng)用框架。其一項(xiàng)重要的特性就是在Java程序使用依賴注入。
Spring使用注解作為XML(Spring的早期版本使用的基于XML配置)的一種替代方式。現(xiàn)在兩者都是可行的。你可以使用XML文件或者注解配置你的項(xiàng)目。在我看來兩者都各有優(yōu)勢(shì)。
我們將在下例中展示兩個(gè)可用注解：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18@Component
public class DependencyInjectionAnnotation
{
private String description;
public String getDescription()
{
return description;
}
@Autowired
public void setDescription(String description )
{
this.description = description;
}
}
在次代碼片段中我們可以找到兩個(gè)使用在了類和方法上的注解。
@Component：說明被標(biāo)記的元素，在本例中是一個(gè)類，是一個(gè)自動(dòng)檢測(cè)的目標(biāo)。這意味著被注解的類，將會(huì)被Spring容器實(shí)例化并管理。
@Autowired：Spring容器將會(huì)嘗試通過類型(這是一種元素匹配機(jī)制)使用這個(gè)set方法來自動(dòng)裝配。此注解也可以使用在構(gòu)造器和屬性上，Spring也會(huì)根據(jù)注解的地方不同采取不同的操作。
12.4. Findbugs
這是一個(gè)用來測(cè)量代碼質(zhì)量，并提供一系列可能提高它的工具。它會(huì)根據(jù)預(yù)定義(或者自定義)的違反規(guī)則來檢查代碼。Findbugs提供一系列注解來允許開發(fā)者來改變默認(rèn)行為。
它主要使用反射讀取代碼(和包含的注解)并決定基于它們，應(yīng)該采取什么行為。
一個(gè)列子是 edu.umd.cs.findbugs.annotations.SuppressFBWarnings 注解期待一種違反規(guī)定的鍵值并把它當(dāng)作參數(shù)。這非常像 java.lang.SuppressWarnings。被用來向 Findbugs 說明當(dāng)執(zhí)行代碼分析的時(shí)候，忽略指定的違反規(guī)則。
這是一個(gè)例子：
1
2
3
4
5
6
7
8
9
10
11@SuppressFBWarnings("HE_EQUALS_USE_HASHCODE" )
public class FindBugsAnnotated
{
@Override
public boolean equals( Object arg0 )
{
return super.equals( arg0 );
}
}
這個(gè)類已經(jīng)重現(xiàn)了 Object 的 equals 方法，但是并沒有重寫 hashCode 方法。這通常會(huì)導(dǎo)致問題，因?yàn)?hashCode 和 equals 兩者應(yīng)該被同時(shí)重寫，否則在使用這個(gè)對(duì)象作為 HashMap 的key值的時(shí)候會(huì)導(dǎo)致錯(cuò)誤。所以，Findbugs會(huì)在違反規(guī)則報(bào)告中創(chuàng)造一個(gè)錯(cuò)誤條目。
如果注解 @SuppressFBWarnings 設(shè)置了 HE_EQUALS_USE_HASHCODE 值以后，處理程序就不會(huì)在拋出這類型的錯(cuò)誤了。
1
2Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and usesObject.hashCode()
Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and usesObject.hashCode()
這個(gè)類重寫了 equals 方法，但是沒有重寫 hashCode 方法，繼承自 java.lang.Object 的 hashCode 方法(返回每個(gè)對(duì)象被JVM賦予的特定值)。因此，這個(gè)類幾乎違反了相同的對(duì)象必須 hashcode 相同的一致性。
如果你認(rèn)為這個(gè)類的實(shí)例不會(huì)插入到哈希表，推薦的做法是像這樣實(shí)現(xiàn) hashCode 方法：
1
2
3
4
5
6
7
8public int hashCode() {
assertfalse :"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)
這個(gè)錯(cuò)誤包含了該問題的一種解釋并且提示如何處理它。在這種情況下，解決方案應(yīng)該是實(shí)現(xiàn) hashCode 方法。
12.5. JAXB
JAXB是一個(gè)用來相互轉(zhuǎn)換和映射XML文件與Java對(duì)象的類庫。實(shí)際上，這個(gè)類庫與標(biāo)準(zhǔn)JRE一起提供，不需要任何額外的下載和配置。可以直接通過引入 java.xml.bind.annotation 包下的類直接使用。
JAXB使用注解來告知處理程序(或者是JVM)XML文件與代碼的相互轉(zhuǎn)化。例如，注解可以用來在代碼上標(biāo)記XML節(jié)點(diǎn)，XMl屬性，值等等。我們將看到一個(gè)例子：
首先，我們聲明一個(gè)類說明它應(yīng)該是XML文件中的一個(gè)節(jié)點(diǎn)：
1
2
3
4
5
6import 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 這個(gè)類在轉(zhuǎn)換后，將會(huì)轉(zhuǎn)換成為XML中的一個(gè)節(jié)點(diǎn)。這個(gè)@XmlType說明了屬性在XML中的順序。JAXB將會(huì)基于這些注解執(zhí)行合適的操作。
除了分離的 getter 和 setter 屬性，再也不需要向這個(gè)類中添加其它東西來完成轉(zhuǎn)換。現(xiàn)在我們需要一個(gè)消費(fèi)器程序來執(zhí)行轉(zhuǎn)換成XML：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22Car 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 );
程序產(chǎn)生的輸入如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
02
Mercedes
SLK
2011
15000
VW
Touran
2005
150000
更多關(guān)于JAXB XML和Java 的轉(zhuǎn)換信息請(qǐng)參考：https://jaxb.java.net/
13. 總結(jié)
在這篇文檔中，我們解釋了Java注解是Java1.5開始一個(gè)非常重要的特性。基本上，注解都是作為包含代碼信息的元數(shù)據(jù)而被標(biāo)記到代碼中。它們不會(huì)改變或者影響代碼的任何意義，而是被第三方稱為消費(fèi)器的程序通過反射的方式使用。
我們列出了Java默認(rèn)的內(nèi)建注解，一些稱為元注解例如：@Target或者 @Retention，又有@Override，@SuppressWarnings，還有一些Java8相關(guān)的注解，比如：@Repeatable，@FunctionalInterface和類型注解。我們還展現(xiàn)了一兩個(gè)結(jié)合使用反射的例子，并描述了一些使用注解的類庫例如Spring， Junit，Hibernate。
注解是Java中一種分析元數(shù)據(jù)的強(qiáng)大機(jī)制，可以在不同的程序中擔(dān)任不同的作用，例如校驗(yàn)，依賴注入，單元測(cè)試。
14. 下載
這是一個(gè)java注解的教程。
15. 資料
這是一些非常有用的關(guān)于Java注解的資料：
總結(jié)
以上是生活随笔為你收集整理的java指导手册,Java 注解指导手册 – 终极向导的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： java 网络 io流_【015期】Ja
- 下一篇： java正则hitend,Java Ma