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();
}
以上我们仅定义了默认值为“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处理程序负责它按照完全随机的无法预知的顺序执行。当所有的测试方法都相互独立的时候，不推荐使用这个注解。但是，当测试的场景需要测试方法按照一定规则的时候，这个注解就派上用场了。
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;
<span style="color: #000000;">为了指定标准的SQL表列名，我们可以写如下注解：</span>
@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 );
<span style="color: #000000;">程序产生的输入如下：</span>
<?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中一种分析元数据的强大机制，可以在不同的程序中担任不同的作用，例如校验，依赖注入，单元测试。
14. 下载
这是一个java注解的教程。
你可以从这里下载本教程所有代码: customAnnotations ( http://a3ab771892fd198a96736e50.javacodegeeks.netdna-cdn.com/wp-content/uploads/2014/11/customAnnotations.zip )
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