在Groovy中使用注解（Annotations） [Groovy文档翻译]

在Groovy中使用注解（Annotations）

介绍

Java 5以上支持使用注解来将元数据包括在程序之中。 Groogy1.1以上也支持这样注解。

注解被用于提供信息给相关工具集和程序库。他们直接地在原始代码存放和提供元数据信息。否则，这些所需的信息将通过使用非声明的方式或使用外部文件来提供。我们不想在这里讨论什么时候使用注解的才适合，只是给您一个快速的认识来理解Groogy的注解。

注解的定义很像Java类文件，但是它使用了@interface关键字。举个例子，这里给出了你怎么样在Java定义一个FeatureRequest注解：

// Java
public @interface FeatureRequest {
    String key();
    String summary();
    String assignee() default "[unassigned]";
    String status() default "[open]";
    String targetVersion() default "[unassigned]";
}

您可能在主题跟踪工具中有这个注解所代表的这种信息。您可以在一个Groovy文件中以如下的方式来使用这个注解：

@FeatureRequest(
    key="GROOVY-9999",
    summary="Support Graphical Annotations",
    assignee="Pete",
    status="Open",
    targetVersion="5.0"
)
class SomeClassWhereFeatureCouldBeUsed {
   // ...
}

现在，如果您有理解这个注解的工具或者程序库，您就可以处理这个源文件(或编译后的类文件)并基于这些得到的元数据执行相关操作。

和你可以定义自己的多种不同的注解一样，现在已经存在许多的工具，程序库和框架来处理这些注解。

要查看这些例子，请参考本页页底给出的资源。

只作为一个例子，这里展示了你该怎样配合Hibernate或者JPA来使用注解：

import javax.persistence.*
 
@Entity
@Table(name="staff")
class Staff implements Serializable {
    @Id @GeneratedValue
    Long id
    String firstname
    String lastname
    String position
}

示例

作为另外一个例子，参考这个XStream例子。

XStream是一个将Java(或者Groovy)对象序列化到XML（或者反序列化回去）的程序库。这个例子展示了在没有使用注解的情况下你该怎样使用它。

// require(groupId:'com.thoughtworks.xstream', artifactId:'xstream', version:'1.3')
import com.thoughtworks.xstream.*
 
class Staff {
    String firstname, lastname, position
}
 
def xstream = new XStream()
def john = new Staff(firstname:'John',
                     lastname:'Connor',
                     position:'Resistance Leader')
 
println xstream.toXML(john)

这是输出结果：

<Staff>
  <firstname>John</firstname>
  <lastname>Connor</lastname>
  <position>Resistance Leader</position>
</Staff>

只作为一个离题的和注解不相关的说明，这里展示了你该怎样将XML写入一个文件中：

new File("john.xml").withOutputStream { out ->
    xstream.toXML(john, out)
}

接着，展示了你可以怎样将它读（从文件中）回来：

// require(groupId:'com.thoughtworks.xstream', artifactId:'xstream', version:'1.3')
// require(groupId:'xpp3', artifactId:'xpp3_min', version:'1.1.4c')
import com.thoughtworks.xstream.*
 
class Staff {
    String firstname, lastname, position
}
 
def xstream = new XStream()
def john
// now read back in
new File("john.xml").withInputStream { ins ->
    john = xstream.fromXML(ins)
}
 
println john.dump()
// => <Staff@12d96f2 firstname=John lastname=Connor position=Resistance Leader>

现在，重点移到注解上来。。。

XStream也允许您更多的控制产生出来的XML (假如您不喜欢它的缺省值)。

这个工作可以通过调用API或者使用注解来完成。

这里就展示了我们该怎样使用XStream的注解来标注我们的Groovy类以便修改产生的XML:

// ...
import com.thoughtworks.xstream.annotations.*
 
@XStreamAlias("person")
class Associate {
    @XStreamAsAttribute
    @XStreamAlias('first-name')
    String firstname
 
    @XStreamAlias('surname')
    String lastname
 
    @XStreamOmitField
    String position
}
 
msg = new Associate(firstname:'Sarah',
                    lastname:'Connor',
                    position:'Protector')
Annotations.configureAliases(stream, Associate)
println stream.toXML(msg)

当运行的时候，它将产生如下输出：

<person first-name="Sarah">
  <surname>Connor</surname>
</person>

与Java的不同

注解可能包含列表。当在Groovy中使用注解的时候，要记住使用Groovy所支持的方括号来标记列表而不是使用Java中默认使用的括号，比如：

// Java
@ManagedOperationParameters({
    @ManagedOperationParameter(name="x", description="The first number"),
    @ManagedOperationParameter(name="y", description="The second number")})

将变成：

// Groovy
@ManagedOperationParameters([
    @ManagedOperationParameter(name="x", description="The first number"),
    @ManagedOperationParameter(name="y", description="The second number")])

进一步趋势

Groovy注解的当前工作集中在使Java注解能够被用于Groovy中。

Groovy注解的进一步的工作可能包括允许您编辑注解定义自身，并且极大可能在Groovy语言本身或者其附带工具中使用注解。