3 Oracle Multimedia Photo Album Sample Applications

CREATE TABLE photos( id           NUMBER PRIMARY KEY,
                     description  VARCHAR2(40) NOT NULL,
                     metaORDImage XMLTYPE,
                     metaEXIF     XMLTYPE,
                     metaIPTC     XMLTYPE,
                     metaXMP      XMLTYPE,
                     image        ORDSYS.ORDIMAGE,
                     thumb        ORDSYS.ORDIMAGE )
--
-- store full-size and thumbnail images as SecureFile LOBS
--
LOB(image.source.localdata)  STORE AS SECUREFILE
LOB(thumb.source.localdata)  STORE AS SECUREFILE
--
-- and bind the XMLType columns to the Oracle Multimedia metadata schemas
XMLType COLUMN metaORDImage
  STORE AS SecureFile CLOB
  XMLSCHEMA "http://xmlns.oracle.com/ord/meta/ordimage"
  ELEMENT "ordImageAttributes"
XMLType COLUMN metaEXIF
  STORE AS SecureFile CLOB
  XMLSCHEMA "http://xmlns.oracle.com/ord/meta/exif"
  ELEMENT "exifMetadata"
XMLType COLUMN metaIPTC
  STORE AS SecureFile CLOB
  XMLSCHEMA "http://xmlns.oracle.com/ord/meta/iptc"
  ELEMENT "iptcMetadata"
XMLType COLUMN metaXMP
  STORE AS SecureFile CLOB
  XMLSCHEMA "http://xmlns.oracle.com/ord/meta/xmp"
  ELEMENT "xmpMetadata";

-- Create preference PA_CTXIDX.
ctx_ddl.create_preference('SCOTT.PA_CTXIDX', 'MULTI_COLUMN_DATASTORE');
 
-- Create a multicolumn datastore.
ctxcols := 'description, '                   ||
            'SCOTT.photo_album.getClob(METAIPTC), ' ||
            'SCOTT.photo_album.getClob(METAEXIF), ' ||
            'SCOTT.photo_album.getClob(METAXMP), '  ||
            'SCOTT.photo_album.getClob(METAORDIMAGE)';
ctx_ddl.set_attribute( ctxpref, 'COLUMNS', ctxcols );
 
 
-- Create the CONTEXT text index.
create  index pa_ctx_idx on photos(description)
indextype is ctxsys.context
parameters ( 'DATASTORE SCOTT.PA_CTXIDX' );

create index pa_path_iptc_idx  on photos( metaIptc )
 indextype is XDB.XMLIndex;
 
create index pa_path_exif_idx  on photos( metaExif )
 indextype is XDB.XMLIndex;
 
create index pa_path_xmp_idx  on photos( metaXMP )
 indextype is XDB.XMLIndex;

CREATE TABLE PHOTOS_UPLOAD( name           VARCHAR2(256) UNIQUE NOT NULL,
                            mime_type      VARCHAR2(128),
                            doc_size       NUMBER,
                            dad_charset    VARCHAR2(128),
                            last_updated   DATE,
                            content_type   VARCHAR2(128),
                            blob_content   BLOB )
-- 
-- store BLOBs as SecureFile LOBs
-- 
LOB(blob_content)  STORE AS SECUREFILE;

3.1.1 Running the PL/SQL Photo Album Application

After you have completed the setup tasks and have built the PL/SQL Photo Album application, including creating a database access descriptor (DAD) entry (as described in the README.txt file), you are ready to run this application.

In the address field of your Web browser, enter the following URL:

<protocol><hostname:port-number>/photoalbum

1. In the <protocol> field, enter http://.

2. In the <hostname:port-number> field, enter the host name and port number of the system where your HTTP server is running.

When first invoked, this photo album application displays any images that are currently stored in the album. By default, the photo album is empty when first installed. To upload a new photograph, select Upload photo. Enter a description of the photograph and the name of the image file, or browse to its directory location. Then, click Upload photo.

The contents of the photo album are displayed, along with a picture of the new photograph. Click the thumbnail image to view the full-size version of the photograph. When this photo album application displays the text view image instead of its thumbnail image, the image format that was uploaded was not recognized by Oracle Multimedia. Click view image to display the full-size image.

You can now begin to load your photo album application with your favorite photographs.

3.1.2 Description of the PL/SQL Photo Album Application

The user interface for the PL/SQL Photo Album application consists of a set of Web pages. You can use these Web pages to perform the tasks shown in Table 3-1. The tasks and the Web pages are introduced in this section and described in further detail in the following sections.

You can explore this photo album application using the navigation bar near the top of each Web task page. The leftmost entry of the navigation bar displays the name of the current Web page. On the right, there are links to other Web pages you can access from the current page. Each Web task page contains a link to the View album page, which is the home page for the application.

This photo album application is implemented as a set of PL/SQL procedures and functions organized in a single PL/SQL package. These procedures combine several database features to create the application. Oracle Multimedia is used to store and process image data. It is also used to extract metadata from images and embed new metadata into images. The XMLType feature is used to store and process the XML metadata documents. Oracle Text indexes are used to accelerate two kinds of metadata searches. Finally, the PL/SQL Web Toolkit is used to create HTML pages and deliver media content.

For detailed information about these database features, see Oracle XML DB Developer's Guide, Oracle Text Application Developer's Guide, and Oracle Database Advanced Application Developer's Guide.

Browsing the Photo Album Using the View album Page The View album page displays thumbnail-size versions of all the images in the photo album and a description link positioned under each thumbnail image. When you select a thumbnail image, the full-size image is displayed. When you select the description link for an image, all the metadata for that image is displayed. The View album page is the home page for the application.

Adding Images to the Photo Album Using the Upload photo Page The Upload photo page displays a simple form to collect a description for a new image and the directory path to the location of the image on the local computer. When you click the Upload photo button, the browser sends the image to the Web server and the image is stored in the database.

Searching for Images by Keyword or Phrase Using the Search album Page The Search album page displays a search album form to collect keywords or phrases to initiate full-text searches through all image metadata. The application queries the database for all images with metadata that contains the specified keywords or phrases. The search results are displayed as a set of thumbnail images. The search album form is also available from the View album page.

Viewing Full-Size Images Using the View entry Page The View entry page displays the full-size image of a specified photograph, including any description text that was entered for that image when it was uploaded.

Examining Image Metadata Using the View metadata Page The View metadata page displays all the metadata that was extracted from the image when it was uploaded. Up to four types of metadata can be displayed.

Writing New XMP Metadata to Images Using the Write XMP metadata Page The Write XMP metadata page displays a form to collect input for five metadata attributes. These attributes are formatted into an XML document that is embedded within the binary image. The new XMP metadata overwrites any existing XMP metadata.

Searching for Images That Contain Specific Metadata Attributes Using the Search metadata Page The Search metadata page collects input for advanced metadata searches. You can specify the type of metadata to be searched. Optionally, you can also limit the search to a specific XML tag within the specified document. The search results are displayed as a set of thumbnail images.

CREATE TABLE photos( id          NUMBER PRIMARY KEY,
                    description VARCHAR2(40) NOT NULL,
                    location    VARCHAR2(40),
                    image       ORDSYS.ORDIMAGE,
                    thumb       ORDSYS.ORDIMAGE )
--
-- store full-size images and thumbnail images as SecureFile LOBs
--
LOB(image.source.localdata)  STORE AS SECUREFILE
LOB(thumb.source.localdata)  STORE AS SECUREFILE;

CREATE SEQUENCE photos_sequence;

3.2.1 Running the Java Servlet Photo Album Application

After you have completed the setup tasks and have built the Java Servlet Photo Album application, you are ready to run it.

In the address field of your Web browser, enter the URL for the default installation of Oracle Fusion Middleware or Oracle Containers for Java EE (OC4J) standalone, as follows:

<protocol><hostname:port-number>/servlet/PhotoAlbumServlet

1. In the <protocol> field, enter http://.

2. In the <hostname:port-number> field, enter the host name and port number of the system where your HTTP server is running.

When first invoked, this photo album application displays any images that are currently stored in the album. By default, the photo album is empty when first installed. To upload a new photograph, select Upload new photo. Enter a description of the photograph, the location where the photograph was taken, and the name of the image file (or browse to its directory location), then click Upload photo. The contents of the photo album are displayed along with a picture of the new photograph. Click the thumbnail image to view the full-size version of the photograph.

When this photo album application displays the text view image instead of its thumbnail image, the image format that was uploaded was not recognized by Oracle Multimedia. Click view image to display the full-size image.

You can now begin to load your photo album application with your favorite photographs.

3.2.2 Description of the Java Servlet Photo Album Application

The Java Servlet Photo Album application combines both business logic and the presentation into a single servlet, which when compiled, creates two class files, PhotoAlbumServlet.class and PhotoAlbumRequest.class.

To follow along with the description of tasks, refer to a copy of the PhotoAlbumServlet.java file, which is available in:

<ORACLE_HOME>/ord/http/demo/servlet (on Linux and UNIX)

<ORACLE_HOME>\ord\http\demo\servlet (on Windows)

PhotoAlbumServlet Class

The PhotoAlbumServlet class performs these tasks:

• Extends the HttpServlet and contains the user-entered connection information.

  public class PhotoAlbumServlet extends HttpServlet
  

• Instantiates a Java stack used to implement a simple connection-pooling mechanism.

  private static Stack connStack = new Stack();
  

• Defines a flag to indicate whether the JDBC Thin driver has been loaded.

  private static boolean driverLoaded = false;
  

• Defines a servlet initialization method.

  public void init( ServletConfig config ) throws ServletException
  {
      super.init(config);
  }
  

• Defines a doGet( ) method to process an HTTP GET request containing an HttpServletRequest object and HttpServletResponse object, and instantiates a PhotoAlbumRequest object to process the request to deliver either a full-size or thumbnail image to the browser, or to display an upload form or the contents of the photo album as thumbnail images.

  public void doGet( HttpServletRequest request,
                     HttpServletResponse response )
      throws ServletException, IOException
  {
      Connection conn = null;
  
      //
      // Use a try-block to ensure that JDBC connections are always returned
      // to the pool.
      //
      try
      {
          //
          // Get a JDBC connection from the pool.
          //
          conn = getConnection();
  
          //
          // Instantiate a PhotoAlbumRequest object to process the request.
          //
          PhotoAlbumRequest albumRequest =
              new PhotoAlbumRequest( conn, request, response );
  
          //
          // Figure out what to do based on query string parameters.
          //
          String view_media = request.getParameter( "view_media" );
          if ( view_media != null )
          {
              //
              // Deliver a full-size or thumbnail image to the browser.
              //
              albumRequest.viewMedia( view_media );
              return;
          }
          else if ( request.getParameter( "view_form" ) != null )
          {
              //
              // Display the HTML upload form.
              //
              albumRequest.viewUploadForm();
          }
          else if ( request.getParameter( "view_entry" ) != null )
          {
              //
              // Display full-size photo image.
              //
              albumRequest.viewPhoto();
          }
          else
          {
              //
              // Display album contents with thumbnail images by default.
              //
              albumRequest.viewAlbum();
          }
      }
      catch ( SQLException e )
      {
          //
          // Log what went wrong.
          //
          e.printStackTrace( System.out );
  
          //
          // Turn SQL exceptions into ServletExceptions.
          //
          throw new ServletException( e.toString() );
      }
      finally
      {
          //
          // If we have a JDBC connection, then return it to the pool.
          //
          freeConnection( conn );
      }
  }
  

• Defines a doPost( ) method to process an HTTP POST request used to upload a new photograph into the album by instantiating a PhotoAlbumRequest object to process the request and then calling the insertNewPhoto( ) method.

  public void doPost( HttpServletRequest request,
                      HttpServletResponse response )
      throws ServletException, IOException
  {
      Connection conn = null;
  
      //
      // Use a try-block to ensure that JDBC connections are always returned
      // to the pool.
      //
      try
      {
          //
          // Get a JDBC connection from the pool.
          //
          conn = getConnection();
  
          //        // Instantiate a PhotoAlbumRequest object to process the request.
          //
          PhotoAlbumRequest albumRequest =
              new PhotoAlbumRequest( conn, request, response );
  
          //
          // Insert the photo into the album.
          //
          albumRequest.insertNewPhoto();
      }
      catch ( SQLException e )
      {
          //
          // Log what went wrong.
          //        e.printStackTrace( System.out );
  
          //
          // Turn SQL exceptions into ServletExceptions.
          //
          throw new ServletException( e.toString() );
      }
      finally
      {
          //
          // If we have a JDBC connection, then return it to the pool.
          //
          freeConnection( conn );
      }
  }
  

In summary, the PhotoAlbumServlet class responds to the HTTP GET and POST requests by allocating a JDBC connection from a connection pool. Each HTTP GET or POST request is assigned its own JDBC connection from the pool to ensure that multiple requests can be serviced concurrently. An HTTP GET request is used to retrieve image data from the photo album, and an HTTP POST request is used to upload image data into the photo album. Then, an instance of the PhotoAlbumRequest class is created to execute the request, it executes the request, then it releases the JDBC connection back to the pool after completing the request.

See Oracle Database JDBC Developer's Guide and Reference for detailed information about using JDBC connections.

PhotoAlbumRequest Class

The PhotoAlbumRequest class does the actual processing of an HTTP GET or POST request, and defines the getPreferredFormat( ) function and these methods:

viewAlbum( )
viewPhoto( )
viewMedia( )
viewUploadForm( )
insertNewPhoto( )
printPageHeader( )
printPageTrailer( )
printMessage( )
printHeading( )
printLink( )

In the viewMedia( ) and insertNewPhoto( ) methods, three objects, OrdHttpResponseHandler, OrdHttpUploadFormData, and OrdHttpUploadFile, are instantiated. These objects are used to call the methods of the respective OrdHttpResponseHandler, OrdHttpUploadFormData, OrdHttpUploadFile classes of Oracle Multimedia Servlets and JSP Java API. For example, in the viewMedia( ) method, the OrdHttpResponseHandler object is instantiated and used to call the sendImage( ) method as shown in this code:

OrdHttpResponseHandler handler =
    new OrdHttpResponseHandler( request, response );
handler.sendImage( img );

The viewAlbum( ), viewPhoto( ), viewMedia( ), and insertNewPhoto( ) methods use the ORAData (formerly getCustomDatum) and ORADataFactory (formerly getFactory) interfaces supplied by Oracle to get the image or thumbnail OrdImage object from the result set to obtain height and width information, to retrieve an image from an OrdImage Java object and deliver it to the browser, and to upload an image in an OrdImage Java object and to also update it in the photos table. For example, the following code segment is from the viewAlbum( ) method:

OrdImage img =
    (OrdImage)rset.getORAData( 4, OrdImage.getORADataFactory() );
.
.
.
out.print( "<td headers=\"image\"><a href=\"" + servletUri +
           "?view_entry=yes&id=" + id + "\">" );
if ( img.getContentLength() > 0 )
{
    if (img.getMimeType().startsWith("image/"))
    {
     out.print( "<img src=\"" + servletUri +
                           "?view_media=thumb&id=" + id + "\"" +
                           " height=" + img.getHeight() +
                           " width=" + img.getWidth() +
                           " alt=\"" + description + "\"" +
         " border=1>" );
    }
}
else
{
    out.print( "[view image]" );
}
out.println( "</a></td>" );
out.println( "</tr>" );

What follows is a more detailed description of each method and what it does:

• The viewAlbum( ) method does the following:

  • Initializes the row count to zero.

  • Writes a common page header on the HTML page using the function printPageHeader( ).

  • Executes a SELECT statement to fetch all the thumbnail images in the photo album, order them by description, and display the description and location information for each along with the thumbnail image if it exists, and returns the results in a result set.

  • Displays the thumbnail images in an HTML table with column headers labeled Description, Location, and Image.

  • Within a while block, reads the contents of the result set by reading the first row's contents beginning with the id value, displays the description and location values, then gets the thumbnail OrdImage object and builds the height and width attributes for each thumbnail image.

  • Displays the thumbnail image using an HTML anchor tag that can be used to display the full-size image. When a user clicks the thumbnail image or view image, the full-size image is displayed.

  • Displays the contents of the photo album within an HTML anchor tag using the tag <IMG SRC="<servlet-path>?view_media=thumb&id=..."> to display the thumbnail images, where <servlet-path> is the value of servletUri. If the thumbnail image was not created because the image format was not supported by Oracle Multimedia, the text view image is displayed instead.

  • Increments the row count to see if the photo album is empty; if so, it displays the message "The photo album is empty".

  • Displays an HTML anchor tag near the bottom of the HTML page using the printLink( ) function with the text Upload new photo.

  • Writes a common trailer at the bottom of the HTML page by calling the printPageHeader( ) function, however, in this case, sets the Boolean argument to false to not display the common page trailer.

  • Closes the result set and the statement.

• The viewPhoto( ) method displays the full-size version of a photograph and does the following:

  • Writes a common page header on the HTML page using the function printPageHeader( ).

  • Gets the value of the id column for the entry being viewed.

  • Executes a SQL SELECT statement to fetch the entry's description, location, and full-size image where the value of id in the where clause is a parameter marker and returns the results in a result set.

  • Gets the image OrdImage object from the result set so it can later build the image height and width attributes within the <IMG SRC=...> image tag.

  • Displays the full-size image in an HTML table beginning with the column names Description and Location, and displays the entry's values for these two columns.

  • Builds the URL to fetch a full-size image for this entry by using an image tag <IMG SRC="<servlet-path>?view_media=image&id=..."> to display an image in the column labeled Photo, where <servlet-path> is the value of servletUri.

  • Displays the full-size images height and width by calling the getHeight( ) and getWidth( ) Oracle Multimedia object methods. If the image format is not recognized by Oracle Multimedia, height and width values are zero and are not displayed.

  • Writes a common page trailer at the bottom of the HTML page by calling the printPageHeader( ) function and setting its Boolean argument to true to display the common page trailer.

  • Closes the result set and the statement.

• The viewMedia( ) method is invoked by both thumbnail and full-size image URLs to retrieve a thumbnail or full-size image from the photos table and deliver it to the browser using the OrdHttpResponseHandler class. This method does the following:

  • Executes a SQL SELECT statement to fetch either the thumbnail or full-size image where the value of id in the where clause is a parameter marker and returns the results in a result set. The SQL SELECT statement is built dynamically with the string media equating to either the thumbnail image column or the full-size image column.

  • Fetches a row from the result set.

  • Gets the OrdImage object from the result set.

  • Uses the OrdHttpResponseHandler class to create an OrdHttpResponseHandler object to retrieve the image from the OrdImage object and deliver it to the browser using the sendImage( ) method. The sendImage( ) method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

  • Closes the result set and the statement.

• The viewUploadForm( ) method displays an HTML form that enables users to upload new photographs and does the following:

  • Calls the printPageHeader( ) function to produce the common page header.

  • Defines the form action as a multipart/form-data POST request.

  • Calls the upload_form_fields static string containing the contents of the upload form. The upload form is defined as a table with rows labeled Description and Location, with an input type of text and named description and location respectively, followed by a row labeled File name:, with an input type of file and named photo, and finally a row with no label, an input type of submit, and a value of Upload photo.

  • Calls the printPageTrailer( ) function to produce the common page trailer.

• The insertNewPhoto( ) method does the following:

  • Uses the OrdHttpUploadFormData class to parse a multipart/form-data POST request containing an uploaded photograph.

  • Uses the OrdHttpUploadFile class to upload the new photograph into the database.

  • Executes a SQL SELECT photos_sequence.nextval statement to get the next value of the id column for the new row to be inserted into the photos table.

  • Executes a SQL INSERT statement to insert a new row in the photos table.

  • Executes a SQL SELECT...FOR UPDATE statement to fetch the initialized full-size and thumbnail image objects from the photos table.

  • Calls the loadImage( ) method in the OrdHttpUploadFile class to populate an OrdImage object named image with the full-size image and sets the properties or attribute values of the image object based on the image contents.

  • Checks to see what the image format is and if it is an image format that cannot be displayed inline by a browser, such as a BMP image format, then calls the getPreferredFormat( ) method to convert a BMP image format and return the preferred image format.

  • Calls the ProcessCopy( ) method in the OrdImage class to process the full-size image, create a thumbnail image, and populate an OrdImage object named thumb.

  • Executes a SQL UPDATE statement to update the full-size and thumbnail images in the database.

  • Displays a photo upload success message and then directs the browser to refresh the page.

• A getPreferredFormat( ) private function, in this sample application, converts a BMP image format and returns the preferred image file format based on the number of colors in the image; returns a MONOCHROME image format if there are no colors, or a JPEG if there are more than 8 colors, or a GIF if there are greater than 0 and fewer than 8 colors.

• A printPageHeader( ) private function displays an HTML header that is common to all HTML responses.

• A printPageTrailer( ) private function displays an HTML trailer that is common to all HTML responses.

• A printMessage( ) private function prints a message on the HTML page.

• A printHeading( ) private function prints a header on the HTML page.

• A printLink( ) function produces an HTML anchor tag in a standard format.

CREATE TABLE photos( id          NUMBER PRIMARY KEY,
                    description VARCHAR2(40) NOT NULL,
                    location    VARCHAR2(40),
                    image       ORDSYS.ORDIMAGE,
                    thumb       ORDSYS.ORDIMAGE )
--
-- store full-size images and thumbnail images as SecureFile LOBs
--
LOB(image.source.localdata)  STORE AS SECUREFILE
LOB(thumb.source.localdata)  STORE AS SECUREFILE;

CREATE SEQUENCE photos_sequence;

3.3.1 Running the JSP Photo Album Application

After you have completed the setup tasks and have built the JSP Photo Album application, you are ready to run it.

In the address field of your Web browser, enter the URL for the default installation of Oracle Fusion Middleware or Oracle Containers for Java EE (OC4J) standalone, as follows:

<protocol><hostname:port-number>/demo/PhotoAlbum.jsp

1. In the <protocol> field, enter http://.

2. In the <hostname:port-number> field, enter the host name and port number of the system where your HTTP server is running.

When first invoked, this photo album application displays any images that are currently stored in the album. By default, the photo album is empty when first installed. To upload a new photograph, select Upload new photo. Enter a description of the photograph, the location where the photograph was taken, and the name of the image file or browse to its directory location, then click Upload photo. The contents of the photo album are displayed along with a picture of the new photograph. Click the thumbnail image to view the full-size version of the photograph.

When this photo album application displays the text view image instead of its thumbnail image, the image format that was uploaded was not recognized by Oracle Multimedia. Click view image to display the full-size image.

You can now begin to load your photo album application with your favorite photographs.

3.3.2 Description of the JSP Photo Album Application

The JSP Photo Album application separates the business logic from the presentation by having a JavaBean containing methods that are accessed from each of five JSP files. When compiled, the application creates the PhotoAlbumBean.class file, which contains the user-entered connection information and defines the functions: getId( ), getDescription( ), getLocation( ), and getPreferredFormat( ) and the following methods:

selectTable( )
selectRowById( )
fetch( )
insertNewPhoto( )
release( )
getConnection( )
freeConnection( )
setId( )
setDescription( )
setLocation( )
getImage( )
getThumb( )

To follow along with the description of tasks, refer to a copy of each JSP file, which is available in:

<ORACLE_HOME>/ord/http/demo/jsp (on Linux and UNIX)

<ORACLE_HOME>\ord\http\demo\jsp (on Windows)

In the PhotoAlbumEntryViewer, PhotoAlbumMediaViewer, PhotoAlbum, and PhotoAlbumInsertPhoto JSP files, the jsp:useBean action tag is used to establish an ID and association with the PhotoAlbumBean class and the OrdHttpJspResponseHandler and OrdHttpUploadFormData classes of Oracle Multimedia Servlets and JSP Java API. For example, the following code appears in the PhotoAlbumInsertPhoto JSP file:

<jsp:useBean id="album" scope="page" class="PhotoAlbumBean"/>
<jsp:useBean id="handler" scope="page"
             class="oracle.ord.im.OrdHttpJspResponseHandler"/>
<jsp:useBean id="formData" scope="page"             class="oracle.ord.im.OrdHttpUploadFormData"/>

This jsp:useBean action tag is used so these objects can be referenced by their respective ID values (album, handler, and formData) to call the methods of these classes.

The OrdHttpUploadFile class of Oracle Multimedia Servlets and JSP Java API is defined as an object with the name uploadPhoto in the insertNewPhoto( ) method in the PhotoAlbumBean.java file and then used to call its loadImage( ) method to load the photograph into the photos table as shown in the following code segments:

public void insertNewPhoto( OrdHttpUploadFile uploadPhoto )
        throws SQLException, ServletException, IOException
.
.
.
uploadPhoto.loadImage( image );
.
.
.

The insertNewPhoto( ) method defined in the PhotoAlbumBean.java file, uses the ORAData (formerly getCustomDatum) and ORADataFactory (formerly getFactory) interfaces supplied by Oracle to upload an image and a thumbnail image in an OrdImage Java object. First, the method executes a SQL SELECT...FOR UPDATE statement to select the row for update, and then, executes a SQL UPDATE statement to update the image and thumb columns for that row in the photos table as shown in the following code segments:

stmt = (OraclePreparedStatement)conn.prepareStatement(
            "select image,thumb from photos where id = ? for update" );
stmt.setString( 1, id );
rset = (OracleResultSet)stmt.executeQuery();
if ( !rset.next() )
{
    throw new ServletException( "new row not found in table" );
}
image = (OrdImage)rset.getORAData( 1, OrdImage.getORADataFactory());
thumb = (OrdImage)rset.getORAData( 2, OrdImage.getORADataFactory());

rset.close();
stmt.close();
.
.
.
    //
    // Prepare and execute a SQL statement to update the full-size and
    // thumbnail images in the database.
    //
    stmt = (OraclePreparedStatement)conn.prepareStatement(
               "update photos set image = ?, thumb = ? where id = ?" );
    stmt.setORAData( 1, image );
    stmt.setORAData( 2, thumb );
    stmt.setString( 3, id );
    stmt.execute();
    stmt.close();

    //
    // Commit the changes.
    //
    conn.commit();
}

The fetch( ) method defined in the PhotoAlbumBean.java file or the PhotoAlbumBean JavaBean, fetches the next row from the result set using the ORAData and ORADataFactory interfaces to retrieve the image and the thumbnail image from an OrdImage Java object, and delivers each to the browser, as shown in the following example:

public boolean fetch()
    throws SQLException
{
    if ( rset.next() )
    {
        id = rset.getString( 1 );
        description = rset.getString( 2 );
        location = rset.getString( 3 );
        image = (OrdImage)rset.getORAData( 4, OrdImage.getORADataFactory() );
        thumb = (OrdImage)rset.getORAData( 5, OrdImage.getORADataFactory() );
        return true;
    }
    else
    {
        rset.close();
        stmt.close();
        return false;
    }
}

What follows is a more detailed description of each JSP file.

PhotoAlbum.jsp

This JSP file is the entry point to the JSP Photo Album application and does the following:

• Uses the PhotoAlbumBean JavaBean to access the contents of the photos table.

• Uses the OrdHttpJspResponseHandler class to facilitate the retrieval of image data from the photos table and its delivery to a browser or other HTTP client from a Java servlet.

• Displays the title of the page in the HTML header and in the common page header.

• Displays the thumbnail images in a table using column headers labeled, Description, Location, and Image.

• Uses a try/catch block to ensure the JDBC connection is released.

• Calls the selectTable( ) method to select all the rows in the photos table.

• Initializes the row count to zero.

• Displays an entry in the photo album by calling the getDescription( ) method, then the getLocation( ) method, and then printing the values in the appropriate columns. If the location information is blank, print a space in the Location column.

• Displays the contents of the photo album as thumbnail images using an HTML anchor tag to call the PhotoAlbumEntryViewer.jsp file to get the ID value by calling the getID( ) function.

• Calls the getThumb( ) method to get the thumbnail image and calls the getContentLength( ) method to determine the image length.

• Tests to see if the value returned for the image length is greater than 0, and if so uses an image tag of the form <IMG SRC="PhotoAlbumMediaViewer.jsp?media=thumb&...> to display the thumbnail image; otherwise, prints the link view image in the column header labeled Image, which, when clicked, retrieves the full-size image.

• Displays a message "The photo album is empty" if the photo album is empty. If the photo album is not empty, this message is displayed "Select the thumbnail to view the full-sized image".

• Ends the try/catch block with a finally clause and releases the JDBC connection by calling the release( ) method.

• Displays a link to the upload form with the text Upload new photo at the bottom of the page that calls the PhotoAlbumUploadForm.jsp file.

PhotoAlbumEntryViewer.jsp

This JSP file is called by the PhotoAlbum.jsp file that displays one full-size version of a photograph in the album. This JSP file does the following:

• Uses the PhotoAlbumBean JavaBean to access the contents of the photos table.

• Uses the OrdHttpJspResponseHandler class to facilitate the retrieval of image data from the photos table and its delivery to a browser or other HTTP client from a Java servlet.

• Displays the title of the page in the HTML header and in the common page header.

• Defines a string named id that calls the getParameter( ) method to get the id value.

• Displays a message "Malformed URL, no id parameter" in the event the value of the id string is null.

• Uses a try/catch block to ensure the JDBC connection is released.

• Calls the selectRowById( ) method with the value of id to select the entry to be displayed. If the next row to be fetched for that id value is not found, display a message "Entry not found: <id value>".

• Displays the entry in the album by calling the getDescription( ) method and displaying its value under the header Description, calling the getLocation( ) method and displaying its value under the Location header.

• Displays one full-size version of a photograph in the album using an image tag in the form <IMG SRC="PhotoAlbumMediaViewer.jsp?media=image&..."> under the Photo header.

• Displays the full-size images height and width by calling the getHeight( ) and getWidth( ) methods. If the image format is not recognized by Oracle Multimedia, height and width values are zero and are not be displayed.

• Displays a link at the bottom of the page Return to photo album that calls the PhotoAlbum.jsp file.

• Ends the try/catch block, and with a finally clause, releases the JDBC connection by calling the release( ) method.

PhotoAlbumMediaViewer.jsp

This JSP file is called by the PhotoAlbum.jsp and PhotoAlbumEntryViewer.jsp files and retrieves a single thumbnail or full-size image from the photos table using the PhotoAlbumBean JavaBean and delivers it to the browser using the OrdHttpResponseHandler class. This JSP file does the following:

• Uses the PhotoAlbumBean JavaBean to access the contents of the photos table.

• Uses the OrdHttpJspResponseHandler class to facilitate the retrieval of image data from the photos table and its delivery to a browser or other HTTP client from a Java servlet.

• Defines a string named id that calls the getParameter( ) method to get the id value.

• Defines a string named media that calls the getParameter( ) method to get the media value.

• Sets a condition to proceed as long as the value of the string id and the value of the string media is not null.

• Uses a try/catch block to ensure the JDBC connection is released.

• Calls the selectRowById( ) method to select a specific row from the photos table for the value of id.

• Delivers the full-size or thumbnail image by first calling the setPageContext( ) method of the OrdHttpJspResponseHandler class to specify the page context object; then, calling the getImage( ) method to return the image to the OrdImage object; then, calling the sendImage( ) method of the OrdHttpResponseHandler class to retrieve the image from the OrdImage object and deliver it to the browser. If the value of media is image, an image is delivered to the browser; if the value of media is thumb, a thumbnail image is delivered to the browser. The sendImage( ) method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

• Ends the try/catch block with a finally clause and releases the JDBC connection by calling the release( ) method.

• Displays this message in the event the request is not understood "PhotoAlbumMediaViewer.jsp - malformed URL".

PhotoAlbumUploadForm.jsp

This JSP file is called by the PhotoAlbum.jsp file that displays an HTML form to enable users to upload new photographs into the album. This JSP file does the following:

• Displays the title of the page in the HTML header and in its common page header.

• Displays any error message under the header "Error message" from a previous attempt to upload an image to determine whether the value of a string is not null after calling the getParameter( ) method with an argument of error.

• Displays a header with the text Upload a new photo.

• Defines the form action specifying the PhotoAlbumInsertPhoto.jsp file to process the upload request as a multipart/form-data POST request.

• Displays the upload form with rows labeled Description, Location, and File name:.

• Displays the contents of the upload form defined as a table with rows labeled Description and Location, both with an input type of text and named description and location respectively, followed by a row labeled File name: with an input type of file and named photo, and finally followed by a row with no label and an input type of submit and a value of Upload photo.

• Displays a link at the bottom of the page Return to photo album that calls the PhotoAlbum.jsp file.

PhotoAlbumInsertPhoto.jsp

This JSP file is called by the PhotoAlbumUploadForm.jsp file that uses the OrdHttpUploadFormData class to parse the POST data in a POST request containing the uploaded photograph. This JSP file does the following:

• Uses the PhotoAlbumBean JavaBean to access the contents of the photos table.

• Uses the OrdHttpJspResponseHandler class to facilitate the retrieval of image data from the photos table and its delivery to a browser or other HTTP client from a JSP file.

• Uses the OrdHttpUploadFormData class to facilitate the processing of POST requests by parsing the POST data containing the multipart/form-data encoding, and making the contents of regular form fields and uploaded files readily accessible to a JSP file.

• Sets the value of the strings description and location to null and the OrdHttpUploadFile object uploadPhoto to null.

• Uses a try/catch block to ensure the JDBC connection is released.

• Passes an OrdHttpUploadFile object to the PhotoAlbumBean class to store the photograph in the database.

• Calls the setServletRequest( ) method of the OrdHttpUploadFormData class to specify the ServletRequest object for the request.

• Tests to see if the request is encoded using the multipart/form-data encoding by calling the isUploadRequest( ) method of the OrdHttpUploadFormData class.

• Forwards the request to the PhotoAlbumUploadForm.jsp file if the call to the isUploadRequest( ) method returns a Boolean expression of not false.

• Parses the form data by calling the parseFormData( ) method of the OrdHttpUploadFormData class.

• Gets the form field values for description and location by calling the getParameter( ) method of the OrdHttpUploadFormData class, and also gets the name of the file to be uploaded by calling the getFileParameter( ) method of the same class.

• Tests to make sure the file name is not null from the getFileParameter( ) method call of the OrdHttpUploadFormData class, then calls the getOriginalFileName( ) method of the OrdHttpUploadFile class to ensure that the original file name as provided by the browser is not null, or that the content length of the file is empty by calling the getContentLength( ) method of the OrdHttpUploadFile class.

• Forwards the request to the PhotoAlbumUploadForm.jsp file if there is a valid image file.

• If the description is null or empty, uses the file name as the description by calling the getSimpleFileName( ) method of the OrdHttpUploadFile class.

• Inserts the new entry into the photos table by calling the setDescription( ), setLocation( ), and insertNewPhoto( ) methods in the PhotoAlbumBean.java JavaBean.

• Ends the try/catch block with a finally clause and releases the JDBC connection by calling the release( ) method and releases all resources held by the OrdHttpUploadFormData object by calling its release( ) method.

• Displays the updated photo album by displaying the title of the page in the HTML header and in its common page header, directing the browser to the main page by calling the PhotoAlbum.jsp file, then displays the header "Photo successfully uploaded into photo album" and the instruction, "Please click on link below or wait for the browser to refresh the page".

• Displays a link at the bottom of the main page Return to photo album that calls the PhotoAlbum.jsp file.

PhotoAlbumBean.java

This is a JavaBean used by the JSP files to access the database.

The first call to the JavaBean for a request causes it to allocate a JDBC connection from a connection pool. Subsequent calls by the same request reuse the same connection. After completing a request, each JSP file is responsible for calling the JavaBean to release the JDBC connection back to the pool. Each HTTP GET or POST request is assigned its own JDBC connection from the pool to ensure that multiple requests can be serviced concurrently.

These methods are defined:

• The selectTable( ) method selects all the rows in the photos table, orders them by location, and returns the results in a result set.

• The selectRowById( ) method selects a specific row from the photos table where the value of id in the where clause is a parameter marker and returns the results in a result set.

• The fetch( ) method fetches the next row from the result set.

• The insertNewPhoto( ) method does the following:

  • Uses the OrdHttpUploadFile class to upload the new photograph into the database.

  • Disables auto-commit by calling the setAutoCommit( ) method with an argument of false.

  • Executes a SQL SELECT photos_sequence.nextval statement to get the next value for the value of the id column for the new row to be inserted into the photos table.

  • Executes a SQL INSERT statement to insert a new row in the photos table.

  • Executes a SQL SELECT...FOR UPDATE statement to fetch the initialized full-size and thumbnail image objects from the photos table.

  • Loads the image by calling the loadImage( ) method in the OrdHttpUploadFile class to populate an OrdImage object named image with the full-size image, and sets the properties or attribute values of the image object based on the image contents.

  • Gets the image file format by calling the getContentFormat( ) method and if it is not null, and if the MIME type is BMP, then tries to process the image by calling the process( ) method and calling the getPreferredFormat( ) method to convert it to a MONOCHROME, GIF, or JPEG image format, based on the number of colors in the image.

  • Tries to copy the full-size image and process it to create the thumbnail image by calling the processCopy( ) method in the OrdImage class and populate the OrdImage object named thumb.

  • Executes a SQL UPDATE statement to update the full-size and thumbnail images in the database.

  • Commits the changes.

• A release( ) method to release the result set and statement objects, and places the JDBC connection back on the free list or stack.

• Get methods (getId( ), getDescription( ), getLocation( ), getImage( ), and getThumb( )) and the set methods (setId( ), setDescription( ), and setLocation( )) are used to get or set attributes for all attributes or columns.

• A getConnection( ) private function implements a simple JDBC connection pool.

• A freeConnection( ) private function releases the JDBC connection back to the pool after completing the request.

• A getPreferredFormat( ) private function returns the preferred image file format based on the number of bits of color in the BMP image; returns a MONOCHROME image if there are no bits of color, returns JPEG if there are more than 8 bits of color, or returns GIF if there are between 1 and 8 bits of color.