10
Creating New Annotation Types

In addition to the supplied annotation types, you can use interMedia Annotator to create your own annotation types in order to better meet the needs of your applications. For example, the owner of an online sales database can define annotations containing inventory and price information alongside the media data and the extracted metadata.

For a complete example of a user-defined annotation type, see <ORACLE_HOME>\ord\Annotator\demo\examples\SampleInventoryAnn.xml, which is included in the Annotator installation.

10.1 Writing a New Annotation Type

You define a new annotation type in an XML file. The XML file must follow the AnnotationDescriptor document type definition (DTD), found at<ORACLE_HOME>\ord\Annotator\lib\descriptors\annotation\AnnotationDescriptor.dtd.

When you finish writing the XML file, you should save it to <ORACLE_HOME>\ord\Annotator\lib\descriptors\annotations.

The DTD describes the AnnotationDescriptor DTD, which contains two elements: AnnotationProperties and AttributeDescriptors.

10.1.1 AnnotationProperties Element

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

• Name

• Version

• Description

• Extends

• Contains

• ClassName

• IconFileName.

Name and Version are required elements. They contain the name of the new annotation type and the version number, respectively.

Description is an optional element that contains a brief description of the annotation as a whole.

Extends is an 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, ClassName, and IconFileName are reserved elements; do not assign values to these elements.

10.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

• AttributeType

• AttributeTypePattern

• AttributeAlias

• AttributeDescription

• AttributeDefaultValue.

AttributeName is a required element that contains the name of your new attribute.

AttributeType is a required element that contains the Java object type of the attribute value. AttributeType must be a Java object type; Java primitives 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 returns 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. This element (which should be used only if the AttributeType is java.lang.Date) specifies the String pattern that should be used when displaying the date. The pattern follows the syntax in java.text.SimpleDateFormat.

AttributeTypePattern is an optional element.

AttributeAlias, AttributeDescription, and AttributeDefaultValue are optional elements that define a shorter attribute name for display purposes, a short description of the attribute, and the default value of the attribute to be inserted in the annotation, respectively.

10.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>

10.2 Using a New Annotation Type

Once you have written your new XML file and included it in the <ORACLE_HOME>\ord\Annotator\lib\descriptors\annotations directory, you will be able to use your new annotation type in the same way that you use the predefined annotation types. See Section 3.1 and Section 3.4 for more information on creating new annotations.

Note: An XML file is space-sensitive; "java.lang.Double" is valid, while "java.lang.Double " is invalid. Be careful that your XML file does not contain extraneous spaces because it could lead to errors.