Release 9.2
Part No. A96120-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle® interMedia Annotator User's Guide Release 9.2 Part No. A96120-01 |
|
This chapter contains reference material for the classes, constructors, and methods that beginning users will need to write a Java application that uses the Oracle interMedia Annotator engine. See the Javadoc included with the interMedia Annotator installation for complete reference information.
This section presents reference information on the constructors and 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.
See Appendix C for descriptions of the attributes defined by this class.
This class extends java.lang.Object.
Format
public Annotation( )
Description
Creates an annotation object.
Parameters
None.
Return Value
None.
Exceptions
None.
Example
Annotation ann = new Annotation( );
Format
public void addSubAnnotation(Annotation annChild)
Description
Adds the given annotation as a subannotation of the current annotation.
Parameters
The annotation to be added as a subannotation.
Return Value
None.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public java.lang.Object getAttribute(java.lang.String szAttrCode)
Description
Gets the value of the given attribute as an Object. The client is responsible for casting the Object appropriately to access the returned value.
Parameters
The attribute code of the attribute to be retrieved, as a String. See Appendix C for descriptions of the attributes defined by interMedia Annotator.
Return Value
This method returns the value of the given attribute, as an Object. If the given attribute has no value, null is returned.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public java.util.Enumeration getAttributes( )
Description
Returns the list of attribute codes where a value has been set. This list does not include any attribute whose value is null. See Appendix C for descriptions of the attributes defined by interMedia Annotator.
Parameters
None.
Return Value
An Enumeration object that contains a list of attribute codes whose values have been set. Each code is returned as an integer.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public AnnotationDesc getDescriptor( )
Description
Returns the AnnotationDesc object that is needed by the XML exporter.
See "Class oracle.ord.media.annotator.descriptors.AnnotationDesc" for more information about the AnnotationDesc object.
Parameters
None.
Return Value
This method returns the AnnotationDesc object that is needed by the XML exporter.
Exceptions
None.
Example
None; only advanced users should call this method directly.
Format
public java.lang.String getName( )
Description
Returns the name of the current annotation.
Parameters
None.
Return Value
This method returns the name of the current annotation.
Exceptions
None.
Example
String name = ann.getName();
Format
public int getNumSubAnnotations( )
Description
Returns the number of subannotations of the current annotation.
Parameters
None.
Return Value
This method returns the number of subannotations, as an integer.
Exceptions
None.
Example
int i = ann.getNumSubAnnotations();
Format
public Annotation getParent( )
Description
Returns the parent object of the annotation.
Parameters
None.
Return Value
This method returns the parent object of this annotation.
Exceptions
None.
Example
Annotation parent = ann.getParent();
Format
public java.util.Enumeration getSampleAnns( )
Description
Gets a list of the subannotations of the current annotation.
Parameters
None.
Return Value
This method returns an Enumeration object that contains a list of the subannotations of the current annotation.
Exceptions
None.
Example
Enumeration eSubAnns = ann.getSampleAnns();
Format
public java.util.Enumeration getSubAnnotations( )
Description
Gets an Enumeration object of the vector of subannotations.
Parameters
None.
Return Value
This method returns an Enumeration object of the vector of subannotations.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public java.net.URL getURL( )
Description
Returns the URL of the annotation.
Parameters
None.
Return Value
This method returns the URL of the annotation.
Exceptions
None.
Example
java.net.URL location = ann.getURL();
Format
public boolean isDescendantOf(java.lang.String szAncestor)
Description
Checks if the current annotation is a subannotation of the given annotation.
Parameters
The annotation of which the current annotation may be a subannotation.
Return Value
This method returns true if the current annotation is a subannotation of the given annotation; false otherwise.
Exceptions
None.
Example
if(subAnn.isDescendantOf("ann")
boolean removedSuccessfully = ann.removeSubAnnotation(subAnn);
Format
public void removeAttribute(java.lang.Object key)
Description
Removes an attribute and its value from the current annotation.
Parameters
The attribute that will be removed. See Appendix C for descriptions of the attributes defined by interMedia Annotator.
Return Value
None.
Exceptions
None.
Example
ann.removeAttribute("SALES_PRICE");
Format
public void removeSampleAnns( )
Description
Removes all subannotations of the current annotation.
Parameters
None.
Return Value
None.
Exceptions
None.
Example
ann.removeSampleAnns();
Format
public boolean removeSubAnnotation(Annotation ann)
Description
Removes the given subannotation from the current annotation.
Parameters
The subannotation to be removed.
Return Value
This method returns true if the subannotation was removed successfully; false otherwise.
Exceptions
None.
Example
See "isDescendantOf( )" for an example of this method.
Format
public void setAttribute(java.lang.String szAttrCode, java.lang.Object oValue)
Description
Inserts a new attribute into the current annotation.
Parameters
The attribute code of the attribute whose value is to be changed, as a String. See Appendix C for descriptions of the attributes defined by interMedia Annotator.
The new value of the attribute, as an Object.
Return Value
None.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
This section presents reference information on the constructor and 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.
See "Class oracle.ord.media.annotator.handlers.AnnTaskManager" for more information on the annotation task manager.
This class extends java.lang.Object.
Format
public AnnTaskMonitor(oracle.ord.media.annotator.handlers.AnnTaskManager annTaskMgr)
Description
Creates an AnnTaskMonitor object.
Parameters
The annotation task manager that tracks the current task on the server side.
Return Value
None.
Exceptions
None.
Example
AnnTaskManager tskmgr = new AnnTaskManager(); AnnTaskMonitor mon = new AnnTaskMonitor(tskmgr);
Format
public java.lang.String getMessage( )
Description
Gets the current message from the task progress monitor.
Parameters
None.
Return Value
This method returns the current message of the task progress monitor, as a String.
Exceptions
None.
Example
String message = atm.getMessage();
Format
public int getTaskCurrent( )
Description
Gets the current value of the task progress monitor.
Parameters
None.
Return Value
This method returns the current value of the task progress monitor. Typically, it returns a number between the start value and the end value of the task. See getTaskStart( ) and getTaskEnd( ) for more information. You can set the current value using the AnnTaskManager.setTaskCurrent( ) method. See "setTaskCurrent(int)" for more information.
Exceptions
None.
Example
See "isDone( )" for an example of this method.
Format
public int getTaskEnd( )
Description
Gets the end value of the task progress monitor.
Parameters
None.
Return Value
This method returns the end value of the task progress monitor. Typically, the task end value is set to 100. You can set the value using the AnnTaskManager.setTask( ) method. See "setTask( )" for more information.
Exceptions
None.
Example
See the isInitialized( ) method for an example of this method.
Format
public int getTaskStart( )
Description
Gets the starting value of the task progress monitor.
Parameters
None.
Return Value
This method returns the initial value of the task progress monitor. Typically, the task start value is set to zero. You can set the value using the AnnTaskManager.setTask( ) method. See "setTask( )" for more information.
Exceptions
None.
Example
int i = atm.getTaskStart();
Format
public boolean isDone( )
Description
Determines if the task has been completed.
Parameters
None.
Return Value
This method returns true if the task has been completed; false otherwise.
Exceptions
None.
Example
if(atm.isDone == false)
int i = atm.getTaskCurrent();
Format
public boolean isInitialized( )
Description
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.
Parameters
None.
Return Value
This method returns true if the annotation task monitor is initialized; false otherwise.
Exceptions
None.
Example
if(atm.isInitialized())
int i = atm.getTaskEnd();
This section presents reference information on the constructors and 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 "Class oracle.ord.media.annotator.listener.AnnListener" 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:
public static final int OP_MODE_ASYNCH
This signifies asynchronous mode.
public static final int OP_MODE_SYNCH
This signifies synchronous mode.
The examples in this section are based on the assumption that an AnnotationHandler object named handler has been created. See Section 3.4 for an example of creating an AnnotationHandler object. In addition, see the online examples SimpleAnnotator.java and SimpleAnnotatorAsynch.java, available in the following directory:
On UNIX:
$ORACLE_HOME/ord/Annotator/demo/examples/src
On Windows:
ORACLE_HOME\ord\Annotator\demo\examples\src
Format
public AnnotationHandler( )
Description
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 "Class oracle.ord.media.annotator.utils.Status" for more information about Status.
Parameters
None.
Return Value
None.
Exceptions
oracle.ord.media.annotator.handlers.AnnotationHandlerException
Example
AnnotationHandler handler = new AnnotationHandler();
Format
public AnnotationHandler(int iOperationMode)
Description
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 "Class oracle.ord.media.annotator.utils.Status" for more information about Status.
Parameters
The mode (either synchronous or asynchronous) that the annotation handler will use.
Return Value
None.
Exceptions
oracle.ord.media.annotator.handlers.AnnotationHandlerException
Example
See Section 3.4 for an example of this method.
Format
public Annotation createAnnotationByname(java.lang.String szAnnName)
Description
Creates a new instance of an annotation, given the annotation type.
Parameters
The annotation type of the annotation to be created.
Return Value
This method returns the newly created annotation.
Exceptions
AnnotatorException
Example
See Section 3.6 for an example of this method.
Format
public void exportToXML(java.io.Writer w, Annotation ann)
Description
Builds an XML representation of an annotation and its subannotations and exports the representation to an XML file.
Parameters
The Writer object that will write the content to XML.
The annotation to be exported.
Return Value
None.
Exceptions
None.
Example
See Section 3.13 for an example of this method.
Format
public AnnTaskMonitor extractMedia(Annotation ann, AnnListener annListener)
Description
Extracts media samples from an annotation. After the extraction is complete, the method calls the call-back function AnnListener.extractionPerformed( ).
Parameters
The annotation from which samples will be extracted.
The listener that will be notified upon the completion of the extraction.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public java.util.Enumeration getAnnotationNames( )
Description
Returns a list of String objects with the names of the annotation types that are defined in the annotation descriptor XML files.
Parameters
None.
Return Value
This method returns a list of String objects with the names of the annotation types that are defined in the annotation descriptor XML files.
Exceptions
AnnotatorException
Example
Enumeration annTypes = handler.getAnnotationNames();
Format
public java.util.Enumeration getParserNames( )
Description
Returns a list of the parser types defined in the parser descriptor XML files.
Parameters
None.
Return Value
This method returns a list of the parser types defined in the parser descriptor XML files.
Exceptions
AnnotatorException
Example
Enumeration parserTypes = handler.getParserNames();
Format
public final java.lang.String getRelVersion( )
Description
Returns the version of the interMedia Annotator release.
Parameters
None.
Return Value
This method returns the version of the interMedia Annotator release.
Exceptions
None.
Example
String release = handler.getRelVersion()
Format
public Annotation importFromXML(java.io.Reader r)
Description
Creates a new Annotation object whose content is read from an XML file.
Parameters
The Reader object that will read the content from the XML file.
Return Value
This method returns a new Annotation object.
Exceptions
oracle.ord.media.annotator.annotations.AnnotationException
oracle.ord.media.annotator.handlers.annotation.AnnotationFactoryException
Example
java.io.FileReader reader = new FileReader("e:\\myAnnotation.xml");
Annotation ann = new Annotation(handler.importFromXML(reader));
Format
public AnnTaskMonitor insertMedia(Annotation ann, OrdMapping om, AnnListener annListener)
Description
Creates a new connection to the database and inserts the annotation into an Oracle interMedia object on the database server.
Parameters
The annotation to be inserted.
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 operation.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
See Section 3.7 for an example of this method.
Format
public AnnTaskMonitor insertMedia(Annotation ann, OrdMapping om, AnnListener annListener,
java.sql.Connection conn)
Description
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( ).
Parameters
The annotation to be inserted.
The mapping between the annotation and an Oracle interMedia object on the database server. See the interMedia 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.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
handler.insertMedia(ann, ofm, listener, null);
Format
public boolean isExtractable (Annotation ann)
Description
Determines if it is possible to extract samples from the given annotation or any of its subannotations.
Parameters
The annotation from which you want to extract samples.
Return Value
This method returns true if it is possible to extract samples; false otherwise.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public boolean isPlayable(Annotation ann)
Description
Determines if it is possible to play the media content represented by the given annotation.
Parameters
The annotation from which you want to play the content.
Return Value
This method returns true if it is possible to play the media content; false otherwise.
Exceptions
None.
Example
if(handler.isPlayable(ann)){
handler.playMedia(ann,listener)
}
Format
public AnnTaskMonitor parseMedia(java.io.InputStream is, java.lang.String sURL,
AnnListener annListener)
Description
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:
Attempts to set the MEDIA_SOURCE_MIME_TYPE attribute in the annotation. Unlike parseMedia(String, AnnListener) and parseMedia(String, AnnListener, String), this method sets only one attribute.
Invokes the call-back function AnnListener.parsePerformed( )
Parameters
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.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
//Assign the URL to a String named szURL
//The current client (represented by this) implements the AnnListener interface
FileInputStream is = new FileInputStream("test.mpg");
AnnTaskMonitor atm = handler.parseMedia(is, szURL, this);
Format
public AnnTaskMonitor parseMedia(java.lang.String sURL, AnnListener annListener)
Description
Parses the source and creates an annotation of the given URL. After the parsing is complete, the method performs the following operations:
Attempts to set the following attributes in the annotation:
MEDIA_SIZE
MEDIA_SOURCE_DIRECTORY
MEDIA_SOURCE_FILENAME
MEDIA_SOURCE_PROTOCOL
MEDIA_SOURCE_URL
MEDIA_SOURCE_MIME_TYPE
Invokes the call-back function AnnListener.parsePerformed( )
Parameters
The URL of the media file to be parsed.
The listener that will be notified upon the completion of the parsing.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
See Section 3.5 for an example of this method.
Format
public AnnTaskMonitor parseMedia(java.lang.String sURL, AnnListener annListener,
java.lang.String szCharEncoding)
Description
Parses the source and creates an annotation of the given URL. After the parsing is complete, the method performs the following operations:
Attempts to set the following attributes in the annotation:
MEDIA_SIZE
MEDIA_SOURCE_DIRECTORY
MEDIA_SOURCE_FILENAME
MEDIA_SOURCE_PROTOCOL
MEDIA_SOURCE_URL
MEDIA_SOURCE_MIME_TYPE
Invokes the call-back function AnnListener.parsePerformed( )
This method allows parsing of annotations from a media file, regardless of the character set used in the media file. For example, this method can parse media that contains international character sets, such as Shift-JIS for Japanese characters.
Parameters
The URL of the media file to be parsed.
The listener that will be notified upon the completion of the parsing.
The character encoding.
Return Value
This method returns the AnnTaskMonitor object associated with this task.
Exceptions
None.
Example
See Section 3.5 for an example of this method.
Format
public void playMedia(Annotation ann, AnnListener annListener)
Description
Plays the content represented by the named annotation. This method is synchronous; it does not return an AnnTaskMonitor object.
Parameters
The annotation from which you want to play the content.
The listener that will be notified upon the completion of the operation.
Return Value
None.
Exceptions
None.
Example
See the isPlayable( ) method for an example of this method.
This section presents reference information on the constructor and 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.
Format
public OrdFileMapping(java.lang.String szFileName)
Description
Creates an OrdFileMapping object, which contains the mapping of the contents of the annotation to the database.
Parameters
The name of the file that contains the mapping.
Return Value
None.
Exceptions
None.
Example
OrdFileMapping ofm = new OrdFileMapping("e:\\mylogic.ofm");
See Section 3.7 for an example that uses this constructor.
Format
public java.lang.String generateStatement(Annotation ann)
Description
Returns the PL/SQL statement that is used to insert the annotation into the database. This statement is processed by the interMedia Annotator preprocessor to insert interMedia Annotator-specific directives.
This method overrides OrdMapping.generateStatement( ).
Parameters
The annotation to be inserted.
Return Value
This method returns the PL/SQL statement that will be used to insert the annotation into the database.
Exceptions
java.io.IOException
Example
String sqlStatement = ofm.generateStatement(ann);
This section presents reference information on the constructor and methods of the MimeMap class. This class holds the mapping between a MIME type or file extension and the annotation, parser, and player names as specified in the MIME map file, Annotator.mime. This class has dependencies on properties from the Preferences class in that the file to be read for the mappings is specified by the Preferences class.
Format
public MimeMap( )
Description
Reads the mapping between a MIME type and the annotation, parser, and player names from the MIME mapping file into a hash table. The mapping file is specified by the MimeMapFile parameter in the Annotator.prefs file. By default, the MIME mapping file is named Annotator.mime and is located in the following directory:
On UNIX: $ORACLE_HOME/ord/Annotator/lib/conf
On Windows: ORACLE_HOME\ord\Annotator\lib\conf
The Annotator.prefs file is also located in this directory. For more information about setting the location of the Annotator.mime file, see Section 2.1.
Parameters
None.
Return Value
None.
Exceptions
oracle.ord.media.annotator.AnnotatorException
Example
MimeMap m_map = new MimeMap();
Format
public java.lang.Object clone( )
Description
Creates and returns a copy of this object. For more information, see the Java documentation for the java.lang.Object.clone( ) method.
Parameters
None.
Return Value
This method returns a copy of the current MimeMapping object, as an Object.
Exceptions
java.lang.CloneNotSupportedException
Example
None; this method should be called only by advanced programmers.
Format
public java.lang.String getAnnotationName(java.lang.String szMimeType)
Description
Returns the class name of the annotation with the specified MIME type.
Parameters
The name of the MIME type.
Return Value
The fully qualified class name of the Annotation that is mapped to the specified MIME type.
Exceptions
None.
Example
String name = m_map.getAnnotationName("image/jpeg");
Format
public java.util.Enumeration getMimeTypes( )
Description
Returns the enumeration of all the MIME types currently registered to be handled by interMedia Annotator.
Parameters
None.
Return Value
This method returns the enumeration of all the MIME types.
Exceptions
None.
Example
Enumeration eMimeTypes = m_map.getMimeTypes();
Format
public int getMimeTypesCount( )
Description
Returns the number of MIME types in the hash table.
Parameters
None.
Return Value
This method returns the number of MIME types in the hash table, as an integer.
Exceptions
None.
Example
int mimeTypeCount = m_map.getMimeTypesCount();
Format
public java.lang.String getParserName(java.lang.String szMIMEType)
Description
Returns the class name of the parser that is mapped to the specified MIME type.
Parameters
The name of the MIME type.
Return Value
This method returns the fully qualified class name of the parser that is mapped to the specified MIME type.
Exceptions
None.
Example
String name = m_map.getParserName("image/jpeg");
Format
public java.util.Enumeration getParsers( )
Description
Returns the enumeration of all the parsers currently registered to a MIME type by interMedia Annotator.
Parameters
None.
Return Value
This method returns the enumeration of all the parsers.
Exceptions
None.
Example
Enumeration eparsers = m_map.getParsers();
Format
public boolean handlesMime(java.lang.String szMIMEType)
Description
Determines if an annotation, parser, or player has been defined in the hash table for the specified MIME type.
Parameters
The name of the MIME type.
Return Value
A Boolean value. True is returned if the specified MIME type has been defined for an annotation, parser, or player; false otherwise.
Exceptions
None.
Example
if(m_map.handlesMime(szMIMEtype) == false) m_map.removeMimeType(szMIMEType);
Format
public void removeMimeType(java.lang.String szMIMEType)
Description
Removes the MIME type from the hash table.
Parameters
The name of the MIME type.
Return Value
None.
Exceptions
None.
Example
m_map.removeMimeType(szMIMEType);
Format
public void saveMIMEMappings()
Description
Writes the MIME settings to the MIME mapping file, Annotator.mime.
Parameters
None.
Return Value
None.
Exceptions
java.io.Exception
Example
None; this method should be called only by advanced programmers.
Format
public void setMimeMap(java.lang.String szMimeType, java.lang.String szAnnotation,
java.lang.String szParser, java.lang.String szPlayer)
Description
Maps a MIME type to an annotation, parser, and player.
Parameters
The name of the MIME type.
The name of the annotation to be mapped to the MIME type.
The name of the parser to be mapped to the MIME type.
The name of the player to be mapped to the MIME type.
Return Value
None.
Exceptions
java.io.IOException
Example
None; this method should be called only by advanced programmers.
This section presents reference information on the methods of the AnnListener interface. The client must implement this interface in order to invoke the interMedia Annotator engine.
This class extends java.util.EventListener.
Format
public void errorOccured(Annotation ann, java.lang.Exception e)
Description
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.
Parameters
The annotation instance.
An exception that explains why the failure occurred.
Return Value
None.
Exceptions
None.
Example
See Section 3.10 for an example of this method.
Format
public void extractionPerformed(Annotation ann)
Description
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. To view the new attributes, the client may need to refresh the annotation.
Parameters
The annotation instance from which the extraction was performed.
Return Value
None.
Exceptions
None.
Example
See Section 3.7 for an example of this method.
Format
public void insertionPerformed(Annotation ann, java.sql.Connection conn)
Description
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( ).
Parameters
The annotation instance that has been inserted into the database.
The JDBC connection used to perform the insertion.
Return Value
None.
Exceptions
None.
Example
See Section 3.8 for an example of this method.
Format
public void parsePerformed(Annotation ann)
Description
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( ).
Parameters
The newly created media annotation.
Return Value
None.
Exceptions
None.
Example
See Section 3.6 for an example of this method.
Format
public void warningOccured(Annotation ann, java.lang.Exception e)
Description
Returns an exception in the case of nonfatal errors.
Parameters
The annotation instance.
An exception that explains why the failure occurred.
Return Value
None.
Exceptions
None.
Example
See Section 3.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.
Format
public void ConsoleOutput(java.lang.String szOutput)
Description
Prints status messages while the engine is running.
Parameters
The status message to be printed.
Return Value
None.
Exceptions
None.
Example
See Section 3.11 for an example of this method.
This section presents reference information on the constructors and 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.
When the engine is initialized, it loads a static copy of the system Preference object, reading from the Annotator.prefs file in the configuration directory. By default, Oracle interMedia Annotator assumes that the configuration directory is the \lib\conf or /lib/conf subdirectory of the current directory.
However, at installation, the configuration files are placed in the following directory:
On UNIX: $ORACLE_HOME/ord/Annotator/lib/conf
On Windows: ORACLE_HOME\ord\Annotator\lib\conf
You must ensure that the configuration directory contains the preferences file and other configuration files before you use Oracle interMedia Annotator. For example, if you run interMedia Annotator from the directory /usr5/myfiles, interMedia Annotator assumes the configuration directory to be /usr5/myfiles/lib/conf.
For more information about the preferences file, see Section 2.1.
You can set the preferences using the setPreferences( ) method and you can retrieve the preferences using the getPrefs( ) method. See "setPreferences( )" and "getPrefs( )" for more information.
The implementation of this class is independent of the other interMedia Annotator classes.
This class extends java.lang.Object and implements oracle.ord.media.annotator.utils.PreferenceConstants and java.lang.Cloneable.
Format
public Preferences( )
Description
Creates a Preferences object, reading preferences from the default preferences file, Annotator.prefs. For more information about this file, see Section 2.1.
Parameters
None.
Return Value
None.
Exceptions
None.
Example
Preferences prefs = new Preferences();
Format
public Preferences(java.util.Properties props)
Description
Creates a Preferences object, reading preferences from a property list and populating the object with the preferences. The list can be loaded from a file, which must use the format and parameters described in Section 2.1.
Parameters
The property list.
Return Value
None.
Exceptions
None.
Example
// Create a new property list.
Properties myprop = new Properties();
// Populate the list with the preferences specified in a file.
// Use a full or relative path for the file name.
myprop.load(new FileInputStream("my_file_name");
Preferences pref = new Preferences(myprop);
Preferences.setPreferences(pref);
Format
public java.lang.Object clone( )
Description
Creates and returns a copy of this object. For more information, see the Java documentation for the java.lang.Object.clone( ) method.
Parameters
None.
Return Value
This method returns a copy of the current Preferences object, as an Object.
Exceptions
java.lang.CloneNotSupportedException
Example
None; this method should be called only by advanced programmers who want to manually access the interMedia Annotator preferences.
Format
public static Preferences getPrefs( )
Description
Gets the system Preferences object of the current annotation.
Parameters
None.
Return Value
This method returns the Preferences object of the current annotation.
Exceptions
None.
Example
See Section 3.4 for an example of this method.
Format
public java.lang.String getProperty(java.lang.String s)
Description
Gets the value of the given property from the preferences of the current annotation.
Parameters
The name of the property for which you will get the value.
Return Value
This method returns the value of the property, as a String.
Exceptions
None.
Example
None; this method should be called only by advanced programmers who want to manually access the interMedia Annotator preferences.
Format
public void saveToFile( )
Description
Saves the preferences to a file.
Parameters
None.
Return Value
None.
Exceptions
None.
Example
None; this method should be called only by advanced programmers who want to manually access the interMedia Annotator preferences.
Format
public static void setPreferences(Preferences prefs)
Description
Sets the system preferences of the current annotation to match the given Preferences object.
Parameters
The preferences to be set in the annotation.
Return Value
None.
Exceptions
None.
Example
Preferences pref = new Preferences(myprop); Preferences.setPreferences(pref);
Format
public void setProperty(java.lang.String s, java.lang.Object o)
Description
Sets the given property to the given value.
Parameters
The name of the property that you will set.
The value to set.
Return Value
None.
Exceptions
None.
Example
See Section 3.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 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 interMedia Annotator engine in the Java virtual machine. Note that the Status class is not thread-safe.
This class extends java.lang.Object.
The class contains the following fields that are used to set the error level:
public static final short ERR_LEVEL_WARNING
public static final short ERR_LEVEL_ERROR
public static final short ERR_LEVEL_FATALERROR
The class contains the following fields that are used to set the output mode:
public static final short OUTPUT_MODE_STATUS
public static final short OUTPUT_MODE_TERSE
public static final short OUTPUT_MODE_TRACE
public static final short OUTPUT_MODE_VERBOSE
Format
public short GetOutputMode( )
Description
Returns the current output mode of the Status object.
Parameters
None.
Return Value
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.
Exceptions
None.
Example
short outputMode = m_st.GetOutputMode();
Format
public static Status getStatus( )
Description
Gets the Status object of the current annotation.
Parameters
None.
Return Value
This method returns the Status object.
Exceptions
None.
Example
See Section 3.4 for an example of this method.
Format
public static void initStatus(OutputListener ol)
Description
Initializes the Status object. This method should be invoked before initializing the AnnotationHandler object.
Parameters
The instance of the OutputListener class that will receive the status messages from the AnnotationHandler object.
Return Value
None.
Exceptions
None.
Example
See Section 3.4 for an example of this method.
Format
public void Report(short omDesignated, java.lang.String szStatus)
Description
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.
Parameters
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.
Return Value
None.
Exceptions
None.
Example
See Section 3.4 for an example of this method.
Format
public void ReportError(short sErrLevel, java.lang.Object oInstance,
java.lang.String szMethodName, int iLineNumber, java.lang.String szDesc)
Description
Reports errors through the System.err stream. Multiple error levels can be given to specify consequences.
Parameters
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.
Return Value
None.
Exceptions
None.
Example
status.ReportError(Status.ERR_LEVEL_WARNING, this,
"name_of_current_method", iCurrentLineNum, "error description");
Format
public void ReportError(short sErrLevel, java.lang.Throwable sException)
Description
Reports errors through the System.err stream. Multiple error levels can be given to specify consequences.
Parameters
The 16-bit error level (ERR_LEVEL_WARNING, ERR_LEVEL_ERROR, or ERR_LEVEL_FATALERROR).
The exception that was raised, as a Throwable object.
Return Value
None.
Exceptions
None.
Example
status.ReportError(Status.ERR_LEVEL_WARNING, myExceptionInstance);
Format
public void SetOutputMode(short omNew)
Description
Sets the status output mode to STATUS, TERSE, TRACE, or VERBOSE.
Parameters
The output mode to be set; the value should be OUTPUT_MODE_STATUS, OUTPUT_MODE_TERSE, OUTPUT_MODE_TRACE, or OUTPUT_MODE_VERBOSE.
Return Value
None.
Exceptions
None.
Example
See Section 3.4 for an example of this method.
|
 Copyright © 1999, 2002 Oracle Corporation All rights reserved |
|