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 inexperienced users will need to write a custom Annotator parser. See the Javadoc included with the Annotator installation for complete reference information.
To create a custom parser, in addition to using these APIs to create a Java class, you must write a parser descriptor XML file and add it to the <ORACLE_HOME>\ord\Annotator/lib/descriptors/parsers directory. For an example of a parser descriptor XML file, see <ORACLE_HOME>\ord\Annotator/lib/descriptors/parsers/AuParser.xml.
This section presents reference information on the methods of the AnnTaskManager class, which creates an annotation task manager. The annotation task manager 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 monitor, see Section 6.4.
This class extends java.lang.Object.
This class contains the following fields:
public void addIterCounter(int iIterCounter)
Adds the given number to the counter.
The value to be added to the counter.
None.
None.
m_annTaskMan.addIterCounter(4);
public void decrIterCounter( )
Decreases the value of the counter by one.
None.
None.
None.
m_annTaskMan.decrIterCounter( );
public void done( )
Signifies that the current task is complete.
None.
None.
None.
See Section 8.9 for an example of this method.
public int getIterCounter( )
Gets the current value of the counter.
None.
This method returns the current value of the counter.
None.
int counter = m_annTaskMan.getIterCounter( );
public java.lang.String getMessage( )
Gets the current message of the task progress monitor.
None.
This method returns the current message of the task progress monitor.
None.
String message = m_annTaskMan.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.
int progress = m_annTaskMan.getTaskCurrent( );
public int getTaskEnd( )
Gets the ending value of the task progress monitor.
None.
This method returns the the ending value of the task progress monitor.
None.
int end = m_annTaskMan.getTaskEnd( );
public int getTaskStart( )
Gets the starting value of the task progress monitor.
None.
This method returns the starting value of the task progress monitor.
None.
See the isInitialized( ) method for an example of this method.
public void incrIterCounter( )
Increases the value of the counter by one.
None.
None.
None.
m_annTaskMan.incrIterCounter( );
public void incrTaskCurrent(int iTaskToAdd)
Adds the given value to the current value of the task progress monitor.
The amount to add to the current value of the task progress monitor.
None.
None.
m_annTaskMan.incrTaskCurrent(4);
public boolean isDone( )
Determines if the current task has been completed.
None.
This method returns true if the current task has been completed; false otherwise.
None.
if(m_annTaskMan.isDone( ) == false) m_annTaskMan.setIterCounter(0);
public boolean isInitialized( )
Determines if the annotation task monitor has been initialized. If it has been initialized, then you will be able to use the getTaskStart( ) and getTaskEnd( ) methods.
None.
This method returns true if the annotation task monitor has been initialized; false otherwise.
None.
if(m_annTaskMan.isInitialized( )) m_annTaskMan.getTaskStart( );
public void setIterCounter(int iIterCounter)
Sets the counter to keep track of an iterative process. When the done( ) method is called, the counter decreases by one. The isDone( ) method returns true if the counter is zero.
The initial value of the counter. The default value is 1.
None.
None.
See the isDone( ) method for an example of this method.
public void setMessage(java.lang.String szMessage)
Sets the message of the task progress monitor.
The message to be set.
None.
None.
m_annTaskMan.setMessage("Parsing AU Header...");
public void setTask(int iTaskStart, int iTaskEnd)
Sets the start and end values of the task progress monitor.
The starting value of the task progress monitor.
The ending value of the task progress monitor.
None.
None.
See Section 8.7 for an example of this method.
public void setTaskCurrent(int iTaskCurrent)
Sets the current value of the task progress monitor.
The value to be set for the task progress monitor.
None.
None.
See Section 8.7 for an example of this method.
public void setTaskCurrent(int iTaskCurrent, java.lang.String szMessage)
Sets the current value and the message of the task progress monitor.
The value to be set for the task progress monitor.
The message to be set for the task progress monitor.
None.
None.
See Section 8.7 for an example of this method.
This section presents reference information on the methods of the AnnotationFactory class. This class is the factory class for annotations; it contains two sub-factories (for parser descriptors and annotation descriptors), which are used to create parsers and annotations. The AnnotationFactory class can also create annotations by name.
This class extends java.lang.Object.
public oracle.ord.media.annotator.annotations.Annotation createAnnotationByName(java.lang.String
szAnnName)
Instantiates an annotation by getting the annotation descriptor from the annotation descriptor factory.
The name of the new annotation.
This method returns a newly created annotation.
oracle.ord.media.annotator.handlers.annotation.AnnotationFactoryException
See Section 5.6 for an example of this method.
This section presents reference information on the methods of the Parser class. This class is the base class for all parsers; you must extend this class to write your own parser. The Parser class is an abstract class that defines the functions that are expected from a parser: parsing metadata, extracting samples, and saving metadata to annotations. You must implement the methods that provide these functions in all subclasses of the Parser class.
The Parser class operates on the basis of an underlying wrapper of a DataInputStream object, which is used to read objects during the parsing process. The Parser object is associated with an annotation instance that is populated with the metadata that the parser finds in the stream. The Parser object is associated with an instance of the AnnTaskManager class that provides the GUI with progress information related to the parsing of the media data. The Parser object is associated with an AnnotationFactory object to create a sub-annotation of the associated annotation instance.
This class extends java.lang.Object and contains the following fields:
This is the AnnotationFactory object that is used to create sub-annotations.
This is the annotation that is processed by the parser.
This is the AnnTaskManager object that is used to produce progress information.
This determines if the parser can extract samples from the annotation. The default is false.
This is the media source to be processed.
This is the in-memory representation of the parser descriptor XML file.
This is the Status object that is used to produce trace information for the GUI.
public abstract void extractSamples( )
Extracts samples from the current media source and sets the samples in the current annotation instance. The AnnotatorEngine object sets the m_madisResource field and the m_annInst field automatically with the setSource( ) and setAnnotation( ) methods, respectively.
None.
None.
ParserException
See the Annotator Javadoc for more information.
See Section 8.9 for an example of this method.
public abstract void parse( )
Parses the source and extracts the metadata. The AnnotatorEngine object sets the m_madisResource field and the m_annInst field automatically with the setSource( ) and setAnnotation( ) methods, respectively.
After running this method, you should call the saveToAnnotation( ) method to set the metadata in the annotation.
None.
None.
ParserException
See the Annotator Javadoc for more information.
See Section 8.7 for an example of this method.
public abstract void saveToAnnotation( )
Sets the extracted metadata in the annotation in the m_annInst field. The annotation is set by the setAnnotation( ) method automatically before parsing.
You should call this method immediately after parsing the media source; this ensures that the annotation is modified only if parsing is successful.
None.
None.
None.
See Section 8.7 for an example of this method.
This section presents reference information on the methods of the MADataInputStream class. This class provides methods to read the following types from an input stream:
This class extends java.lang.Object.
public int available( )
Returns the number of bytes that can be read or skipped in this input stream without blocking by the next caller of a method for this input stream.
None.
This method returns the number of bytes that can be read or skipped without blocking by the next caller.
java.io.IOException
int availbytes = m_madisResource.available( );
public void close( )
Closes the input stream and releases any system resources associated with the stream.
None.
None.
None.
if(m_madisResource.getLeft( ) == 0) m_madisResource.close( );
public void endBlock(FourCC fccChunk)
Skips all unread bytes in the marked block.
The Four Character Code used to identify the block; it is used for reading purposes only.
None.
java.io.IOException
FourCC code = m_madisResource.readFourCC( ); long size = m_madisResource.readLong( ); m_madisResource.startBlock(size); ... m_madisResource.endBlock(code);
public long getBytesRead( )
Gets the total number of bytes read from the input stream.
None.
This method returns the total number of bytes read.
None.
long bytesRead = m_madisResource.getBytesRead( );
public long getLeft( )
Gets the number of unread bytes in the input stream.
None.
This method returns the number of unread bytes in the input stream.
None.
See the close( ) method for an example of this method.
public boolean isLittleEndian( )
Checks to see whether or not the input stream is able to read data that is in the little-endian format.
None.
This method returns true if the stream is able to read little-endian data; false otherwise.
None.
See the setLittleEndian( ) method for an example of this method.
public void mark(int readLimit)
Marks the current position in the input stream. A subsequent call to the reset( ) method repositions the stream at the last marked position.
The maximum number of bytes that can be read before the mark position becomes invalid.
None.
None.
m_madisResource.mark(5000); int i = 128; if(i == m_madisResource(skipBytes(i)) int data = m_madisResource.readInt( ); m_madisResource.reset( );
public final int read(byte[ ] b)
Reads some number of bytes from the input stream and stores them in the buffer array b. The number of bytes actually read is returned as an integer. To ensure that some data will always be read into the buffer, this method blocks until input data is available, end-of-file is detected, or an exception is thrown.
If b is null, a NullPointerException is thrown. If the length of b is 0, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least 1 byte. If no byte is available because the stream is at end-of-file, the value -1 is returned; otherwise, at least 1 byte is read and stored in b.
The buffer into which the data will be read.
This method returns the number of bytes that were read.
java.io.IOException
byte[ ] buffer = new byte[4000]; m_madisResource.read(buffer);
public final int read(byte[ ] b, int off, int len)
Reads a number of bytes (up to the value of len) of data from the input stream into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly 0. The number of bytes actually read is returned as an integer.
If len is 0, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least 1 byte. If no byte is available because the stream is at end-of-file, the value -1 is returned; otherwise, at least 1 byte is read and stored into the array.
To ensure that some data will always be read into the buffer, this method blocks until input data is available, end-of-file is detected, or an exception is thrown.
If b is null, a NullPointerException is thrown. If the value of off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If the first byte cannot be read for any reason other than end-of-file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed.
The buffer into which the data will be read.
The offset from the beginning of the buffer at which the data will be read.
The maximum number of bytes to be read.
This method returns the number of bytes that were read.
java.io.IOException
byte[ ] buffer = new byte[4000]; m_madisResource.read(buffer,64,128);
public AVILanguage readAVILanguage( )
Reads the next AVI language code in the underlying input stream.
See the Javadoc for more information about the AVILanguage class.
None.
This method returns the AVI language code that was read from the input stream.
java.io.IOException
AVILanguageCode code = m_madisResource.readAVILanguage( );
public byte readByte( )
Reads the next byte from the input stream.
None.
This method returns the byte that was read from the input stream.
java.io.IOException
byte b = m_madisResource.readByte( );
public int readByteArray(byte[ ] bBuffer, int iNumBytesToRead)
Reads the given number of bytes from the underlying data input stream into the given byte array.
The byte array into which the data will be read.
The number of bytes to be read.
This method returns the number of bytes that were read.
java.io.IOException
int i = 256; byte[ ] b = new byte[i]; if(i == m_madisResource.readByteArray(b,i)) System.out.println("Read successful");
public byte[ ] readByteArray(int iNumBytesToRead)
Reads the given number of bytes from the underlying data input stream into a byte array.
The number of bytes to be read.
This method returns the byte array that was read.
java.io.IOException
int i = 256; byte[ ] b = new byte[i]; b = m_madisResource.readByteArray(i);
public long readColor48( )
Reads 6 bytes from the data stream and returns a value in the primitive type long that represents the color in RGB format.
This is used for the QuickTime file format.
None.
This method returns the value of the color in RGB format in the primitive type long.
java.io.IOException
long RGB = m_madisResource.readColor48( );
public java.util.Date readDate( )
Reads the next java.util.Date object from the underlying input stream.
None.
This method returns the java.util.Date object that was read from the input stream.
java.io.IOException
java.util.Date date = m_madisResource.readDate( );
public java.util.Date readDate(int iLen, java.lang.String szPattern)
Returns the bytes read from the data stream as a java.util.Date object, using the given named pattern.
The number of bytes to be read.
The date pattern of the bytes, following the specification of java.text.SimpleDateFormat.
This method returns a java.util.Date object that was read.
java.io.IOException
java.util.Date date = m_madisResource.readDate(13,"yyyy.MM.dd hh:mm a")
public Extended readExtended( )
Reads the next 80-bit, extended floating-point number in the underlying input stream.
See the Javadoc for more information about the Extended class.
None.
This method returns the 80-bit, extended floating-point number that was read from the input stream.
java.io.IOException
Extended number = m_madisResource.readExtended( );
public FixedPoint16 readFixedPoint16( )
Reads the next 16-bit, fixed-point number in the underlying input stream.
See the Javadoc for more information about the FixedPoint16 class.
None.
This method returns the 16-bit, fixed-point number that was read from the input stream.
java.io.IOException
FixedPoint16 number = m_madisResource.readFixedPoint16( );
public FixedPoint32 readFixedPoint32( )
Reads the next 32-bit, fixed-point number in the underlying input stream.
See the Javadoc for more information about the FixedPoint32 class.
None.
This method returns the 32-bit, fixed-point number that was read from the input stream.
java.io.IOException
FixedPoint32 number = m_madisResource.readFixedPoint32( );
public FourCC readFourCC( )
Reads the next Four Character Code in the underlying input stream.
See the javadoc for more information about the FourCC class.
None.
This method returns the Four Character Code that was read from the input stream.
java.io.IOException
FourCC code = m_madisResource.readFourCC( );
public int readInt( )
Reads the next int from the input stream.
None.
This method returns the int that was read from the input stream.
None.
See the mark( ) method for an example of this method.
public long readLong( )
Reads the next value of the primitive type long from the underlying input stream.
None.
This method returns the value of the primitive type long that was read from the input stream.
java.io.IOException
long number = m_madisResource.readLong( );
public java.lang.String readPascalString( )
Reads the next Pascal string from the underlying input stream and returns the contents of the Pascal string as a Java String object.
None.
This method returns the contents of the Pascal string, as a Java String object.
java.io.IOException
String pascal = m_madisResource.readPascalString( );
public java.lang.String readPascalString(int iNumBytesToRead)
Reads the next Pascal string from the underlying input stream and returns the contents of the Pascal string as a Java String object.
The number of bytes to read from the input stream.
This method returns the contents of the Pascal string, as a Java String object.
java.io.IOException
String pascal = m_madisResource.readPascalString(32);
public java.lang.String readPascalString(java.lang.Short sLengthSize)
Reads the next enhanced Pascal string from the underlying input stream and returns the contents of the Pascal string as a Java String object.
An enhanced Pascal string is a Pascal string with a string length of 8, 16, or 32 bits set at the beginning, followed by the contents of the string. The length must be 8, 16, or 32 bits.
The number of bits in the string. It must be 8, 16, or 32.
This method returns the contents of the Pascal string, as a Java String object.
java.io.IOException
String pascal = m_madisResource.readPascalString(32);
public QTLanguage readQTLanguage( )
Reads the next QuickTime language code from the underlying input stream.
See the Javadoc for more information about the QTLanguage object.
None.
This method returns the QuickTime language code that was read from the input stream.
java.io.IOException
QTLanguage code = m_madisResource.readQTLanguage( );
public Rectangle readRectangle( )
Reads 8 bytes of data from the input stream, which are interpreted as the coordinates of a rectangle.
This is used for the QuickTime and RIFF data formats.
None.
This method returns the 8 bytes that were read from the input stream, as a Rectangle object.
java.io.IOException
Rectangle size = m_madisResource.readRectangle( );
public short readShort( )
Reads the next short in the input stream.
None.
This method returns the short that was read from the input stream.
None.
short number = m_madisResource.readShort( );
public java.lang.String readString(int iNumBytesToRead)
Reads the given number of bytes from the underlying input stream and formats them as a String.
The number of bytes to be read.
This method returns the String that was read from the input stream.
java.io.IOException
String info = m_madisResource.readString(24);
public int readUnsignedByte( )
Reads the next unsigned byte from the underlying input stream.
None.
This method returns the unsigned byte that was read from the input stream object.
java.io.IOException
int number = m_madisResource.readUnsignedByte( );
public long readUnsignedInt( )
Reads the next unsigned int from the underlying input stream.
None.
This method returns the unsigned int that was read from the input stream.
java.io.IOException
long number = m_madisResource.readUnsignedInt( );
public int readUnsignedShort( )
Reads the next unsigned short from the underlying input stream.
None.
This method returns the short that was read from the input stream.
java.io.IOException
int number = m_madisResource.readUnsignedShort( );
public void reset( )
Repositions the underlying input stream to the point at which the last mark was placed.
None.
None.
java.io.IOException
See the mark( ) method for an example of this method.
public void setLittleEndian(boolean bLittleEndian)
Sets whether or not the input stream can read data that is stored in little-endian format.
Determines whether or not the stream can read data that is stored in little-endian format.
None.
None.
if(m_madisResource.isLittleEndian( )) m_madisResource.setLittleEndian(false);
public int skipBytes(int iNum)
Skips the given number of bytes in the underlying input stream.
The number of bytes to be skipped.
This method returns the number of bytes to be skipped.
java.io.IOException
See the mark( ) method for an example of this method.
public long skipBytes(long lNum)
Skips the given number of bytes in the underlying input stream.
The number of bytes to be skipped.
This method returns the number of bytes that was skipped.
java.io.IOException
long number = 256; if(number == m_madisResource.skipBytes(number) int data = m_madisResource.readInt( );
public void startBlock(long lSizeLeft)
Sets a block that begins at the current point in the stream and contains the given number of bytes.
This construct is useful for file formats where a Four Character Code serves as the identifier of a block, followed by the number of bytes in the block.
The number of bytes in the block.
None.
None.
m_madisResource.startBlock(128);
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|