8
Creating New Annotation Types

In addition to the supplied annotation types, you can use Oracle 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 the following file, which is included when you install Oracle interMedia Annotator:

• On UNIX:

  $ORACLE_HOME/ord/Annotator/demo/examples/SampleInventoryAnn.xml
  
  

• On Windows:

  ORACLE_HOME\ord\Annotator\demo\examples\SampleInventoryAnn.xml
  

8.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), which is defined in the AnnotationDescriptor.dtd file. This file is located in the annotations subdirectory. The following shows the full specification for this directory:

• On UNIX:

  $ORACLE_HOME/ord/Annotator/lib/descriptors/annotations
  
  

• On Windows:

  ORACLE_HOME\ord\Annotator\lib\descriptors\annotations
  
  

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

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>

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.

8.2 Using a New Annotation Type

When you finish writing the XML file, you should save it to the annotations directory.

Now you can use your new annotation type in the same way that you use the predefined annotation types. See Chapter 2 and Chapter 3 for more information on creating new annotations.