[译] Java注解

2017-06-25 本文已影响0人风雪围城

原地址
注解允许我们在源码中添加一些元信息。它自JDK5 引入，对于代码中的操作并没有直接的影响。

注解用途

编译器指令：有三个内建注解（@Deprecated, @Override 和 @SuppressWarninigs）。它们被用来作为编译器指令。举例来说，@Override注解用来告诉编译器该方法是一个重写方法。
编译期指令：注解可以向编译器提供编译时期指令，用于产生代码、XML文件等。
运行时指令：我们可以定义一些运行时注解，用以通过Java反射访问。

注解基础概念

注解通常以 @ 符号开始，紧跟着是注解名。@ 符号告诉编译器，这是一个注解。
举例而言，@Override
这里 @ 符号代表这是一个注解,而 Override 就是注解的名字。

我们可以在哪里使用注解

注解可以被应用于类、接口、方法和属性。下面的注解就是被应用于方法当中。

@Override
void myMethod() { 
    //Do something 
}

Java内建注解

Java有三个内建注解：

@Override
@Deprecated
@SuppressWarnings

@Override
当我们在子类中重写方法，我们应该把这个注解标注在方法上。这样讲增强代码的可读性，同时可以避免一些误操作。比如说，当我们改变了父类中的方法签名，如果使用了注解，就必须同步更改子类中的方法签名，否则编译器将抛出编译期错误。如果你没有使用注解，可能很难跟踪这种错误。
@Deprecated
这个注解被用来标注在类、方法和属性上，表明其已经过时了，不再被使用。当程序中再使用该类、方法或者属性时，编译器将抛出警告。当一个元素被标记为过时，应该在JavaDoc中标记 @deprecated 。注意这里@Deprecated 和 @deprecated 的区别。@deprecated 被用来作为文档记录目的。

/**
 * @deprecated
 * reason for why it was deprecated
 */
@Deprecated
public void anyMethodHere(){
    // Do something
}

@SuppressWarning
这个注解用来告诉编译器忽略指定的警告。

@SuppressWarnings("deprecation")
    void myMethod() {
        myObject.deprecatedMethod();
}

如上所示，正在调用一个过时的方法，编译器将给出一个警告，然而当我们使用@SuppressWarnings 注解，这个警告将被忽略。

创建自定义注解

使用 @interface 来创建注解，紧跟着时注解名。
注解也可以拥有元素，他们看起来像方法一样。在下面的例子中，我们有四个元素，但是我们不应该提供这些元素的实现。
所有的注解继承自 java.lang.annotation.Annotatoin 接口。

import java.lang.annotation.Documented;
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;
 
@Documented
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface MyCustomAnnotation{
    int studentAge() default 18;
    String studentName();
    String stuAddress();
    String stuStream() default "CSE";
}

注意：所有的元素都有一个默认值设置。在创建或者使用注解的时候，可以被跳过。举例来说，我想在一个类中使用上面的注解，可以这样做：

@MyCustomAnnotation(
    studentName="Chaitanya",
    stuAddress="Agra, India"
)
public class MyClass {
...
}

我们并没有对studentAge和stuStream元素赋值，因为这并不是必要的（在注解被定义的时候已经设置了默认值）。但是，如果没有设置默认值，我们需要在使用注解的时候给这些元素提供值。
注意：我们可以在注解中使用数组元素。用例如下：

//定义部分
@interface MyCustomAnnotation {
    int      count();
    String[] books();
}
//使用部分  
@MyCustomAnnotation(
    count=3,
    books={"C++", "Java"}
)
public class MyClass {

}

现在重新回到话题：在自定义注解的例子中，我们使用了四个注解：@Documented, @Target, @Inherited, @Retention. 下面我们分别讨论他们。

@Documented

该注解表示，注解元素将被写入到 JavaDoc 中：

ava.lang.annotation.Documented
@Documented
public @interface MyCustomAnnotation {
  //Annotation body
}
.............................................................
@MyCustomAnnotation
public class MyClass { 
     //Class body
}

当为MyClass生成 javadoc文档的时候，文档中将包含 MyCustomAnnotation 注解。

Target

该注解指定我们可以在哪里使用它。如下面例子所示，我们定义了target 类型为 METHOD,这也意味着该注解只能应用于方法中。

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

@Target({ElementType.METHOD})
public @interface MyCustomAnnotation {

}
.......................................................................
public class MyClass {
   @MyCustomAnnotation
   public void myMethod()
   {
       //Doing something
   }
}

注意：
1）如果你没有定义 Target 类型，默认可以应用于任何元素。
2）除了ElementType.METHOD,注解中还可以有下面的 Target 值：
ElementType.METHOD
ElementType.PACKAGE 包
ElementType.PARAMETER 参数
ElementType.TYPE 类
ElementType.ANNOTATION_TYPE 注解
ElementType.CONSTRUCTOR 构造函数
ElementType.LOCAL_VARIABLE 局部变量
ElementType.FIELD 属性

@Inherited

该注解表明，被注解标注的类，它的所有子类将继承该注解：

java.lang.annotation.Inherited

@Inherited
public @interface MyCustomAnnotation {

}
................................................................
@MyCustomAnnotation
public class MyParentClass { 
  ... 
}
................................................................
public class MyChildClass extends MyParentClass { 
   ... 
}

这里，MyParentClass 使用了标注@inherited 的注解--- @MyCustomAnnotation。这意味着在MyChildClass中，将继承 @MyCustomAnnotation。

@Retention
表明注解保留的时间长度。

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

@Retention(RetentionPolicy.RUNTIME)
@interface MyCustomAnnotation {
    
}

在这里，我们使用了 RetentionPolicy.RUNTIME. 其实，这里还有两个选项。下面我们来分别说明：
RetentionPolicy.RUNTIME: 该注解在运行时可用，通过Java反射获取。
RetentionPolicy.CLASS: 该注解应用于 .class 文件中，但是在运行时不可用。
RetentionPolicy.SOURCE: 该注解在程序源码中可用，在 .class 文件中和运行时均不可用。

用例

for(Class<?> c:clzz){
            if(c.isAnnotationPresent(HandlerType.class)){
                HandlerType handlerType=c.getAnnotation(HandlerType.class);
                ChannelType channelType=handlerType.channelType();
                MessageType messageType=handlerType.messageType();
                try {
                    Object obj= c.newInstance();
                    if(obj instanceof AbstractHandler){
                        handlers.put(getKey(channelType, messageType), (AbstractHandler)obj);
                    }
                }catch (Exception e) {
                    continue;
                }
            }
        }