8
Creating New Annotation Types

8.1.1 AnnotationProperties Element

The AnnotationProperties element contains elements that provide information about the annotation as a whole. These elements are the following:

• Name: Required element. It contains the name of the new annotation type.

• Version: Required element. It contains the version number.

• Description: Optional element. It contains a brief description of the annotation as a whole.

• Extends: Optional element. It contains the name of another annotation type, which your new annotation type will extend. That is, your new annotation type will include all the attribute definitions from the given annotation type, as well as any additional attributes that you define.

  However, you cannot write over the attributes that are inherited from the existing annotation type; you can create only new attributes. If you want to create an annotation type that is not related to another annotation type, do not include the Extends element.

• Contains: Reserved element. Do not assign a value to this element.

• ClassName: Reserved element. Do not assign a value to this element.

• IconFileName: Reserved element. Do not assign a value to this element.

8.1.2 AttributeDescriptors Element

The AttributeDescriptors element contains one or more AttributeDescriptor elements. An AttributeDescriptor element contains one AttributeProperties element.

An AttributeProperties element contains elements that provide information about the specific attributes of your new annotation type. These elements are the following:

• AttributeName: Required element. It contains the name of your new attribute.

• AttributeType: Required element. It contains the Java object type of the attribute value. AttributeType must be a Java object type; Java primitive types are not allowed in your XML document. For example, if you want to use an integer, do not use int, but rather java.lang.Integer.

  Almost any Java object type can be used as the AttributeType, as long as the Java object type defines two valid methods: public String toString( ) and public static Object valueOf(String), where Object is the Java object type. These methods return the contents of the object as a valid String and return the contents of a given String as a valid object of type Object, respectively.

  The class java.util.Date is a special case; it does not use the previous methods to provide a String representation of the contents of the object. Instead, it uses the AttributeTypePattern element.

• AttributeTypePattern: Optional element which should be used only if the AttributeType is java.lang.Date. This element specifies the String pattern that should be used when displaying the date. The pattern follows the syntax in java.text.SimpleDateFormat.

• AttributeAlias: Optional element. It defines a shorter attribute name for display purposes.

• AttributeDescription: Optional element. It defines a short description of the attribute.

• AttributeDefaultValue: Optional element. It defines the default value of the attribute to be inserted in the annotation.

8.1.3 Element Hierarchy

In general, the structure of your XML document should be similar to the following:

<?xml version="1.0">

<!DOCTYPE AnnotationDescriptor SYSTEM "AnnotationDescriptor.dtd>

<AnnotationDescriptor>

   <AnnotationProperties>

      <Name>...</Name>

      <Version>...</Version>

      <Description>...</Description>

      <Extends>...</Extends>

   </AnnotationProperties>

   <AttributeDescriptors>

      <AttributeDescriptor>

         <AttributeProperties>

            <AttributeName>...</AttributeName>

            <AttributeType>...</AttributeType>

            <AttributeTypePattern>...</AttributeTypePattern>

            <AttributeAlias>...</AttributeAlias>

            <AttributeDescription>...</AttributeDescription>

            <AttributeDefaultValue>...</AttributeDefaultValue>

         </AttributeProperties>

      </AttributeDescriptor>

      <AttributeDescriptor>

      .

      .

      .

      </AttributeDescriptor>

   </AttributeDescriptors>

</AnnotationDescriptor>