Before you can begin using Oracle Multimedia with Java, you must set up your environment to compile and run Java programs.

Follow these steps:

The following example shows how to import multimedia data from the file system into the database in a Java application.

public void writeImageToDatabase(int id, String fileName )
            throws SQLException, IOException
                      {
       //Define the PL/SQL block to insert the new row.

       final String INSERT_BLOB = "DECLARE "
                    + "    src_id        NUMBER; "
                    + "BEGIN "
                    + "    src_id := ?;"
                    + "    DELETE FROM image_blob_table WHERE id=src_id; "
                    + "    INSERT INTO image_blob_table t (id, image_blob) "
                    + "           VALUES(src_id, empty_blob()) "
                    + "           RETURNING t.image_blob INTO ?; "
                    + "END;";
       try {

             //Create the statement object.
             final OracleCallableStatement pstmt =
                   (OracleCallableStatement)connection.prepareCall
                   (INSERT_BLOB);

             //Binding the variables to the statement.
             pstmt.setInt(1, id); //ID
             pstmt.registerOutParameter(2, OracleTypes.BLOB);
             pstmt.execute(); //Execute the PL/SQL statement.

             //Get the BLOB locator from the table.
             BLOB blob = pstmt.getBLOB(2);
             File binaryFile = new File(fileName);
             FileInputStream instream = new FileInputStream(binaryFile);

             //Retrieve the ideal buffer size to use in writing to the BLOB.
             int size = 1024*1024; // 1MB.
             byte[] buffer = new byte[size];
             int read = -1;
             long position =1;

             //Read the file to the byte array buffer, then write it to the BLOB.
             while ((read = instream.read(buffer)) != -1)

                {
                      blob.setBytes(position,buffer,0,read);
                      position+=read;
                }

                instream.close();
                connection.commit();


       } catch (FileNotFoundException e) {
               throw new FileNotFoundException("File " + fileName +" not Found.");
       } catch (IOException e) {
               throw new IOException("Error while reading " + fileName);

       }

           }

Call writeImageToDatabase( ) passing the row id and source file path:

//Write data from a local file into a BLOB in the database.
quickstart.writeImageToDatabase(1, "flowers.jpg");

java.sql.SQLException: ORA-22990: LOB locators cannot span transactions

conn.setautoCommit(false);

After the image data is imported from the file system into the table image_blob_table, the database does not know what the binary bytes in the BLOB column image_blob represent. The following example shows how to use the ORDSYS.ORD_IMAGE.getProperties( ) procedure of the Oracle Multimedia PL/SQL package to extract the image properties into the Java application.

public HashMap <String, Object> getProperties_example_j(int id )
       throws SQLException
  {
//Define the PL/SQL block to extract the properties.
final String getPropertiesStmt = "DECLARE "
         + "    src                         BLOB; "
         + "    img_mimeType                VARCHAR2(32); "
         + "    img_width                   INTEGER; "
         + "    img_height                  INTEGER; "
         + "    img_contentLength           INTEGER; "
         + "    img_fileFormat             VARCHAR2(32); "
         + "    img_contentFormat           VARCHAR2(32); "
         + "    img_compressionFormat      VARCHAR2(32); "
         + "BEGIN "
         + "    SELECT image_blob INTO src FROM image_blob_table"
         + "           WHERE id=?; "
         + "    ORDSYS.ORD_IMAGE.getProperties(src, "
         + "                  img_mimeType, "
         + "                  img_width, "
         + "                  img_height, "
         + "                  img_fileFormat, "
         + "                  img_compressionFormat, "
         + "                  img_contentFormat, "
         + "                  img_contentLength); "
         + "    ? := img_mimeType; "
         + "    ? := img_width; "
         + "    ? := img_height; "
         + "    ? := img_contentLength; "
         + "    ? := img_fileFormat; "
         + "    ? := img_contentFormat;"
         + "    ? := img_compressionFormat; "
         + "END;";

//Create the statement object.
final OracleCallableStatement pstmt =
     (OracleCallableStatement)connection.prepareCall(getPropertiesStmt);

//Binding the variables to the statement.
pstmt.setInt(1, id);
pstmt.registerOutParameter(2, OracleTypes.VARCHAR);
pstmt.registerOutParameter(3, OracleTypes.INTEGER);
pstmt.registerOutParameter(4, OracleTypes.INTEGER);
pstmt.registerOutParameter(5, OracleTypes.INTEGER);
pstmt.registerOutParameter(6, OracleTypes.VARCHAR);
pstmt.registerOutParameter(7, OracleTypes.VARCHAR);
pstmt.registerOutParameter(8, OracleTypes.VARCHAR);

//Execute the statement.
pstmt.execute();

//Create a HashMap object and populate it with the properties.
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("mimeType", pstmt.getString(2));
map.put("width", pstmt.getInt(3) );
map.put("height", pstmt.getInt(4));
map.put("contentLength", pstmt.getInt(5));
map.put("fileFormat", pstmt.getString(6));
map.put("contentFormat", pstmt.getString(7));
map.put("compressionFormat", pstmt.getString(8));

return map;
   }

Call getProperties_example_j( ) passing the id, then iterate over the HashMap to print the properties.

System.out.println("Original image properties");
       HashMap<String, Object> attributesMap= quickstart.getProperties_example_j(1);
       //Iterate over the HashMap.
       for (Map.Entry<String, Object> entry : attributesMap.entrySet()) {
              System.out.println(entry.getKey() + " = " + entry.getValue());
       }

     Exception in thread "main" java.sql.SQLException: ORA-29400: data cartridge error

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.

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

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.

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

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;

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

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.

    -- ORDImage.import also calls ORDImage.setProperties.
  img.import(ctx); 
  
  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;
/

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;
/

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.

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

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.

These examples are extracted from the PL/SQL sample applications that are described in Oracle Multimedia PL/SQL Photo Album Sample Application and Oracle Multimedia Code Wizard Sample Application for the PL/SQL Gateway.

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

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 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 (including htp, htf, and owa ) 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.

The following figure shows these main components: Oracle HTTP Server, the Web browser, and the database.

Figure 2-1 Components of a PL/SQL Web Application

Description of "Figure 2-1 Components of a PL/SQL Web Application"

The numbers in the preceding figure represent steps that describe how a client Web browser request is turned into a Web page response from the execution of the PL/SQL procedure:

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.

Web application developers who use the PL/SQL Gateway 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.

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.

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

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 on 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 demonstrates how this operation works. For example, to invoke the Code Wizard administration URL, enter the following URL:

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.