[java]注解
注解(也被称为元数据)为我们在代码中添加信息提供了一种形式化的方法,使我们可以在稍后某个时刻非常方便地使用这些数据。
注解的语法比较简单,除了@符号的使用之外,它基本上与Java固有的语法一致。java SE5内置了三种,定义在java.lang中的注解:
- @Override,表示当前的方法定义将覆盖父类中的方法。
- @Deprecated,如果程序员使用了注解它的元素,那么编译器将会发出警告信息。
- @Suppress Warnings,关闭不当的 编译器警告信息。在java SE5之前的版本中,也可以使用该注解,不过会被忽略不起作用。
一、元注解
Java目前只内置了三种标准注解,以及四种元注解。元注解专职负责注解其他的注解:
@Target | 表示该注解可以用于什么地方。可能的ElementType参数包括: |
CONSTRUCTOR:构造器的声明 | |
FIELD:域声明(包括enum实例) | |
LOCAL_VARIABLE:局部变量声明 | |
METHOD:方法声明 | |
PACKAGE:包声明 | |
PATAMETER:参数声明 | |
TYPE:类、接口(包括注解类型)或enum声明 |
@Retention | 表示需要在什么级别保存该注解信息。可选的RetentionPolicy参数包括: |
SOURCE:注解将被编译器丢弃 | |
CLASS:注解在class文件中可用,但会被VM丢弃 | |
RUNTIME:VM将在运行期也保留注解,因此可以通过反射机制读取注解的信息 |
@Documented | 将此注解包含在Javadoc中 |
@Inherited | 允许子类继承父类中的注解 |
二、定义注解
在注解中,一般都会包含一些元素以表示某些值。当分析处理注解时,程序或工具可以利用这些值。注解的元素看起来就像接口的方法,唯一的方法是你可以为其制定默认值。
没有元素的注解称为标记注解。
@interface用来声明一个注解,其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称,返回值类型就是参数的类型(返回值类型只能是基本类型、Class、String、enum)。可以通过default来声明参数的默认值。
下面是一个简单的注解,我们可以用它来跟踪一个项目中的用例。
//UseCase.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.METHOD)@Retention(RetentionPolicy.RUNTIME)public @interface UseCase {int id();
String description() default "no description";}
//PasswordUtils.java
import java.util.List;
public class PasswordUtils {@UseCase(id=47,description = "Passwords must comtain at least one numeric")
public boolean validatePassword(String password){return (password.matches("\\w*\\d\\w*"));}@UseCase(id=48)public String encryptPassword(String password){
return new StringBuilder(password).reverse().toString();}@UseCase(id = 49,description = "New passwords can not equal previously used ones")
public boolean checkForNewPassword(List<String> prevPasswords,String password){return !prevPasswords.contains(password);
}}
注解的元素在使用时表现为名-值对的形式,并需要置于@UseCase声明之后的括号内。在encryptpassword()方法的注解中,并没有给出description元素的值,因此,在UseCase的注解处理器分析处理这个类时会使用该元素的默认元素。
三、编写注解处理器
使用注解的过程中,很重要的一个部分就是创建与使用注解处理器。
下面是一个非常简单的注解处理器,我们将用它来读取PasswordUtils类,并使用反射机制查找@UseCase标记。我们为其提供了一组id值,然后他会列出在 PasswordUtils中找到用例,以及缺失的用例。
//UseCaseTracker.java
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
public class UseCaseTracker {public static void main(String[] args) {List<Integer> useCases=new ArrayList<>();
Collections.addAll(useCases,47,48,49,50);trackUseCases(useCases,PasswordUtils.class);
}private static void trackUseCases(List<Integer> useCases, Class<?> cl) {for (Method m:cl.getDeclaredMethods()){
UseCase uc = m.getAnnotation(UseCase.class);
if (uc!=null){System.out.println("Found Use Case:"+uc.id()+" "+uc.description());useCases.remove(new Integer(uc.id()));
}}for (int i:useCases){System.out.println("Warning: Miss use case-"+i);
}}}
输出:
Found Use Case:47 Passwords must comtain at least one numericFound Use Case:48 no descriptionFound Use Case:49 New passwords can not equal previously used onesWarning: Miss use case-50
这个程序用到了两个反射的方法:getDeclaredMethod()和getAnnotation(),它们都属于AnnotatedElement接口(Class、Method和Field等类都实现了该接口)。getAnnotation()方法返回指定类型的注解对象,在这里就是UseCase。如果被注解的方法上没有该类型的注解,则返回null。然后我们通过调用id()和description()方法从返回的UseCase对象中提取元素的值。其中,encryptPassword()方法在注解的时候没有指定description的值,因此处理器在处理它对应的注解时,通过description()方法取得的是默认值no description。
四、注解元素
标签@UseCase由UseCase.java定义,其中包含int元素id,以及一个String元素description。注解元素可用的类型如下所示:
- 所有基本类型(int,float,boolean等)
- String
- Class
- enum
- Annotation
- 以上类型的数组
如果使用其他类型,编译器会报错。
五、默认值设置
元素不能有不确定的值。也就是说,元素必须要么具有默认值,要么在使用注解时提供元素的值。
其次,对于非基本类型的元素,无论是在源代码中声明或是在注解接口中定义默认值时,都不能以null作为其值。这个约束使得处理器很难表现一个元素的存在或缺失的状态,因为在每个注解的声明中,所有的元素都是存在,并且都具有相应的值。。为了绕开这个约束,我们只能定义一些特殊的值,例如空字符串或负数,以表示某个元素不存在。
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.METHOD)@Retention(RetentionPolicy.RUNTIME)@interface SimulatingNull {
int id() default -1;String description() default "";
}
六、生成外部文件
假设你希望提供一些基本的对象/关系映射功能,能够自动生成数据库表,用以存储JavaBean对象。你可以选择使用XML描述文件,指明类的名字、每个成员以及数据库映射的相关信息。然而,使用注解的话,你可以将所有信息都保存在JavaBean源文件中。为此,我们需要一些新的注解,用以定义与Bean关联的数据库表的名字,以及与Bean属性关联的列的名字和SQL类型。
以下是一个注解的定义,它告诉注解处理器,你需要生成一个数据库表:
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Created by pc on 2016/2/18.*/@Target(ElementType.TYPE)@Retention(RetentionPolicy.RUNTIME)public @interface DBTable {public String name() default "";}
在@Target注解中指定的每一个ElementType就是一个约束,它告诉编译器,这个自定义的注解只能应用于该类型。程序员可以指定enum ElementType中的某一个值,或者以逗号分隔的形式指定多个值。如果想要将注解应用于所有的ElementType那么可以省去@Target元注解,不过这并不常见。
注意,@DBTable有一个name()元素,该注解通过这个元素为处理器创建数据库表提供表的名字。
接下来是为修饰JavaBean域准备的注解:
//Constraints.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)public @interface Constraints {boolean primaryKey() default false;boolean allowNull() default true;boolean unique() default false;}
//SQLString.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)public @interface SQLString {int value() default 0;String name() default "";
Constraints constraints() default @Constraints;
}
//SQLInteger.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)public @interface SQLInteger {String name() default "";
Constraints constraints() default @Constraints;
}
注解处理器通过@Constraints注解提取出数据表的元数据,另外两个@interface定义的是SQL类型。这些SQL类型具有name()元素和constraints()元素。后者利用了注解嵌套的功能将column类型的数据库约束信息嵌入其中。注意constraints()元素的默认值时@Constraints。由于@Constraints注解类型之后,没有在括号中指明@Constraints中的元素的值。因此,constraints()元素的默认值实际上就是一个所有元素艘为默认值的@Constraints注解。如果要领嵌入@Constraints注解中的unique()元素为true,并以此作为constraints()元素的默认值,则需要如下定义元素:
public @interface Uniqueness {Constraints constraints() default @Constraints(unique = true);}
下面是一个简单的Bean定义,我们在其中应用了以上的这些注解:
@DBTable(name = "MEMBER")
public class Member {static int memberCount;@SQLString(30)String firstName;@SQLString(50)String lastName;@SQLIntegerInteger age;@SQLString(value = 30, constraints = @Constraints(primaryKey = true))
String handle;public String getHandle() {
return handle;
}public String getFirstName() {
return firstName;
}public String getLastName() {
return lastName;
}public String toString() {
return handle;
}public Integer getAge() {
return age;
}}
类的注解@DBTable给定了值MEMBER,它将会用来作为表的名字。Bean的属性firstName和lastName,都被注解为@SQLString类型,并且其元素值分别为30和50,。这些注解有两个有趣的地方:第一,他们都使用了嵌入的@Constraints注解的默认值;第二,它们都使用了快捷方式,何为快捷方式呢?如果程序员的注解中定义了名为value的元素,并且在应用该注解的时候,如果该元素是唯一需要赋值的一个元素,那么此时无需使用名-值的这种语法,而只需要在括号内给出value元素所需要的值即可。这可以应用于任何合法类型的元素。当然了,这也限制了程序员必须将次元素命名为value,不过在上面的例子中,这不但时语义更清晰,而且这样的注解语句也更容易理解:
@SQLString(30)
处理器将在创建表的时候使用该值设置SQL列的大小。
实现处理器:
import java.lang.annotation.Annotation;
import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.List;
/**
* Created by pc on 2016/2/18.*/public class TableCreator {public static void main(String[] args) throws Exception {if (args.length < 1) {
System.out.println("argument:annotated classes");
System.exit(0);}for (String className : args) {
Class<?> cl = Class.forName(className);DBTable dbTable = cl.getAnnotation(DBTable.class);
if (dbTable == null) {System.out.println("No DBTable annotations in class " + className);
continue;
}String tableName = dbTable.name();//if the name is empty,use the class name
if (tableName.length() < 1) {
tableName = cl.getName().toUpperCase();}List<String> columnDefs = new ArrayList<>();
for (Field field : cl.getDeclaredFields()) {
String columnName = null;
Annotation[] anns = field.getDeclaredAnnotations();if (anns.length < 1) {
continue;
}if (anns[0] instanceof SQLInteger) {SQLInteger sInt = (SQLInteger) anns[0];//Use field name if name not specified
if (sInt.name().length() < 1) {
columnName = field.getName().toUpperCase();} else {
columnName = sInt.name();}columnDefs.add(columnName + " INT " + getConstraints(sInt.constraints()));
}if (anns[0] instanceof SQLString) {SQLString sString = (SQLString) anns[0];if (sString.name().length() < 1) {
columnName = field.getName().toUpperCase();} else {
columnName = sString.name();}columnDefs.add(columnName + " VARCHAR(" + sString.value() + ")" + getConstraints(sString.constraints()));}StringBuilder createCommand = new StringBuilder("CREATE TABLE" + tableName + "(");for (String columnDef : columnDefs)
createCommand.append("\n " + columnDef + ",");String tableCreate = createCommand.substring(0, createCommand.length() - 1) + ");";
System.out.println("Table Creation SQL for " + className + " is :\n" + tableCreate);}}}private static String getConstraints(Constraints con) {String constraints = "";if (!con.allowNull())
constraints += "NOT NULL";
if (con.primaryKey())
constraints += " PRIMARY KEY";
if (con.unique())
constraints += " UNIQUE";
return constraints;
}}
输入args: Member
输出:
Table Creation SQL for Member is :
CREATE TABLEMEMBER(FIRSTNAME VARCHAR(30));Table Creation SQL for Member is :
CREATE TABLEMEMBER(FIRSTNAME VARCHAR(30),LASTNAME VARCHAR(50));Table Creation SQL for Member is :
CREATE TABLEMEMBER(FIRSTNAME VARCHAR(30),LASTNAME VARCHAR(50),AGE INT );Table Creation SQL for Member is :
CREATE TABLEMEMBER(FIRSTNAME VARCHAR(30),LASTNAME VARCHAR(50),AGE INT ,HANDLE VARCHAR(30) PRIMARY KEY);
main()方法会处理命令行传入的每一个类名。使用forName()方法加载每一个类,并使用getAnnotation(DBTable.class)检查该类是否带有@DBTable注解。如果有,就将发现的表名保存下来。然后读取这个类的所有域,并用getDeclaredAnnotation()进行检查。该方法返回一个包含一个域上的所有注解的数组。最后用instanceof操作符来判断这些注解是否是@SQLInteger或SQLString类型,如果是的话,在对应的处理块中将构造出相应column名的字符串片段。注意,由于注解没有继承机制,所以要获得近似多态上网行为,使用getDeclaredAnnotation()是唯一的方法。
嵌套中的@Constraint注解被传递给getConstraints()方法,由它负责构造一个包含SQL约束的String对象。
需要注意的是,上面的演示的技巧对于真实的对象/关系映射而言,是很幼稚的。例如使用@DBTable类型的注解,程序员以参数的形式给出表的名字,如果程序员想要改变表的名字,这将迫使其必须重新编译Java代码。这不是我们希望看到的结果。现在已经有了很多可用的framework,可以将对象映射到关系数据库,并且其中越来越多的framework已经开始利用注解了。