6 Custom DataSource and DataSink for JMF Versions 2.0 and 2.1

6.1.1 Registration Method 1

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

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

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

3. 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

http://java.sun.com/products/java-media/jmf/index.jsp

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:

user=<database user>
password=<password>
url=<jdbc connection string>
<mediaSource1>=<procedure1>
<mediaSource2>=<procedure2>
<mediaSink1>=<procedure3>
...

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:

CREATE OR REPLACE PROCEDURE  getVideoForRetrieval(
           myVideoLob    OUT BLOB, 
           myMimeType    OUT VARCHAR2,
           myid          IN  INTEGER)
       AS
       BEGIN
           SELECT t.myvideo.getContent(), t.myvideo.getMimeType()
           INTO myVideoLob, myMimeType
           FROM videostore t
           WHERE videoid=myid;
       END;

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:

1. Start JMStudio.

2. 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.

3. 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

http://java.sun.com/jmf