Apache Commons项目简介之Attributes

                        Apache Commons项目简介之Attributes
0.简介
Apache Commons项目是专注于开发可重用的Java组件。
Apache Commons项目由三部分组成：
Commons Proper - 可重用Java组件库。
Commons Sandbox - Java组件开发工作空间。
Commons Dormant - sandbox中不活跃的项目存储库。
Apache Commons开发人员使每个组件尽可能少的依赖其他的lib，以便这些组件可以方便的部署，而不是需要将依赖的库依次部署。另外，Commons组件的接口尽可能的保持不变，这样可以在实现这些组件的时候针对接口进行开发，确保兼容性。
本文主要介绍第一部分的项目，即可重用的稳定的Java组件库。由于库中的每个子项目都包含了特定的功能，所以本文不会对这些功能面面俱到的介绍，而是针对库中的每个子项目，尽可能的介绍其应用场景，以及列举典型的样例。

1.Attributes介绍
Attribute是可以添加到类，方法以及成员的有值对象。该对象是只读的，常量，可以被其他具有相同值的对象进行无缝替代。例如，java.lang.Integer就是值对象，可以使用任何其他的同类的其他实例来替换当前的实例，前提是它们是equal的。而java.io.Socket就不是值对象，因为不能将一个socket实例使用其他的实例替换，因为它反应一个真实的资源，即链接。
因此，attribute类是可变的。并且不能使用Socket或者类似的类作为属性。

为类添加属性的一般方式如下，其中方括号内的为可选的：
@@[target] ClassName([constructor args] [named args])
target：attribute将被应用到那些子元素上面。类和成员没有子元素，但是方法有。方法的子元素可以是参数或者返回值。如果是参数，那么就使用.argument名字，例如：
/**
 * @@.arg1 MyAttribute()
 */
public Object myMethod (int arg1) { ... }
这样就可以将MyAttribute附加到方法的第一个参数上，而不是方法本身，这个属性通过Attributes.getParameterAttributes(Method, int)。
而为返回值添加属性是使用.return：
/**
 * @@.return MyAttribute()
 */
public Object myMethod (int arg1) { ... }
该属性可以通过Attributes.getReturnAttributes(Method)来获取。
ClassName：表示属性类的名字。可以使用full qualified name或者unqualified name。
constructor args：传递给构造方法的参数。
name args：通过使用set方法来为属性设置值。

所有属性的值的获取都是通过org.apache.commons.attributes.Attributes方法来获取的，详细api请参考JavaDoc。

attribute类必须包含了一个public的构造方法。

2.Attributes Demo程序
Attributes子项目可以供java开发人员来使用C#/.Net风格的属性。
a.Ant样例：
前提条件：下载以下jar文件并将其放在ANT安装目录的lib中。
关于Ant的更多信息，请参考：http://ant.apache.org/
    *api: commons-attributes-api-2.2.jar
    http://www.ibiblio.org/maven/commons-attributes/jars/commons-attributes-api-2.2.jar
    注意不要修改这个文件的名字，因为在build.xml文件中使用了该名字。
    *Ant task: commons-attributes-compiler-2.2.jar
    http://www.ibiblio.org/maven/commons-attributes/jars/commons-attributes-compiler-2.2.jar
    注意不要修改上面的两个文件的名字，因为在build.xml文件中使用了该名字。
    *qDox 1.5: qdox-1.5.jar
    http://www.ibiblio.org/maven/qdox/jars/qdox-1.5.jar

样例java代码如下：
import org.apache.commons.attributes.Attributes;

class MyAttribute {
    private final String ctorArg;
    private String namedArg = null;
   
    public MyAttribute (String ctorArg) {
        this.ctorArg = ctorArg;
    }
   
    public void setNamedArgument (String namedArg) {
        this.namedArg = namedArg;
    }
   
    public String toString () {
        return "[MyAttribute  constructor argument: /"" +
            ctorArg + "/" named argument: /"" + namedArg + "/"]";
    }
}
上面的类MyAttribute只是一个简单的java类，定义了一个常量和一个成员变量以及用于初始化常量的构造方法。
/**
 * @@MyAttribute ("This string is passed to the constructor.",
 *                namedArgument="This argument will be passed to the setNamedArgument method")
 */
public class AttributeDemo {
    public static void main (String args[]) {
        System.out.println (Attributes.getAttributes (AttributeDemo.class));
    }
}
通过使用Commons Attributes，我们给AttributeDemo类添加了一个实例，两个@表示这是一个属性，这使得Attribute编译器获取这个属性，第一个字符串传递给构造方法，第二个参数的格式为name = expression,结果是setNamedArgument被调用。
在main方法中，Attributes.getAttributes方法会返回附加给AttributeDemo类的所有属性集合。
build.xml文件只是包含了clean，compile-attributes，compile，run以及javadoc这些target。其中attibute-compiler的作用是生成额外的java source类(每个使用attributes的类都会生成一个额外的java类)。接下来这些额外的java source回合初始的java source一起被编译：
+------------+                              +--------------------+
|Java Sources|----> Attribute Compiler ---->|Generated Java Files|  
+------------+                              +--------------------+
      |                                                 |
      |                                                 |
      |               +-------------+                   |
      +-------------->|Java Compiler|<------------------+
                      +-------------+
                             |
                             v
                    +-----------------+
                    |Java .class files|
                    +-----------------+
！当然，在使用之前需要通过taskdef来启用Attribute Compiler。
<project default="run" name="commons-attributes ant demo" basedir=".">
    <taskdef resource="org/apache/commons/attributes/anttasks.properties"/>
接下来，就是使用Attribute编译器对java source进行编译：
<target name="compile-attributes" description="o Run the commons-attributes precompiler">
    <attribute-compiler destdir=".">
        <fileset dir="." includes="*.java"/>
    </attribute-compiler>
</target>
该步骤的结果就是生成包含attributes信息的java source文件。为既存的.java文件自动生成attribute repositories(.java文件)，一旦生成成功之后，就可以进行正常的编译了。

在上面的例子中，使用了QDox项目的jar作为依赖。QDox是一个高速，低耗的javadoc解析器，用于从源代码中获取类/接口/方法的javadoc注释(即带@标记的注释)。主要用于代码生成器或者文档工具。笔者会在稍后的一篇文章中进行详细的介绍。

b.Maven样例
所有的文件都包含在maven_demo.zip(http://commons.apache.org/attributes/maven_demo.zip)中。
为了运行该程序，需要完成以下工作：
声明依赖-->安装commons-attributes插件-->通过设置project属性来启用插件。
声明依赖关系：
<dependency>
    <groupId>commons-attributes</groupId>
    <artifactId>commons-attributes-api</artifactId>
    <version>2.2</version>
</dependency>

<dependency>
    <groupId>commons-attributes</groupId>
    <artifactId>commons-attributes-compiler</artifactId>
    <version>2.2</version>
</dependency>
安装插件：
可以通过运行maven命令：
$ maven install
$ maven install-plugin
或者下载插件到maven的plugin目录来安装插件。
设置properties属性：
由于Maven会将所有的插件应用到所有被编译的projects，所以有必要显式的启用attribute compiler，以免不需要该插件的project错误的使用。
######################################################################
# Commons-Attributes
######################################################################
org.apache.commons.attributes.enable=true
org.apache.commons.attributes.index.enable=true

可以通过以下的命令运行程序：
$ unzip maven_demo.zip
$ cd maven_demo
$ maven run

3.依赖项目
ant1.5
maven-xdoc-plugin1.9.2(Site Only - v1.9.2)
qdox1.5
xerces2.2.1
xml-apis1.0.b2

4.后记
实际上，Attributes的功能与Tiger(Java5.0)中的annotations是一致的，可能5.0中的annotations的功能更强大一些。但是对于使用Java低版本sdk的用户来说，Commons-Attributes还是一个选择。
Apache开发人员的建议是，如果可以升级到5.0，那么尽量升级到5.0，而不是使用Attributes。一旦5.0的普及程度达到1.3和1.4的时候，关于metadata的其他开发都会停止，例如JSR175，MetaClass，qDox，JAM等。但是相对于这几种metadata框架，Attributes具有简单易用的API，强大的annotation特点，类型安全以及低消耗等特点。

5.小结
本文简要的介绍了apache commons项目的子项目Attributes项目的使用。