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风格的属性。
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注释(即带@标记的注释)。主要用于代码生成器或者文档工具。

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特点，类型安全以及低消耗等特点。