Oracle interMedia Annotator User's Guide Release 9.0.1 Part Number A88784-01 |
|
This chapter contains reference material for the classes and methods that beginning users will need to write a Java application that uses the Annotator engine. See the Javadoc included with the Annotator installation for complete reference information.
This section presents reference information on the methods of the Annotation class. This class is the superclass for all annotations; it offers the necessary data structure to hold logical annotations, their modifiers, and their accessor methods.
The attribute codes defined in this class are contained in Annotation.xml.
This class extends java.lang.Object.
public void addSubAnnotation(Annotation annChild)
Adds the given annotation as a sub-annotation of the current annotation.
The annotation to be added as a sub-annotation.
None.
None.
See Section 5.6 for an example of this method.
public java.lang.Object getAttribute(java.lang.String szAttrCode)
Gets the value of the given attribute as an Object. The client is responsible for casting the Object appropriately to access the returned value.
The attribute code of the attribute to be retrieved, as a String.
This method returns the value of the given attribute, as an Object. If the given attribute has no value, null is returned.
None.
See Section 5.6 for an example of this method.
public java.util.Enumeration getAttributes( )
Returns the list of attribute codes where a value has been set. This list does not include any attribute whose value is null.
None.
An Enumeration object that contains a list of attribute codes whose values have been set. Each code is returned as an Integer.
None.
See Section 5.6 for an example of this method.
public AnnotationDesc getDescriptor( )
Returns the AnnotationDesc object that is needed by the XML exporter.
For more information about the AnnotationDesc object, see Section 6.2.
None.
This method returns the AnnotationDesc object that is needed by the XML exporter.
None.
None; only advanced users should call this method directly.
public java.lang.String getName( )
Returns the name of the current annotation.
None.
This method returns the name of the current annotation.
None.
String name = ann.getName( );
public int getNumSubAnnotations( )
Returns the number of sub-annotations of the current annotation.
None.
This method returns the number of sub-annotations, as an integer.
None.
int i = ann.getNumSubAnnotations( );
public Annotation getParent( )
Returns the parent object of the annotation.
None.
This method returns the parent object of this annotation.
None.
Annotation parent = ann.getParent( );
public java.util.Enumeration getSampleAnns( )
Gets a list of the sub-annotations of the current annotation.
None.
This method returns an Enumeration object that contains a list of the sub-annotations of the current annotation.
None.
Enumeration eSubAnns = ann.getSampleAnns( );
public java.util.Enumeration getSubAnnotations( )
Gets an Enumeration object of the vector of sub-annotations.
None.
This method returns an Enumeration object of the vector of sub-annotations.
None.
See Section 5.6 for an example of this method.
public java.net.URL getURL( )
Returns the URL of the annotation.
None.
This method returns the URL of the annotation.
None.
java.net.URL location = ann.getURL( );
public boolean isDescendantOf(java.lang.String szAncestor)
Checks if the current annotation is a sub-annotation of the given annotation.
The annotation of which the current annotation may be a sub-annotation.
This method returns true if the current annotation is a sub-annotation of the given annotation; false otherwise.
None.
if(subAnn.isDescendantOf("ann") boolean removedSuccessfully = ann.removeSubAnnotation(subAnn);
public void removeAttribute(java.lang.Object key)
Removes an attribute and its value from the current annotation.
The attribute that will be removed.
None.
None.
ann.removeAttribute(SALES_PRICE);
public void removeSampleAnns( )
Removes all sub-annotations of the current annotation.
None.
None.
None.
ann.removeSampleAnns( );
public boolean removeSubAnnotation(Annotation ann)
Removes the given sub-annotation from the current annotation.
The sub-annotation to be removed.
This method returns true if the sub-annotation was removed successfully; false otherwise.
None.
See the isDescendantOf( ) method for an example of this method.
public void setAttribute(java.labg.String szAttrCode, java.lang.Object oValue)
Inserts a new attribute into the current annotation.
The attribute code of the attribute whose value is to be changed, as a String.
The new value of the attribute, as an Object.
None.
None.
See Section 5.6 for an example of this method.
This section presents reference information on the methods of the AnnotationDesc class, which creates annotation descriptor objects. This class provides the attribute definitions of the annotation.
This class extends oracle.ord.media.annotator.descriptors.Descriptor.
public java.util.Vector getAncestors( )
Gets the parent annotations of the current annotation.
None.
This method returns a Vector object that contains the parent annotations of the current annotation.
None.
None; only advanced users should call this method directly.
public AttributeDesc getAttributeDesc(java.lang.String szAttributeName)
Gets the attribute descriptor for the given attribute.
The name of the attribute for which you want to get the attribute descriptor.
This method returns the attribute descriptor of the given attribute, as an AttributeDesc object.
None.
None; only advanced users should call this method directly.
public java.util.Enumeration getSuppAttributes( )
Gets the supported attribute descriptions defined in the annotation type.
None.
This method returns an Enumeration object that contains the supported attribute descriptions defined in the annotation type, as AttributeDesc objects.
None.
None; only advanced users should call this method directly.
This section presents reference information on the methods of the ParserDesc class, which creates parser descriptor objects. This class provides the definitions of the operations defined by the parsers, their parameters, their options, and the option parameters.
This class extends oracle.ord.media.annotator.descriptors.Descriptor.
public OperationDesc getOperationDesc(java.lang.String szOpName)
Gets the operation descriptor of the given operation.
The name of the operation whose descriptor will be returned.
This method returns the operation descriptor of the given operation, as an OperationDesc object.
None.
None; only advanced users should call this method directly.
public java.util.Enumeration getOperations( )
Gets the descriptions of the operations supported by the parser, as defined in the parser descriptor.
None.
This method returns an Enumeration object that contains the descriptions of the operations supported by the parser, as OperationDesc objects.
None.
None; only advanced users should call this method directly.
public boolean isEnabledAndExecutable(java.lang.szOpName)
Checks that the given operation is enabled and executable.
The name of the operation to check.
This method returns true if the method is enabled and executable; false otherwise.
oracle.ord.media.annotator.descriptors.DescriptorException
None; only advanced users should call this method directly.
This section presents reference information on the methods of the AnnTaskMonitor class, which creates an annotation task monitor. The annotation task monitor object is one of the components involved in monitoring tasks as they are being performed by an AnnotationHandler object (or annotation handler). Whenever a task is started by an annotation handler, an annotation task manager and an annotation task monitor are created. The annotation task manager runs on the server side; it tracks the progress of the task on the database server. The annotation task monitor runs on the client side; it tracks the progress value and messages from the returned annotation task monitor instance through a task progress monitor.
For more information on the annotation task manager, see Section 9.1.
This class extends java.lang.Object.
public java.lang.String getMessage( )
Gets the current message from the task progress monitor.
None.
This method returns the current message of the task progress monitor, as a String.
None.
String message = atm.getMessage( );
public int getTaskCurrent( )
Gets the current value of the task progress monitor.
None.
This method returns the current value of the task progress monitor.
None.
See the isDone( ) method for an example of this method.
public int getTaskEnd( )
Gets the end value of the task progress monitor.
None.
This method returns the end value of the task progress monitor.
None.
See the isInitialized( ) method for an example of this method.
public int getTaskStart( )
Gets the starting value of the task progress monitor.
None.
This method returns the initial value of the task progress monitor.
None.
int i = atm.getTaskStart( );
public boolean isDone( )
Determines if the task has been completed.
None.
This method returns true if the task has been completed; false otherwise.
None.
if(atm.isDone == false) int i = atm.getTaskCurrent( );
public boolean isInitialized( )
Checks if the annotation task monitor has been initialized. If it has, the getStartTask( ) and getEndTask( ) methods can be called to find the starting and ending times of the task.
None.
This method returns true if the annotation task monitor is initialized; false otherwise.
None.
if(atm.isInitialized( )) int i = atm.getTaskEnd( );
This section presents reference information on the methods of the AnnotationHandler class, which creates an annotation handler. This class provides methods that produce an annotation for a given content source. An application that calls AnnotationHandler should implement the AnnListener interface to listen to the various responses to the handler. See Section 6.7 for more information.
You should create and use only one AnnotationHandler instance in your application. AnnotationHandler is stateless and thread-safe; you can have multiple threads calling the same AnnotationHandler instance.
This class extends java.lang.Object.
This class contains the following fields:
This signifies asynchronous mode.
This signifies synchronous mode.
The examples in this section are based on the assumption that an AnnotationHandler object named handler has been created. See AnnotationHandler( ) and AnnotationHandler(int) for examples of creating an AnnotationHandler object.
public AnotationHandler( )
Creates an AnnotationHandler object. As a default, the constructor uses the asynchronous mode of operations.
To ensure all engine traces are handled, the caller must create a Status instance before creating an annotation handler. See Section 6.10 for more information about Status.
None.
None.
oracle.ord.media.annotator.handlers.AnnotationHandlerException
private AnnotationHandler handler = new AnnotationHandler( );
public AnnotationHandler(int iOperationMode)
Creates an AnnotationHandler object. As a default, the constructor uses the asynchronous mode of operations.
The AnnotationHandler class contains two static integers named OP_MODE_ASYNCH and OP_MODE_SYNCH. To create an annotation handler that runs in asynchronous mode, set iOperationMode to OP_MODE_ASYNCH. To create an annotation handler that runs in synchronous mode, set iOperationMode to OP_MODE_SYNCH.
To ensure all engine status messages are handled, the caller must create a Status instance before creating an annotation handler. See Section 6.10 for more information about Status.
The mode (either synchronous or asynchronous) that the annotation handler will use.
None.
oracle.ord.media.annotator.handlers.AnnotationHandlerException
See Section 5.4 for an example of this method.
public Annotation createAnnotationByname(java.lang.String szAnnName)
Creates a new instance of an annotation, given the annotation type.
The annotation type of the annotation to be created.
This method returns the newly created annotation.
AnnotatorException
See Section 5.6 for an example of this method.
public void exportToXML(java.io.Writer w, Annotation ann)
Builds an XML representation of an annotation and its sub-annotations and exports the representation to an XML file.
The Writer object that will write the content to XML.
The annotation to be exported.
None.
None.
See Section 5.13 for an example of this method.
public AnnTaskMonitor extractMedia(Annotation ann, AnnListener annListener)
Extracts media samples from an annotation. After the extraction is complete, the method calls the call-back function AnnListener.extractionPerformed( ).
The annotation from which samples will be extracted.
The listener that will be notified upon the completion of the parsing.
This method returns the AnnTaskMonitor object associated with this task.
None.
See Section 5.6 for an example of this method.
public java.util.Enumeration getAnnotationNames( )
Returns a list of String objects with the names of the annotation types that are defined in the resource file.
None.
This method returns a list of String objects with the names of the annotation types that are defined in the resource file.
AnnotatorException
Enumeration annTypes = handler.getAnnotationNames( );
public java.util.Enumeration getParserNames( )
Returns a list of the parser types defined in the resource file.
None.
This method returns a list of the parser types defined in the resource file.
AnnotatorException
Enumeration parserTypes = handler.getParserNames( );
public final java.lang.String getRelVersion( )
Returns the version of the interMedia Annotator release.
None.
This method returns the version of the interMedia Annotator release.
None.
String release = handler.getRelVersion( )
public Annotation importFromXML(java.io.Reader r)
Creates a new Annotation object whose content is read from an XML file.
The Reader object that will read the content from the XML file.
This method returns a new Annotation object.
oracle.ord.media.annotator.annotations.AnnotationException
oracle.ord.media.annotator.handlers.annotation.AnnotationFactoryException
java.io.FileReader reader = new FileReader("e:\\myAnnotation.xml"); Annotation ann = new Annotation(handler.importFromXML(reader));
public AnnTaskMonitor insertMedia(Annotation ann, OrdMapping om, AnnListener annListener)
Creates a new connection to the database and inserts the annotation into an Oracle interMedia object on the database server.
The annotation from which samples will be extracted.
The mapping between the annotation and an Oracle interMedia object on the database server.
The listener that will be notified upon the completion of the parsing.
This method returns the AnnTaskMonitor object associated with this task.
None.
See Section 5.7 for an example of this method.
public AnnTaskMonitor insertMedia(Annotation ann, OrdMapping om, AnnListener annListener,
java.sql.Connection conn)
Creates a new connection to the database and inserts the annotation into an Oracle interMedia object. After the parsing is complete, the method calls the call-back method AnnListener.insertionPerformed( ).
The annotation from which samples will be extracted.
The mapping between the annotation and an Oracle interMedia object on the database server. See the Annotator Javadoc for more information about the OrdMapping object.
The listener that will be notified upon the completion of the operation.
The connection to the database. If this parameter is set to null, a new connection will be created.
This method returns the AnnTaskMonitor object associated with this task.
None.
handler.insertMedia(ann, ofm, listener, null);
where:
public boolean isExtractable (Annotation ann)
Determines if it is possible to extract samples from the given annotation or any of its sub-annotations.
The annotation from which you want to extract samples.
This method returns true if it is possible to extract samples; false otherwise.
None.
See Section 5.6 for an example of this method.
public boolean isPlayable(Annotation ann)
Determines if it is possible to play the media content represented by the given annotation.
The annotation from which you want to play the content.
This method returns true if it is possible to play the media content; false otherwise.
None.
if(handler.isPlayable(ann)){ handler.playMedia(ann,listener) }
where:
public AnnTaskMonitor parseMedia(java.io.InputStream is, java.lang.String sURL,
AnnListener annListener)
Parses the source associated with the given InputStream and creates an annotation of the given URL. After the parsing is complete, the method performs the following operations:
The InputStream of the media file to be parsed.
The URL of the media file to be parsed.
The listener that will be notified upon the completion of the parsing.
This method returns the AnnTaskMonitor object associated with this task.
None.
//Assign the URL to a string named szURL //The current client (represented by this) implements the AnnListener interface FileInputStream fStream = new FileInputStream("test.mpg"); AnnTaskMonitor atm = handler.parseMedia(fStream, szURL, this);
public AnnTaskMonitor parseMedia(java.lang.String sURL, AnnListener annListener)
Parses the source and creates an annotation of the given URL. After the parsing is complete, the method performs the following operations:
The URL of the media file to be parsed.
The listener that will be notified upon the completion of the parsing.
This method returns the AnnTaskMonitor object associated with this task.
None.
See Section 5.5 for an example of this method.
public void playMedia(Annotation ann, AnnListener annListener)
Plays the content represented by the named annotation. This method is synchronous; it does not return an AnnTaskMonitor object.
The annotation from which you want to play the content.
The listener that will be notified upon the completion of the parsing.
None.
None.
See the isPlayable( ) method for an example of this method.
This section presents reference information on the methods associated with the OrdFileMapping object, which maps the contents of an annotation instance to specific tables and specific rows in the database.
This class extends oracle.ord.media.annotator.handlers.db.OrdMapping.
public java.lang.String generateStatement(Annotation ann)
Returns the PL/SQL statement that is used to insert the annotation into the database. This statement is processed by the Annotator pre-processor to insert Annotator-specific directives.
This method overrides OrdMapping.generateStatement( ).
The annotation to be inserted.
This method returns the PL/SQL statement that will be used to insert the annotation into the database.
java.io.IOException
String sqlStatement = ofm.generateStatement(ann);
public OrdFileMapping(java.lang.String szFileName)
Creates an OrdFileMapping object, which contains the mapping of the contents of the annotation to the database.
The name of the file that contains the mapping.
None.
None.
See Section 5.7 for an example of this method.
This section presents reference information on the methods of the AnnListener interface. The client must implement this interface in order to invoke the Annotator engine.
This class extends java.util.EventListener.
public void errorOccured(Annotation ann, java.lang.Exception e)
Returns an exception in the case of fatal errors.
If an error is generated by AnnotationHandler.insertMedia( ), the JDBC connection is automatically rolled back and closed.
The annotation instance.
An exception that explains why the failure occurred.
None.
None.
See Section 5.10 for an example of this method.
public void extractionPerformed(Annotation ann)
Performs any necessary operations after the completion of media sample extraction. This method is the call-back function of AnnotationHandler.extractMedia( ).
After the extraction is completed, new attributes are defined in the annotation. The new attributes are relative to the extracted sample; a refresh on the client is probably required.
The annotation instance from which the extraction was performed.
None.
None.
See Section 5.7 for an example of this method.
public void insertionPerformed(Annotation ann, java.sql.Connection conn)
Performs any necessary operations after the completion of the insertion of the annotation into the database. These operations include explicitly committing or rolling back the changes to the database and closing the connection to the database.
You can keep the connection to the database open and pass it to another call of AnnotationHandler.insertMedia( ); however, it is your responsibility to check the thread-safety of the connection.
This method is the call-back function of AnnotationHandler.extractMedia( ).
The annotation instance that has been inserted into the database.
The JDBC connection used to perform the insertion.
None.
None.
See Section 5.8 for an example of this method.
public void parsePerformed(Annotation ann)
Performs any necessary operations on the annotation after it is created and before it is uploaded to the database. This method is the call-back function of AnnotationHandler.parseMedia( ).
The newly created media annotation.
None.
None.
See Section 5.6 for an example of this method.
public void warningOccured(Annotation ann, java.lang.Exception e)
Returns an exception in the case of non-fatal errors.
The annotation instance.
An exception that explains why the failure occurred.
None.
None.
See Section 5.9 for an example of this method.
This section presents reference information on the methods of the OutputListener interface. The client invokes this method to process status output from the engine.
This class extends java.util.EventListener.
public void ConsoleOutputd(java.lang.String szOutput)
Prints status messages while the engine is running.
The status message to be printed.
None.
None.
See Section 5.11 for an example of this method.
This section presents reference information on the methods associated with the Preferences class. This class is primarily used by the engine. It supports the loading of preferences, the dynamic changing of preferences, and saving preferences to a file. The implementation of this class is independent of the other Annotator classes.
This class extends java.lang.Object and implements oracle.ord.media.annotator.utils.PreferenceConstants and java.lang.Cloneable.
public java.lang.Object clone( )
Creates and returns a copy of this object. For more information, see the Java 1.2 documentation for the java.lang.Object.clone( ) method.
None.
This method returns a copy of the current Preferences object, as an Object.
java.lang.CloneNotSupportedException
None; this method should be called only by advanced programmers who want to manually access the Annotator preferences.
public static Preferences getPrefs( )
Gets the Preferences object of the current annotation.
None.
This method returns the Preferences object of the current annotation.
None.
See Section 5.4 for an example of this method.
public java.lang.String getProperty(java.lang.String s)
Gets the value of the given property from the preferences of the current annotation.
The name of the property for which you will get the value.
This method returns the value of the property, as a String.
None.
None; this method should be called only by advanced programmers who want to manually access the Annotator preferences.
public Preferences( )
Creates a Preferences object.
None.
None.
None.
None; this method should be called only by advanced programmers who want to manually access the Annotator preferences.
public void saveToFile( )
Saves the preferences to a file.
None.
None.
None.
None; this method should be called only by advanced programmers who want to manually access the Annotator preferences.
public static void setPreferences(Preferences prefs)
Sets the preferences of the current annotation to match the given Preferences object.
The preferences to be set in the annotation.
None.
None.
None; this method should be called only by advanced programmers who want to manually access the Annotator preferences.
public void setProperty(java.lang.String s, java.lang.Object o)
Sets the given property to the given value.
The name of the property that you will set.
The value to set.
None.
None.
See Section 5.4 for an example of this method.
This section presents reference information on the methods associated with the Status class. This class updates the current status in the GUI of the application. The user can choose from three supported status modes. In order, from least output to most output, they are STATUS (or TERSE), VERBOSE, and TRACE.
The Status class follows a singleton pattern, so only one instance is needed for all instances of the Annotator engine in the Java virtual machine.
This class extends java.lang.Object.
The class contains the following fields that are used to set the error level:
The class contains the following fields that are used to set the output mode:
public short GetOutputMode( )
Returns the current output mode of the Status object.
None.
This method returns the current output mode of the Status object. The possible values are OUTPUT_MODE_STATUS, OUTPUT_MODE_TERSE, OUTPUT_MODE_TRACE, or OUTPUT_MODE_VERBOSE.
None.
short outputMode = m_st.GetOutputMode( );
public static Status getStatus( )
Gets the Status object of the current annotation.
None.
This method returns the Status object.
None.
See Section 5.4 for an example of this method.
public static void initStatus(OutputListener ol)
Initializes the Status object. This method should be invoked before initializing the AnnotationHandler object.
The instance of the OutputListener class that will receive the status messages from the AnnotationHandler object.
None.
None.
See Section 5.4 for an example of this method.
public void Report(short omDesignated, java.lang.String szStatus)
Prints the given message to the appropriate output source. The output source is set internally when the Status object is instantiated.
This method should be used by parser developers only.
The output mode. If the output mode given here is of a lower priority than the output mode that has been set for the engine, the message will not be reported.
The message to be reported.
None.
None.
See Section 5.4 for an example of this method.
public void ReportError(short sErrLevel, java.lang.Object oInstance,
java.lang.String szMethodName, int iLineNumber, java.lang.String szDesc)
Reports errors through the System.err stream. Multiple error levels can be given to specify consequences.
The 16-bit error level (ERR_LEVEL_WARNING, ERR_LEVEL_ERROR, or ERR_LEVEL_FATALERROR).
The object pointer of the source of the error.
The name of the method where the error occurred, as a String.
The line number where the error occurred.
A lengthy description of the error.
None.
None.
status.ReportError(Status.ERR_LEVEL_WARNING, this, "name_of_current_method", iCurrentLineNum, "error description");
public void ReportError(short sErrLevel, java.lang.Throwable sException)
Reports errors through the System.err stream. Multiple error levels can be given to specify consequences.
The 16-bit error level (ERR_LEVEL_WARNING, ERR_LEVEL_ERROR, or ERR_LEVEL_FATALERROR).
The exception that was raised, as a Throwable object.
None.
None.
status.ReportError(Status.ERR_LEVEL_WARNING, myExceptionInstance);
public void SetOutputMode(short omNew)
Sets the status output mode to STATUS, TERSE, TRACE, or VERBOSE.
The output mode to be set; the value should be OUTPUT_MODE_STATUS, OUTPUT_MODE_TERSE, OUTPUT_MODE_TRACE, or OUTPUT_MODE_VERBOSE.
None.
None.
See Section 5.4 for an example of this method.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|