天天看點
傳回

Java注解Annotation詳解

從JDK5開始，Java增加了Annotation(注解)，Annotation是代碼裡的特殊标記，這些标記可以在編譯、類加載、運作時被讀取，并執行相應的處理。通過使用Annotation，開發人員可以在不改變原有邏輯的情況下，在源檔案中嵌入一些補充的資訊。代碼分析工具、開發工具和部署工具可以通過這些補充資訊進行驗證、處理或者進行部署。

Annotation提供了一種為程式元素（包、類、構造器、方法、成員變量、參數、局域變量）設定中繼資料的方法。Annotation不能運作，它隻有成員變量，沒有方法。Annotation跟public、final等修飾符的地位一樣，都是程式元素的一部分，Annotation不能作為一個程式元素使用。

1 定義Annotation

定義新的Annotation類型使用@interface關鍵字（在原有interface關鍵字前增加@符号）。定義一個新的Annotation類型與定義一個接口很像，例如：

public @interface Test{
}

定義完該Annotation後，就可以在程式中使用該Annotation。使用Annotation，非常類似于public、final這樣的修飾符，通常，會把Annotation另放一行，并且放在所有修飾符之前。例如：

@Test
public class MyClass{
....
}

1.1 成員變量

Annotation隻有成員變量，沒有方法。Annotation的成員變量在Annotation定義中以“無形參的方法”形式來聲明，其方法名定義了該成員變量的名字，其傳回值定義了該成員變量的類型。例如：

public @interface MyTag{
    string name();
    int age();
}

示例中定義了2個成員變量，這2個成員變量以方法的形式來定義。

一旦在Annotation裡定義了成員變量後，使用該Annotation時就應該為該Annotation的成員變量指定值。例如：

public class Test{
    @MyTag(name="蕃薯"，age=30)
    public void info(){
    ......
    }
}

也可以在定義Annotation的成員變量時，為其指定預設值，指定成員變量預設值使用default關鍵字。示例：

public @interface MyTag{
    string name() default "我蘭";
    int age() default 18;
}

如果Annotation的成員變量已經指定了預設值，使用該Annotation時可以不為這些成員變量指定值，而是直接使用預設值。例如：

public class Test{
    @MyTag
    public void info(){
    ......
    }
}

根據Annotation是否包含成員變量，可以把Annotation分為如下兩類：

  • 标記Annotation：沒有成員變量的Annotation被稱為标記。這種Annotation僅用自身的存在與否來為我們提供資訊，例如@override等。
  • 中繼資料Annotation：包含成員變量的Annotation。因為它們可以接受更多的中繼資料，是以被稱為中繼資料Annotation。

1.2 元注解

在定義Annotation時，也可以使用JDK提供的元注解來修飾Annotation定義。JDK提供了如下4個元注解（注解的注解，不是上述的”中繼資料Annotation“）：

  • @Retention
  • @Target
  • @Documented
  • @Inherited

1.2.1 @Retention

@Retention用于指定Annotation可以保留多長時間。

@Retention包含一個名為“value”的成員變量，該value成員變量是RetentionPolicy枚舉類型。使用@Retention時，必須為其value指定值。value成員變量的值隻能是如下3個：

  • RetentionPolicy.SOURCE：Annotation隻保留在源代碼中，編譯器編譯時，直接丢棄這種Annotation。
  • RetentionPolicy.CLASS：編譯器把Annotation記錄在class檔案中。當運作Java程式時，JVM中不再保留該Annotation。
  • RetentionPolicy.RUNTIME：編譯器把Annotation記錄在class檔案中。當運作Java程式時，JVM會保留該Annotation，程式可以通過反射擷取該Annotation的資訊。

示例：

package com.demo1;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

//name=value形式
//@Retention(value=RetentionPolicy.RUNTIME)

//直接指定
@Retention(RetentionPolicy.RUNTIME)
public @interface MyTag{
	String name() default "我蘭";
}

如果Annotation裡有一個名為“value“的成員變量，使用該Annotation時，可以直接使用XXX(val)形式為value成員變量指派，無須使用name=val形式。

1.2.2 @Target

@Target指定Annotation用于修飾哪些程式元素。@Target也包含一個名為”value“的成員變量，該value成員變量類型為ElementType[ ]，ElementType為枚舉類型，值有如下幾個：

  • ElementType.TYPE：能修飾類、接口或枚舉類型
  • ElementType.FIELD：能修飾成員變量
  • ElementType.METHOD：能修飾方法
  • ElementType.PARAMETER：能修飾參數
  • ElementType.CONSTRUCTOR：能修飾構造器
  • ElementType.LOCAL_VARIABLE：能修飾局部變量
  • ElementType.ANNOTATION_TYPE：能修飾注解
  • ElementType.PACKAGE：能修飾包

示例1（單個ElementType）：

package com.demo1;

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

@Target(ElementType.FIELD)
public @interface AnnTest {
	String name() default "sunchp";
}

示例2（多個ElementType）：

package com.demo1;

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

@Target({ ElementType.FIELD, ElementType.METHOD })
public @interface AnnTest {
	String name() default "sunchp";
}

1.2.3 @Documented

如果定義注解A時，使用了@Documented修飾定義，則在用javadoc指令生成API文檔後，所有使用注解A修飾的程式元素，将會包含注解A的說明。

@Documented
public @interface Testable {
}      
public class Test {
	@Testable
	public void info() {
	}
}
Java注解Annotation詳解

1.2.4 @Inherited

@Inherited指定Annotation具有繼承性。

package com.demo2;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

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

}      
package com.demo2;

@MyTag
public class Base {

}      
package com.demo2;

//SubClass隻是繼承了Base類
//并未直接使用@MyTag注解修飾
public class SubClass extends Base {
	public static void main(String[] args) {
		System.out.println(SubClass.class.isAnnotationPresent(MyTag.class));
	}
}

示例中Base使用@MyTag修飾，SubClass繼承Base，而且沒有直接使用@MyTag修飾，但是因為MyTag定義時，使用了@Inherited修飾，具有了繼承性，是以運作結果為true。

如果MyTag注解沒有被@Inherited修飾，則運作結果為：false。

1.3 基本Annotation

JDK預設提供了如下幾個基本Annotation：

  • @Override 

限定重寫父類方法。對于子類中被@Override 修飾的方法，如果存在對應的被重寫的父類方法，則正确；如果不存在，則報錯。@Override 隻能作用于方法，不能作用于其他程式元素。

  • @Deprecated

用于表示某個程式元素（類、方法等）已過時。如果使用被@Deprecated修飾的類或方法等，編譯器會發出警告。

  • @SuppressWarning

抑制編譯器警告。訓示被@SuppressWarning修飾的程式元素（以及該程式元素中的所有子元素，例如類以及該類中的方法.....）取消顯示指定的編譯器警告。例如，常見的@SuppressWarning（value="unchecked"）

  • @SafeVarargs

@SafeVarargs是JDK 7 專門為抑制“堆污染”警告提供的。

2 提取Annotation資訊（反射）

當開發者使用了Annotation修飾了類、方法、Field等成員之後，這些Annotation不會自己生效，必須由開發者提供相應的代碼來提取并處理Annotation資訊。這些處理提取和處理Annotation的代碼統稱為APT（Annotation Processing Tool）。

JDK主要提供了兩個類，來完成Annotation的提取：

  • java.lang.annotation.Annotation接口：這個接口是所有Annotation類型的父接口（後面會分析Annotation的本質，Annotation本質是接口，而java.lang.annotation.Annotation接口是這些接口的父接口）。
  • java.lang.reflect.AnnotatedElement接口：該接口代表程式中可以被注解的程式元素。

2.1 java.lang.annotation.Annotation

java.lang.annotation.Annotation接口源碼:

package java.lang.annotation;

public interface Annotation {

    boolean equals(Object obj);

    int hashCode();

    String toString();

    Class<? extends Annotation> annotationType();
}

java.lang.annotation.Annotation接口的主要方法是annotationType( )，用于傳回該注解的java.lang.Class。

2.2 java.lang.reflect.AnnotatedElement

java.lang.reflect.AnnotatedElement接口源碼：

package java.lang.reflect;

import java.lang.annotation.Annotation;

public interface AnnotatedElement {

     boolean isAnnotationPresent(Class<? extends Annotation> annotationClass);

    <T extends Annotation> T getAnnotation(Class<T> annotationClass);

    Annotation[] getAnnotations();

    Annotation[] getDeclaredAnnotations();
}

主要方法有：

  • isAnnotationPresent(Class<? extends Annotation> annotationClass)：判斷該程式元素上是否存在指定類型的注解，如果存在則傳回true，否則傳回false。
  • getAnnotation(Class<T> annotationClass)：傳回該程式元素上存在的指定類型的注解，如果該類型的注解不存在，則傳回null
  • Annotation[] getAnnotations()：傳回該程式元素上存在的所有注解。

java.lang.reflect.AnnotatedElement接口是所有程式元素（例如java.lang.Class、java.lang.reflect.Method、java.lang.reflect.Constructor等）的父接口。類圖結構如下：

Java注解Annotation詳解

是以程式通過反射擷取了某個類的AnnotatedElement對象（例如，A類method1()方法的java.lang.reflect.Method對象）後，就可以調用該對象的isAnnotationPresent( )、getAnnotation( )等方法來通路注解資訊。

為了擷取注解資訊，必須使用反射知識。

PS：如果想要在運作時提取注解資訊，在定義注解時，該注解必須使用@Retention(RetentionPolicy.RUNTIME)修飾。

2.3 示例

2.3.1 标記Annotation

給定一個類的全額限定名，加載類，并列出該類中被注解@MyTag修飾的方法和沒被修飾的方法。

注解定義：

package com.demo1;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

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

}

注解處理：

package com.demo1;

import java.lang.reflect.Method;

public class ProcessTool {
	public static void process(String clazz) {
		Class targetClass = null;

		try {
			targetClass = Class.forName(clazz);
		} catch (ClassNotFoundException e) {
			e.printStackTrace();
		}

		for (Method m : targetClass.getMethods()) {
			if (m.isAnnotationPresent(MyTag.class)) {
				System.out.println("被MyTag注解修飾的方法名：" + m.getName());
			} else {
				System.out.println("沒被MyTag注解修飾的方法名：" + m.getName());
			}
		}
	}
}

測試類：

package com.demo1;

public class Demo {
	public static void m1() {

	}

	@MyTag
	public static void m2() {

	}
}      
package com.demo1;

public class Test {

	public static void main(String[] args) {
		ProcessTool.process("com.demo1.Demo");
	}
}

運作結果：

沒被MyTag注解修飾的方法名：m1
被MyTag注解修飾的方法名：m2
沒被MyTag注解修飾的方法名：wait
沒被MyTag注解修飾的方法名：wait
沒被MyTag注解修飾的方法名：wait
沒被MyTag注解修飾的方法名：equals
沒被MyTag注解修飾的方法名：toString
沒被MyTag注解修飾的方法名：hashCode
沒被MyTag注解修飾的方法名：getClass
沒被MyTag注解修飾的方法名：notify
沒被MyTag注解修飾的方法名：notifyAll

2.3.2 中繼資料Annotation

給定一個類的全額限定名，加載類，找出被注解MyTag修飾的方法，并輸出每個方法的MyTag注解的屬性。

package com.demo1;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MyTag {
	String name() default "我蘭";

	int age() default 18;
}      
package com.demo1;

import java.lang.reflect.Method;

public class ProcessTool {
	public static void process(String clazz) {
		Class targetClass = null;

		try {
			targetClass = Class.forName(clazz);
		} catch (ClassNotFoundException e) {
			e.printStackTrace();
		}

		for (Method m : targetClass.getMethods()) {
			if (m.isAnnotationPresent(MyTag.class)) {
				MyTag tag = m.getAnnotation(MyTag.class);
				System.out.println("方法" + m.getName() + "的MyTag注解内容為：" + tag.name() + "，" + tag.age());
			}
		}
	}
}

      
package com.demo1;

public class Demo {
	public static void m1() {

	}

	@MyTag
	public static void m2() {

	}

	@MyTag(name = "蕃薯")
	public static void m3() {

	}

	@MyTag(name = "蕃薯", age = 30)
	public static void m4() {

	}
}      
package com.demo1;

public class Test {

	public static void main(String[] args) {
		ProcessTool.process("com.demo1.Demo");
	}
}      
方法m2的MyTag注解内容為：我蘭，18
方法m3的MyTag注解内容為：蕃薯，18
方法m4的MyTag注解内容為：蕃薯，30

若要擷取注解中的成員變量值，直接調用注解對象的"成員變量民( )"形式的方法就行，例如示例中的tag.name()等。

PS：在編譯器編譯注解定義時，自動在class檔案中，添加與成員變量同名的抽象方法，用于反射時擷取成員變量的值。

通過上面的示例可以看出，其實Annotation十分簡單，它是對源代碼增加的一些特殊标記，這些特殊标記可通過反射擷取，當程式擷取這些特殊标記後，程式可以做出相應的處理（當然也可以完全忽略這些Annotation）。

3 注解本質

對于示例”2.3.2 中繼資料Annotation“中的MyTag注解，在編譯後，生成一個MyTag.class檔案。反編譯該class檔案：

javap -verbose -c MyTag.class > m.txt

MyTag注解的位元組碼為：

Java注解Annotation詳解

通過分析位元組碼可知：

  • 注解實質上會被編譯器編譯為接口，并且繼承java.lang.annotation.Annotation接口。
  • 注解的成員變量會被編譯器編譯為同名的抽象方法。
  • 根據Java的class檔案規範，class檔案中會在程式元素的屬性位置記錄注解資訊。例如，RuntimeVisibleAnnotations屬性位置，記錄修飾該類的注解有哪些；flags屬性位置，記錄該類是不是注解；在方法的AnnotationDefault屬性位置，記錄注解的成員變量預設值是多少。

我們再反編譯下示例”2.3.2 中繼資料Annotation“中的Demo測試類，檢視下”被注解修飾的方法是怎樣記錄自己被注解修飾的“：

javap -verbose -c Demo.class > d.txt

反編譯結果如下：

Java注解Annotation詳解

通過位元組碼可知：

在位元組碼檔案中，每個方法都有RuntimeVisibleAnnotations屬性位置，用來放置注解和注解的成員變量指派。JVM在解析class檔案時，會解析RuntimeVisibleAnnotations屬性，并建立相應類型的注解對象，并将成員變量指派。

如果要明白JVM對注解的運作機制，需要對class檔案的格式規範有一定了解。（資料）

4 注解的意義

為編譯器提供輔助資訊 — Annotations可以為編譯器提供而外資訊，以便于檢測錯誤，抑制警告等.

編譯源代碼時進行而外操作 — 軟體工具可以通過處理Annotation資訊來生成原代碼，xml檔案等等.

運作時處理 — 有一些annotation甚至可以在程式運作時被檢測，使用.

總之，注解是一種中繼資料，起到了”描述，配置“的作用。

好文轉載：http://www.open-open.com/lib/view/open1423558996951.html

上一篇: 解決No enclosing instance of type * is accessible
下一篇: 去除url字尾(.html,.jsp等)的有效方法