Introduction

The basic goal of the project is to support the inclusion and extraction of custom metadata associated with various program elements of a Java class or interface. An individual element of metadata associated with a program element, for example a method, is commonly referred to as an attribute. These attributes are inserted at compile time and then can be retrieved later at runtime.

An overhaul of the project will take place soon, removing the need for attribute marker interfaces.

Status

In CVS 9/13/03 Added a very experimental compiler adapter for Ant to make compilation easier. It might also be implemented easier using an Ant javac task listener. You can now use attrib4j in your ant file like this.

 
 <property name="build.compiler" value="attrib4j.ant.Attrib4jCompilerAdapter"/>	
 <property name="attrib4j.destdir" value="${build}/generated"/>
 <property name="attrib4j.packages" value="attrib4j.examples.attributes"/>

 <target name="compile" depends="prepare" >
   <javac srcdir="${examples}" 
          destdir="${build}/examples">
   </javac>    
 </target>	

Future release will make it easier to set parameters specific to attrib4j by either using an attrib4jSetup task or the javac task compilerargs attribute.

Release 0.9.0 on 9/12/03 Made the attrib4jCompiler Ant task easier to use. The Ant CompilerAdapter is another approach being investigated. Anyway, now the syntax looks like this

 
  <!-- include the custom task -->
  <taskdef name="attrib4jCompiler" classname="attrib4j.ant.Attrib4jTask"/>

  <target name="compile" depends="example-attributes">
  <attrib4jCompiler sourcepath="${examples}"
                    classpath="${build}/examples"
                    destdir="${build}/generated"
                    attributepackages="attrib4j.examples.attributes">
		<fileset dir="${examples}"/>
    </attrib4jCompiler>
  </target>
	            

The XML attributes for the custom task are the following.

  • sourcepath - The location of the source .java files to parse for javadoc attribute comments.
  • classpath - The location of the corresponding .class files to modify with attribute information.
  • destdir - The location where the modified .class files will be placed. (Currently looking into overwriting in the same location as classpath)
  • attributepackages - Specifies what packages to prepend to classname listed after the javadoc '@' symbol. This allows you not to use the fully qualified name (FQN) when specifying the attribute class in your code

Released 0.8.9 on 9/1/03. Fixed a bug in parsing parameters. You should now put a space after your attribute classname followed by the constructor parenthesis. For example

/**
 * @Pointcut ("* *set(..)")
 */

This is necessary because of how the Javadoc engine parses out the "name" and "text" parts of Javadoc comments. I think QDox has the same requirement. Added a test case for this situation. Fixed a small bug for resolving paths on Unix. Switched to latest Maven, though still use a build.xml for releases and running unit tests.

After quite a bit of time away from the project, I will be starting to attack the issues on the todo list.

You can download Attrib4j here. Read the docs under the links 'Getting Started' and 'Usage' for more detailed information on working with Attrib4j.

Background

The inclusion of attributes as part of Microsoft's .NET framework has increased the attention of how meta-data may be used in day to day programming. Interestingly, there was similar, but more limited, functionality available when Microsoft created their Visual J++ compiler. On the Java side of the fence there have been a couple of efforts geared towards providing similar functionality, most notably the open source project xDoclet and BEA's EJBGen. These both 'hijack' the Javadoc tool provided in the JDK or a similar tool to extract additional meta-data/attributes from program elements. This technique was described in the JavaWorld article by yours truly and inspired the creation of these Javadoc based tools. While this technique is rather effective, there is a desire to formalize this mechanism and introduce meta-data features into the Java language itself. These efforts are being coordinated through the work of the Java Community Process, specifically JSR 175 , "A Metadata Facility for the JavaTM Programming Language".

While the findings of this JSR are not yet public, this project has similar goals and will hopefully be able to bring comparable functionality to versions of the JDK that do not natively support attributes. (Probably pre-1.5 JDKs).

There are now also two other related Java attributes projects. An apache-commons project apache-commons-attributes , Nanning , and Ideanest Attributes

Approach

Attrib4j provides support for creating and manipulating attributes by using the familar Javadoc notation and using byte code manipulation libraries such as BCEL. . The basic approach is to use Javadoc, or another equivalent source code parser such as Qdox, to extract the meta-data tags. BCEL to insert custom attributes into the Java class files. These attributes can then be retrieved later at runtime.

For a more detailed introduction to this software, please read the following Paper ( Note: currenlty not there...will put it up locally soon) Also take a look at the Usage and Getting Started sections.

That's all for now. Keep checking back for updates. Many thanks to Ted Neward for kick starting the code base.

Older News

Released 0.8.8 on 4/23/03. The syntax to specify an attribute has changed! It is no longer required to use the '@attribute' tag before the classname of the attribute. Instead the attribute can be specified immediately following the '@' symbol. For example instead of @attribute Debug(true), you can just directly type @Debug(true). This is a more natural syntax for the user. Valid javadoc documentation tags are still allowed. Note that in the in the current implementation any spaces in the text immediately following the '@' symbol is used by the javdoc engine as the token to seperate the javadoc comment into the 'Name' and 'Text' part. This results in parsing the constructor syntax incorrectly and will be fixed in an upcoming release. The old syntax to declare attributes is still supported by setting the system property attrib4j.Syntax to the value 'javadoc'. Support for the old syntax will be removed in a later release.

Released 0.8.6 on 4/18/03. Inheritance of attribute declared in a superclass or interface are now supported for attributes declared on methods. You can also specify a filter class when retreiving method attributes.

Released 0.8.4 on 4/10/03. You now have the option of not using a fully qualified name (FQN) to specify an attribute class. For example, instead of typing '@attribute attrib4j.examples.attributes.Transaction("Required")', you can now type '@attribute Transaction("Required")'. In order to do this you must specify a comma delimited list of package names to the attribute compiler that will be prepended to the classname specified after the @attribute tag. The option is named 'attributepackages' and it is also exposed in the Ant task.

Released 0.8.2 on 4/1/03. Added first iteration of custom Ant task. Updated docs. Misc improvements to doclet. General code cleanup. 4/1/03

Made a first relase. 0.8.0 on 3/21/03 Wrote getting started documentation.

Restructured the package by introducing a base class 'Attribute' and a class 'Attributes' that contains convenience methods to access attributes. Only the BCEL implementation has been updated to reflect these changes. This should make it easier to use the package. 3/18/02

A long time away :-( Started to add support to handle 'ordinary' Javadoc comments. An option to the doclet -usejavadocattributes true will trigger the creation of a attribj4.attributes.JavadocAttribute for each Javadoc tag that does not start with '@attribute'. Added simple support to specify 'filters' when asking for attributes. Attribute.getCustomClassAttribute(Class c, Object o), where object 'o' is an instance that acts as a filter. Need to clean up the retrieval interface - make it more clean etc. 12/14/02

Put method parameter matching in BCEL Extractor, Improved tests. Code clean up. 11/20/02

Added first support for method and field attributes with bcel. 11/19/02

Abstract factory for bytecode library 11/5/02

Initial import. 10/29/02

Last Updated: April 23, 2003.