5
interMedia Annotator Engine Example

This chapter provides a description of SimpleAnnotator.java, which is an example of a user-developed application that was written using the interMedia Annotator engine APIs for use in a synchronous environment.

You can find the source code at the following location:

<ORACLE_HOME>/ord/Annotator/demo/examples/src/
SimpleAnnotator.java

The code that appears in this chapter will not necessarily match the code shipped as SimpleAnnotator.java. If you want to run this example on your system, use the file provided with the interMedia Annotator installation; do not attempt to compile and run the code presented in this chapter.

Note: This chapter contains examples of Java code. Some of the code examples display boldface numbers enclosed in brackets; these indicate that further explanation of that code will be in the numbered list immediately following the example.

The Annotator client example in SimpleAnnotator.java contains user-defined methods that use Java and interMedia Annotator APIs to perform the following operations:

• Initialize an instance of the Annotator client

• Set preferences

• Parse a media source file

• Get and set attributes of the annotation

• Define sub-annotations

• Extract media samples from the media source file

• Upload the annotation to an Oracle database

5.1 Import Statements

Example 5-1 shows the import statements that must be included to properly run an Annotator client.

Example 5-1 Import Statements

import java.net.*;
import java.io.*;
import java.util.*;
import java.text.*;
import java.sql.*;

import oracle.ord.media.annotator.handlers.annotation.*;
import oracle.ord.media.annotator.annotations.Attribute;
import oracle.ord.media.annotator.annotations.Annotation;
import oracle.ord.media.annotator.listeners.*;
import oracle.ord.media.annotator.handlers.*;
import oracle.ord.media.annotator.handlers.db.*;
import oracle.ord.media.annotator.utils.*;
import oracle.ord.media.annotator.AnnotatorException;

5.2 Class Definition and Instance Variables

Example 5-2 shows the class definition and instance variables for the sample Annotator client.

Example 5-2 Class Definition and Instance Variables

public class SimpleAnnotator implements AnnListener, OutputListener{
     private Status m_st;
     private AnnotationHandler m_ah;

An Annotator client must implement the AnnListener interface to have access to the callback methods used for Annotator engine operations. See Section 6.7 for more information.

An Annotator client must implement OutputListener to get access to traces from the engine. See Section 6.8 for more information.

The class contains two instance variables:

• m_st is the Status object that will be used to update the status in the GUI of the application. See Section 6.10 for more information.

• m_ah is the AnnotationHandler object that will actually produce the annotation for the given content source. See Section 6.5 for more information.

5.3 main( ) Method

Example 5-3 shows the main( ) method.

Example 5-3 main( ) Method (SimpleAnnotator)

public static void main(String[ ] args){
     [1] if(args.length == 0){
          System.err.println("Usage: java SimpleAnnotator mediaURL");
          System.err.println("mediaURL: URL of the media you want to parse 
               (for example, file:/myjpeg.jpg"));
          return;
     }

     [2] SimpleAnnotator sa = new SimpleAnnotator( );
     [3] sa.init( );

     [4] String szURL = args[0];
     [5] sa.parse(szURL);
}

The code in the main( ) method performs the following operations:

1. Tests to make sure the URL of the media source file to be parsed was passed as an argument. If there are no arguments, an error message is printed.

   The URL of the media source file to be operated upon should be the first argument.

2. Creates an empty instance of SimpleAnnotator.

3. Calls the init( ) method to initialize the newly created SimpleAnnotator instance. See Section 5.4 for more information on the init( ) method.

   Once the SimpleAnnotator instance is initialized, the client can invoke the Annotator engine operations, such as parsing, extraction, and insertion.

4. Creates a String named szURL and sets its value to the first argument (that is, the URL of the media source file).

5. Calls the parse( ) method to parse the media source file.

   See Section 5.5 for more information on the parse( ) method.

5.4 init( ) Method

Example 5-4 shows the contents of the init( ) method, which initializes the Annotator client. This method is specific to this example.

Example 5-4 init( ) Method

public void init( ){
     [1] report("Initializing Annotator Engine..."); 

     [2] Status.initStatus(this);
     [3] m_st = Status.getStatus( );
     [4] m_st.SetOutputMode(Status.OUTPUT_MODE_VERBOSE);

     [5] try { 
          m_ah = new AnnotationHandler(AnnotationHandler.OP_MODE_SYNCH);
     } 
     [6] catch(Exception e) { 
          report("Initializing... Failed."); 
          reportError(e); 
     }

     [7] Preferences prefs = Preferences.getPrefs( );
     [8] prefs.setProperty(SZ_CONN_PASSWORD, "mypassword");

     [9] report("Initializing Annotator Engine... Done");
}

The code in the init( ) method performs the following actions:

1. Prints a message that the initialization is beginning. See Section 5.12 for more information on the report(String) method.

2. Initializes the Status object. Because SimpleAnnotator implements the OutputListener class, the current instance of SimpleAnnotator can receive the status messages. See initStatus( ) in Section 6.10 for more information.

3. Sets the initialized Status object to the m_st instance variable.

4. Sets the status output mode to VERBOSE.

5. Creates a new AnnotationHandler instance in synchronous mode and sets it to the m_ah instance variable.

6. Catches any exceptions that were raised in the previous step and prints the error to the screen with the report( ) and reportError( ) methods. See Section 5.14 for more information on the reportError( ) method.

   If the Status and AnnotationHandler objects were both created with no errors, you will be able to set any necessary preferences.

7. Creates a Preferences object and initialize it.

8. Sets a new preference named SZ_CONN_PASSWORD.

9. Prints a message that initialization was successful.

5.5 parse( ) Method

Example 5-5 shows the contents of the parse( ) method. This method is specific to this example.

Example 5-5 parse( ) Method

public void parse(String szURL){
     if(m_ah != null){
          AnnTaskMonitor atm = m_ah.parseMedia(szURL, this); 
     }
}

The code in the parse( ) method calls the AnnotationHandler.parseMedia( ) method with the URL and the AnnotationListener as parameters. Because SimpleAnnotator implements AnnListener, the current instance of SimpleAnnotator can be used.

See Section 6.5 for more information about the parseMedia( ) method.

AnnotationHandler.parseMedia( ) is called only if the annotation handler has been initialized properly in the init( ) method.

When AnnotationHandler.parseMedia( ) has finished parsing the source file and building the annotation, it calls the AnnListener.parsePerformed( ) call-back function. This method is overridden in the SimpleAnnotator class, so the actual method called is SimpleAnnotator.parsePerformed( ). See Section 5.6 for more information.

5.6 parsePerformed( ) Method

Example 5-6 shows the parsePerformed( ) method. Because your application must implement AnnListener, this method is required.

Example 5-6 parsePerformed( ) Method

public void parsePerformed(Annotation ann){
     [1] if(ann != null){
          [2] String szMimeType = (String) ann.getAttribute
               ("MEDIA_SOURCE_MIME_TYPE");
          [3] Enumeration eAttrs = ann.getAttributes( );
          while(eAttrs.hasMoreElements( )){
               [4] Attribute attr = (Attribute)eAttrs.nextElement( );
               Object oAttrValue = attr.getValue( );
          }
          [5] Enumeration eSubAnns = ann.getSubAnnotations( );
          while (eSubAnns.hasMoreElements( )){
               [6] Annotation subAnn = (Annotation)eSubAnns.nextElement( );
          }
          /**
           * Example: (Advanced)
           */
          try {
               [7] Annotation inventoryAnn = m_ah.createAnnotationByName
                    ("InventoryAnn");
               [8] ann.addSubAnnotation(inventoryAnn);
               [9] inventoryAnn.setAttribute("SALES_PRICE", new Float(19.99));
          }
          [10] catch (AnnotatorException ae){
               errorOccured(ann, ae);
               return;
          }
          [11] report(ann);
     }
     [12] if(m_ah.isExtractable(ann)){
          [13] m_ah.extractMedia(ann);
     }
}

The code in the parsePerformed( ) method performs the following operations:

1. Executes the code in the next block only if a valid annotation was passed by the caller.

   If the caller did pass a valid annotation, you would typically use the parsePerformed( ) method to manipulate the annotation before it is uploaded to the database. Steps 2 through 11 show examples of the kinds of operations you may perform. The tasks in steps 7 through 10 should be used only by advanced programmers.

2. Gets the value of the MEDIA_SOURCE_MIME_TYPE attribute of the annotation and casts it into a String object.

3. Gets a list of all attributes that have a valid value and stores their names in an Enumeration object.

4. Accesses the values stored in the Enumeration.

5. Gets all sub-annotations of the annotation and stores them in an Enumeration object.

6. Accesses the values stored in the Enumeration.

7. Creates an empty annotation named inventoryAnn.

8. Adds inventoryAnn to ann as a sub-annotation.

9. Sets the SALES_PRICE attribute in inventoryAnn to 19.99.

10. Catches any errors raised in steps 7 through 9 and reports them with the errorOccured( ) method. See Section 5.10 for more information on the errorOccured( ) method.

11. Uses the report(Annotation) method to print the annotation as an XML file. See Section 5.13 for more information.

12. Checks to see if it is possible to extract samples from the annotation or any of its subannotations. If it is possible, the code in step 13 is executed. If not, the code in step 13 is skipped.

13. Extracts the media samples from the annotation.

    When AnnotationHandler.extractMedia( ) has finished, it calls the call-back function AnnListener.extractionPerformed( ). This method is overridden in the SimpleAnnotator class, so the actual method called is SimpleAnnotator.extractionPerformed( ). See Section 5.7 for more information.

5.7 extractionPerformed( ) Method

Example 5-7 shows the extractionPerformed( ) method. Because your application must implement AnnListener, this method is required.

Example 5-7 extractionPerformed( ) Method

public void extractionPerformed(Annotation ann){
     [1] report(ann);
     [2] OrdFileMapping ofm = new OrdFileMapping("e:\\mylogic.ofm");
     [3] m_ah.insertMedia(ann, ofm, this);
}

The code in the extractionPerformed( ) method performs the following operations:

1. Uses the report(Annotation) method to print the annotation as an XML file. See Section 5.13 for more information.

2. Creates a new OrdFileMapping object based on the mapping file located at "e:\\mylogic.ofm."

3. Uploads the annotation to the database, using the OrdFileMapping object to map the contents of the annotation to the proper locations on the database.

   Alternatively, you could specify a Connection object that represents the JDBC connection to be used in the upload process. The same JDBC connection can be used for multiple upload operations. See Section 6.5, "insertMedia(Annotation,OrdMapping,AnnListener,Connection)" for more information.

   When AnnotationHandler.insertMedia( ) has finished, it calls the call-back function AnnListener.insertionPerformed( ). This method is overridden in the SimpleAnnotator class, so the actual method called is SimpleAnnotator.insertionPerformed( ). See Section 5.8 for more information.

5.8 insertionPerformed( ) Method

Example 5-8 shows the insertionPerformed( ) method. Because your application must implement AnnListener, this method is required.

Example 5-8 insertionPerformed( ) Method

public void insertionPerformed(Annotation ann, Connection conn){ 
     try {
          [1] conn.commit( );
          [2] conn.close( );
     }
     [3] catch (SQLException sqle){
          errorOccured(ann, sqle);
     }
};

The code in the insertionPerformed( ) method performs the following operations:

1. Commits all changes made to the database.

2. Closes the connection to the database.

   Instead of closing the connection, the client could reuse the connection by passing it to another AnnotationHandler call.

3. Catches any errors raised in steps 1 and 2 and reports them with the errorOccured( ) method. See Section 5.10 for more information on the errorOccured( ) method.

5.9 warningOccured( ) Method

Example 5-9 shows the warningOccured( ) method. Because your application must implement AnnListener, this method is required.

Example 5-9 warningOccured( ) Method

public void warningOccured(Annotation ann, Exception e){ 
     reportError(e); 
}

The code in the warningOccured( ) method implements the AnnListener.warningOccured( ) method. This method uses the reportError( ) method to capture the warning and report it. If a warning occurs and this method is called, the Annotator engine continues to operate.

See Section 5.15 for more information on the reportError( ) method.

5.10 errorOccured( ) Method

Example 5-10 shows the errorOccured( ) method. Because your application must implement AnnListener, this method is required.

Example 5-10 errorOccured( ) Method

public void errorOccured(Annotation ann, Exception e){
     reportError(e);
}

The code in the errorOccured( ) method implements the AnnListener.errorOccured( ) method. This method uses the reportError( ) method to capture the error and report it. If an error occurs and this method is called, the Annotator engine will not continue to operate.

See Section 5.15 for more information on the reportError( ) method.

5.11 ConsoleOutput( ) Method

Example 5-11 shows the ConsoleOutput( ) method. Because your application must implement OutputListener, this method is required.

Example 5-11 ConsoleOutput( ) method

public void ConsoleOutput(String sz){
     report(sz);
}

The code in the ConsoleOutput( ) method implements the OutputListener.ConsoleOutput( ) method. This method uses the report(String) method to print messages during execution.

See Section 5.12 for more information on the report(String) method.

5.12 report(String) Method

Example 5-12 shows the report(String) method. This method is specific to this example.

Example 5-12 report(String) Method

public void report(String szValue){
     System.err.println(szValue);
}

The code in the report(String) method prints the given stream to the error stream.

5.13 report(Annotation) Method

Example 5-13 shows the report(Annotation) method. This method is specific to this example.

Example 5-13 report(Annotation) Method

public void report(Annotation ann){
     [1] StringWriter sw = new StringWriter( );
     [2] m_ah.exportToXML(sw, ann);
     [3] report(sw.toString( ));      
}

The code in the report(Annotation) method performs the following operations:

1. Creates a new StringWriter object.

2. Creates an XML representation of the given annotation and uses the StringWriter object to write the contents to XML.

3. Casts the generated XML into a String object and uses the report(String) method to print the annotation to the error stream.

5.14 reportWarning( ) Method

Example 5-14 shows the reportWarning( ) method. This method is specific to this example.

Example 5-14 reportWarning( ) Method

public void reportWarning(Exception e){
     report("WARNING:");
     reportError(e);
}

This method uses the reportError( ) method to report the given error.

5.15 reportError( ) Method

Example 5-15 shows the reportError( ) method. This method is specific to this example.

Example 5-15 reportError( ) Method

public void reportError(Exception e){
     StringWriter sw = new StringWriter( );
     PrintWriter  pw = new PrintWriter(sw);
     e.printStackTrace(pw);
     report(sw.toString( ));
}

The code in the reportError( ) method captures the contents of the exception, casts them into a String object, and uses the report(String) method to print the exception to the error stream.