Introduction

There are two supported mechanisms for accessing Attributes about a Class or a Package at runtime. The first method allows the developer to access the complete metadata structure for the class or package. The second approach is to use the Attributes utility class to access attributes about specific programming elements.

The Attributes Utility Class

The Attributes utility class exists to simplify access to class attributes. The Attributes class has several static methods that allow you to retrieve the attributes associated with a particular programming element. The developer can also retrieve all attributes with a particular name or just the first attribute with a particular name. These methods were designed to match common use cases.

Consider the example where you have a source file marked up as follows.

/**
 * @dna.component
 * @dna.service type="MyService"
 * @dna.service type="MyExtendedService"
 */
public class MyClass
   implements MyService, MyExtendedService
{
   ...
}

The developer could access all the Attributes for MyClass using the following code;

// The return value must contain the three
// attributes; dna.component and two
// dna.service attributes
Attribute[] attributes =
    Attributes.getAttributes( MyClass.class );

Alternatively the developer could just access the attributes with the name "dna.service" using the following code;

// The return value must contain the two
// "dna.service" attributes
Attribute[] attributes =
    Attributes.getAttributes( MyClass.class, "dna.service" );

The developer could also access the single "dna.component" attribute using;

// The return value must be the dna.component attribute
Attribute attribute =
    Attributes.getAttribute( MyClass.class, "dna.component" );

Equivelent methods exist for retrieval of attributes for methods and fields. Rather than passing the Class instance in the developer passes the Field or Method object.

// Get all attributes attached to doMagic() method
Method method =
    MyClass.class.getMethod( "doMagic", new Class[0] );
Attribute[] attributes =
    Attributes.getAttributes( method );

// Get all attributes attached to m_magicLevel field
Field field =
    MyClass.class.getField( "m_magicLevel" );
Attribute[] attributes =
    Attributes.getAttributes( field );

Equivelent methods exist for retrieval of attributes for methods and fields. Rather than passing the Class instance in the developer passes the Field or Method object.

// Get all attributes attached to doMagic() method
Method method =
    MyClass.class.getMethod( "doMagic", new Class[0] );
Attribute[] attributes =
    Attributes.getAttributes( method );

// Get all attributes attached to m_magicLevel field
Field field =
    MyClass.class.getField( "m_magicLevel" );
Attribute[] attributes =
    Attributes.getAttributes( field );

The Package programming element is not handled in an identical manner. The java.lang.Package is not associated with a particular ClassLoader but is global to the JVM. However the same package may have classes in multiple different ClassLoaders and each different ClassLoader may contain different metadata about the same Package. Thus the Attributes utility class does not support access to Package attributes and the complete PackageDescriptor must be loaded via standard mechanisms.

Accessing Complete Descriptors

The other method of accessing metadata about programming elements is to directly load and manipulate the PackageDescriptor and ClassDescriptor objects. The developer accesses the descriptors using the MetaClassIntrospector to retrieve the ClassDescriptor and PackageDescriptor objects. The Descriptors can then be traversed to access the relevent metadata such as Method and Field attributes. See below for an example usage and the API docs for detailed description of the Descriptor objects.

ClassDescriptor clazzDescriptor =
    MetaClassIntrospector.getClassDescriptor( MyClass.class );

FieldDescriptor[] fields = clazzDescriptor.getFields()
processFields( fields );

MethodDescriptor[] methods = clazzDescriptor.getMethods()
processMethods( methods );

PackageDescriptor pakkageDescriptor =
    MetaClassIntrospector.getPackageDescriptor( MyClass.class );
Attribute[] attributes = pakkageDescriptor.getAttributes();