2
Getting Started with Oracle interMedia Annotator

This chapter describes how to get started in using Oracle interMedia Annotator. It discusses the following topics:

Setting Preferences
Available URL Protocols
Using Oracle interMedia Annotator

2.1 Setting Preferences

Before you can use Oracle interMedia Annotator, you must specify preferences for the environment. You specify the preferences in the Annotator.prefs file, located 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.

The format of entries in the preferences file is:

preference_parameter=preference_value

Table 2-1 shows the names of the preference parameters and the possible values for each parameter.

Table 2-1 Preferences

Parameter	Description
`MimeMapFile`	The name of the MIME types mapping file, which maps MIME types to a file extension, annotation, parser, and player. The file must be located in the configuration directory as specified by the `configDirectory` parameter. By default, the file name is `Annotator.mime`.
`MimeTypesFile`	The name of the MIME types file, which controls what MIME types are sent to the client for a given extension. The file must be located in the configuration directory as specified by the `configDirectory` parameter. By default, the file name is `mime.types`.
`configDirectory`	Optional parameter representing the specification for the configuration directory. By default, interMedia Annotator assumes that the configuration directory is the `lib/conf` or `lib\conf` subdirectory of the current directory. If this parameter is set, the configuration files, such as the preference file and MIME types mapping file, must be located in the specified directory and the value of the `configDirectory` parameter in the preferences file in that directory must be consistent with the actual location of the files. 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
descriptorDirectory	Optional parameter representing the specification for the descriptor directory. By default, interMedia Annotator assumes that the descriptor directory is the `lib/descriptors` or `lib\descriptors` subdirectory of the current directory. If this parameter is set, the descriptor files must be located in the specified directory. At installation, the descriptor files are placed in the following directory: On UNIX: $ORACLE_HOME/ord/Annotator/lib/descriptors On Windows: ORACLE_HOME\ord\Annotator\lib\descriptors
`connectDriver`	The name of the JDBC driver you are using. For example: `oracle.jdbc.driver.OracleDriver`
`connectJDBCProt`	The prefix for the JDBC driver, which describes whether it is the JDBC OCI driver or the JDBC Thin driver. For the JDBC OCI driver: `jdbc:oracle:oci8:@` For the JDBC Thin driver: `jdbc:oracle:thin`
`connectHost`	The name of the host on which the Oracle database server to which you want to upload media data is installed. For example: `myhost`
`connectPort`	The port number of the host on which the Oracle database server is installed.
`connectSID`	The SID for the Oracle database.
`connectUserName`	A database user name, which is used to upload media data into the database.
`connectPassword`	The password of the database user.
`serviceName`	The service name of the database. Use the following format: host-name:port_name:oracle-sid
`useHttpProxy`	Whether or not to use an HTTP proxy server to annotate media sources that are available remotely over the Internet through the HTTP protocol. Specify `true` if you are running in a secure environment. Valid values are: `true` `false`
`httpProxyServer`	The URL of the HTTP proxy server. The following shows an example of a URL for a proxy server: `www-ourproxy.ourcompany.com`
`httpProxyPort`	The port number of the proxy server.
`mediaDirectory`	The directory that contains the source media.
`uploadOci8BlobBlockSize`	The block size to use to upload BLOBs when you are using the JDBC OCI driver. In most cases, use the default value in the preferences file.
`uploadOci8ClobBlockSize`	The block size to use to upload CLOBs when you are using the JDBC OCI driver. In most cases, use the default value in the preferences file.
`uploadThinBlobBlockSize`	The block size to use to upload BLOBs when you are using the JDBC Thin driver. In most cases, use the default value in the preferences file.
`uploadThinClobBlockSize`	The block size to use to upload CLOBs when you are using the JDBC Thin driver. In most cases, use the default value in the preferences file.
`uploadRootAnn`	Whether or not to upload, not only a subannotation, but any annotations and subannotations that are predecessors of the subannotation. Valid values are: `true` `false`
`sqlFileName`	The script to run to insert an annotation.
`openSaveDirectory`	The default directory to which annotations will be saved and from which saved annotations will be opened. This parameter is specific to the demo utility.
`defaultOfm`	The full path of the default PL/SQL upload template ((file extension .ofm), which is used to upload media data to the database. This parameter is specific to the demo utility.
`ofmDirectory`	The directory to which PL/SQL upload templates (file extension .ofm), will be written. This parameter is specific to the demo utility.

Note:

For information about the demo utility, see Section D.1.

You can also set preferences by using the Preferences.setProperty( ) method. See "setProperty( )" for more information.

The following sections discuss using some of the preferences to configure your environment before you begin to use Oracle interMedia Annotator.

2.1.1 Setting the Connection to the Database

You can connect to an Oracle database using the JDBC Thin driver or the JDBC OCI driver.

To use the JDBC Thin driver, specify the following in the Annotator.prefs file:

For the value of the parameter connectDriver, enter the following:
```
oracle.jdbc.driver.OracleDriver
```
For value of the parameter connectJDBCProt, enter the following:
```
jdbc:oracle:thin
```
For value of the parameter serviceName, enter the service name of your database, using the following format:
```
host-name:port_name:oracle-sid
```

To use the JDBC OCI driver, specify the following:

For the value of the parameter connectDriver, enter the following:
```
oracle.jdbc.driver.OracleDriver
```
For value of the parameter connectJDBCProt, enter the following:
```
jdbc:oracle:oci8:@
```
For the value of the parameter serviceName, enter the service name of your database, using the syntax used by Oracle Net. See the Oracle9i Net Services Administrator's Guide for more information.

2.1.2 Specifying the Proxy Settings

Oracle interMedia Annotator can annotate media sources that are available remotely over the Internet through the HTTP protocol.

If you are running in a secure environment, you must configure Oracle interMedia Annotator to use your proxy server before you can access the Internet. To configure the proxy server, specify the following in the Annotator.prefs file:

For the parameter useHttpProxy, enter the value true.
For the parameter httpProxyServer, enter the address of your HTTP proxy server. For example:
```
www-ourproxy.ourcompany.com
```
For the parameter httpProxyPort, enter the port number for the HTTP proxy server.

2.2 Available URL Protocols

Oracle interMedia Annotator can parse media sources accessible through the URL protocols shown in Table 2-2.

Table 2-2 Available URL Protocols

URL Protocol	Description
`file`	Access all the files on local or remotely mounted disks in your computer.
`http`	Access media available through an Internet Web server.

If you are parsing a local file or a file available over the Internet through the HTTP protocol, Oracle interMedia Annotator extracts the time-independent attributes from the media file and inserts them into a logical annotation.

If you are parsing a media source with multiple tracks, such as a video source, a subannotation is created for each track.

2.3 Using Oracle interMedia Annotator

To use Oracle interMedia Annotator, you take the following general steps:

Create and initialize an instance of the annotator client.
Optionally, set preferences using the Preferences.setProperty( ) method. You can set preferences such as the type of JDBC driver or information about the HTTP Server proxy. See setProperty( ) for more information about this method.
Parse a media source file from a given URL to create an annotation about the source. Use the Annotation.parseMedia( ) method to parse the source file.
Optionally, get the defined attributes of the annotation and set additional attributes for the annotation.

Oracle interMedia Annotator defines a given number of attributes (see Appendix C for a complete list of attributes). However, not all media sources will provide values for every attribute. You can use the Annotation.getAttribute( ) method to get the existing attributes and t he Annotation.setAttribute( ) method to add a value to your annotation for any attribute that does not have a value.
Get any subannotations using the Annotation.getSubAnnotations( ) method and, optionally, define additional subannotations, using the Annotation.addSubAnnotation( ) method.

An annotation will usually contain one or more subannotations, which contain the metadata associated with a portion of the media source, such as a text track or an audio track. In addition to these populated subannotations, you can define your own subannotations by adding an empty annotation and then populating it with your own values.
For parsers such as the QuickTime parser, you can extract media samples from the media source file, using the AnnotationHandler.extractMedia( ) method.
Upload the annotation to an Oracle database, using the AnnotationHandler.insertMedia( ) method.