2 Oracle Multimedia Application Development

2.1.1 Java Class Libraries and Other Packages and Interfaces

Oracle Multimedia provides these Java class libraries, which enable access (insert, update, and retrieve) and manipulation (process) of multimedia data stored in the database:

• Oracle Multimedia Java API class library

• Java Advanced Imaging (JAI) classes in the Oracle Multimedia Java API class library

• Oracle Multimedia Servlets and JSP Java API class library

• Oracle Multimedia JSP Tag Library

And, Oracle Multimedia provides these specialized Java class libraries:

• Oracle Multimedia DICOM Java API class library

• Oracle Multimedia Mid-Tier Java API class library

Oracle Multimedia also integrates with the Oracle Multimedia/Oracle Application Development Framework Business Components (ADF Business Components) integration package, and with C++ and traditional 3GLs through modern class library interfaces. Class libraries provide access to multimedia data stored in the database in several ways.

Oracle Multimedia Java API Class Library

Using the Java database connectivity (JDBC) interface, the Oracle Multimedia Java API class library enables you to use Java proxy classes for Oracle Multimedia database objects to quickly develop Java applications for use on any tier (client, application server, or database) to manipulate and modify audio, image, and video data, or heterogeneous media data stored in a database. Oracle Multimedia Java API makes it possible for JDBC result sets to include both traditional relational data and Oracle Multimedia columns of object type media data, to easily select and operate on the result set, to access object attributes, and to invoke object methods. Section 1.10.1 for general information, and Section 2.4 for a description of how to use Java and JDBC to develop media-rich Java client applications using this Java class library.

Java Advanced Imaging Classes

The Oracle Multimedia Java API class library includes several Java Advanced Imaging (JAI) classes. The Oracle Multimedia Java API describes three types of stream objects, which provide interfaces to BLOB and BFILE data, that can be used by JAI. These classes enable a JAI application to read and write image data stored in a database using Oracle Multimedia OrdImage objects, or in BLOBs or BFILEs. See Section 1.10.4 for general information.

Oracle Multimedia Servlets and JSP Java API Class Library

The Oracle Multimedia Servlets and JSP Java API class library supports Web technologies, enabling you to quickly develop Java applications using Java servlets and JavaServer Pages (JSP). See Section 1.10.3 for general information. Section 2.5 describes how to develop media-rich Java-based Web applications using this Java class library. Section 3.2 includes an example of a Java servlet application, and Section 3.3 includes an example of a JSP application.

Oracle Multimedia JSP Tag Library

The Oracle Multimedia JSP Tag Library is an extension of the Oracle Multimedia Servlets and JSP Java API class library. This Java class library provides JSP tags that simplify retrieving and uploading media data from and to Oracle Database in multimedia JSP Web applications.

Oracle Multimedia DICOM Java API Class Library

Oracle Multimedia DICOM Java API is a specialized class library that enables users to write Java applications using the Oracle Multimedia object designed to store Digital Imaging and Communications in Medicine (DICOM) data. See Section 1.6.4 for general information.

Oracle Multimedia Mid-Tier Java API Class Library

Oracle Multimedia Mid-Tier Java API is a specialized class library that enables users to write Java applications for extracting DICOM metadata outside of Oracle Database before the data is loaded into the database.

Oracle Multimedia/Oracle Application Development Framework Business Components Integration Package

The Oracle Multimedia/Oracle Application Development Framework Business Components (ADF Business Components) integration package includes the Oracle Multimedia domain classes and a set of utilities for use with Oracle JDeveloper. Oracle JDeveloper is a Java-integrated development environment (IDE) tool that supports the application framework (ADF Business Components), enabling you to build multitier, component-based Internet applications. See Section 1.10.3 for general information.

2.1.2 Integration With PL/SQL Gateway and PL/SQL Web Toolkit

Oracle Multimedia uses the PL/SQL Gateway (mod_plsql) feature of the Oracle HTTP Server and the PL/SQL Web Toolkit features of Oracle Fusion Middleware and Oracle Database to listen for browser requests, to execute stored PL/SQL procedures in the database using Oracle Net and Oracle Call Interface (OCI), and to generate an HTML page containing data and code for the response returned to the Web browser for display. As a Web application developer, you can write PL/SQL servlets and PL/SQL server pages (PSP) that invoke PL/SQL procedures stored in the database through an Oracle Net connection and OCI. See Section 2.3 for a description of how to use PL/SQL Gateway and PL/SQL Web Toolkit to develop PL/SQL Web applications. See Section 3.1 for an example of an application that uses the PL/SQL Gateway and PL/SQL Web Toolkit for Oracle Fusion Middleware and Oracle Database.

2.1.3 Integration With Components in Other Oracle Development Tools

Oracle Multimedia integrates Oracle development tools with tightly integrated components to enable you to quickly and easily develop applications that provide access to (insert, update, and retrieve) and manipulation (process) of multimedia data stored in the database for delivery to Web browsers and client applications. These development tools include:

• Oracle Portal

• Oracle JDeveloper

• Oracle Designer

• Oracle Content Management SDK

Oracle Portal

Oracle Portal is a simple browser-based environment for building and deploying enterprise information portlets (EIPs). An enterprise portal provides access to portlets, which are summarized versions of applications and Web content situated in defined regions of the Web page. Oracle Portal portlets execute PL/SQL stored procedures residing in the database, which in turn generate an HTTP response in the form of a generated HTML page. Oracle Portal contains two predefined components: Forms and Reports, which both support rich media content being uploaded or downloaded between the database and the portal framework form or report. See Section 1.10.3 for general information.

Oracle JDeveloper

Oracle JDeveloper is an IDE tool, which is written 100% in Java, that supports the application framework (Oracle Application Development Framework Business Components). An Oracle Multimedia/ADF Business Components integration package includes the Oracle Multimedia domain classes and a set of utilities. The domain classes are wrappers of Oracle Multimedia Java API and inherit all the underlying multimedia retrieval, upload, and manipulation methods. The domain classes support the ADF Business Components APIs and provide built-in integrated multimedia capabilities, while the utility classes support the retrieval, rendering, and uploading of multimedia content. See Section 1.10.3 for general information.

Oracle Designer

Oracle Designer is a tool used to manage software configuration management for controlling the evolution of an application from identification of components, through initiation, evaluation, authorization, development, and implementation. Oracle Designer can generate C++ classes that enable applications running on the client, on Oracle Fusion Middleware, or on Oracle Database to call Oracle Multimedia methods.

Oracle Content Management SDK

Oracle Content Management SDK enables you to create custom file system applications using XML and Java that use the features and capabilities of the database and a variety of Web-based interfaces, such as Java servlets and JSP pages, or executing SQL or calling stored PL/SQL procedures for execution in the transaction context of the database.

2.1.4 Integration With Third-Party Streaming Media Servers

Oracle Multimedia integrates with third-party streaming media servers to enable dynamic and direct delivery of multimedia data stored in the database to a media player client. These third-party streaming servers include:

• Oracle Multimedia Plug-in for RealNetworks Server

• Oracle Multimedia Plug-in for Microsoft Windows Media Services

You can download these plug-ins from the Oracle Multimedia Software section of the Oracle Technology Network Web site at

http://www.oracle.com/technology/products/multimedia/

Oracle Multimedia Plug-in for RealNetworks Server

Oracle Multimedia Plug-in for RealNetworks Server is a data source plug-in that enables a RealNetworks server to stream media data directly from Oracle Database to a media player client. The plug-in is installed with RealNetworks Server, and configured and managed using the administration tool of the streaming server. See Oracle Multimedia Plug-in for RealNetworks Streaming Servers Readme.

Oracle Multimedia Plug-in for Microsoft Windows Media Services

Oracle Multimedia Plug-in for Microsoft Windows Media Services enables Microsoft Windows Media servers to stream multimedia content to a client directly from Oracle Database. This plug-in is installed on Windows 2003 Server, and configured with Windows Media Services. See Oracle Multimedia Plug-in for Microsoft Windows Media Services Readme.

2.2.1 Setting Up Your Environment for PL/SQL

To access files with PL/SQL, you must create a directory object in the database that points to a directory that is accessible by the database server. For example, the following command creates the MEDIA_DIR directory in the sample schema:

CREATE DIRECTORY MEDIA_DIR AS
    'c:\oracle\product\10.2.0\db_1\demo\schema\product_media';

To retrieve media data from the database to a file, you must grant the write permission on the specified directory to the appropriate user. For example:

GRANT WRITE ON DIRECTORY MEDIA_DIR TO SCOTT;

To upload media data from a file to the database, you must grant the read permission on the specified directory to the appropriate user. For example:

GRANT READ ON DIRECTORY MEDIA_DIR TO SCOTT;

2.2.2 Media Query in PL/SQL

You can include media attributes (for example: height, width, and MIME type) in standard SQL queries by using accessor methods (for example: getHeight, getWidth, and getMimeType). Example 2-1, Example 2-2, and Example 2-3 show how to use these accessor methods to query one or more object attributes for image, audio, and video objects, respectively.

SELECT t.product_id                  id,
       t.product_photo.getHeight()   height,
       t.product_photo.getWidth()    width,
       t.product_photo.getMimeType() mimetype
  FROM pm.online_media t;

SELECT t.product_id                  id,
       t.product_audio.getMimeType() mimetype
  FROM pm.online_media t;

SELECT t.product_id                  id,
       t.product_video.getMimeType() mimetype
  FROM pm.online_media t;

2.2.3 Media Download in PL/SQL

To download media from the database into a file on the file system, call the export method of the Oracle Multimedia object. The following code example exports the image in the row with product_id 3117 to a file named 3117.jpg in the directory MEDIA_DIR. This code example highlights in bold the PL/SQL statements where this export operation takes place.

DECLARE
  img ORDImage;
  ctx RAW(64) := NULL;
BEGIN
  SELECT  product_photo 
    INTO  img 
    FROM  pm.online_media
    WHERE product_id = 3117;
  img.export(ctx, 'FILE', 'MEDIA_DIR', '3117.jpg');
END;
/

2.2.4 Media Upload in PL/SQL

Media upload means importing media data from the file system into the database tablespaces. The following series of steps is typical:

1. Insert a new row into the table, creating new objects by using the init method of the Oracle Multimedia object type.

2. Call the import method of the Oracle Multimedia object to bring the data from the file system into the database.

3. Call the setProperties method of the Oracle Multimedia object to determine and populate the attributes of the object.

4. Update the table so that the Oracle Multimedia object in the table contains the attribute values extracted in the previous step.

The PL/SQL code that implements these steps for inserting a new row in the PM.ONLINE_MEDIA table is shown in this example:

DECLARE
  img ORDImage;
  aud ORDAudio;
  vid ORDVideo;
  ctx RAW(64) := NULL;
BEGIN
  -- Insert a new row into the pm.online_media table.
  DELETE FROM pm.online_media WHERE product_id = 3003;
  INSERT INTO pm.online_media 
         (product_id, 
          product_photo, 
          product_audio,
          product_video)
  VALUES (3003, 
          ORDImage.init('FILE', 'MEDIA_DIR', 'laptop.jpg'),
          ORDAudio.init('FILE', 'MEDIA_DIR', 'laptop.mpa'),
          ORDVideo.init('FILE', 'MEDIA_DIR', 'laptop.rm'))
  RETURNING product_photo, product_audio, product_video
  INTO img, aud, vid;
  
  -- Bring the media into the database and populate the attributes.
  img.import(ctx); 
  -- ORDImage.import also calls ORDImage.setProperties.
  
  aud.import(ctx);
  aud.setProperties(ctx);
 
  vid.import(ctx);
  vid.setProperties(ctx);
    
  -- Update the table with the properties we have extracted.
  UPDATE pm.online_media
  SET    product_photo = img,
         product_audio = aud,
         product_video = vid
  WHERE  product_id = 3003;
  
  COMMIT;
END;
/

2.2.5 Handling Oracle Multimedia Exceptions in PL/SQL

Possible errors that can occur during run time should always be handled in your application. This practice enables the program to continue its operation even when it encounters a run-time error. This practice also enables users to know what went wrong during program operation. Proper error handling practices ensure that, whenever possible, you are always able to recover from an error while running an application. In addition, proper error handling provides you with the information you need so you always know what went wrong.

This section demonstrates proper error handling practices using code examples. These examples show how to handle some common Oracle Multimedia errors and other types of errors in PL/SQL programs. These examples are extracted from the PL/SQL sample applications that are described in Chapter 3 and Chapter 4. (See Oracle Multimedia Reference for more examples.)

When handling exceptions, PL/SQL uses exception blocks. For example, in PL/SQL, the exception can appear as:

BEGIN
<some program logic>
EXCEPTION
     WHEN OTHERS THEN
     <some exception logic>
END;

When you design, code, and debug your application, you are aware of the places in your program where processing might stop due to a failure to anticipate an error. Those are the places in your program where you must add exception handling blocks to handle the potential errors.

The examples in this section describe exception handling in the Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application.

The following subsections provide additional details and examples of exception handling in PL/SQL:

• Handling the Setting of Properties for Unknown Image Formats in PL/SQL

• Handling Image Processing for Unknown Image Formats in PL/SQL

BEGIN
   new_image.setProperties();
EXCEPTION
   WHEN OTHERS THEN
         new_image.contentLength := upload_size;
         new_image.mimeType := upload_mime_type;
END;

BEGIN
   new_image.processCopy( 'maxScale=50,50', new_thumb);
EXCEPTION
   WHEN OTHERS THEN
      new_thumb.deleteContent();
      new_thumb.contentLength := 0;
END;

2.3.1 Using the PL/SQL Gateway and PL/SQL Web Toolkit

Oracle Fusion Middleware and Oracle Database install Oracle HTTP Server powered by the Apache HTTP server that contains the PL/SQL Gateway to communicate directly with a client Web browser.

Oracle HTTP Server serves mainly the static HTML files, images, and so on, that a Web application uses, and is usually located in the file system where Oracle HTTP Server is installed. Oracle HTTP Server contains modules or plug-ins that extend its functions. One of these modules supplied by Oracle is the mod_plsql module, also known as the PL/SQL Gateway. The PL/SQL Gateway serves data dynamically from the database to Web browsers by calling PL/SQL stored procedures. The PL/SQL Gateway receives requests from a Web browser in the form of PL/SQL servlets or PL/SQL server pages that are mapped to PL/SQL stored procedure calls. PL/SQL stored procedures retrieve data from the database and generate an HTTP response containing the data and code from the PL/SQL Web Toolkit to display the generated Web page in a Web browser. The PL/SQL Web Toolkit contains a set of packages called htp, htf, and owa packages that can be used in the stored procedures to get information about the request, construct HTML tags, and return header information to the client Web browser.

Figure 2-1 shows these main components of the PL/SQL development environment, Oracle HTTP Server (a component of Oracle Fusion Middleware and Oracle Database), the Web browser, and the database. The following information describes how a client Web browser request is turned into a Web page response from the execution of the PL/SQL procedure:

1. A client Web browser sends a PL/SQL server page or servlet request to Oracle HTTP Server.

2. Oracle HTTP Server routes the request to the PL/SQL Gateway (mod_plsql).

3. The PL/SQL Gateway forwards the request to the database using configuration information stored in the database access descriptor (DAD) and connects to the database.

4. The PL/SQL Gateway prepares the call parameters and invokes the PL/SQL package and the PL/SQL stored procedure in the application.

5. The PL/SQL procedure generates an HTML page using data from the database and special packages in the PL/SQL Web Toolkit accessed from the database. The PL/SQL Web Toolkit contains a set of packages called htp, htf, and owa packages that are used in the stored procedures to get information about the request, construct HTML tags, and return header information back to the client Web browser as the response returned to the PL/SQL Gateway.

6. The PL/SQL Gateway sends the response to Oracle HTTP Server.

7. Oracle HTTP Server sends the response to the client Web browser for display as a formatted Web page.

Figure 2-1 Components of the PL/SQL Development Environment

Description of "Figure 2-1 Components of the PL/SQL Development Environment"

Usually, the returned formatted Web page has one or more additional links, and each link, when selected, sends another request to the database through the PL/SQL Gateway to execute one or more stored procedures. The generated response displays data on the client Web page usually with additional links, which, when selected, execute more stored procedures that return the generated response for display as yet another formatted Web page, and so on. This is how the PL/SQL application in the PL/SQL development environment is designed to work.

Web application developers who use the PL/SQL development environment, create a PL/SQL package specification and body that describe procedures and functions that comprise the application. The package specification defines the procedures and functions used by the application, and the package body is the implementation of each procedure and function. All packages are compiled and stored in the database to perform specific operations for accessing data in the database and formatting HTML output for Web page presentation. To invoke these stored PL/SQL procedures, Web application developers use the request/response PL/SQL servlets and PL/SQL server pages (PSP) to enable Web browser clients to send requests and get back responses using HTTP.

Oracle HTTP Server maps a URL entered in a browser to a specific PL/SQL procedure stored in the database. It does this by storing specific configuration information in a DAD for each stored procedure. Thus, each DAD contains the database connection information that the Web server requires to translate the URL entered into a database connection to call the stored procedure.

Oracle HTTP Server listens for a request, routes the request to the PL/SQL Gateway, which forwards it to the database. Configuration information values stored in a DAD determine the database alias to use, the connection string to use for remote access, the procedure to use for uploading or downloading documents, and the user name and password information to enable access to the database. From the Web browser, the user specifies the URL that invokes the PL/SQL Gateway. The URL has a defined format for specifying all the required and optional parameters, including the location of the DAD and the name of the PL/SQL stored procedure to run, as shown in Example 2-4.

protocol://hostname[:port number]/DAD-name/[[!][schema name.]
 [package name.]procedure_name[?query_string]]

To use the Oracle Multimedia Photo Album sample application and the PL/SQL Web Toolkit described in Section 3.1, the URL can be simplified to the format shown in Example 2-5.

protocol://<hostname>[:<port-number>]/DAD-name/]procedure_name

When the URL is entered in the Web browser, it includes the protocol (HTTP or HTTPS), the name of the hosting Web server, and the port number to which it is listening to handle requests. Next, the specified virtual path includes /pls/<DAD-name> to indicate that the Web server is configured to invoke mod_plsql, and the location of the DAD on the Web server.

In Example 2-4, the last five parameters include the exclamation point (!) character, schema name, package name, procedure name, and query string. From the syntax, the exclamation point, schema name, package name, and query string parameters are optional; only the procedure name is required.

The exclamation point indicates that flexible parameter passing is being used. The schema name, if omitted, is resolved based on the user name. The package name, if omitted, means the procedure is standalone. The query string parameters are for the stored procedure and follow a special format. Of these five parameters, the procedure name must be specified in both the DAD and the URL. The other four parameters are specified in either the DAD or the URL, or not at all, depending on the application.

The URL displays the home page for the specified DAD. When the URL is entered in the address field of the Web browser page, it invokes either the specified DAD location only, or the specified DAD location along with the procedure name, or the specified DAD location along with the schema.package.procedure name. The response is returned as an HTML page. The HTML page contains the requested data and any other specified code for display in the client's Web browser. The Code Wizard described in Chapter 4 demonstrates how this operation works. For example, to invoke the Code Wizard administration URL, enter the following URL shown in that chapter:

http://<hostname>:<port-number>/pls/ordcwadmin

The virtual path includes pls to indicate that the Web server is configured to invoke mod_plsql, followed by the name of the DAD used for the Code Wizard administrator, ordcwadmin.

When the HTML page is displayed, it resolves to the following URL for the Code Wizard administrator:

http://<hostname>:<port-number>/pls/ordcwadmin/ORDCWPKG.menu

ORDCWPKG.menu represents the package.procedure name, which is specified as the default home page in the ordcwadmin DAD.

When the PL/SQL Gateway is invoked, it uses the stateless model and does not permit a transaction to span across multiple HTTP requests. In this stateless model, applications typically can create a session to maintain state by using one of these techniques: HTTP cookies, a hidden HTML field as an HTML form element of the HTML Form package, or storage of vital information in database tables for query.

2.4.1 Setting Up Your Environment for Java

Before you can begin using any of the Java APIs provided by Oracle Multimedia, you must set up your environment to compile and run Java programs.

Follow these steps:

1. Specify the environment variable CLASSPATH, and ensure that this variable includes the appropriate Oracle Java archive (JAR) files for the Oracle Multimedia features and any other features that you intend to use.

   For each Oracle JAR file, Table 2-1 lists the name of the file and its contents, the Oracle Multimedia and other features that require it, and details about the JDK version, the platform, and the path name under the <ORACLE_HOME> directory where you can obtain it.

   Table 2-1 Java Archive Files for Oracle Multimedia

   Oracle JAR File and Contents	Required By	JDK Version, Platform, and Location
   Name: ordim.jar Description: Oracle Multimedia Java proxy classes	All Oracle Multimedia features	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/ordim.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\ordim.jar
   Name: ojdbc5.jar Description: Oracle JDBC library	All Oracle Multimedia features	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/jdbc/lib/ojdbc5.jar JDK 5 or later, on Windows: <ORACLE_HOME>\jdbc\lib\ojdbc5.jar
   Name: xdb.jar Description: Oracle XDB Java classes library	DICOM feature Oracle Multimedia metadata extraction	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/rdbms/jlib/xdb.jar JDK 5 or later, on Windows: <ORACLE_HOME>\rdbms\jlib\xdb.jar
   Name: xmlparserv2.jar Description: Oracle XML Parser library	DICOM feature Oracle Multimedia metadata extraction Mid-Tier Java API feature	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/lib/xmlparserv2.jar JDK 5 or later, on Windows: <ORACLE_HOME>\lib\xmlparserv2.jar
   Name: orddcmmt.jar Description: Oracle Multimedia Mid-Tier Java classes	Mid-Tier Java API feature	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/orddcmmt.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\orddcmmt.jar
   Name: ordimdcm.jar Description: Oracle Multimedia DICOM Java library	Mid-Tier Java API feature	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/ordimdcm.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\ordimdcm.jar
   Name: orddicom.jar Description: Oracle Multimedia DICOM Java proxy classes	DICOM feature	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/orddicom.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\orddicom.jar
   Name: ordhttp.jar Description: Oracle Multimedia Servlets and JSP Java HTTP classes	Java servlets and JavaServer Pages (JSP) applications	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/ordhttp.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\ordhttp.jar
   Name: ordjsptag.jar Description: Oracle Multimedia JSP Tag Library (Optional)	JavaServer Pages (JSP) applications	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/ord/jlib/ordjsptag.jar JDK 5 or later, on Windows: <ORACLE_HOME>\ord\jlib\ordjsptag.jar
   Name: orai18n.jar Description: NLS Character Set Conversion library (Optional)	NLS character set conversion requiredFoot 1	JDK 5 or later, on Linux and UNIX: <ORACLE_HOME>/jlib/orai18n.jar JDK 5 or later, on Windows: <ORACLE_HOME>\jlib\orai18n.jar

   
   

   ^Footnote 1 If NLS character set conversion is required between the client application and the database, you must include the orai18n.jar file in the CLASSPATH variable. If NLS character set conversion is required, but the appropriate library is not specified, character-based attributes of Oracle Multimedia object types may be returned as hexadecimal-encoded strings. See Oracle Database JDBC Developer's Guide for more information about NLS character set conversion.

   Note:

   If you are using the JDBC OCI driver, specify the location of the JDBC OCI shared library in one of these variables:

   • LD_LIBRARY_PATH (for Linux or UNIX)

   • PATH (for Windows)

   Depending on your platform, store the JDBC OCI shared library at one of these locations under the <ORACLE_HOME> directory:

   
   <ORACLE_HOME>/lib (for libocijdbc11.so on Linux and UNIX)
   <ORACLE_HOME>\bin (for ocijdbc11.dll on Windows)
   

   Because this library path is shared, it may have been specified previously to enable the use of other client applications, such as SQL*Plus.

2. Add one or more of the following import statements to the Java program:

   Along with the standard JDBC classes included in the java.sql package, you must also import the Oracle JDBC extension class oracle.jdbc.OracleResultSet, as follows:

   import oracle.jdbc.OracleResultSet;
   

   Based on the type of media to be handled in the Java application, you might also have to add one or more of following import statements:

   import oracle.ord.im.OrdAudio;
   import oracle.ord.im.OrdDoc;
   import oracle.ord.im.OrdImage;
   import oracle.ord.im.OrdVideo;
   

2.4.2 Media Retrieval in Java

Oracle Multimedia objects can be retrieved into Java applications as Java proxy objects to the Oracle Multimedia database objects with the same names: OrdAudio, OrdDoc, OrdImage, and OrdVideo. After the JDBC connection is established, follow these steps to retrieve Oracle Multimedia Java objects:

1. Create the JDBC statement to select Oracle Multimedia objects from the database:

   String query = "select product_photo, product_audio,"+
     " product_video, product_testimonials from" +   
     " pm.online_media where product_id=3117";
   PreparedStatement pstmt = conn.prepareStatement(query);
   

2. Execute the query and obtain the result set:

   OracleResultSet rset = (OracleResultSet)pstmt.executeQuery();
   

3. Retrieve the Oracle Multimedia Java object from the result set:

   if ( rset.next() )
   {
   
     OrdImage imgProxy = (OrdImage)rset.getORAData(
             "product_photo", OrdImage.getORADataFactory());
     OrdAudio audProxy = (OrdAudio)rset.getORAData(
             "product_audio", OrdAudio.getORADataFactory());
     OrdVideo vidProxy = (OrdVideo)rset.getORAData(
             "product_video", OrdVideo.getORADataFactory());
     OrdDoc docProxy = (OrdDoc)rset.getORAData(
             "product_testimonials",
             OrdDoc.getORADataFactory());
   }
   

   Note:

   In Oracle Multimedia release 8i and release 9i, the getCustomDatum method is used to retrieve the Oracle Multimedia Java objects. In Oracle JDBC release 10g, the getCustomDatum method was deprecated and replaced by the getORAData method.

   In your Java program environment, be sure to use the same version for both the Oracle Multimedia Java Client library (ordim.jar) and the Oracle JDBC library.

4. Retrieve the media attributes. Media attributes can be retrieved directly from Oracle Multimedia Java objects. For example:

   int height = imgProxy.getHeight();
   int width = imgProxy.getWidth();
   String audFormat = audProxy.getFormat();
   String vidMimetype = vidProxy.getMimeType();
   

2.4.3 Media Upload in Java

Follow these steps to upload media data into Oracle Multimedia database objects in a Java application:

1. Enter this statement to enable the JDBC connection object to set the autocommit flag to false:

   conn.setAutoCommit(false);
   

2. Retrieve Oracle Multimedia Java objects from the database for updating. You can load media data into existing Oracle Multimedia objects in a table or into nonexisting Oracle Multimedia objects by creating a new row in a table.

   The following example includes a query you can use to load media data into existing Oracle Multimedia objects in a table.

   //"for update" is required in the query string 
   //since we will update the row later.
   String query1 = "select product_photo," +
   " product_audio, product_video," +         
   " product_testimonials from" + 
   " pm.online_media where product_id=3106" +
   " for update";
    
   PreparedStatement pstmt = conn.prepareStatement(query1);
    
   OracleResultSet rset = (OracleResultSet)pstmt.executeQuery();
   
   if ( rset.next() )
   {
    
     OrdImage imgProxy = (OrdImage)rset.getORAData(
             "product_photo", OrdImage.getORADataFactory());
     OrdAudio audProxy = (OrdAudio)rset.getORAData( 
             "product_audio", OrdAudio.getORADataFactory());
     OrdVideo vidProxy = (OrdVideo)rset.getORAData( 
             "product_video", OrdVideo.getORADataFactory());
     OrdDoc docProxy = (OrdDoc)rset.getORAData( 
             "product_testimonials",
             OrdDoc.getORADataFactory());
   }
    
   rset.close();
   pstmt.close();
   

   The following example includes a query you can use to load media data into nonexisting Oracle Multimedia objects by creating a new row.

   Note:

   This code segment assumes that there is no row with product_id=3106 in the pm.online_media table.

   String query2 = 
     "begin insert into pm.online_media " +
     " (product_id, product_photo, product_audio," +
     " product_video, product_testimonials) values" +
     " (3106, ordimage.init()," +
     " ordaudio.init(), ordvideo.init()," +
     " orddoc.init()) returning product_photo," +    
     " product_audio, product_video," +   
     " product_testimonials into ?, ?, ?, ?;end;";
    
   OracleCallableStatement cstmt =
    (OracleCallableStatement) conn.prepareCall(query2);
   cstmt.registerOutParameter(1, OrdImage._SQL_TYPECODE,
                                  OrdImage._SQL_NAME);
   cstmt.registerOutParameter(2, OrdAudio._SQL_TYPECODE,
                                  OrdAudio._SQL_NAME);
   cstmt.registerOutParameter(3, OrdVideo._SQL_TYPECODE,
                                  OrdVideo._SQL_NAME);
   cstmt.registerOutParameter(4, OrdDoc._SQL_TYPECODE,
                                  OrdDoc._SQL_NAME);
    
   cstmt.execute();
    
   OrdImage imgProxy = (OrdImage)cstmt.getORAData(1,
                        OrdImage.getORADataFactory());
   OrdAudio audProxy = (OrdAudio)cstmt.getORAData(2, 
                        OrdAudio.getORADataFactory());
   OrdVideo vidProxy = (OrdVideo)cstmt.getORAData(3, 
                        OrdVideo.getORADataFactory());
   OrdDoc docProxy = (OrdDoc)cstmt.getORAData(4, 
                        OrdDoc.getORADataFactory());
    
   cstmt.close();
   

3. Load the media data from a file to the Oracle Multimedia Java objects by calling the loadDataFromFile method:

   String imageFileName = "laptop.jpg";
   String audioFileName = "laptop.mpa";
   String videoFileName = "laptop.rm";
   String docFileName = "laptop.jpg";
   imgProxy.loadDataFromFile(imageFileName);
   audProxy.loadDataFromFile(audioFileName);
   vidProxy.loadDataFromFile(videoFileName);
   docProxy.loadDataFromFile(docFileName);
   

4. Set the properties of the Oracle Multimedia objects by populating the Java object fields with media attributes (optional):

   imgProxy.setProperties();
   audProxy.setProperties(new byte[1][64]);
   vidProxy.setProperties(new byte[1][64]);
   docProxy.setProperties(new byte[1][64], true);
   

   Note:

   The setProperties method tries to recognize the format of the media and populate the objects field with media information such as image height, image width, format, MIME type, and so on. If the media format is not recognized, the java.sql.SQLException error is thrown.

5. Update the database table with Oracle Multimedia Java objects that have data already loaded:

   String query3 = "update pm.online_media set" +
       " product_photo=?, product_audio=?," + 
       " product_video=?, product_testimonials=?" +
       " where product_id=3106";
       OraclePreparedStatement pstmt = 
    (OraclePreparedStatement)conn.prepareStatement(query3);
       pstmt.setORAData(1, imgProxy);
       pstmt.setORAData(2, audProxy);
       pstmt.setORAData(3, vidProxy);
       pstmt.setORAData(4, docProxy);
    
       pstmt.execute();
       pstmt.close();
   

6. Commit the transaction:

   conn.commit();
   

2.4.4 Handling Oracle Multimedia Exceptions in Java

Possible errors that can occur during run time should always be handled in your application. This practice enables the program to continue its operation even when it encounters a run-time error. This practice also enables users to know what went wrong during program operation. Proper error handling practices ensure that, whenever possible, you are always able to recover from an error while running an application. In addition, proper error handling provides you with the information you need so you always know what went wrong.

This section demonstrates proper error handling practices using code examples. These examples show how to handle some common Oracle Multimedia errors and other types of errors in Java programs. These examples are extracted from the Java sample applications that are described in Chapter 3 and Chapter 5. (See Oracle Multimedia Reference for more examples.)

When handling exceptions, Java uses the try/catch block. For example, in Java, the exception can appear as:

try {
    //<some program logic>)
}
catch (exceptionName a) {
//Exception logic
}
finally {
//Execute logic if try block is executed even if an exception is caught
}

When you design, code, and debug your application, you are aware of the places in your program where processing might stop due to a failure to anticipate an error. Those are the places in your program where you must add exception handling blocks to handle the potential errors.

The examples in this section describe exception handling using the try/catch block. These examples are included in the Oracle Multimedia Java API sample application, the Oracle Multimedia Java Servlet Photo Album application, and the Oracle Multimedia JavaServer Pages Photo Album application.

The following subsections provide additional details and examples of exception handling in Java:

• Handling the Setting of Properties for Unknown Image Formats in Java

• Handling Image Processing for Unknown Image Formats in Java

static boolean setProperties(OrdImage img)
  {
    try
    {
      img.setProperties();
      return true;
    }
    catch (SQLException e)
    {
      return false;
    }
  }

try
        {
            image.processCopy( "maxScale=50,50", thumb );
        }
        catch ( SQLException e )
        {
            thumb.deleteContent();
            thumb.setContentLength( 0 );
        }

2.5.1 Media Retrieval in Java-Based Web Applications

In general, displaying a Web page that contains images in a Web browser requires two HTTP round trips.

In the first trip, the Web browser makes an HTTP request to the URL of the Web page that contains the images. The Web server responds with the Web page text content and the URLs for the media content. The URL is the src attribute of the <img> tag in the Web page.

In the second trip, the Web browser makes another HTTP request to the URL in the <img> tag to get the image binary data, and then displays the image in the browser.

In a Java-based Web application, sending media data from the database to an HTTP client (Web browser) requires the proper media URL (generated in the first HTTP response); and the proper media delivery component (a servlet or JSP for the second HTTP response).

The following subsections provide additional details and examples of this process:

• Media URL

• Media Delivery Component

<img src="OrdGetMedia.jsp?id=1"/>

import oracle.ord.im.OrdHttpResponseHandler;
 
protected void doGet(HttpServletRequest request,
 HttpServletResponse response)
  throws ServletException, java.io.IOException
{
// obtain oracle.ord.im.OrdImage object 
// imgProxy follows the Section "Media Retrieval in Java"
 . . . 
 
// deliver the image data to the browser
OrdHttpResponseHandler handler = 
new OrdHttpResponseHandler( request, response);
handler.sendImage(imgProxy);
 
 . . . 
 }

<%@ page 
import="oracle.ord.im.OrdHttpJspResponseHandler" 
%>
 
<jsp:useBean id = "handler" scope="page"
     class = "oracle.ord.im.OrdHttpJspResponseHandler" 
/>
 
<%
// obtain oracle.ord.im.OrdImage object 
// imgProxy follows the Section "Media Retrieval in Java"
. . . 
 
// deliver the image data to the browser
   handler.setPageContext( pageContext );
   handler.sendImage(imgProxy);
   return;
%>

2.5.2 Media Upload in Java-Based Web Applications

The HTML form enables you to input and upload data from a Web browser to a Web server for processing. The following HTML code segment is an example of the HTML form that uploads a file. This code example highlights in bold the SQL statements and areas in the code where this operation takes place.

<form action="uploadAction.jsp" method="post" 
enctype="multipart/form-data">
id: <input type="text" name="id"/>
description: <input type="text" name="description"/>
Photo: <input type="file" name="photo"/>
</form>

Referring to the preceding code example, setting the value of the enctype attribute in the <form> tag to "multipart/form-data" specifies multipart/form-data format encoding of the uploaded data. The value of the action attribute in the <form> tag represents the name of the JSP that handles the uploaded data.

To handle the uploaded data in a JSP or servlet, follow these steps:

1. Decode the uploaded file. Because this file is encoded in multipart/form-data format, the data must be decoded before further processing can proceed. You can use the OrdHttpUploadFormData class to decode the encoded HTTP request data and obtain the uploaded file as an instance of the OrdHttpUploadFile object. You can use this class explicitly or implicitly to get the decoded uploaded file.

   The following example demonstrates how to use the OrdHttpUploadFormData class explicitly to get the uploaded file, and highlights in bold the SQL statements and significant areas in the code where this operation takes place. Use this method within the servlet or JSP that handles the upload HTTP request.

   //
   // Import OrdHttpUploadFormData and OrdHttpUploadFile class:
   // In a servlet:
   // import oracle.ord.im.OrdHttpUploadFormData;
   // import oracle.ord.im.OrdHttpUploadFile;
   // In a JSP:
   // <%@ page import="oracle.ord.im.OrdHttpUploadFormData" %>
   // <%@ page import="oracle.ord.im.OrdHttpUploadFile" %>
   //
    
   //
   // Following code snippets should be within <% %> if in a JSP.
   //
    
   // Create an OrdHttpUploadFormData object and use it to parse 
   // the multipart/form-data message.
   //
   OrdHttpUploadFormData formData = new OrdHttpUploadFormData(
    request );
   formData.parseFormData();
    
   //
   // Get the description, location, and photo.
   //
   String id = formData.getParameter( "id" );
   String description = formData.getParameter( "description" );
   OrdHttpUploadFile photo = formData.getFileParameter( "photo" );
    
   //
   // Process the uploaded file.
   //
    ...
    
   //
   // Release the resources.
   //
   formData.release();
   

   To avoid instantiating and releasing the OrdHttpUploadFormData class explicitly in each JSP or servlet that handles the uploaded data, you can use the OrdHttpUploadFormData class implicitly by configuring the Web application with the OrdMultipartFilter class. Using the OrdMultipartFilter class ensures that any HTTP request that is encoded in multipart/form-data format is decoded and passed along to the JSP or servlet that further processes the request.

   The following substeps and accompanying examples describe how to use the OrdHttpUploadFormData class implicitly to get the uploaded file. These code examples highlight in bold the SQL statements and significant areas in the code where this operation takes place.

   1. Configure the filter by adding this code to the web.xml file in your Web application:

      <filter>
          <filter-name>OrdMultipartFilter</filter-name>
          <filter-class>
      oracle.ord.im.OrdMultipartFilter
          </filter-class>
      </filter>
      <filter-mapping>
          <filter-name>OrdMultipartFilter</filter-name>
          <servlet-name>*.jsp</servlet-name>
      </filter-mapping>
      

   2. Obtain the form data and the uploaded file in the JSP or servlet after the filter is configured:

      //
      // Get the id, description, and photo.
      //
      String id = request.getParameter( "id" );
      String description = request.getParameter( "description" );
       oracle.ord.im.OrdHttpUploadFile photoFile = 
        request.getFileParameter("photo");
      

      where request is the HttpServletRequest object passed to the JSP or servlet.

2. Save the uploaded file to the database. After the OrdHttpUploadFile object is obtained by explicitly or implicitly using the OrdHttpUploadFormData class, the uploaded file is ready to be loaded into an Oracle Multimedia object in the database, using this statement:

   photoFile.loadImage(imgProxy);
   

   where photoFile is the OrdHttpUploadFile object andimgProxy is an OrdImage object obtained in Step 1 in Section 2.4.3.

   The loadImage method implicitly calls the setProperties method to populate the object fields.

   After the data is loaded into the Oracle Multimedia Java object, you can update the corresponding Oracle Multimedia object in the database table by following Steps 4 and 5 in Section 2.4.3.