全面解析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 就可以产生了。

(0)

相关推荐

  • java注解的全面分析

    全面解析java注解 Java中的常见注解 a.JDK中的注解 @Override 覆盖父类或者父接口的方法     @Deprecated 表示方法已经过时     @SuppressWarnings("deprecation") 忽略方法过时警告 b.常见的第三方注解 例如Spring中的@Autowired(自动注入) 注解的分类 a.按照运行机制分 1.源码注解         注解只在源码中存在,编译成class文件就不存在了 2.编译时注解         注解在源码和cl

  • Java注解之Retention、Documented、Inherited介绍

    Retention注解 Retention(保留)注解说明,这种类型的注解会被保留到那个阶段. 有三个值: 1.RetentionPolicy.SOURCE -- 这种类型的Annotations只在源代码级别保留,编译时就会被忽略 2.RetentionPolicy.CLASS -- 这种类型的Annotations编译时被保留,在class文件中存在,但JVM将会忽略 3.RetentionPolicy.RUNTIME -- 这种类型的Annotations将被JVM保留,所以他们能在运行时

  • 详解Java Spring各种依赖注入注解的区别

    注解注入顾名思义就是通过注解来实现注入,Spring和注入相关的常见注解有Autowired.Resource.Qualifier.Service.Controller.Repository.Component. Autowired是自动注入,自动从spring的上下文找到合适的bean来注入 Resource用来指定名称注入 Qualifier和Autowired配合使用,指定bean的名称 Service,Controller,Repository分别标记类是Service层类,Contro

  • 详解Java的Spring框架中的注解的用法

    1. 使用Spring注解来注入属性 1.1. 使用注解以前我们是怎样注入属性的 类的实现: class UserManagerImpl implements UserManager { private UserDao userDao; public void setUserDao(UserDao userDao) { this.userDao = userDao; } ... } 配置文件: <bean id="userManagerImpl" class="com.

  • Java Annotation(Java 注解)的实现代码

    如果你想知道java annotation是什么?你可以先看看:"http://www.infoq.com/articles/Annotation-Hammer" 下面是我做的一个demo: 项目结构: 运行效果: ==================================================== 代码部分: 注:很多人会考虑这个问题,"这样做的目的是什么?我们可以做一个配置文件(xml,properties等),不是比这个跟方便...或者说 直接把我们

  • Java中三种简单注解介绍和代码实例

    简单Java注解 JDK5提供的简单注解类型只有3个. 这三个都是用来预防错误或者进行提醒的,分别是: 1.Override 2.Deprecated 3.Suppresswarnings 需要注意,JDK5(另一个说法,Tiger)实际上并没有许多内置注解;相反,它允许核心Java支持注解特性的能力. JSR-175中严格规定它用来定义元数据功能. 需要由程序员编写自定义的注解类型,其他JSR标准也编写了一系列标准注解类型. 下面将用实例来深入讲解这三个简单注解. Override 注解 Ov

  • java教程之java注解annotation使用方法

    1.概述 注解可以定义到方法上,类上,一个注解相当与一个类,就相当于实例了一个对象,加上了注解,就相当于加了一个标志. 常用的注解:@Override:表示重新父类的方法,这个也可以判断是否覆盖的父类方法,在方法前面加上此语句,如果提示的错误,那么你不是覆盖的父类的方法,要是提示的没有错误,那么就是覆盖的父类的方法.@SuppressWarnings("deprecation"):取消编译器的警告(例如你使用的方法过时了)@Deprecated:在方法的最上边也上此语句,表示此方法过时

  • Java8中的类型注解浅析

    注解大家都知道,从java5开始加入这一特性,发展到现在已然是遍地开花,在很多框架中得到了广泛的使用,用来简化程序中的配置.那充满争议的类型注解究竟是什么?复杂还是便捷? 一.什么是类型注解 在java 8之前,注解只能是在声明的地方所使用,比如类,方法,属性:java 8里面,注解可以应用在任何地方,比如: 创建类实例 复制代码 代码如下: new @Interned MyObject(); 类型映射 复制代码 代码如下: myString = (@NonNull String) str; i

  • java自定义注解接口实现方案

    java注解是附加在代码中的一些元信息,用于一些工具在编译.运行时进行解析和使用,起到说明.配置的功能. 注解不会也不能影响代码的实际逻辑,仅仅起到辅助性的作用.包含在 java.lang.annotation 包中. 1.元注解 元注解是指注解的注解.包括 @Retention @Target @Document @Inherited四种. 1.1.@Retention: 定义注解的保留策略 Java代码 复制代码 代码如下: @Retention(RetentionPolicy.SOURCE

  • 小议Java中@param注解与@see注解的作用

    @ param @ param标签可以归档方法或构造器的某个单一参数,或者归档类.接口以及泛型方法的类型参数.在使用@ param标签时,我们应该针对方法的每一个参数都使用一个该标签.每个段落的第一个词会被当作参数名,而余下的部分则会被当作是对它的描述: @param max The maximum number of words to read. 当归档类型参数时,我们应该在类型参数名两边加上<和>: @param一e element type of this List 然而,类型参数通常并

随机推荐