全面解析Java中的注解与注释

注解
一、什么是 Annotation？ （注解 or 注释）
Annotation, 准确的翻译应该是 -- 注解。 和注释的作用完全不一样。
Annotation 是JDK5.0及以后版本引入的一个特性。 与类、接口、枚举是在同一个层次，可以成为java 的一个类型。
语法是以@ 开头
简单来说，
注释是程序员对源代码的类，方法，属性等做的一些记忆或提示性描述(比如这个方法是做什么用的)，是给人来看的。
注解则是Java 编译器可以理解的部分，是给编译器看的。
举个简单的例子来看一下注解的使用和作用。
@Override 是比较常见的Java 内置注解，它的作用就是在编译代码的时候检查子类中定义的方法是否正确。

package annotation; 

public abstract class Animal { 

  public abstract void eat();
} 

package annotation; 

public class Cat extends Animal{ 

  @Override
  public void eat(String food) {
  }
}

这里在子类Cat中 eat 方法被注解为覆写父类的方法， 但是却比父类方法多出一个参数。
如果是在Eclipse 在编辑的话， 直接就会有红色叉叉提示。(代码编译会通不过)。
如果去掉@Override的注解的话， 编译没问题， 但是Cat 中eat方法就是这个类的一个新的方法了，而不是从父类继承的了。

二、常见的Java 内置注解
包含@Override ， 还有哪些常见的Java内置注解？
1. @Deprecated
注解为不建议使用，可以用在 方法和类上。
基本上这种方法和类都是因为升级或性能上面的一些原因废弃不建议使用，但是为了兼容或其他原因，还必须保留。
所以就打上这个注解。
在Java 本身的API中就有很多这样的例子， 方法打上了这个注解，进到Source code 会看到替代的新的方法是哪个。
在eclipse 中编写code时，添加此注解的方法在声明和调用的地方都会加上删除线。

2.@Override

3.@SuppressWarnings
忽略警告。
如果你的code在转型或其他的部分有一些警告的话，但是你又想忽略这些警告，就可以使用这个注解了。
1)deprecation 使用了不赞成使用的类或方法时的警告

2)unchecked 执行了未检查的转换时警告

3)fallthrough 当使用switch操作时case后未加入break操作，而导致程序继续执行其他case语句时出现的警告

4)path 当设置一个错误的类路径、源文件路径时出现的警告

5)serial 当在可序列化的类上缺少serialVersionUID定义时的警告

6)fianally 任何finally子句不能正常完成时警告

7)all 关于以上所有情况的警告

三、自定义注解
除了Java本身提供的内置注解， Java 还提供了定制自定义注解的功能。
定义的方式就是使用注解定义注解， 用来定义注解的注解称为元注解。
主要的元注解有以下四个：@Target ；@Retention；@Documented；@Inherited
1. @Target 表示该注解用于什么地方，使用在类上，方法上，或是属性等
可能的 ElemenetType 参数包括：
ElemenetType.CONSTRUCTOR 构造器声明
ElemenetType.FIELD 域声明（包括 enum 实例）
ElemenetType.LOCAL_VARIABLE 局部变量声明
ElemenetType.METHOD 方法声明
ElemenetType.PACKAGE 包声明
ElemenetType.PARAMETER 参数声明
ElemenetType.TYPE 类，接口（包括注解类型）或enum声明
2. @Retention 表示在什么级别保存该注解信息
可选的 RetentionPolicy 参数包括：
RetentionPolicy.SOURCE 注解将被编译器丢弃
RetentionPolicy.CLASS 注解在class文件中可用，但会被VM丢弃
RetentionPolicy.RUNTIME VM将在运行期也保留注释，因此可以通过反射机制读取注解的信息。
3. @Documented ，产生doc时，是否包含此注解
将此注解包含在 javadoc 中
4.  @Inherited
允许子类继承父类中的注解
看一些简单定义的例子：

package annotation; 

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; 

@Target(ElementType.METHOD)
public @interface MyAnnotation {
  String value();
} 

@Retention(RetentionPolicy.SOURCE)
@interface MyAnnotation1 { }  

@Retention(RetentionPolicy.CLASS)
@interface MyAnnotation2 {}  

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

@Documented
@interface MyAnnotation4 {} 

@Inherited
@interface MyAnnotation5 { }

四、使用例子：

package annotation; 

import java.lang.annotation.Annotation; 

@MyAnnotation3
public class TestAnnotation {
  public static void main(String[] args) {
    // TODO Auto-generated method stub
    Annotation annotation = TestAnnotation.class.getAnnotation(MyAnnotation3.class);
    System.out.println(annotation.toString());
  } 

}

打印出结果： @annotation.MyAnnotation3()
以上例子如果替换使用 MyAnnotation1 和 MyAnnotation2 的话， 则取到的annotation的值为空，这就是RetentionPolicy 不同的差别。

五、Annotation的作用

介绍到此，可以总结一下Annotation的作用了。
基础的大致可以分为三类:
1. 编写文档
2. 代码分析
3. 编译检查
但是，开源框架对其赋予了更多的作用
比如：
Hibernate,注解配置，

@Column("aa")
private String xx;

这个类似于XML配置，简化程序中的配置
相对与把一部分元数据从XML文件移到了代码本身之中，在一个地方管理和维护。
内部如何实现的？ -- java 反射机制，类似与以上例子。

注释
虽然注解、注释只相差一个字，但是用法就差异很大。
还是那句话， 注解给编译器看， 注释是给人看的。
基于此的话， 对于一个方法来说：
1. 把这个方法的作用， 输入，输出描述清楚就可以了，更多的可以加上一些作者呀，版本呀这样一些信息
2. 注释编排的美观一些
做到这两点应该就可以了。 举个例子：

/*******************************************************************************
* NAME:     usage
* DESCRIPTION: XXX
* ARGUMENTS:  N/A
* RETURN:
* AUTHOR:    oscar999
* VERSION:   V0.1
*******************************************************************************/

看上去这是一个不错的注释^^.

但是对于Java 语言来说， 注释被赋予了更多的功能。 就是你可以使用javadoc 这个功能把代码中的注释导出到  html 的文件中。
如果你的代码是共用性很高的代码的话， 这份文档就是一份API的参考文档， 类似Java API.
所以， 要产生出这样的文档，就要遵循java 定义的一些注释规范， 才能产生出规范的文档出来。

一、Java 类方法的标准注释
还是从类的方法的注释说起。

  /**
   * Read a line of text. A line is considered to be terminated by any one
   * of a line feed ('\n'), a carriage return ('\r'), or a carriage return
   * followed immediately by a linefeed.
   *
   * @param   ignoreLF1 If true, the next '\n' will be skipped
<pre code_snippet_id="74911" snippet_file_name="blog_20131120_2_8365599" name="code" class="java">   * @param   ignoreLF2 If true, the next '\n' will be skipped</pre>   *   * @return   A String containing the contents of the line, not including   *       any line-termination characters, or null if the end of the   *       stream has been reached   *   * @see    java.io.LineNumberReader#readLine()   *   * @exception IOException If an I/O error occurs   */

（不去关注以上注释的意义，只关注其定义的样式）
1. 首先看最上面的 “Read a line of text.  A line .. ” 这一段是对这个方法的一些描述。

第一个句号前面的部分， 也就是 “Read a line of text.” 会出现在 “方法摘要” 中

2. @param 定义的是方法的输入参数，（可以添加多个）出现在“ 方法详细信息” 中。（参数和参数描述之间使用空格隔开， 在产生的文档中转成了  -）

3. @return  返回值的描述
4. @see  参考的描述
5. @exception 异常抛出的描述
美观考虑， 不同类的标签可以换一行显示， 比如 @param 和 @return 直接空一行。

二、Java 类标准注释
类的注释和方法注释的格式基本相同。 区别的地方：
1. 放置的位置不同。 类的注释放在类定义的上面， 方法的注释放在方法定义的上面。
2. 类的注释比较会使用   @version  @author  @since 这样的标签。
看模板

/** will buffer the input from the specified file. Without buffering, each
* invocation of read() or readLine() could cause bytes to be read from the
* file, converted into characters, and then returned, which can be very
* inefficient.
*
*
* Test Description
*
* <p> Programs that use DataInputStreams for textual input can be localized by
* replacing each DataInputStream with an appropriate BufferedReader.
*
* @see FileReader
* @see InputStreamReader
*
* @version 0.1, 11/20/13
* @author  oscar999
* @since  JDK1.5
*/

doc 中显示的效果是：
同样， 描述的第一句出现在“类概要”中。

类的详细信息显示如下：

值得注意的是 description 中<p> 的使用。 如果没有加<p> , 在java code 中不管是否有换行，产生的doc 中都不换行。 加上<p> 的话， doc 中出现换行。

三、补充
补充一下， 产生javadoc的方法：
1. 命名行方式：  javadoc  + 参数

2. 使用Eclipse IDE 导出
如果在Eclipse IDE 中， 在源文件或是项目上右键单击 , 选 Export  --->
Java --> Javadoc 就可以产生了。