6 Custom DataSource and DataSink for JMF Versions 2.0 and 2.1

Sun Microsystems provides a Java Media Framework (JMF) API that enables audio, video and other time-based media to be added to Java applications and applets.

The Oracle interMedia Custom DataSource and DataSink feature is an extension to JMF versions 2.0 and 2.1. This feature allows a JMF application to upload time-based media data into or retrieve media data from a database that contains Oracle interMedia ("interMedia") video or audio objects. A protocol is defined that permits media data stored in interMedia video or audio objects in the database to be accessed through a URL that contains information necessary to select the audio or video data from the database.

6.1 Installing and Registering Custom DataSource and DataSink

To install Custom DataSource and DataSink, save the ordjmf.jar file to your hard disk. By default, the file will be stored in the following location:

<ORACLE_HOME>\ord\jlib

Then, enter the path name for the ordjmf.jar file into your CLASSPATH environment variable.

To register Custom DataSource and DataSink, select one of the methods described in the following subsections.

6.1.1 Registration Method 1

To register Custom DataSource and DataSink with Registration Method 1 follow these steps:

Start the JMFRegistry.bat file in your %JMF_HOME%/bin directory.

Add oracle.ord to both the protocol Prefix List and Content Prefix List on the PackageManager tab. Then, click commit for both lists.

Close the JMFRegistry.

6.1.2 Registration Method 2

To register Custom DataSource and DataSink with Registration Method 2:

Add oracle.ord to the protocol Prefix List and Content Prefix List in your application program through the JMF PackageManager.

For more information about JMF, see the JMF API documentation and specification available at the Sun Microsystems Web site at

6.2 Using Custom DataSource and DataSink

Using Custom DataSource and DataSink includes the following procedures:

Defining the ordjmf.properties file.

Uploading media data into Oracle Database through Custom DataSink.

Retrieving media data from Oracle Database through Custom DataSource.

You can access media data in the database through Sun Microsystems JMStudio or a JMF application.

The following subsections describe these procedures.

6.2.1 Defining the Property File

The property file, ordjmf.properties, is used to define the database connection and the PL/SQL procedures to retrieve or upload media data to the database. This file can be located in any directory, but the directory must be specified in your CLASSPATH variable. The ordjmf.properties file defines the following name-value pairs:

The value <jdbc connection string> is used to set up a Java Database Connectivity (JDBC) connection with the database. The JDBC connection can be either an Oracle JDBC Thin Driver or an Oracle JDBC OCI Driver connection string.

For the Thin driver, the connection string should be similar to the following:

jdbc:oracle:thin:@<host>:<port>:<sid>

For the OCI driver, the connection string should be similar to the following:

jdbc:oracle.oci:@MyHostString

where MyHostString is a TNSNAMES entry in the file tnsnames.ora on the client computer from which you are connecting.

Multiple media data sources and data sinks can be defined in the ordjmf.properties file. Each source or sink is defined as a name and value pair. The name is used in the MediaLocator string (see Section 6.2.2 and Section 6.2.3). The value must be the name of an existing PL/SQL procedure that supports uploading or retrieving media data in the database.

6.2.2 Uploading Media Data

The format of the MediaLocator upload string is one continuous string, similar to the following:

im://upload/<sinkName>/<arg1>:<arg2>:...:<argn>

The parameter upload is the keyword that is required to indicate an upload operation of the media data.

The parameter <sinkName> is the name defined in the ordjmf.properties file. It refers to a predefined PL/SQL procedure that retrieves the media in a BLOB in a SQL SELECT ... FOR UPDATE statement. The first argument in the PL/SQL procedure must be an output parameter of BLOB data type. The second argument must be an input parameter of VARCHAR2 data type to represent the MIME type of the uploading media. The predefined PL/SQL procedure can use the input parameter of the media MIME type in any way necessary.

The following example shows that for a table named videostore with columns (OrdVideo myvideo, Integer videoid), the PL/SQL procedure could be defined as follows:

CREATE OR REPLACE PROCEDURE getVideoForUpdate(
myVideoLob OUT BLOB,
myMimetype IN VARCHAR2,
myid IN INTEGER)
AS
myvid ordsys.ordvideo;
BEGIN
-- Update the MIME type first
SELECT t.myvideo INTO myvid from videostore t
WHERE videoid=myid FOR UPDATE;
myvid.setMimeType(myMimetype);
myvid.setLocal();
myvid.setUpdateTime(SYSDATE);
UPDATE videostore SET myvideo=myvid WHERE videoid=myid;
-- Get the BLOB for uploading
SELECT t.myvideo.getContent() INTO myVideoLob
FROM videostore t
WHERE videoid=myid FOR UPDATE;
END;

An example of the use of the MediaLocator upload string through the Custom DataSink is as follows:

im://upload/sink1/1

where sink1 is the mediaSink name, and is defined in the ordjmf.properties file as sink1=getVideoForUpdate. Through the use of this URL, the JMF application can upload and update the media into the BLOB stored in the videostore table where the value of videoid is equal to 1.

The parameters <arg1>, <arg2>, ..., <argn> are the input parameters to the PL/SQL procedure, which can be used to locate the media data in the database. In the previous example, there is only one input parameter in the PL/SQL procedure getVideoForUpdate. Thus, the <arg1> parameter corresponds to the getVideoForUpdate input parameter myid, and the value of <arg1> is equal to 1.

6.2.3 Retrieving Media Data

The format of the MediaLocator retrieval string is one continuous string, similar to the following:

im://retrieval/<sourceName>/<arg1>:<arg2>:...:<argn>

The parameter retrieval is the keyword that is required to indicate a retrieve operation of the media data.

The parameter <sourceName> is the name defined in the ordjmf.properties file. It refers to a predefined PL/SQL procedure that retrieves the media in a BLOB as well as the MIME type of the media. The first argument in the PL/SQL procedure must be an output parameter of BLOB data type. The second argument must be an output parameter of VARCHAR2 data type to represent the MIME type of the media.

The following example shows that, for a table named videostore with columns (OrdVideo myvideo, Integer videoid), the PL/SQL procedure could be defined as follows:

An example of the use of the MediaLocator retrieval string through the Custom DataSource feature is as follows:

im://retrieval/source2/1

where source2 is the data source name and is defined in the ordjmf.properties file as source2=getVideoForRetrieval. Through the use of this URL, the JMF application can retrieve media from the BLOB stored in the videostore table where the value of videoid is equal to 1.

The parameters <arg1>, <arg2>, ..., <argn> are input parameters to the PL/SQL procedure, which can be used to locate the media data in the database. In the previous example, there is only one input parameter in the PL/SQL procedure getVideoForRetrieval. Thus, the <arg1> parameter corresponds to the getVideoForRetrieval input parameter myid and the value of <arg1> is equal to 1.

6.2.4 Accessing Media Data Through JMStudio

To access media data in the database through Sun Microsystems JMStudio, follow these steps:

Start JMStudio.

Select File, then select Open URL:. In the Open URL dialog box, enter the MediaLocator string that points to the data in the database, then click OK.

JMStudio should play the media data stored in the database.

6.2.5 Accessing Media Data Through a JMF Application

To access media data in the database through a JMF application, use the MediaLocator strings defined in Section 6.2.2 and Section 6.2.3 as the input or output URL. This will enable the JMF application to access the media data in the database through Custom DataSource and DataSink for JMF 2.0 and 2.1.

For examples of JMF applications, refer to the JMF sample programs available at the Sun Microsystems Web site at