2 Application Development

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 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. For more information about handling PL/SQL exceptions, see Oracle Database PL/SQL Language Reference.

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

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]]

For a detailed description of each parameter and the options available, see Oracle Fusion Middleware User's Guide for mod_plsql in the Oracle Fusion Middleware Online Documentation Library.

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.

For more information, see Oracle Database Advanced Application Developer's Guide.

2.4.1 Setting Up Your Environment for Java

Before you can begin using Oracle Multimedia Java API, 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 libraries for the Oracle Multimedia and other features that you intend to use.

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

   Table 2-1 Java Libraries for Oracle Multimedia

   Name of Oracle Java Library	Related Features	JDK Version, Platform, and Location
   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
   Oracle Multimedia Java classes library	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
   Oracle Multimedia DICOM Java classes library	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
   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
   Oracle Multimedia Servlets and JSP Java classes library	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
   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 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. For more information about handling Java exceptions, see Oracle Database Java Developer's Guide and Oracle Database JDBC Developer's Guide.

The following examples 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.

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

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