Oracle Multimedia enables you to develop either traditional client/server or two-tier applications, or multitier applications. Either method can then deploy Web applications to run on an application server tier, be tightly integrated with Oracle Database, and enable users to access the application from their desktop through a Web browser.
Using a complete development framework supported by class library interfaces, you can create production quality Oracle Multimedia applications for use in a production environment where users can interact with the application through either the standalone client interface or a Web browser. For Web applications, which are based on standards such as TCP/IP, HTTP, HTML, XML, and XHTML, this capability is facilitated by rapid developments in the underlying technology. As key software components become more tightly integrated, developers' tasks to design, create, and manage Web applications become faster, easier, and simpler to implement.
Using either the object type interface or the relational interface, Oracle Multimedia provides Internet support for Oracle Fusion Middleware and Oracle Database and authoring tools so you can quickly develop Web-based applications to upload to the database, retrieve from it, and manipulate multimedia data for delivery to Web browsers.
This chapter includes these sections:
See these chapters for more sample applications:
| Chapter | Sample Application |
|---|---|
| Chapter 3 | Describes the Oracle Multimedia Photo Album sample Web application, which is implemented using PL/SQL, Java servlets, and JavaServer Pages (JSP). This sample application demonstrates how to apply the steps described in Section 2.3 and Section 2.5 in a real Web application to upload and retrieve media data stored in a database. |
| Chapter 4 | Describes the Oracle Multimedia Code Wizard application, which lets you create PL/SQL stored procedures for the PL/SQL Gateway for uploading and retrieving media data stored in a database using Oracle Multimedia object types. |
| Chapter 5 | Describes the Oracle Multimedia Java API sample application, which is implemented using Java, JDBC, and Oracle Multimedia Java classes. This sample application demonstrates how to apply the steps described in Section 2.4 in a real Java application to upload and retrieve media data stored in a database. |
Oracle Multimedia supports application development by providing these tools and capabilities, which are briefly described in the following subsections:
Oracle Multimedia provides these Java class libraries, which enable access (insert, update, and retrieve) and manipulation (process) of multimedia data stored in the database:
Oracle Multimedia Java API class library
Java Advanced Imaging (JAI) classes in the Oracle Multimedia Java API class library
Oracle Multimedia Servlets and JSP Java API class library
Oracle Multimedia JSP Tag Library
And, Oracle Multimedia provides these specialized Java class libraries:
Oracle Multimedia DICOM Java API class library
Oracle Multimedia Mid-Tier Java API class library
Oracle Multimedia also integrates with the Oracle Multimedia/Oracle Application Development Framework Business Components (ADF Business Components) integration package, and with C++ and traditional 3GLs through modern class library interfaces. Class libraries provide access to multimedia data stored in the database in several ways.
Oracle Multimedia Java API Class Library
Using the Java database connectivity (JDBC) interface, the Oracle Multimedia Java API class library enables you to use Java proxy classes for Oracle Multimedia database objects to quickly develop Java applications for use on any tier (client, application server, or database) to manipulate and modify audio, image, and video data, or heterogeneous media data stored in a database. Oracle Multimedia Java API makes it possible for JDBC result sets to include both traditional relational data and Oracle Multimedia columns of object type media data, to easily select and operate on the result set, to access object attributes, and to invoke object methods. Section 1.10.1 for general information, and Section 2.4 for a description of how to use Java and JDBC to develop media-rich Java client applications using this Java class library.
|
See Also:
|
Java Advanced Imaging Classes
The Oracle Multimedia Java API class library includes several Java Advanced Imaging (JAI) classes. The Oracle Multimedia Java API describes three types of stream objects, which provide interfaces to BLOB and BFILE data, that can be used by JAI. These classes enable a JAI application to read and write image data stored in a database using Oracle Multimedia OrdImage objects, or in BLOBs or BFILEs. See Section 1.10.4 for general information.
|
See Also: Oracle Multimedia Java API Reference for reference information about the JAI classes in this Java class library |
Oracle Multimedia Servlets and JSP Java API Class Library
The Oracle Multimedia Servlets and JSP Java API class library supports Web technologies, enabling you to quickly develop Java applications using Java servlets and JavaServer Pages (JSP). See Section 1.10.3 for general information. Section 2.5 describes how to develop media-rich Java-based Web applications using this Java class library. Section 3.2 includes an example of a Java servlet application, and Section 3.3 includes an example of a JSP application.
|
See Also: Oracle Multimedia Servlets and JSP Java API Reference for reference information about this Java class library |
Oracle Multimedia JSP Tag Library
The Oracle Multimedia JSP Tag Library is an extension of the Oracle Multimedia Servlets and JSP Java API class library. This Java class library provides JSP tags that simplify retrieving and uploading media data from and to Oracle Database in multimedia JSP Web applications.
|
See Also: Oracle Multimedia JSP Tag Library Guide for complete information about this Java class library |
Oracle Multimedia DICOM Java API Class Library
Oracle Multimedia DICOM Java API is a specialized class library that enables users to write Java applications using the Oracle Multimedia object designed to store Digital Imaging and Communications in Medicine (DICOM) data. See Section 1.6.4 for general information.
|
See Also:
|
Oracle Multimedia Mid-Tier Java API Class Library
Oracle Multimedia Mid-Tier Java API is a specialized class library that enables users to write Java applications for extracting DICOM metadata outside of Oracle Database before the data is loaded into the database.
|
See Also:
|
Oracle Multimedia/Oracle Application Development Framework Business Components Integration Package
The Oracle Multimedia/Oracle Application Development Framework Business Components (ADF Business Components) integration package includes the Oracle Multimedia domain classes and a set of utilities for use with Oracle JDeveloper. Oracle JDeveloper is a Java-integrated development environment (IDE) tool that supports the application framework (ADF Business Components), enabling you to build multitier, component-based Internet applications. See Section 1.10.3 for general information.
|
See Also: Oracle Database 2 Day + Java Developer's Guide for more information about Oracle JDeveloper and ADF Business Components |
Oracle Multimedia uses the PL/SQL Gateway (mod_plsql) feature of the Oracle HTTP Server and the PL/SQL Web Toolkit features of Oracle Fusion Middleware and Oracle Database to listen for browser requests, to execute stored PL/SQL procedures in the database using Oracle Net and Oracle Call Interface (OCI), and to generate an HTML page containing data and code for the response returned to the Web browser for display. As a Web application developer, you can write PL/SQL servlets and PL/SQL server pages (PSP) that invoke PL/SQL procedures stored in the database through an Oracle Net connection and OCI. See Section 2.3 for a description of how to use PL/SQL Gateway and PL/SQL Web Toolkit to develop PL/SQL Web applications. See Section 3.1 for an example of an application that uses the PL/SQL Gateway and PL/SQL Web Toolkit for Oracle Fusion Middleware and Oracle Database.
|
See Also: Oracle Database Advanced Application Developer's Guide for more information about developing PL/SQL Web applications |
Oracle Multimedia integrates Oracle development tools with tightly integrated components to enable you to quickly and easily develop applications that provide access to (insert, update, and retrieve) and manipulation (process) of multimedia data stored in the database for delivery to Web browsers and client applications. These development tools include:
Oracle Portal
Oracle JDeveloper
Oracle Designer
Oracle Content Management SDK
Oracle Portal
Oracle Portal is a simple browser-based environment for building and deploying enterprise information portlets (EIPs). An enterprise portal provides access to portlets, which are summarized versions of applications and Web content situated in defined regions of the Web page. Oracle Portal portlets execute PL/SQL stored procedures residing in the database, which in turn generate an HTTP response in the form of a generated HTML page. Oracle Portal contains two predefined components: Forms and Reports, which both support rich media content being uploaded or downloaded between the database and the portal framework form or report. See Section 1.10.3 for general information.
|
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Portal in the Oracle Fusion Middleware Online Documentation Library for more information about this tool |
Oracle JDeveloper
Oracle JDeveloper is an IDE tool, which is written 100% in Java, that supports the application framework (Oracle Application Development Framework Business Components). An Oracle Multimedia/ADF Business Components integration package includes the Oracle Multimedia domain classes and a set of utilities. The domain classes are wrappers of Oracle Multimedia Java API and inherit all the underlying multimedia retrieval, upload, and manipulation methods. The domain classes support the ADF Business Components APIs and provide built-in integrated multimedia capabilities, while the utility classes support the retrieval, rendering, and uploading of multimedia content. See Section 1.10.3 for general information.
|
See Also: Oracle Fusion Middleware Extension SDK Reference for Oracle JDeveloper in the Oracle Fusion Middleware Online Documentation Library for more information about this tool |
Oracle Designer
Oracle Designer is a tool used to manage software configuration management for controlling the evolution of an application from identification of components, through initiation, evaluation, authorization, development, and implementation. Oracle Designer can generate C++ classes that enable applications running on the client, on Oracle Fusion Middleware, or on Oracle Database to call Oracle Multimedia methods.
Oracle Content Management SDK
Oracle Content Management SDK enables you to create custom file system applications using XML and Java that use the features and capabilities of the database and a variety of Web-based interfaces, such as Java servlets and JSP pages, or executing SQL or calling stored PL/SQL procedures for execution in the transaction context of the database.
Oracle Multimedia integrates with third-party streaming media servers to enable dynamic and direct delivery of multimedia data stored in the database to a media player client. These third-party streaming servers include:
Oracle Multimedia Plug-in for RealNetworks Server
Oracle Multimedia Plug-in for Microsoft Windows Media Services
You can download these plug-ins from the Oracle Multimedia Software section of the Oracle Technology Network Web site at
http://www.oracle.com/technology/products/multimedia/
Oracle Multimedia Plug-in for RealNetworks Server
Oracle Multimedia Plug-in for RealNetworks Server is a data source plug-in that enables a RealNetworks server to stream media data directly from Oracle Database to a media player client. The plug-in is installed with RealNetworks Server, and configured and managed using the administration tool of the streaming server. See Oracle Multimedia Plug-in for RealNetworks Streaming Servers Readme.
|
See Also:
|
Oracle Multimedia Plug-in for Microsoft Windows Media Services
Oracle Multimedia Plug-in for Microsoft Windows Media Services enables Microsoft Windows Media servers to stream multimedia content to a client directly from Oracle Database. This plug-in is installed on Windows 2003 Server, and configured with Windows Media Services. See Oracle Multimedia Plug-in for Microsoft Windows Media Services Readme.
PL/SQL is a completely portable, high-performance transaction processing language that combines the data manipulation power of SQL with the data processing power of procedural languages.
This section briefly describes how to manipulate Oracle Multimedia database objects with the PL/SQL Application Programming Interface (API). The following Oracle Multimedia object types are available for storing media in the database:
ORDAudio
ORDDoc
ORDImage
ORDVideo
The examples in this section use the sample schemas, which may be installed when you install Oracle.
The following subsections describe how to use various components of the PL/SQL development environment:
|
See Also:
|
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;
|
Caution: Performing any of these prohibited actions could cause internal errors and security violations in the database management system.These users, under which Oracle-supplied Oracle Multimedia data types are installed, are created during database installation, and might change in future releases:
Do not connect to or modify any of these users or their contents (which are supplied by Oracle Multimedia and reserved by Oracle), with this exception:
|
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.
Example 2-1 Image Query (Height, Width, and MimeType Attributes)
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;
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;
/
Media upload means importing media data from the file system into the database tablespaces. The following series of steps is typical:
Insert a new row into the table, creating new objects by using the init method of the Oracle Multimedia object type.
Call the import method of the Oracle Multimedia object to bring the data from the file system into the database.
Call the setProperties method of the Oracle Multimedia object to determine and populate the attributes of the object.
Update the table so that the Oracle Multimedia object in the table contains the attribute values e xtracted 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;
/
Possible errors that can occur during run time should always be handled in your application. This practice enables the program to continue its operation even when it encounters a run-time error. This practice also enables users to know what went wrong during program operation. Proper error handling practices ensure that, whenever possible, you are always able to recover from an error while running an application. In addition, proper error handling provides you with the information you need so you always know what went wrong.
This section demonstrates proper error handling practices using code examples. These examples show how to handle some common Oracle Multimedia errors and other types of errors in PL/SQL programs. These examples are extracted from the PL/SQL sample applications that are described in Chapter 3 and Chapter 4. (See Oracle Multimedia Reference for more examples.)
When handling exceptions, PL/SQL uses exception blocks. For example, in PL/SQL, the exception can appear as:
BEGIN
<some program logic>
EXCEPTION
WHEN OTHERS THEN
<some exception logic>
END;
When you design, code, and debug your application, you are aware of the places in your program where processing might stop due to a failure to anticipate an error. Those are the places in your program where you must add exception handling blocks to handle the potential errors.
The examples in this section describe exception handling in the Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application.
The following subsections provide additional details and examples of exception handling in PL/SQL:
Handling the Setting of Properties for Unknown Image Formats in PL/SQL
Handling Image Processing for Unknown Image Formats in PL/SQL
|
See Also: Oracle Database PL/SQL Language Reference for more information about handling PL/SQL exceptions |
If your program tries to set the properties of an uploaded image (it reads the image data to get the values of the object attributes so it can store them in the appropriate attribute fields) and the image format is not recognized, then the setProperties( ) method fails. To catch this exception and work around this potential problem, the application uses the following exception block:
BEGIN
new_image.setProperties();
EXCEPTION
WHEN OTHERS THEN
new_image.contentLength := upload_size;
new_image.mimeType := upload_mime_type;
END;
In this example, this exception handler sets the MIME type and length of the image based on the values from the upload table described at the beginning of the insert_new_photo procedure. The browser sets a MIME type header when the file is uploaded. The application reads this header to set the ORDImage field.
If your program tries to process an image in cases when the image format is unknown, the processCopy( ) method always fails. To work around this potential problem, the application uses the following exception block:
BEGIN
new_image.processCopy( 'maxScale=50,50', new_thumb);
EXCEPTION
WHEN OTHERS THEN
new_thumb.deleteContent();
new_thumb.contentLength := 0;
END;
In this example from the Oracle Multimedia PL/SQL Web Toolkit Photo Album application, when the image format is unknown and a thumbnail image cannot be created, this exception handler deletes the content of the thumbnail image and sets its length to zero.
SQL developers who are familiar with the database can develop Web applications that exclusively use Oracle Fusion Middleware and Oracle Database using the PL/SQL development environment. With the PL/SQL development environment, developers can come quickly up to speed to develop PL/SQL-based Web applications.
Developing Web applications using PL/SQL consists of developing one or more PL/SQL packages consisting of sets of stored procedures that interact with Web browsers through HTTP. Stored procedures can be executed in several ways:
From a hypertext link that calls a stored procedure when it is selected
By clicking Submit on an HTML form to denote the completion of a task such as filling out a form supplied on the HTML page
By passing parameters to a stored procedure based on user choices from a list
Information in the stored procedure, such as tagged HTML text, is displayed in the Web browser as a Web page. These dynamic Web pages are generated by the database and are based on the database contents and the input parameters passed in to the stored procedure. Using PL/SQL stored procedures is especially efficient and powerful for generating dynamic Web page content.
There are two ways of generating HTML output from PL/SQL:
Using function calls to generate each HTML tag for output using the PL/SQL Web Toolkit package that is part of Oracle Fusion Middleware and Oracle Database and whose owa packages are loaded into a common schema so that all users can access it
Embedding PL/SQL code in Web pages (PL/SQL server pages)
Use Oracle Multimedia when media data such as images, audio, video, or combinations of all three are to be uploaded into and retrieved from database tables using the Oracle Multimedia object types and their respective sets of methods.
Media upload procedures first perform a SQL INSERT operation to insert a row of data in the media table, which also initializes instances of the respective Oracle Multimedia object columns with an empty BLOB. Next, a SQL SELECT FOR UPDATE operation selects the object columns for update. Finally, a SQL UPDATE operation updates the media objects in their respective columns. Oracle Multimedia methods are called to perform these tasks:
Initialize the object columns with an empty BLOB.
Set attributes to indicate media data is stored internally in a BLOB.
Get values of the object attributes and store them in the object attributes.
When exceptions occur, determine the length of the BLOB content and its MIME type.
Media retrieval operations involve these tasks:
Retrieving the object from the database into a local object
Checking the cache validity of the object based on its updated time versus that of the HTTP header time
Determining where the media object is located: in the database, in a BFILE, or at a URL location; then, getting the media, and downloading it for display on an HTML page
Oracle Multimedia methods are called to get the time that the media object was last updated, to determine if the media is stored locally in the database, in a BFILE, or at a URL location, to get the MIME type of the media object, and finally to retrieve the media data.
The following subsection describes how to use some Web components of the PL/SQL development environment:
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:
A client Web browser sends a PL/SQL server page or servlet request to Oracle HTTP Server.
Oracle HTTP Server routes the request to the PL/SQL Gateway (mod_plsql).
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.
The PL/SQL Gateway prepares the call parameters and invokes the PL/SQL package and the PL/SQL stored procedure in the application.
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.
The PL/SQL Gateway sends the response to Oracle HTTP Server.
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
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.
Example 2-4 URL Format to Invoke mod_plsql in a Web Browser
protocol://hostname[:port number]/DAD-name/[[!][schema name.] [package name.]procedure_name[?query_string]]
|
See Also: Oracle Fusion Middleware User's Guide for mod_plsql in the Oracle Fusion Middleware Online Documentation Library for a detailed description of each parameter and the available options |
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.
Example 2-5 URL Format to Invoke mod_plsql for the Photo Album Application
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.
|
See Also: Oracle Database Advanced Application Developer's Guide for more information about PL/SQL Web applications |
Developers who are familiar with Java and Java database connectivity (JDBC) can write media-rich Java applications using Oracle Multimedia Java API. The classes in Oracle Multimedia Java API are the Java proxy classes for Oracle Multimedia database objects. These Java classes provide access to Oracle Multimedia database objects through JDBC in a Java application.
The Java classes in Oracle Multimedia Java API are included in the oracle.ord.im.* package. These Java classes are named similarly to the Oracle Multimedia database objects, and in compliance with the standard Java naming convention:
OrdAudio
OrdDoc
OrdImage
OrdVideo
Developers who write medical imaging applications can use Oracle Multimedia DICOM Java API and Oracle Multimedia Mid-Tier Java API. In Oracle Multimedia DICOM Java API, the OrdDicom class provides access to Oracle Multimedia DICOM database objects in a Java application. The classes in Oracle Multimedia Mid-Tier Java API enable developers to write Java applications for extracting DICOM metadata outside of Oracle Database.
The examples in this section use the sample schemas, which may be installed when you install Oracle.
The following subsections describe how to use various components of the Java development environment with JDBC:
|
See Also:
|
Before you can begin using any of the Java APIs provided by Oracle Multimedia, you must set up your environment to compile and run Java programs.
Follow these steps:
Specify the environment variable CLASSPATH, and ensure that this variable includes the appropriate Oracle Java archive (JAR) files for the Oracle Multimedia features and any other features that you intend to use.
For each Oracle JAR file, Table 2-1 lists the name of the file and its contents, the Oracle Multimedia and other features that require it, and details about the JDK version, the platform, and the path name under the <ORACLE_HOME> directory where you can obtain it.
Table 2-1 Java Archive Files for Oracle Multimedia
| Oracle JAR File and Contents | Required By | JDK Version, Platform, and Location |
|---|---|---|
|
Name: Description: Oracle Multimedia Java proxy classes |
All Oracle Multimedia features |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle JDBC library |
All Oracle Multimedia features |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle XDB Java classes library |
DICOM feature Oracle Multimedia metadata extraction |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle XML Parser library |
DICOM feature Oracle Multimedia metadata extraction Mid-Tier Java API feature |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle Multimedia Mid-Tier Java classes |
Mid-Tier Java API feature |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle Multimedia DICOM Java library |
Mid-Tier Java API feature |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle Multimedia DICOM Java proxy classes |
DICOM feature |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle Multimedia Servlets and JSP Java HTTP classes |
Java servlets and JavaServer Pages (JSP) applications |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: Oracle Multimedia JSP Tag Library (Optional) |
JavaServer Pages (JSP) applications |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
|
Name: Description: NLS Character Set Conversion library (Optional) |
NLS character set conversion requiredFoot 1 |
JDK 5 or later, on Linux and UNIX:
JDK 5 or later, on Windows:
|
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:
Depending on your platform, store the JDBC OCI shared library at one of these locations under the <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. |
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;
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:
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);
Execute the query and obtain the result set:
OracleResultSet rset = (OracleResultSet)pstmt.executeQuery();
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 ( |
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();
Follow these steps to upload media data into Oracle Multimedia database objects in a Java application:
Enter this statement to enable the JDBC connection object to set the autocommit flag to false:
conn.setAutoCommit(false);
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 withproduct_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();
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);
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. |
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();
Commit the transaction:
conn.commit();
Possible errors that can occur during run time should always be handled in your application. This practice enables the program to continue its operation even when it encounters a run-time error. This practice also enables users to know what went wrong during program operation. Proper error handling practices ensure that, whenever possible, you are always able to recover from an error while running an application. In addition, proper error handling provides you with the information you need so you always know what went wrong.
This section demonstrates proper error handling practices using code examples. These examples show how to handle some common Oracle Multimedia errors and other types of errors in Java programs. These examples are extracted from the Java sample applications that are described in Chapter 3 and Chapter 5. (See Oracle Multimedia Reference for more examples.)
When handling exceptions, Java uses the try/catch block. For example, in Java, the exception can appear as:
try {
//<some program logic>)
}
catch (exceptionName a) {
//Exception logic
}
finally {
//Execute logic if try block is executed even if an exception is caught
}
When you design, code, and debug your application, you are aware of the places in your program where processing might stop due to a failure to anticipate an error. Those are the places in your program where you must add exception handling blocks to handle the potential errors.
The examples in this section describe exception handling using the try/catch block. These examples are included in the Oracle Multimedia Java API sample application, the Oracle Multimedia Java Servlet Photo Album application, and the Oracle Multimedia JavaServer Pages Photo Album application.
The following subsections provide additional details and examples of exception handling in Java:
|
See Also:
|
The IMUtil class of the Oracle Multimedia Java API sample application contains utility methods for common image functions. One of these methods is the setProperties( ) method. The static method takes an OrdImage object as an input parameter and calls the setProperties( ) method on the object.
static boolean setProperties(OrdImage img)
{
try
{
img.setProperties();
return true;
}
catch (SQLException e)
{
return false;
}
}
If an exception is thrown, the setProperties( ) method returns false to indicate failure; otherwise it returns true. See Chapter 5 for a full description of the Oracle Multimedia Java API sample application, and for more information about using the setProperties( ) method in a Java application.
In the insertNewPhoto( ) method in both the PhotoAlbumServlet class of the Oracle Multimedia Java Servlet Photo Album application and in the PhotoAlbumBean class of the Oracle Multimedia JavaServer Pages Photo Album application, a new photograph is inserted into the photo album, creating a thumbnail image at the same time. If the application tries to process an image in cases when the image format is unknown, then when the application calls the processCopy( ) method, the application always fails. To work around this potential problem, the application uses the following try block and catch block to catch any SQL exceptions:
try
{
image.processCopy( "maxScale=50,50", thumb );
}
catch ( SQLException e )
{
thumb.deleteContent();
thumb.setContentLength( 0 );
}
In this example, when the image format is unknown and a thumbnail image cannot be created, the application catches the SQL exception and calls the deleteContent( ) method to delete the content of the thumbnail image, and then calls the setContentLength( ) method to set its length to zero.
On the Java platform, a Web application is a dynamic extension of a Web server. A Java-based Web application is composed of Java servlets, JSP pages, or both. Java servlets are Java classes that dynamically process HTTP requests and construct HTTP responses. JSP pages are text-based documents that execute as servlets, but enable a more natural approach to creating static content.
Oracle Multimedia Servlets and JSP Java API is based on Oracle Multimedia Java API. The classes in Oracle Multimedia Servlets and JSP Java API facilitate the retrieval and uploading of media data from and to Oracle Database in a Java-based Web application.
The Java classes in Oracle Multimedia Servlets and JSP Java API are included in the oracle.ord.im.* package. The classes are as follows:
OrdHttpResponseHandler
OrdHttpJspResponseHandler
OrdHttpUploadFormData
OrdHttpUploadFile
OrdMultipartFilter
OrdMultipartWrapper
The OrdHttpResponseHandler class facilitates the retrieval of the media data from Oracle Database and its delivery to an HTTP client from a Java servlet. The OrdHttpJspResponseHandler class provides the same features for JSP pages. The OrdHttpUploadFormData, OrdHttpUploadFile, OrdMultipartFilter, and OrdMultipartWrapper classes facilitate the uploading of media data from a Web client to Oracle Database.
Before you can begin using Oracle Multimedia Servlets and JSP Java API, you must set up your environment with the appropriate Java libraries, as described in Step 1, Section 2.4.1.
The following subsections describe how to use various components of the Java development environment for Web applications:
|
See Also: Oracle Multimedia Servlets and JSP Java API Reference for details about the available classes and methods in this Java API |
In general, displaying a Web page that contains images in a Web browser requires two HTTP round trips.
In the first trip, the Web browser makes an HTTP request to the URL of the Web page that contains the images. The Web server responds with the Web page text content and the URLs for the media content. The URL is the src attribute of the <img> tag in the Web page.
In the second trip, the Web browser makes another HTTP request to the URL in the <img> tag to get the image binary data, and then displays the image in the browser.
In a Java-based Web application, sending media data from the database to an HTTP client (Web browser) requires the proper media URL (generated in the first HTTP response); and the proper media delivery component (a servlet or JSP for the second HTTP response).
The following subsections provide additional details and examples of this process:
When media data is stored as static files on the Web server, the media URL is the relative or absolute path to the media files on the file system. When media data is stored in a database, the media URL is generally composed of a media delivery component (a servlet or JSP) and the parameters for the media delivery component. The media delivery component is the target for the second HTTP request to retrieve the media data. The parameters for the media delivery component are used by the media delivery component to query and locate the media data in the database. For example:
<img src="OrdGetMedia.jsp?id=1"/>
where OrdGetMedia.jsp in the media URL "OrdGetMedia.jsp?id=1" is the media delivery component, and id=1 is the parameter to the media delivery component.
Because media data is stored in the database as Oracle Multimedia objects, the media delivery component must dynamically retrieve the media data as Java objects (see Section 2.4.2), based on certain query conditions. Then, you can use either the OrdHttpResponseHandler or the OrdHttpJspResponsehandler class in Oracle Multimedia Servlets and JSP Java API to deliver the data to the HTTP client (Web browser).
The following example demonstrates the use of a Java servlet as the media delivery component, and highlights in bold the SQL statements and significant areas in the code where this operation takes place.
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); . . . }
The following example demonstrates the use of a JSP page as the media delivery component, and highlights in bold the SQL statements and significant areas in the code where this operation takes place.
<%@ 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; %>
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:
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.
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>
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.
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.
audio data
Media data produced by an audio recorder, an audio source, or by program algorithms. Audio recording devices take analog or continuous signals and convert them into digital values with specific audio characteristics.
content metadata
Data that describes the content of image media, such as the name of the photographer, and the date and time when a photograph was taken.
DICOM content
Standalone DICOM Information Objects that are encoded according to the data structure and encoding definitions of PS 3.10-2007 of the DICOM standard (commonly referred to as DICOM Part 10 files). For more information about DICOM Information Objects, see the DICOM standard, which is available worldwide from the NEMA Web site at
heterogeneous media data
Assorted media data, such as audio data, image data, video data, and other types of media data. The data can have a variety of formats, depending upon the application that generated it.
image data
Media data produced by a document or photograph scanner, a video source, other specialized image capture devices, or by program algorithms. Image capture devices take analog or continuous signals and convert them into digital values on a two-dimensional grid of data points known as pixels. Devices involved in the capture and display of images are under application control.
image interchange format
A well-defined organization and use of image attributes, data, and often compression schemes that enables different applications to create, exchange, and use images. Interchange formats are often stored as disk files.
image metadata format
Standard protocols and techniques used to store image metadata within an image file. Formats include: EXIF, IPTC-IIM, and XMP.
JSP
JavaServer Pages, Java text-based documents that execute as Java servlets, but which permit a more natural approach to creating static content than using servlets.
lossless compression schemes
Compression schemes that squeeze an image so that when it is decompressed, the resulting image is bit-for-bit identical with the original.
lossy compression schemes
Compression schemes that do not result in an identical image when decompressed, but rather, one in which the changes may be imperceptible to the human eye. Lossy schemes generally provide higher compression than lossless compression schemes.
media data
Data from audio, image, DICOM format medical images and other objects, video, or other heterogeneous media.
Oracle interMedia
In Oracle Database 11g Release 1 (11.1), the name Oracle interMedia was changed to Oracle Multimedia.
ORDDicom
Object relational type for characteristics of DICOM content produced by medical devices. See Oracle Multimedia DICOM Developer's Guide for more information about this object type.
ORDSource
Object relational type that stores data source information for audio, heterogeneous, image, and video data characteristics.
portlets
Summarized versions of applications and Web content situated in defined regions of a Web page that are accessible through enterprise portals.
technical metadata
Data that describes image media in a technical sense, such as the height and width of an image, in pixels, or the type of compression used to store the image.
video data
Media data produced by a video recorder, a video camera, digitized animation video, other specialized video recording devices, or by program algorithms. Some video recording devices take analog or continuous signals and convert them into digital values with specific video characteristics.
User's Guide
11g Release 2 (11.2)
E10777-03
August 2010
Oracle Multimedia enables Oracle Database to store, manage, and retrieve images, audio, video, DICOM format medical images and other objects, or other heterogeneous media data in an integrated fashion with other enterprise information. Oracle Multimedia extends Oracle Database reliability, availability, and data management to multimedia content in traditional, Internet, electronic commerce, medical, financial, and other media-rich applications.
Oracle Multimedia User's Guide, 11g Release 2 (11.2)
E10777-03
Copyright © 1999, 2010, Oracle and/or its affiliates. All rights reserved.
Primary Author: Sue Pelski
Contributors: Robert Abbott, Melliyal Annamalai, Fengting Chen, Dongbai Guo, Dong Lin, Susan Mavris, Valarie Moore, David Noblet, James Steiner, Yingmei Sun, Manjari Yalavarthy, Jie Zhang
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Image files can contain information about the content of the images, the image rasters, and image metadata. In general, data about data is referred to as metadata. In this case, metadata refers to additional information about the actual images, which is stored in the image files along with the images.
This chapter includes these sections:
Several types of metadata can be stored in an image file, and each type can serve a different purpose. One type, technical metadata, is used to describe an image in a technical sense. For example, technical metadata can include attributes about an image, such as its height and width, in pixels, or the type of compression used to store it. Another type, content metadata, can further describe the content of an image, the name of the photographer, and the date and time when a photograph was taken.
Metadata is stored in image files using a variety of mechanisms. Digital cameras and scanners automatically insert metadata into the images they create. Digital photograph processing applications like Adobe Photoshop enable users to add or edit metadata to be stored with the image. Annotating digital images with additional metadata is a common practice in photographic and news gathering applications, for image archiving usages, and at the consumer level.
Storing metadata with image data in the same containing file provides encapsulation. With encapsulation, both types of data can be shared and exchanged reliably as one unit. Metadata that is stored in the image file format is referred to as embedded metadata.
For a large number of image file formats, Oracle Multimedia can extract and manage a limited set of metadata attributes. These attributes include: height, width, contentLength, fileFormat, contentFormat, compressionFormat, and mimeType. For a limited number of image file formats, Oracle Multimedia can extract a rich set of metadata attributes. This metadata is represented in schema-based XML documents. These XML documents can be stored in a database, indexed, searched, updated, and made available to applications using the standard mechanisms of Oracle Database.
Oracle Multimedia can also write or embed metadata supplied by users into a limited number of image file formats. The application provides the metadata as a schema-based XML document. Oracle Multimedia processes the XML document and writes the metadata into the image file.
Oracle Multimedia supports metadata extraction and metadata embedding for the GIF, TIFF, and JPEG file formats.
|
See Also: Oracle Multimedia Reference for information about the image file formats supported by Oracle Multimedia |
The term image metadata format refers to the standard protocols and techniques used to store image metadata within an image file. The following subsections describe the embedded image metadata formats supported by Oracle Multimedia:
The Exchangeable Image File Format (EXIF) is the standard for image file storage for digital still cameras. It was developed by the Japan Electronic Industry Development Association (JEIDA) as a standard way of storing images created by digital cameras and metadata about the images. EXIF image metadata can be stored in TIFF and JPEG format images. Oracle Multimedia supports the extraction of EXIF metadata from TIFF and JPEG file formats.
The International Press Telecommunications Council-Information Interchange Model (IPTC-IIM) Version 4 is a standard developed jointly by the International Press Telecommunications Council and the Newspaper Association of America. This metadata standard is designed to capture information that is important to the activities of news gathering, reporting, and publishing. These information records are commonly referred to as IPTC tags.
The use of embedded IPTC tags in image file formats became widespread with the use of the Adobe Photoshop tool for image editing. IPTC metadata can be stored in TIFF and JPEG format images. Oracle Multimedia supports the extraction of IPTC metadata from TIFF and JPEG file formats.
The Extensible Metadata Platform (XMP) is a standard metadata format, developed by Adobe, for the creation, processing, and interchange of metadata in a variety of applications. XMP uses Resource Description Framework (RDF) technology for data modeling. XMP also defines how the data model is serialized (converted to a byte stream), and embedded within an image file. Oracle Multimedia supports the extraction of XMP metadata from GIF, TIFF, and JPEG file formats. Oracle Multimedia also supports writing XMP data packets into GIF, TIFF, and JPEG file formats.
|
See Also:
|
After metadata has been extracted from the binary image file, the next step is to represent the metadata in a form that can be easily stored, indexed, queried, updated, and presented. Oracle Multimedia returns image metadata in XML documents. These documents are based on XML schemas that Oracle Multimedia registers with the database. Each type of image metadata has a separate XML schema. These XML schemas are used by the metadata methods of the ORDImage object type.
The XML documents can be stored in XMLType columns within the database. These documents are easily searched and processed using the wide range of standards-based XML technologies provided by Oracle XML DB.
|
See Also:
|
The following examples of metadata extraction and embedding use the photos table, which is defined by the Photo Album sample application. The implementation of the Photo Album sample application is defined in the PL/SQL package PHOTO_ALBUM. See Section 3.1 for a complete description of the Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application.
The photos table stores two instances of an image: the full-size photograph and a thumbnail image. This table can also store up to four different image metadata documents. These documents are stored in the columns named metaORDImage, metaEXIF, metaIPTC, and metaXMP, and represent image metadata from the ORDImage, EXIF, IPTC, and XMP metadata formats, respectively. The metadata columns are of type XMLType, and they are bound to the corresponding metadata XML schemas that Oracle Multimedia provides.
The following subsections describe some operations you can perform with image metadata:
Before you can extract or embed metadata, you must create the table and columns where the metadata is to be stored. The following PL/SQL code segment creates the photos table with four XMLTYPE columns (metaORDImage, metaEXIF, metaIPTC, and metaXMP) to store each type of image metadata, and two ORDIMAGE columns (image and thumb) for the original image and the thumbnail image, respectively. Each metadata column is bound to its corresponding metadata schema. For example, the metaEXIF column is bound to the XML schema stored at http://xmlns.oracle.com/ord/meta/exif, and is defined as the XML element exifMetadata.
The code statements where the image metadata columns are defined and bound to XML schemas are highlighted in bold.
--
-- Create the PHOTOS table
--
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 images 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
XMLSCHEMA "http://xmlns.oracle.com/ord/meta/ordimage"
ELEMENT "ordImageAttributes"
XMLType COLUMN metaEXIF
XMLSCHEMA "http://xmlns.oracle.com/ord/meta/exif"
ELEMENT "exifMetadata"
XMLType COLUMN metaIPTC
XMLSCHEMA "http://xmlns.oracle.com/ord/meta/iptc"
ELEMENT "iptcMetadata"
XMLType COLUMN metaXMP
XMLSCHEMA "http://xmlns.oracle.com/ord/meta/xmp"
ELEMENT "xmpMetadata";
The following PL/SQL procedure extracts metadata from an image and stores it in the specified columns in the photos table you created. This procedure demonstrates the getMetadata( ) method, which returns an array of XML documents. The root element of each document is examined to determine the metadata type. The UPDATE statement stores the documents in the corresponding columns in the photos table.
The code statement where the getMetadata( ) method is called is highlighted in bold.
--
-- fetch the metadata and sort the results
--
PROCEDURE extractMetadata(inID IN INTEGER)
IS
img ORDSYS.ORDIMAGE;
metav XMLSequenceType;
meta_root VARCHAR2(40);
xmlORD XMLType;
xmlXMP XMLType;
xmlEXIF XMLType;
xmlIPTC XMLType;
BEGIN
-- select the image
SELECT image
INTO img
FROM PHOTOS
WHERE id = inID;
-- extract all the metadata
metav := img.getMetadata( 'ALL' );
-- process the result array to discover what types of metadata were
returned
FOR i IN 1..metav.count() LOOP
meta_root := metav(i).getRootElement();
CASE meta_root
WHEN 'ordImageAttributes' THEN xmlORD := metav(i);
WHEN 'xmpMetadata' THEN xmlXMP := metav(i);
WHEN 'iptcMetadata' THEN xmlIPTC := metav(i);
WHEN 'exifMetadata' THEN xmlEXIF := metav(i);
ELSE NULL;
END CASE;
END LOOP;
-- Update metadata columns
--
UPDATE photos
SET metaORDImage = xmlORD,
metaEXIF = xmlEXIF,
metaIPTC = xmlIPTC,
metaXMP = xmlXMP
WHERE id = inID;
END extractMetadata;
The following PL/SQL procedure demonstrates the putMetadata( ) method. This procedure accepts six arguments. The entry_id argument identifies the image in the photos table to be updated. The remaining arguments (title, creator, date, description, and copyright) are strings to be formatted into an XMP packet and embedded within the target image.
This example creates an XML document instance based on the Oracle Multimedia XML schema for XMP metadata. (This schema is preregistered with Oracle XML DB. See Oracle XML DB Developer's Guide for more information.) The schema for XMP metadata defines a single, global element <xmpMetadata>. The <xmpMetadata> element contains a single, well-formed RDF document. The RDF document contains a single <RDF> element, which is derived from the rdf namespace. This RDF document is constructed using elements defined by the Dublin Core Schema.
The call to the putMetadata( ) method embeds the metadata document into the image file. The UPDATE statement stores the new image and the new metadata back in the photos table.
The code statement where the putMetadata( ) method is called is highlighted in bold.
--
-- write the metadata to the image
--
PROCEDURE write_metadata( entry_id IN VARCHAR2,
title IN VARCHAR2,
creator IN VARCHAR2,
date IN VARCHAR2,
description IN VARCHAR2,
copyright IN VARCHAR2 )
IS
img ORDSYS.ORDImage;
xmp XMLType;
buf VARCHAR2(5000);
BEGIN
-- select the image
SELECT image
INTO img
FROM PHOTOS
WHERE id = entry_id FOR UPDATE;
-- Create the XMP packet it must be schema valid
-- to "http://xmlns.oracle.com/ord/meta/xmp"
-- and contain an <RDF> element. This example uses
-- the Dublin Core schema.
/* An example XML instance document
<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp"
xsi:schemaLocation="http://xmlns.oracle.com/ord/meta/xmp
http://xmlns.oracle.com/ord/meta/xmp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title>A Winter Day</dc:title>
<dc:creator>Frosty S. Man</dc:creator>
<dc:date>21-Dec-2004</dc:date>
<dc:description>a sleigh ride</dc:description>
<dc:copyright>North Pole Inc.</dc:copyright>
</rdf:Description>
</rdf:RDF>
</xmpMetadata>
*/
buf := '<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp"
xsi:schemaLocation="http://xmlns.oracle.com/ord/meta/xmp
http://xmlns.oracle.com/ord/meta/xmp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description about="" xmlns:dc="http://purl.org/dc/elements/1.1/">';
IF title IS NOT NULL THEN
buf := buf || '<dc:title>' || htf.escape_sc(title) || '</dc:title>';
END IF;
IF creator IS NOT NULL THEN
buf := buf || '<dc:creator>' || htf.escape_sc(creator)
|| '</dc:creator>';
END IF;
IF date IS NOT NULL THEN
buf := buf || '<dc:date>' || htf.escape_sc(date)
|| '</dc:date>';
END IF;
IF description IS NOT NULL THEN
buf := buf || '<dc:description>' || htf.escape_sc(description)
|| '</dc:description>';
END IF;
IF copyright IS NOT NULL THEN
buf := buf || '<dc:copyright>' || htf.escape_sc(copyright)
|| '</dc:copyright>';
END IF;
buf := buf || '
</rdf:Description>
</rdf:RDF>
</xmpMetadata>';
-- create the XML document
xmp := XMLType.createXML(buf, 'http://xmlns.oracle.com/ord/meta/xmp');
-- write the metadata
img.putMetadata( xmp, 'XMP' );
-- update the image
UPDATE photos
SET image = img,
metaXMP = xmp
WHERE id = entry_id;
END write_Metadata;
This chapter describes the Oracle Multimedia Java API sample application. The Oracle Multimedia Java API sample application is a Java application that uses Oracle Multimedia Java classes to demonstrate how to upload, download, update, and delete Oracle Multimedia objects, including image, audio, and video. It also demonstrates how to extract attributes from media content, generate thumbnail images, and display media.
This chapter assumes the following:
You are familiar with developing Java applications using Oracle Multimedia Java classes.
You have installed and configured the Oracle Multimedia Java API sample application.
After installing the Oracle Database Examples media, the sample application files and README.txt file are located at:
<ORACLE_HOME>/ord/im/demo/java (on Linux and UNIX)
<ORACLE_HOME>\ord\im\demo\java (on Windows)
This chapter describes how to run the Oracle Multimedia Java API sample application. See Section 2.4.1 and the README.txt file for additional requirements and instructions on installing, configuring, compiling, and running this sample application.
This chapter includes these sections:
More Sample Applications
See these chapters for more sample applications:
Chapter 3 describes these Photo Album sample Web applications:
Oracle Multimedia PL/SQL Web Toolkit Photo Album application (Section 3.1)
Oracle Multimedia Java Servlet Photo Album application (Section 3.2)
Oracle Multimedia JSP Photo Album application (Section 3.3)
These Web applications use PL/SQL scripts, Java servlet files, and JSP files to demonstrate various ways to upload and retrieve media using Oracle Multimedia object types.
Chapter 4 describes the Oracle Multimedia Code Wizard sample application, a media upload and retrieval Web application for the PL/SQL Gateway.
To use the Oracle Multimedia Java API sample application to retrieve, save, play, and delete multimedia data from the Oracle Database sample schemas, you must perform these steps:
Install Oracle Database with Oracle Multimedia.
Grant the appropriate permissions to the user who is connecting to the database.
Compile and start the sample application.
Log in and run the sample application.
The following section describes the Java class files, and shows code examples that demonstrate how to use Oracle Multimedia object types and methods and other Oracle objects in a Java application.
The Oracle Multimedia Java API sample application lets you retrieve multimedia data from the Oracle Database sample schemas, save to a file, play, and delete from the sample schema image, audio, video, and testimonial data using these Oracle Multimedia object types:
OrdImage
OrdAudio
OrdVideo
OrdDoc
This sample application uses the PRODUCT_INFORMATION table in the Order Entry (OE) sample schema, and the ONLINE_MEDIA table in the Product Media (PM) sample schema.
|
Note: After installing Oracle Multimedia, if the OE and PM sample schemas do not exist, you must install them manually before compiling and running the sample application. |
The Oracle Multimedia Java API sample application, when compiled, creates the class files shown in Table 5-1:
Table 5-1 Java Class Files in the Compiled Sample Application
| Name | Description |
|---|---|
|
|
Creates the sample application frame and maintains the only connection to the database. This class is the entry point of this sample application. |
|
|
Extends the |
|
|
Extends the |
|
|
Performs the SQL SELECT statement to retrieve rows of the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Loads a media stream (photo, video, audio, and testimonials), from a file to the |
|
|
Saves a media stream from the database to a target file. |
|
|
Extends the |
The major flow among these class files is: IMExample to IMExampleFrame to IMLoginDialog (login) to IMExampleFrame.showDefaultTable( ) to IMExampleQuery to IMProductDialog to one group of classes (IMImagePanel, IMAudioPanel, IMVideoPanel, IMDocPanel), and finally to the last group of classes (IMLoadFile, IMSaveFile, IMMediaPanel).
Table 5-2 lists and describes the remaining Java class files in this sample application:
Table 5-2 Additional Java Class Files in the Sample Application
| Name | Description |
|---|---|
|
|
Includes common utilities such as a method to generate and update thumbnail images, wrapper methods for each setProperties( ) method of each media object type to separate the exceptions caused by unrecognizable formats, and cleanup methods to close the following: resultSet, Statement, input stream and its reader, and output stream and its writer. |
|
|
Loads and stores the mapping between plug-in players and the MIME type. |
|
|
Extends the |
|
|
Displays various messages for the sample application and classifies the message level as error, warning, or suggestion. |
|
|
Extends the |
|
|
Extends and puts into subclasses the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends the |
|
|
Describes the IMConstants interface, which contains all the constants for column names, media types, message types, and message dialog titles. |
|
|
Extends and puts into subclasses the |
|
|
Extends and puts into subclasses the |
|
|
Extends and puts into subclasses the |
|
|
Extends and puts into subclasses the |
|
|
Extends and puts into subclasses the |
|
|
Extends the |
|
|
Extends the |
|
|
Extends and puts into subclasses the |
|
|
Extends the |
|
|
Includes common GUI utilities. |
The following subsections describe the main operations that are performed within specific classes in the Oracle Multimedia Java API sample application:
This class defines the following methods followed by a description of what each method does:
The loadMedia( ) method to retrieve the media objects from the database. This method performs a SQL SELECT...FOR UPDATE statement on the PM.ONLINE_MEDIA table where the PRODUCT_ID column is a parameter marker; then this class uses the getORAData and getORADataFactory interfaces to get the media data objects from the result set.
The displayMedia( ) method to display the media data, which in turn calls the corresponding media display methods displayImage( ), displayAudio( ), displayVideo( ), and displayDoc ( ).
The displayImage( ) method calls the IMImagePanel.display( ) method to display the image data attributes, display the thumbnail image, and display the full sized image using a media player that supports this MIME type.
The displayAudio( ) method calls the IMAudioPanel.display( ) method to display the audio data attributes and play the audio stream using a media player that supports this MIME type.
The displayVideo( ) method calls the IMVideoPanel.display( ) method to display the video data attributes and play the video stream using a media player that supports this MIME type.
The displayDoc( ) method calls the IMDocPanel.display( ) method to display the testimonial data attributes and play the testimonial data using a media player that supports this MIME type.
The following code example shows the loadMedia( ), displayMedia( ), displayImage( ), displayAudio( ), displayVideo( ), and displayDoc( ) methods, and highlights in bold the SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used.
private void loadMedia() throws SQLException, IOException
{
String sQuery =
"select product_photo, product_thumbnail, product_audio, product_video, " +
"product_testimonials from pm.online_media where product_id = ? for update";
OracleConnection conn = null;
OracleResultSet rs = null;
OraclePreparedStatement pstmt = null;
boolean isInsertNeeded = false;
byte[] ctx[] = new byte[1][64];
try
{
conn = IMExample.getDBConnection();
pstmt = (OraclePreparedStatement)conn.prepareStatement(sQuery);
pstmt.setInt(1, m_iProdId);
rs = (OracleResultSet)pstmt.executeQuery();
if (rs.next() == true)
{
m_img = (OrdImage)rs.getORAData(1, OrdImage.getORADataFactory());
m_imgThumb = (OrdImage)rs.getORAData(2, OrdImage.getORADataFactory());
m_aud = (OrdAudio)rs.getORAData(3, OrdAudio.getORADataFactory());
m_vid = (OrdVideo)rs.getORAData(4, OrdVideo.getORADataFactory());
m_doc = (OrdDoc)rs.getORAData(5, OrdDoc.getORADataFactory());
}
displayMedia();
rs.close();
pstmt.close();
}
finally
{
IMUtil.cleanup(rs, pstmt);
}
}
private void displayMedia() throws SQLException, IOException
{
displayImage();
displayAudio();
displayVideo();
displayDoc();
}
/** * Add the product photo panel.
*/
private void displayImage() throws SQLException, IOException
{
m_jImgPanel = new IMImagePanel(this,
m_img, m_imgThumb, m_iProdId, m_colorFieldBg);
m_jImgPanel.display();
m_jImgPanel.getAccessibleContext().setAccessibleName
("Product photo panel");
m_jImgPanel.getAccessibleContext().setAccessibleDescription
("Product photo panel with an image icon on the left, " +
"image attribute panel in the middle and image control" +
"panel on the right.");
m_jMediaPanel.add(m_jImgPanel);
Component jImgFocus = m_jImgPanel.getFirstFocusComponent();
}
/**
* Add the product audio panel.
*/
private void displayAudio() throws SQLException, IOException
{
m_jAudPanel = new IMAudioPanel(this, m_aud, m_iProdId, m_colorFieldBg);
m_jAudPanel.display();
m_jAudPanel.getAccessibleContext().setAccessibleName
("Product audio panel");
m_jAudPanel.getAccessibleContext().setAccessibleDescription(
"Product audio panel with an audio icon at the left, " +
"audio attribute panel in the middle and audio control" +
"panel at the right.");
m_jMediaPanel.add(m_jAudPanel);
}
/**
* Add the product video panel.
*/
private void displayVideo() throws SQLException, IOException
{
m_jVidPanel = new IMVideoPanel(this, m_vid, m_iProdId, m_colorFieldBg);
m_jVidPanel.display();
m_jVidPanel.getAccessibleContext().setAccessibleName
("Product audio panel");
m_jVidPanel.getAccessibleContext().setAccessibleDescription(
"Product audio panel with an video icon at the left, " +
"video attribute panel in the middle and video control" +
"panel at the right.");
m_jMediaPanel.add(m_jVidPanel);
}
/**
* Add the product testimonials panel.
*/
private void displayDoc() throws SQLException, IOException
{
m_jDocPanel = new IMDocPanel(this, m _doc, m_iProdId, m_colorFieldBg);
m_jDocPanel.display();
m_jDocPanel.getAccessibleContext().setAccessibleName
("Product testimonials panel");
m_jDocPanel.getAccessibleContext().setAccessibleDescription(
"Product testimonials panel with an document icon at the left, " +
"testimonials attribute panel in the middle and testimonials control" +
"panel at the right.");
m_jMediaPanel.add(m_jDocPanel);
}
See Operations in the IMImagePanel Class, Operations in the IMAudioPanel Class, Operations in the IMVideoPanel Class, and Operations in the IMDocPanel Class for code examples of the corresponding m_jXxxPanel.display( ) methods, where Xxx represents the particular media data type, Img, Aud, Vid, or Doc.
This class displays the image panel, the product photo and its attributes, and the thumbnail image, and lists for reading and writing metadata. What follows is a more detailed description of each of the methods that are defined and what each method does:
The display( ) method, which first calls the insertProperty( ) method, which calls the Oracle Multimedia image object type methods getMimeType( ), getHeight( ), getWidth( ), and getContentlength( ) to get the attributes of the image to display in a table, and lays out the user interface components for reading and writing image metadata.
For supported formats, the class displays the product photo thumbnail image, which is generated by calling the IMUtil.generateThumbnail( )method to create the thumbnail image from the product photo.
The addThumbnail( ) method to show the new thumbnail image.
The changeThumbnail( ) method to change the thumbnail image.
The saveToFile( ) method to save the photo to a file.
The deleteMedia( ) method to delete the product photo image and its thumbnail image from the database by setting the image object type columns to empty using the OrdImage.init( ) method.
The play( ) media method to show the image using a media player.
The setMedia( ) method to set the photo and thumbnail object.
The notExist( ) method checks whether the image data exists and returns true if the BLOB is empty or is not associated with an existing BFILE; otherwise, it returns false.
The getDataInByteArray( ) method retrieves image data into a byte array by calling the Oracle Multimedia importData( ) method first for the BFILE and returns the results of calling the Oracle Multimedia getDataInByteArray( ) method.
The refreshPanel( ) method refreshes the dis play when updating the photo image, attributes, and thumbnail image.
The getFirstFocusComponent( ) method enforces the correct focus order.
The emptyPanel( ) method clears the icon and attribute panel.
The showMetadata( ) method to pop up a window for displaying metadata for the selected type.
The writeMetadata( ) method to display the write metadata dialog.
The following code example includes the display( ), insertProperty( ), notExist( ), getDataInByteArray( ), and refreshPanel( ) methods, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
void display() throws IOException, SQLException
{
addControlPane();
if (notExist(m_img))
{
// The image does not exist.
m_hasMedia = false;
layoutEmpty(s_sNotExist);
}
else
{
m_hasMedia = true;
// If image exists, try to show the attributes.
if (insertProperty())
{
// Show the thumbnail image.
// If the thumbnail image does not exist, generate it first.
if (m_imgThumb != null)
{
String sFormat = m_imgThumb.getFormat();
if (notExist(m_imgThumb) ||
( !("JFIF".equalsIgnoreCase(sFormat)) &&
!("GIFF".equalsIgnoreCase(sFormat))
))
{
m_imgThumb = IMUtil.generateThumbnail(m_iProdId, m_img, m_imgThumb);
}
byte[] thumbnail = getDataInByteArray(m_imgThumb);
addThumbnail(thumbnail);
}
else
{
m_imgThumb = IMUtil.generateThumbnail(m_iProdId, m_img, m_imgThumb);
byte[] thumbnail = getDataInByteArray(m_imgThumb);
addThumbnail(thumbnail);
}
}
}
}
.
.
.
boolean insertProperty() throws SQLException
{
boolean isFormatSupported = false;
String sMimeType = m_img.getMimeType();
if (sMimeType == null)
isFormatSupported = IMUtil.setProperties(m_img);
else
isFormatSupported = true;
if (!isFormatSupported)
{
layoutEmpty(s_sNotSupported);
}
else
{
Object[][] data =
{
{"MIME Type", m_img.getMimeType()},
{"Height", new Integer(m_img.getHeight()).toString()},
{"Width", new Integer(m_img.getWidth()).toString()},
{"Content Length", new Integer(m_img.getContentLength()).toString()}
};
.
.
.
}
return isFormatSupported; }
.
.
.
static boolean notExist(OrdImage img) throws SQLException, IOException
{
if (img == null)
return true;
else
{
if (img.isLocal() && (img.getDataInByteArray() == null))
return true;
else if (!img.isLocal() && (":///".equals(img.getSource())))
return true;
else
{
if (!img.isLocal())
{
BFILE bfile = img.getBFILE();
if (!bfile.fileExists())
return true;
else
return false;
}
else
return false;
}
}
}
.
.
.
static byte[] getDataInByteArray(OrdImage img) throws SQLException, IOException
{
if (notExist(img))
return null;
else
{
if (!img.isLocal())
{
byte[] ctx[] = new byte[1][4000];
try
{
img.importData(ctx);
}
catch (SQLException e)
{
new IMMessage(IMConstants.ERROR, "MEDIA_SOURCE_ERR", e);
return null;
}
}
return img.getDataInByteArray();
}
}
.
.
.
void refreshPanel(boolean isFormatSupported) throws SQLException, IOException
{
m_hasMedia = true;
if (isFormatSupported)
{
if (m_jAttrTbl == null)
{
m_jAttrPane.remove(m_jEmpty);
m_jIconPane.remove(m_jIcon);
byte[] thumbnail = getDataInByteArray(m_imgThumb);
addThumbnail(thumbnail);
insertProperty();
}
else
{
byte[] thumbnail = getDataInByteArray(m_imgThumb);
changThumbnail(thumbnail);
m_jAttrTbl.setValueAt(m_img.getMimeType(), 0, 1);
m_jAttrTbl.setValueAt(new Integer(m_img.getHeight()).toString(), 1, 1);
m_jAttrTbl.setValueAt(new Integer(m_img.getWidth()).toString(), 2, 1);
m_jAttrTbl.setValueAt(new Integer(m_img.getContentLength()).toString(),3, 1);
}
}
.
.
.
}
This class shows a dialog to display detailed information for metadata in a product photograph. This class also defines the displayMetadata( ) method and describes what it does.
The displayMetadata( ) method retrieves metadata from the image by using the Oracle Multimedia OrdImage getMetadata( ) method, and then displays the metadata.
The following code example includes the displayMetadata( ) method, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
private void displayMetadata(String sMetaType)
{
XMLDocument doc = null;
try
{
//
// Retrieves the metadata into an XMLType array
//
XMLType xmlList[] = m_img.getMetadata(sMetaType);
if (xmlList.length == 1)
{
DOMParser parser = new DOMParser();
parser.setValidationMode(XMLConstants.NONVALIDATING);
parser.setPreserveWhitespace(false);
parser.parse(new StringReader(XMLType.createXML(xmlList[0]).getStringVal()));
doc = parser.getDocument();
}
}
.
.
.
}
This class shows a dialog to write metadata into a product photograph. This class also defines the writeMetadata( ) method and describes what it does.
The writeMetadata( ) method writes XMP metadata into the image metadata by using the Oracle Multimedia OrdImage putMetadata( ) method.
The following code example includes the writeMetadata( ) method, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
void writeMetadata()
{
try
{
//
// Let the StringBuffer to hold the XMP packet
//
StringBuffer sb = new StringBuffer(
"<xmpMetadata xmlns=\"http://xmlns.oracle.com/ord/meta/xmp\" "
+ " xsi:schemaLocation=\"http://xmlns.oracle.com/ord/meta/xmp "
+ " http://xmlns.oracle.com/ord/meta/xmp\" "
+ " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" > "
+ " <rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"> "
+ " <rdf:Description about=\"\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\"> "
);
String str = null;
if ( (str=m_jTitleField.getText()) != null)
sb.append("<dc:title>" + str + "</dc:title>");
if ( (str=m_jCreatorField.getText()) !=null)
sb.append("<dc:creator>" + str + "</dc:creator>");
if ( (str=m_jDateField.getText()) !=null)
sb.append("<dc:date>" + str + "</dc:date>");
if ( (str=m_jDescriptionField.getText()) !=null)
sb.append("<dc:description>" + str + "</dc:description>");
if ( (str=m_jCopyrightField.getText()) !=null)
sb.append("<dc:rights>" + str + "</dc:rights>");
sb.append("</rdf:Description></rdf:RDF></xmpMetadata>");
XMLType xmp = XMLType.createXML(IMExample.getDBConnection(), sb.toString(),
"http://xmlns.oracle.com/ord/meta/xmp", true, true);
//
// Make sure the image data is local
//
if (!m_img.isLocal())
{
byte[] ctx[] = new byte[1][4000];
m_img.importData(ctx);
}
//
// Call Ordimage.putMetadata
//
m_img.putMetadata(xmp, "XMP", "utf-8");
this.dispose();
}
.
.
.
}
This class displays the video panel, the product video, and its attributes. This class is identical in structure and functions similarly to the IMImagePanel class. See Operations in the IMImagePanel Class for descriptions of methods.
The following code example includes the display( ), insertProperty( ), notExist( ), getDataInByteArray( ), and refreshPanel( ) methods, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
void display() throws IOException, SQLException
{
addControlPane();
// Set the video icon.
m_jIcon = new JLabel(new ImageIcon(IMExampleFrame.class.getResource("OrdVideo.gif")));
m_jIcon.setLabelFor(m_jAttrPane);
m_jIconPane.add(m_jIcon, BorderLayout.CENTER);
if (notExist())
{
// The video does not exist.
m_hasMedia = false;
layoutEmpty(s_sNotExist);
}
else
{
m_hasMedia = true;
// If the video exists, try to show the attributes.
insertProperty();
}
}
.
.
.
boolean insertProperty() throws SQLException
{
boolean isFormatSupported = false;
String sMimeType = m_vid.getMimeType();
if (sMimeType == null)
isFormatSupported = IMUtil.setProperties(m_vid);
else
isFormatSupported = true;
if (!isFormatSupported)
{
layoutEmpty(s_sNotSupported);
}
else
{
Object[][] data =
{
{"MIME Type", m_vid.getMimeType()},
{"Height", new Integer(m_vid.getHeight()).toString()},
{"Width", new Integer(m_vid.getWidth()).toString()},
{"Duration", new Integer(m_vid.getVideoDuration()).toString()},
{"Content Length", new Integer(m_vid.getContentLength()).toString()}
};
.
.
.
}
return isFormatSupported; }
.
.
.
boolean notExist() throws SQLException, IOException
{
if (m_vid == null)
return true;
else
{
if (m_vid.isLocal() && (m_vid.getDataInByteArray() == null))
return true;
else if (!m_vid.isLocal() && (":///".equals(m_vid.getSource())))
return true;
else
{
if (!m_vid.isLocal())
{
BFILE bfile = m_vid.getBFILE();
if (!bfile.fileExists())
return true;
else
return false;
}
else
return false;
}
}
}
.
.
.
byte[] getDataInByteArray(OrdVideo vid) throws SQLException, IOException
{
if (!m_hasMedia)
return null;
else
{
if (!vid.isLocal())
{
byte[] ctx[] = new byte[1][4000];
try
{
vid.importData(ctx);
}
catch (SQLException e)
{
new IMMessage(IMConstants.ERROR, "MEDIA_SOURCE_ERR", e);
return null;
}
}
return vid.getDataInByteArray();
}
}
.
.
.
void refreshPanel(boolean isFormatSupported) throws SQLException, IOException
{
m_hasMedia = true;
if (isFormatSupported)
{
if (m_jAttrTbl == null)
{
m_jAttrPane.remove(m_jEmpty);
insertProperty();
}
else
{
m_jAttrTbl.setValueAt(m_vid.getMimeType(), 0, 1);
m_jAttrTbl.setValueAt(new Integer(m_vid.getHeight()).toString(), 1, 1);
m_jAttrTbl.setValueAt(new Integer(m_vid.getWidth()).toString(), 2, 1);
m_jAttrTbl.setValueAt(new Integer(m_vid.getVideoDuration()).toString(), 3, 1);
m_jAttrTbl.setValueAt(new Integer(m_vid.getContentLength()).toString(), 4, 1);
}
}
.
.
.
}
This class displays the audio panel, the product audio, and its attributes. This class is identical in structure and functions similarly to the IMImagePanel class. See Operations in the IMImagePanel Class for descriptions of methods.
The following code example includes the display( ), insertProperty( ), notExist( ), getDataInByteArray( ), and refreshPanel( ) methods, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
void display() throws IOException, SQLException
{
addControlPane();
// Set the audio icon.
m_jIcon = new JLabel(new ImageIcon(IMExampleFrame.class.getResource("OrdAudio.gif")));
m_jIcon.setLabelFor(m_jAttrPane);
m_jIconPane.add(m_jIcon, BorderLayout.CENTER);
if (notExist())
{
// The audio does not exist.
m_hasMedia = false;
layoutEmpty(s_sNotExist);
}
else
{
m_hasMedia = true;
// If the audio exists, try to show the attributes.
insertProperty();
}
}
.
.
.
boolean insertProperty() throws SQLException
{
boolean isFormatSupported = false;
String sMimeType = m_aud.getMimeType();
if (sMimeType == null)
isFormatSupported = IMUtil.setProperties(m_aud);
else
isFormatSupported = true;
if (!isFormatSupported)
{
layoutEmpty(s_sNotSupported);
}
else
{
Object[][] data =
{
{"MIME Type", m_aud.getMimeType()},
{"Duration", new Integer(m_aud.getAudioDuration()).toString()},
{"Content Length", new Integer(m_aud.getContentLength()).toString()}
};
.
.
.
}
return isFormatSupported;
}
.
.
.
boolean notExist() throws SQLException, IOException
{
if (m_aud == null)
return true;
else
{
if (m_aud.isLocal() && (m_aud.getDataInByteArray() == null))
return true;
else if (!m_aud.isLocal() && (":///".equals(m_aud.getSource())))
return true;
else
{
if (!m_aud.isLocal())
{
BFILE bfile = m_aud.getBFILE();
if (!bfile.fileExists())
return true;
else
return false;
}
else
return false;
}
}
}
.
.
.
byte[] getDataInByteArray(OrdAudio aud) throws SQLException, IOException
{
if (!m_hasMedia)
return null;
else
{
if (!aud.isLocal())
{
byte[] ctx[] = new byte[1][4000];
try
{
aud.importData(ctx);
}
catch (SQLException e)
{
new IMMessage(IMConstants.ERROR, "MEDIA_SOURCE_ERR", e);
return null;
}
}
return aud.getDataInByteArray();
}
}
.
.
.
void refreshPanel(boolean isFormatSupported) throws SQLException, IOException
{
m_hasMedia = true;
if (isFormatSupported)
{
if (m_jAttrTbl == null)
{
m_jAttrPane.remove(m_jEmpty);
insertProperty();
}
else
{
m_jAttrTbl.setValueAt(m_aud.getMimeType(), 0, 1);
m_jAttrTbl.setValueAt(new Integer(m_aud.getAudioDuration()).toString(), 1, 1);
m_jAttrTbl.setValueAt(new Integer(m_aud.getContentLength()).toString(), 2, 1);
}
}
.
.
.
}
This class displays the doc panel, the product testimonials, and its attributes. This class is identical in structure and functions similarly to the IMImagePanel class. See Operations in the IMImagePanel Class for descriptions of methods.
The following code example includes the display( ), insertProperty( ), notExist( ), getDataInByteArray( ), and refreshPanel( ) methods, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
void display() throws IOException, SQLException
{
addControlPane();
// Set the icon.
m_jIcon = new JLabel(new ImageIcon(
IMExampleFrame.class.getResource("OrdDoc.gif")
));
m_jIcon.setLabelFor(m_jAttrPane);
m_jIconPane.add(m_jIcon, BorderLayout.CENTER);
if (notExist())
{
// The doc does not exist.
m_hasMedia = false;
layoutEmpty(s_sNotExist);
}
else
{
// If the doc exists, show the attribute table.
m_hasMedia = true;
insertProperty();
}
}
.
.
.
boolean insertProperty() throws SQLException
{
boolean isFormatSupported = false;
String sMimeType = m_doc.getMimeType();
if (sMimeType == null)
isFormatSupported = IMUtil.setProperties(m_doc);
else
isFormatSupported = true;
if (!isFormatSupported)
{
layoutEmpty(s_sNotSupported);
}
else
{
Object[][] data =
{
{"MIME Type", m_doc.getMimeType()},
{"Content Length", new Integer(m_doc.getContentLength()).toString()}
};
.
.
.
}
return isFormatSupported;
}
.
.
.
boolean notExist() throws SQLException, IOException
{
if (m_doc == null)
return true;
else
{
if (m_doc.isLocal() && (m_doc.getDataInByteArray() == null))
return true;
else if (!m_doc.isLocal() && (":///".equals(m_doc.getSource())))
return true;
else
{
if (!m_doc.isLocal())
{
BFILE bfile = m_doc.getBFILE();
if (!bfile.fileExists())
return true;
else
return false;
}
else
return false;
}
}
}
.
.
.
byte[] getDataInByteArray(OrdDoc doc) throws SQLException, IOException
{
if (!m_hasMedia)
return null;
else
{
if (!doc.isLocal())
{
byte[] ctx[] = new byte[1][4000];
try
{
doc.importData(ctx, false);
}
catch (SQLException e)
{
new IMMessage(IMConstants.ERROR, "MEDIA_SOURCE_ERR", e);
return null;
}
}
return doc.getDataInByteArray();
}
}
.
.
.
void refreshPanel(boolean isFormatSupported) throws SQLException, IOException
{
m_hasMedia = true;
if (isFormatSupported)
{
if (m_jAttrTbl == null)
{
m_jAttrPane.remove(m_jEmpty);
insertProperty();
}
else
{
m_jAttrTbl.setValueAt(m_doc.getMimeType(), 0, 1);
m_jAttrTbl.setValueAt(new Integer(m_doc.getContentLength()).toString(), 1, 1);
}
}
.
.
.
}
This class loads a media stream from a file to a database for each of the media object types. First, it checks whether this PRODUCT_ID column exists in the PM.ONLINE_MEDIA table and if not, it inserts a new row into the table. Then, it creates and initializes a new media object for each media object type, updates the media data, that is, loads it into the database if it is not already stored there, and finally, sets the media attributes for each media data object.
In this class, the IMFileLoad( ) method calls the initFileChooser( ) method, then the initFileChooser( ) method calls the loadNewMedia( ) method, which does the row insertion and initializing of the media object type columns, and then calls the updateMedia( ) method to update the media and to set the media attributes.
The following code example includes the loadNewMedia( ) and UpdateMedia( ) methods, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used as previously described:
private void loadNewMedia()
throws SQLException, FileNotFoundException, SecurityException, IOException
{
boolean isInsertNeeded = false;
String sQuery = null;
OracleConnection conn = null;
OracleResultSet rs = null;
OraclePreparedStatement pstmt = null;
try
{
conn = IMExample.getDBConnection();
if (m_obj == null)
{
// First, check whether or not this product exists in the
// pm.online_media table. If it exists, isInsertNeeded is set to false;
// or else, isInsertNeeded is set to true.
sQuery = new String(
"select product_id from pm.online_media where product_id = ?");
pstmt = (OraclePreparedStatement) conn.prepareStatement(sQuery);
pstmt.setInt(1, m_iProdId);
rs = (OracleResultSet)pstmt.executeQuery();
if (rs.next() == false)
isInsertNeeded = true;
else
isInsertNeeded = false;
rs.close();
pstmt.close();
if (isInsertNeeded)
{
// If this product is not in the pm.online_media table,
// insert a row in pm.online_media for this product,
// and initialize the media object at the same time.
sQuery = new String(
"insert into pm.online_media (product_id, product_photo, " +
"product_photo_signature, product_thumbnail, product_video, " +
"product_audio, product_text, product_testimonials) values (" +
"?, ORDSYS.ORDImage.init(), ORDSYS.ORDImageSignature.init(), " +
"ORDSYS.ORDImage.init(), ORDSYS.ORDVideo.init(), " +
"ORDSYS.ORDAudio.init(), null, ORDSYS.ORDDoc.init())");
pstmt = (OraclePreparedStatement) conn.prepareCall(sQuery);
pstmt.setInt(1, m_iProdId);
pstmt.execute();
pstmt.close();
}
}
if (!isInsertNeeded)
{
// Create a new media object.
switch (m_iTypeIdentifier)
{
case IMG_TYPE:
sQuery = new String(
"update pm.online_media set " + m_sColName +
" = ORDSYS.ORDImage.init() where product_id = ?");
break;
case AUD_TYPE:
sQuery = new String(
"update pm.online_media set " + m_sColName +
" = ORDSYS.ORDAudio.init() where product_id = ?");
break;
case VID_TYPE:
sQuery = new String(
"update pm.online_media set " + m_sColName +
" = ORDSYS.ORDVideo.init() where product_id = ?");
break;
case DOC_TYPE:
sQuery = new String(
"update pm.online_media set " + m_sColName +
" = ORDSYS.ORDDoc.init() where product_id = ?");
break;
default:
new IMMessage(IMConstants.ERROR, "UNKNOWN_TYPE");
break;
}
pstmt = (OraclePreparedStatement) conn.prepareCall(sQuery);
pstmt.setInt(1, m_iProdId);
pstmt.execute();
pstmt.close();
}
// At this point, there is a row in the online_media table
// for this product and the desired media object is initialized.
// In the following, we update the media object pointer and
// acquire the right to modify it by selecting again from the
// database.
//
sQuery = new String(
"select " + m_sColName +
" from pm.online_media where product_id = ? for update");
pstmt = (OraclePreparedStatement) conn.prepareStatement(sQuery);
pstmt.setInt(1, m_iProdId);
rs = (OracleResultSet)pstmt.executeQuery();
if (rs.next() == false)
throw new SQLException();
else
{
switch (m_iTypeIdentifier)
{
case IMG_TYPE:
m_img = (OrdImage)rs.getORAData(1, OrdImage.getORADataFactory());
break;
case AUD_TYPE:
m_aud = (OrdAudio)rs.getORAData(1, OrdAudio.getORADataFactory());
break;
case VID_TYPE:
m_vid = (OrdVideo)rs.getORAData(1, OrdVideo.getORADataFactory());
break;
case DOC_TYPE:
m_doc = (OrdDoc)rs.getORAData(1, OrdDoc.getORADataFactory());
break;
default:
new IMMessage(IMConstants.ERROR, "UNKNOWN_TYPE");
break;
}
// Update the media object.
updateMedia();
}
rs.close();
pstmt.close();
}
finally
{
IMUtil.cleanup(rs, pstmt);
}
}
/**
* Update the media and also set the media properties.
*/
private void updateMedia()
throws SQLException, FileNotFoundException, SecurityException, IOException
{
String sQuery = null;
OracleConnection conn = null;
byte[] ctx[] = new byte[1][64];
OraclePreparedStatement pstmt = null;
boolean isFormatSupported = false;
try
{
conn = IMExample.getDBConnection();
sQuery = new String(
"update pm.online_media set " + m_sColName +
" = ? where product_id = ?");
pstmt = (OraclePreparedStatement) conn.prepareCall(sQuery);
pstmt.setInt(2, m_iProdId);
switch (m_iTypeIdentifier)
{
case IMG_TYPE:
m_img.loadDataFromFile(m_jFileChooser.getText());
isFormatSupported = IMUtil.setProperties(m_img);
m_img.setLocal();
pstmt.setORAData(1, m_img);
break;
case AUD_TYPE:
m_aud.loadDataFromFile(m_jFileChooser.getText());
isFormatSupported = IMUtil.setProperties(m_aud);
m_aud.setLocal();
pstmt.setORAData(1, m_aud);
// We need to update thee media pointer for display,
// because the input media pointer may be null.
((IMAudioPanel)m_parent).setMedia(m_aud);
((IMAudioPanel)m_parent).refreshPanel(isFormatSupported);
break;
case VID_TYPE:
m_vid.loadDataFromFile(m_jFileChooser.getText());
isFormatSupported = IMUtil.setProperties(m_vid);
m_vid.setLocal();
pstmt.setORAData(1, m_vid);
((IMVideoPanel)m_parent).setMedia(m_vid);
((IMVideoPanel)m_parent).refreshPanel(isFormatSupported);
break;
case DOC_TYPE:
m_doc.loadDataFromFile(m_jFileChooser.getText());
isFormatSupported = IMUtil.setProperties(m_doc);
m_doc.setLocal();
pstmt.setORAData(1, m_doc);
((IMDocPanel)m_parent).setMedia(m_doc);
((IMDocPanel)m_parent).refreshPanel(isFormatSupported);
break;
default:
new IMMessage(IMConstants.ERROR, "UNKNOWN_TYPE");
break;
}
pstmt.execute();
pstmt.close();
// Update the thumbnail image.
if (m_iTypeIdentifier == IMG_TYPE)
{
if (isFormatSupported)
m_imgThumb = IMUtil.generateThumbnail(m_iProdId, m_img, m_imgThumb);
((IMImagePanel)m_parent).setMedia(m_img, m_imgThumb);
((IMImagePanel)m_parent).refreshPanel(isFormatSupported);
}
}
finally
{
IMUtil.cleanup(pstmt);
}
}
This class contains common utilities, such as a generateThumbnail( ) static method, wrapper methods for the setProperties( ) methods for each media object type to separate the exceptions caused by unrecognizable formats, and finally, several cleanup methods.
The following code example includes the generateThumbnail( ) method, and highlights in bold any SQL query statements and areas in the code where Oracle Multimedia and other Oracle object types and methods are used:
static OrdImage generateThumbnail(int iProdId, OrdImage img, OrdImage imgThumb)throws SQLException { String sQuery = null; OracleConnection conn = null; OracleResultSet rs = null; OraclePreparedStatement pstmt = null; try { conn = IMExample.getDBConnection(); if (imgThumb == null) { // The thumbnail media pointer is not initialized. // Initialize it first. sQuery = new String("update pm.online_media set product_thumbnail = " +"ORDSYS.ORDImage.init() where product_id = ?");pstmt = (OraclePreparedStatement) conn.prepareCall(sQuery); pstmt.setInt(1, iProdId); pstmt.execute(); pstmt.close(); // Acquire the new pointer and the permission to update. sQuery = new String("select product_thumbnail from pm.online_media " +"where product_id = ? for update");pstmt = (OraclePreparedStatement) conn.prepareStatement(sQuery); pstmt.setInt(1, iProdId); rs = (OracleResultSet)pstmt.executeQuery(); if (rs.next() == false) throw new SQLException(); elseimgThumb = (OrdImage)rs.getORAData(1, OrdImage.getORADataFactory());rs.close(); pstmt.close(); } // Generate the thumbnail image.img.processCopy("maxScale=64 64, fileFormat=GIFF", imgThumb);// Update the thumbnail image in the database. sQuery = new String("update pm.online_media set product_thumbnail = ? where product_id = ?");pstmt = (OraclePreparedStatement) conn.prepareCall(sQuery); pstmt.setORAData(1, imgThumb); pstmt.setInt(2, iProdId); pstmt.execute(); pstmt.close(); return imgThumb; } finally { IMUtil.cleanup(rs, pstmt); } }
This guide describes how to use Oracle Multimedia, which ships with Oracle Database. It describes the management and integration of audio, image, and video, or other heterogeneous media data with other Oracle tools and software, and with third-party tools and software.
In Oracle Database 11g Release 1 (11.1), the name Oracle interMedia was changed to Oracle Multimedia. The feature remains the same, only the name has changed. References to Oracle interMedia were replaced with Oracle Multimedia although, some references to Oracle interMedia or interMedia might still appear in graphical user interfaces, code examples, and related documents in the Documentation Library for Oracle Database 11g Release 2 (11.2).
The sample code in this guide might not match the code shipped with Oracle Database Examples media. To run examples that are shipped with Oracle Database Examples media on your system, use the files provided with Oracle Database Examples media. Do not attempt to compile and run the code in this guide.
See Oracle Database New Features Guide for information about Oracle Database and the features and options that are available to you.
This guide is for application developers and database administrators who are interested in storing, retrieving, and manipulating audio, image, video, and heterogeneous media data in a database, including developers of audio, heterogeneous media data, image, and video specialization options. After familiarizing yourself with the concepts presented in this guide, consult Oracle Multimedia Reference for API information.
Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
|
Note: For information added after the release of this guide, see the onlineREADME.txt file under your <ORACLE_HOME> directory. Depending on your operating system, this file may be in
See your operating system-specific installation guide for more information. |
For more information about using Oracle Multimedia in a development environment, see the following documents in the Oracle Database Online Documentation Library:
For more information about using JDBC, see Oracle Database JDBC Developer's Guide.
For more information about using XML, see Oracle XML DB Developer's Guide.
For reference information about Oracle Multimedia Java classes in Javadoc format, see the following Oracle API documentation (also known as Javadoc) in the Oracle Database Online Documentation Library:
For information about using the Oracle Multimedia JSP Tag Library, see Oracle Multimedia JSP Tag Library Guide in the Oracle Multimedia Software section of the Oracle Technology Network Web site.
For more information about Java, including information about Java Advanced Imaging (JAI), see the API documentation provided by Oracle.
Many of the examples in this guide use the sample schemas. See Oracle Database Sample Schemas for information about how these schemas were created and how you can use them.
Although Boolean is a proper noun, it is presented as boolean in this guide when its use in Java code requires case-sensitivity.
The following text conventions are also used in this guide:
| Convention | Meaning |
|---|---|
| boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
| italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
This appendix describes the management of Oracle Multimedia.
This appendix includes these sections:
|
Note: See the Oracle MultimediaREADME.txt file located in <ORACLE_HOME>/ord/im/admin for the latest information. |
The Oracle Multimedia installation procedure performs these functions:
Creates the database users shown in Table B-1 with the privileges required by Oracle Multimedia.
Creates the default passwords shown in Table B-2 for the Oracle Multimedia and MDSYS user accounts, and then locks the accounts and marks their default passwords as expired.
Table B-2 User Accounts and Default Passwords
| User Account | Installation Password |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Grants the EXECUTE privilege to the user group PUBLIC for the Oracle Multimedia packages and objects installed in these schemas:
ORDSYS
ORDPLUGINS
SI_INFORMTN_SCHEMA
MDSYS
Oracle Multimedia is automatically installed and configured with Oracle Database.
The following subsections describe the steps to perform before manual installation and configuration of Oracle Multimedia, and the steps for manually installing and configuring it:
|
Caution: Performing any of these prohibited actions could cause internal errors and security violations in the database management system.These users are created during database installation, and might change in future releases:
Do not delete any of these users. Do not connect to or modify any of these users or their contents (which are supplied by Oracle Multimedia and reserved by Oracle), with these exceptions:
|
Before installing and configuring Oracle Multimedia manually, perform these steps:
Install Oracle Database, including PL/SQL, Oracle JVM, Oracle XML Database, and Oracle XDK.
Create the database.
Start the database.
Verify that the required software is correctly installed and valid, as follows:
Run SQL*Plus, connect as SYSDBA, and enter these queries:
SQL> select version, status from dba_registry where comp_id='JAVAVM'; SQL> select version, status from dba_registry where comp_id='XDB'; SQL> select version, status from dba_registry where comp_id='XML';
Examine the results of the queries to ensure that each version value is identical to the version of Oracle Multimedia that you are installing and each status value is VALID.
|
See Also: Oracle Database Installation Guide for your operating system for more detailed information |
These steps are not required if you use the Database Configuration Assistant.
To install and configure Oracle Multimedia manually, perform these steps (<ORACLE_HOME> represents the Oracle home directory):
Use Oracle Universal Installer to install the files that comprise Oracle Multimedia on your system.
Decide which tablespace to use for the Oracle Multimedia users, and which tablespace to use for the Oracle Spatial/Oracle Multimedia Location Services user (see Table B-1). Oracle recommends using the SYSAUX tablespace for all of these users.
Create the users and grant the appropriate privileges, as follows:
Start SQL*Plus and connect as SYSDBA:
% sqlplus SQL> CONNECT sys as sysdba
Call the script ordinst.sql, with two parameters for the Oracle Multimedia tablespace and the Oracle Spatial/Oracle Multimedia Location Services tablespace:
On Linux and UNIX:
SQL> @<ORACLE_HOME>/ord/admin/ordinst.sql SYSAUX SYSAUX
On Windows:
SQL> @<ORACLE_HOME>\ord\admin\ordinst.sql SYSAUX SYSAUX
Install the Oracle Multimedia types and packages, as follows:
Call the script catim.sql, while you are connected as SYSDBA:
On Linux and UNIX:
SQL> @<ORACLE_HOME>/ord/im/admin/catim.sql
On Windows:
SQL> @<ORACLE_HOME>\ord\im\admin\catim.sql
Now Oracle Multimedia is ready for use.
After installing or upgrading Oracle Multimedia, you can verify the Oracle Multimedia installation by calling the Oracle Multimedia validation procedure.
To run the Oracle Multimedia validation procedure, perform these steps:
Start SQL*Plus and connect as SYSDBA:
% sqlplus SQL> CONNECT sys as sysdba
Execute the procedure sys.validate_ordim:
SQL> execute sys.validate_ordim;
If the validation procedure detects invalid objects, it lists the first few invalid objects and sets the registry entry to INVALID; otherwise, it silently sets the Oracle Multimedia registry entry to VALID.
Verify that the registry entry for Oracle Multimedia is correct, as follows:
Enter this query from SQL*Plus, while you are connected as SYSDBA:
SQL> select version, status from dba_registry where comp_id='ORDIM';
Examine the result of the query to ensure that the version value is correct and the status value is VALID.
If you upgrade a database from an earlier release of Oracle Database, Oracle Multimedia is upgraded automatically if it is detected in the source database.
Oracle Multimedia is automatically downgraded when you downgrade a database with the Oracle Multimedia feature installed.
|
Caution: Do not modify your DICOM data model repository until you are sure that you are not going to downgrade from Oracle Database 11g Release 2 (11.2) back to the source release.Changes to the Oracle Multimedia DICOM data model repository (such as document insertions or deletions) that you make after a database upgrade are lost after a database downgrade. |
To remove Oracle Multimedia manually, perform these steps:
Start SQL*Plus, and connect as SYSDBA:
% sqlplus SQL> CONNECT sys as sysdba
Call the script catcmprm.sql, with the parameter ORDIM:
On Linux and UNIX:
SQL> @<ORACLE_HOME>/rdbms/admin/catcmprm.sql ORDIM
On Windows:
SQL> @<ORACLE_HOME>\rdbms\admin\catcmprm.sql ORDIM
If one or more components that depend on Oracle Multimedia (such as Oracle Spatial) are installed, this message appears:
ORDIM cannot be removed as it has the following dependencies:
Component: SDO Namespace: SERVER
If no dependent components are installed, a message appears, indicating either that Oracle Multimedia is or is not in use.
Then, a prompt asks if you really want to remove Oracle Multimedia.
Reply to the prompt with Y or y to remove Oracle Multimedia.
Oracle Multimedia is removed with force (regardless of whether it is in use).
This chapter describes media upload and retrieval Web applications using Oracle Multimedia object types, using these distinct Oracle Multimedia Photo Album sample Web applications:
Oracle Multimedia PL/SQL Photo Album Sample Application uses the PL/SQL Gateway and PL/SQL Web Toolkit for Oracle Fusion Middleware and Oracle Database (see Section 3.1)
Oracle Multimedia Java Servlet Photo Album Sample Application uses the Oracle Multimedia Servlets and JSP Java API (see Section 3.2)
Oracle Multimedia JSP Photo Album Sample Application uses the Oracle Multimedia Servlets and JSP Java API (see Section 3.3)
This chapter assumes the following:
You are familiar with:
Developing PL/SQL applications using the PL/SQL Gateway and PL/SQL Web Toolkit
Developing Java-based Web applications using JDBC, creating Java source code, compiling it into byte code (.class) files, and deploying class files into respective servlet containers required by Oracle HTTP Server for Oracle Fusion Middleware and Oracle Database
You have installed and configured these sample applications:
Oracle Multimedia PL/SQL Web Toolkit Photo Album application
Oracle Multimedia Java Servlet Photo Album application
Oracle Multimedia JSP Photo Album application
See the README.txt file for each respective sample application for installation and configuration information.
More Sample Applications
See these chapters for more sample applications:
Chapter 4 describes the Oracle Multimedia Code Wizard sample application, a media upload and retrieval Web application for the PL/SQL Gateway.
Chapter 5 describes the Oracle Multimedia Java API sample application. This sample application lets you retrieve, save, play, and delete multimedia data from the Oracle Database sample schemas using Oracle Multimedia Java classes and Oracle Multimedia object types.
The Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application demonstrates how to perform the following operations:
Use the Oracle Multimedia image object type to upload, retrieve, and process media data stored in Oracle Database.
Combine the image metadata methods of Oracle Multimedia with the XML document management capabilities of Oracle XML DB and the full-text indexing and search features of Oracle Text to create a solution that can extract, store, and search metadata that is embedded in binary image files.
Collect new metadata from a user, format the metadata into an XML document, and store the document in the binary image.
When installed, this photo album application creates several schema objects that are important to the following discussion. These objects include the photos table, which is defined by the following CREATE TABLE statement:
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";
The data types for the image and thumb columns are defined as Oracle Multimedia image object types. These columns are used to store the full-size images and the generated thumbnail images, respectively. The LOB storage clauses direct the database to store the full-size and thumbnail images in SecureFile LOBs, which are the highest performing storage option for binary data.
The table also defines four columns of type XMLType to store XML documents that contain four different kinds of image metadata. Each column is bound to a specific Oracle Multimedia metadata schema. Each metadata schema defines precisely the data model of the metadata document. These schemas are registered with Oracle XML DB when the database is created. The column definitions specify that the database uses unstructured storage to manage the XML metadata documents. Some advantages of using unstructured storage to manage XML include fast retrieval of the complete document and the ability to use XMLIndex indexes to improve the performance of XPath-based queries.
When installed, this photo album application also creates other schema objects. These schema objects include two types of indexes that accelerate metadata searches: a CONTEXT text index and an XMLIndex index.
The CONTEXT type is a text index over all columns that contain descriptive information about the image. These columns include PHOTOS.DESCRIPTION, which is a VARCHAR2 data type, and these four XMLType columns: PHOTOS.METAIPTC, PHOTOS.METAEXIF, PHOTOS.METAXMP, and PHOTOS.METAORDIMAGE. The CONTEXT text index is used to accelerate metadata searches by implementing the photo album search feature that enables users to search for photographs by keyword or phrase.
The CONTEXT text index is created by the following statements. (This example assumes that this photo album application has been installed in the SCOTT schema.)
-- 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' );
The XMLIndex index is used to accelerate metadata searches by permitting users to search only certain types of image metadata and limiting the search to specific portions of an XML document. For example, the following statements create three indexes of type XMLIndex to speed up existsNode( ) queries on columns of type XMLType:
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;
During the installation, as prescribed by the PL/SQL Gateway, a document upload table is defined by the following CREATE TABLE statement:
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;
Each image uploaded using the PL/SQL Gateway is stored in the PHOTOS_UPLOAD table. An upload procedure (insert_new_photo) automatically moves the uploaded image from the specified PHOTOS_UPLOAD table to the photo album applications table called photos.
After installing the Oracle Database Examples media, the sample application files and README.txt file are located at:
<ORACLE_HOME>/ord/http/demo/plsqlwtk (on Linux and UNIX)
<ORACLE_HOME>\ord\http\demo\plsqlwtk (on Windows)
See the README.txt file for additional requirements and instructions on installing and using this sample application.
The following subsections provide more information about the PL/SQL Photo Album application:
|
See Also:
|
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
In the <protocol> field, enter http://.
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.
The PL/SQL 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.
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.
Table 3-1 PL/SQL Photo Album Sample Application Overview
| User Task | Web Page | PL/SQL Procedures |
|---|---|---|
Browsing the photo album Section 3.1.2.1 | View album Figure 3-1 | view_albumExample 3-1 print_albumExample 3-2 print_image_linkExample 3-3 deliver_mediaExample 3-4 |
Adding images to the photo album Section 3.1.2.2 | Upload photo Figure 3-2 | view_upload_formprint_upload_formExample 3-5 insert_new_photoExample 3-6 |
Searching for images by keyword or phrase Section 3.1.2.3 | Search album Figure 3-3 | view_albumExample 3-1 print_albumExample 3-2 |
Viewing full-size images Section 3.1.2.4 | View entry Figure 3-4 | view_entryExample 3-7 print_image_linkExample 3-3 deliver_mediaExample 3-4 |
Examining image metadata Section 3.1.2.5 | View metadata Figure 3-5 | view_metadataExample 3-8 print_metadataExample 3-9 |
Writing new XMP metadata to images Section 3.1.2.6 | Write XMP metadata Figure 3-6 | write_metadataExample 3-10 |
Searching for images that contain specific metadata attributes Section 3.1.2.7 | Search metadata Figure 3-7 | search_metadataExample 3-11 |
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.
Pages in the PL/SQL Photo Album Sample Application
The following subsections,which are summarized here, describe each page in the PL/SQL Photo Album application:
Use the View album page to display 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
Use the Upload photo page to display 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
Use the Search album page to display 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.
Use the View entry page to display the full-size image of a specified photograph, including any description text that was entered for that image when it was uploaded.
Use the View metadata page to display 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
Use the Write XMP metadata page to display 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
Use the Search metadata page to collect input and perform 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.
The home page for this photo album application, View album, displays the contents of the photo album as thumbnail images in four-column format. Each thumbnail image is also a link to the View entry page. When you click a thumbnail image link, the application displays the full-size image on a View entry page. Included under each thumbnail image on the View album page is the image description that was entered when the image was uploaded to the album. The description is also a link to the View metadata page where all the metadata for this photograph can be examined.
Near the top of the View album page, there is a text entry field (in the shape of a rectangular box) that accepts user input for a full-text search through all the photo album metadata. The Search button to the right of the text field initiates the search. The search results are displayed on the Search album page, which is discussed in Section 3.1.2.3.
At the top of the View album page, there is a navigation bar, which includes links to other photo album pages. From the View album page, you can navigate to the Search metadata page or the Upload photo page. These pages are described in Section 3.1.2.7 and Section 3.1.2.2, respectively.
Figure 3-1 shows the View album page for an album that contains several images.
Figure 3-1 View album Page with Uploaded Images
The PL/SQL procedures view_album, print_album, print_image_link, and deliver_media are the primary application components that implement the View album page. The view_album procedure is a public procedure that takes a single optional argument. By default, the argument has a NULL value. Or, it can have the value of the string entered in the text entry field on the Search album page. When the search argument is NULL, the SELECT statement retrieves the id,description, and thumb columns for all entries in the photos table. When the search string is not NULL, the SELECT statement uses the CONTAINS operator to restrict the result set to only images with metadata that matches the search string. (Section 3.1 describes how the application creates a multicolumn text index over the four XMLType columns PHOTOS.METAIPTC, PHOTOS.METAEXIF, PHOTOS.METAXMP, and PHOTOS.METAORDIMAGE as well as the PHOTOS.DESCRIPTION column.)
Example 3-1 contains some relevant lines of code in the view_album procedure.
Example 3-1 Procedure view_album
--
-- no search criteria so fetch all entries
--
IF search IS NULL THEN
OPEN album_cur FOR
SELECT id, description, thumb
FROM photos
ORDER BY id;
print_album( album_cur, 'The photo album is empty.' );
CLOSE album_cur;
ELSE
-- -- use the full-text index to select entries matching the search criteria
--
OPEN album_cur FOR
SELECT id, description, thumb
FROM photos
WHERE CONTAINS( description, trim(search) ) > 0
ORDER BY id;
print_album( album_cur, 'No photos were found.' );
CLOSE album_cur;
END IF;
The SELECT statement is bound to the cursor variable album_cur and passed to the procedure print_album, which creates the HTML output.
The print_album procedure uses the HTP and HTF packages from the PL/SQL Web Toolkit to create the HTML tags that format the output into a four-column table. Each cell in the table contains two links or anchor tags. The first link is to the View entry page, which displays the full-size version of the image. This anchor is implemented by PHOTO_ALBUM.VIEW_ENTRY, and passes entry_id as a query string input argument. If the thumbnail image has a nonzero length, then procedure print_image_link is called to create an HTML <img> tag that is the content (the thumbnail image) of the anchor link. The string thumb and the entry_id are passed to procedure print_image_link, along with the image description, and the height and width of the thumbnail image. These values are used to create the <img> tag.
If an image is in a format that Oracle Multimedia does not support, the application cannot create a thumbnail version of the image. In this case, the content of the anchor link is the text view image.
Example 3-2 contains some relevant lines of code in the print_album procedure.
Example 3-2 Procedure print_album
-- escape the description text
sc_description := htf.escape_sc( entry.description );
--
-- Display the thumbnail image as an anchor tag which can be used
-- to display the full-size image. If the image format is not
-- supported by Oracle Multimedia, then a thumbnail would not have been
-- produced when the image was uploaded, so use the text '[view
-- image]' instead of the thumbnail.
--
htp.print( '<td headers="c' || colIdx || '" align="center" >
<a href="PHOTO_ALBUM.VIEW_ENTRY?entry_id=' ||
entry.id || '">' );
IF entry.thumb.contentLength > 0
THEN
print_image_link( 'thumb', entry.id, sc_description,
entry.thumb.height, entry.thumb.width );
ELSE
htp.prn( '[view image]' );
END IF;
htp.print( '</a>' );
-- Create link to the metadata
htp.prn('<br>');
htp.anchor( curl=>'PHOTO_ALBUM.VIEW_METADATA?entry_id=' || entry.id,
ctext=>sc_description );
htp.prn('</td>');
The procedure print_image_link uses the height and width arguments to populate the height and width attributes of the <img> tag. The description argument is used to create text for the alt attribute. If the description argument is empty, a default string is constructed. Finally, the src attribute is set to the URL PHOTO_ALBUM.DELIVER_MEDIA with two query string arguments, media and entry_id. The media argument controls whether the thumbnail or full-size version of the image is delivered. The entry_id argument identifies the image to be delivered.
Example 3-3 contains s ome relevant lines of code in the print_image_link procedure.
Example 3-3 Procedure print_image_link
-- add height and width to tag if non zero
IF height > 0 AND width > 0 THEN
attributes := attributes || ' height=' || height || ' width=' || width;
END IF;
-- create an alt text if none given
IF alt IS NULL THEN
IF type = 'thumb' THEN
alt2 := 'thumb-nail image ';
ELSE
alt2 := 'full-size image ';
END IF;
alt2 := alt2 || 'for album entry ' || entry_id;
ELSE
alt2 := alt;
END IF;
htp.img( curl=>'PHOTO_ALBUM.DELIVER_MEDIA?media=' || type ||
ampersand || 'entry_id=' || entry_id,
calt=>alt2, cattributes=>attributes );
The procedure deliver_media fetches the image content from the database. The If-Modified-Since HTTP request header is compared to the last modification time of the image. If the image has not been modified, a response is sent that the browser can display the image from its cache. Otherwise, the image MIME type and last modified time are sent to the Web server, along with the image content.
Example 3-4 contains some relevant lines of code in the deliver_media procedure.
Example 3-4 Procedure deliver_media
--
-- Fetch the thumbnail or full-size image from the database.
--
IF media = 'thumb'
THEN
SELECT thumb INTO local_image FROM photos WHERE id = entry_id;
ELSE
SELECT image INTO local_image FROM photos WHERE id = entry_id;
END IF;
--
-- Check update time if browser sent If-Modified-Since header
--
IF ordplsgwyutil.cache_is_valid( local_image.getUpdateTime() )
THEN
owa_util.status_line( ordplsgwyutil.http_status_not_modified );
RETURN;
END IF;
--
-- Set the MIME type and deliver the image to the browser.
--
owa_util.mime_header( local_image.mimeType, FALSE );
ordplsgwyutil.set_last_modified( local_image.getUpdateTime() );
owa_util.http_header_close();
IF owa_util.get_cgi_env( 'REQUEST_METHOD' ) <> 'HEAD' THEN
wpg_docload.download_file( local_image.source.localData );
END IF;
The Upload photo page is used to add new images to the photo album. The page displays a form with two text entry fields. In the Description: field, you can optionally enter a word or short phrase that describes the image. In the File name: field, enter the name of the image file or click Browse... to locate the image file to be uploaded. The Upload photo button under the File name: field starts the upload operation. When the image is successfully uploaded, the View album page appears. From that page, you can display the contents of the photo album, as described in Section 3.1.2.1.
At the top of the Upload photo page, there is a navigation bar, which includes links to other photo album pages. From the Upload photo page, you can return to the View album page or select the Search metadata page. These pages are described in Section 3.1.2.1 and Section 3.1.2.7, respectively.
Figure 3-2 shows an Upload photo page with all the entry fields completed.
The PL/SQL procedures view_upload_form, print_upload_form, and insert_new_photo are the primary application components that implement the Upload photo page. Together, view_upload_form and print_upload_form create the HTML page that is displayed. The page contains a form tag, a portion of which is shown in Example 3-5. The target of the form is PHOTO_ALBUM.INSERT_NEW_PHOTO.
Example 3-5 contains some relevant lines of code in the print_upload_form procedure.
Example 3-5 Procedure print_upload_form
<form action="PHOTO_ALBUM.INSERT_NEW_PHOTO" method="post" enctype="multipart/form-data"> database.
Procedure insert_new_photo receives the form, processes the inputs, and stores the new image in the database.
First, the insert_new_photo procedure checks that a file name was entered into the upload form. The image size, MIME type, and BLOB locator for the image content are selected from the document upload table, and the size is checked to ensure that the image is not of zero length. If the description field is blank, a description is created using the file name.
Next, the ORDSYS.ORDIMAGE.INIT( ) function is called to initialize the thumb and image ORDImage object type columns with an empty BLOB for the new row to be stored in the photos table. A SQL SELECT FOR UPDATE statement fetches the newly initialized thumbnail image and full-size image object type columns for updating. A DBMS_LOB.COPY operation loads the image from the upload table into the image ORDImage object type column.
The ORDImage object method setProperties( ) reads the image and sets the image object attributes. Because some browsers cannot display some image formats inline, in this sample application, BMP formatted images are converted to a JPEG image format (for images with more than 8 bits of color), or a GIFF image format (for images with less than 9 bits of color) by calling the get_preferred_format function. A processCopy( ) operation is performed on the full-size image to create the thumbnail image.
The ORDImage object getMetadata( ) method is called to extract all supported types of image metadata. The root element of each XML document in the return vector is examined to discover the metadata type so that the documents can be stored in the correct columns.
Then, a SQL UPDATE statement stores the full-size image, the thumbnail image, and the image metadata documents in the database. Procedure sync_indexes is called to force an update of the text indexes. Finally, the form data input is deleted from the document upload table. A success message is returned to the browser, and the browser is redirected to the View album page.
Example 3-6 contains some relevant lines of code in the insert_new_photo procedure.
Example 3-6 Procedure insert_new_photo
--
-- Make sure a file name has been provided. If not, display an error
-- message, then re-display the form.
--
IF new_photo IS NULL OR LENGTH( new_photo ) = 0
THEN
print_page_header;
print_error( 'Please supply a file name.' );
print_upload_form;
print_page_trailer( TRUE );
return;
END IF;
--
-- Get the length, MIME type and the BLOB of the new photo from the
-- upload table.
--
SELECT doc_size,
mime_type,
blob_content
INTO upload_size,
upload_mime_type,
upload_blob
FROM photos_upload
WHERE name = new_photo;
--
-- Make sure we have a valid file.
--
IF upload_size = 0
THEN
print_page_header;
print_heading( 'Error message' );
htp.print( '<hr size="-1"><p>Please supply a valid image file.</p>' );
print_upload_form;
print_page_trailer( TRUE );
return;
END IF;
--
-- If the description is blank, then use the file name.
--
IF c_description IS NULL
THEN
c_description := new_photo;
pos := INSTR( c_description, '/', -1 );
IF pos > 0
THEN
c_description := SUBSTR( c_description, pos + 1 );
END IF;
c_description := SUBSTR( 'Image from file: ' ||
c_description || '.', 1, 40 );
END IF;
--
-- Insert a new row into the table, returning the newly allocated sequence
-- number.
INSERT INTO photos ( id, description, metaExif, metaIPTC, metaXMP,
image, thumb )
VALUES ( photos_sequence.nextval, c_description, NULL, NULL, NULL,
ORDSYS.ORDIMAGE.INIT(), ORDSYS.ORDIMAGE.INIT() )
RETURN id
INTO new_id;
--
-- Fetch the newly initialized full-size and thumbnail image objects.
--
SELECT image,
thumb
INTO new_image,
new_thumb
FROM photos
WHERE id = new_id
FOR UPDATE;
--
-- Load the photo from the upload table into the image object.
--
DBMS_LOB.COPY( new_image.source.localData, upload_blob, upload_size );
new_image.setLocal();
--
-- Set the properties. If the image format is not recognized, then
-- the exception handler will set the MIME type and length from the
-- upload table.
--
BEGIN
new_image.setProperties();
EXCEPTION
WHEN OTHERS THEN
new_image.contentLength := upload_size;
new_image.mimeType := upload_mime_type;
END;
--
-- Some image formats are supported by Oracle Multimedia but cannot be
-- displayed inline by a browser. The BMP format is one example.
-- Convert the image to a GIF or JPEG based on number of colors in the
-- image.
--
IF new_image.contentFormat IS NOT NULL AND
( new_image.mimeType = 'image/bmp' OR
new_image.mimeType = 'image/x-bmp' )
THEN
BEGIN
new_image.process(
'fileFormat=' ||
get_preferred_format( new_image.contentFormat ) );
EXCEPTION
WHEN OTHERS THEN
NULL;
END;
END IF;
--
-- Try to copy the full-size image and process it to create the thumbnail.
-- This may not be possible if the image format is not recognized.
--
BEGIN
new_image.processCopy( thumb_scale, new_thumb );
EXCEPTION
WHEN OTHERS THEN
new_thumb.deleteContent();
new_thumb.contentLength := 0;
END;
--
-- fetch the metadata and sort the results
--
BEGIN
metav := new_image.getMetadata( 'ALL' );
FOR i IN 1..metav.count() LOOP
meta_root := metav(i).getRootElement();
CASE meta_root
WHEN 'ordImageAttributes' THEN xmlORD := metav(i);
WHEN 'xmpMetadata' THEN xmlXMP := metav(i);
WHEN 'iptcMetadata' THEN xmlIPTC := metav(i);
WHEN 'exifMetadata' THEN xmlEXIF := metav(i);
ELSE NULL;
END CASE;
END LOOP;
EXCEPTION
WHEN OTHERS THEN
NULL;
END;
--
-- Update the full-size and thumbnail images in the database.
-- Update metadata columns
--
UPDATE photos
SET image = new_image,
thumb = new_thumb,
metaORDImage = xmlORD,
metaEXIF = xmlEXIF,
metaIPTC = xmlIPTC,
metaXMP = xmlXMP
WHERE id = new_id;
-- -- update the text indexes
-- sync_indexes;
--
-- Delete the row from the upload table.
--
DELETE FROM photos_upload WHERE name = new_photo;
COMMIT;
--
-- Redirect browser to display full album.
-- print_page_header(
'<meta http-equiv="refresh" content="2;url=PHOTO_ALBUM.VIEW_ALBUM">' );
print_heading( 'Photo successfully uploaded into photo album' );
You can use the View album and Search album pages to perform a keyword or phrase search of the metadata stored in the photo album. On either of these pages, enter the keyword or phrase in the Full text search: text entry field and click Search. This photo album application uses the CONTEXT text index to locate images that have metadata containing the text you entered. If the search is successful, the thumbnail versions of the matching images are displayed in a four-column table. Select the thumbnail image to view the full-size version, or select the description link below the thumbnail image to view the metadata for the image. If the search fails, the message "No photos were found" is displayed.
At the top of the Search album page, there is a navigation bar, which includes links to other photo album pages. From the Search album page, you can return to the View album page or select the Search metadata or Upload photo pages. These pages are described in Section 3.1.2.1, Section 3.1.2.7, and Section 3.1.2.2, respectively.
Figure 3-3 shows a Search album page that contains the results of a successful search operation.
Figure 3-3 Search album Page Showing Results
Full-text searching of the photo album is implemented by the view_album procedure. See Section 3.1.2.1 for a discussion of this procedure.
When you select a thumbnail image, the application directs you to the View entry page. This page displays the description of the image and the full-size version of the image.
At the top of the View entry page, there is a navigation bar, which includes links to other photo album pages. From the View entry page, you can return to the View album page, or select any of the View metadata, Write metadata, Search metadata, or Upload photo pages. These pages are described in Section 3.1.2.1, Section 3.1.2.5, Section 3.1.2.6, Section 3.1.2.7, and Section 3.1.2.2, respectively.
Figure 3-4 shows a View entry page that contains the description and the full-size version of an image.
Figure 3-4 View entry Page with a Full-Size Image
The PL/SQL procedures view_entry, print_image_link, and deliver_media are the primary application components that implement the View entry page. The procedure view_entry takes a single parameter, entry_id, which uniquely locates the image in the photos table. The description and image object are fetched from the photos table. The procedure print_image_link creates the HTML <img> tag, and then calls procedure deliver_media to fetch the image content. See Section 3.1.2.1 for more information about the print_image_link and deliver_media procedures.
Example 3-7 contains some relevant lines of code in the view_entry procedure.
Example 3-7 Procedure view_entry
--
-- Fetch the row.
--
BEGIN
SELECT htf.escape_sc(description), image
INTO sc_description, photo
FROM photos
WHERE id = entry_id;
EXCEPTION
WHEN no_data_found THEN
print_error( 'Image <b>' || htf.escape_sc(entry_id) ||
'</b> was not found.</p>' );
print_page_trailer( TRUE );
return;
END;
print_image_link( 'image', entry_id, sc_description,
photo.height, photo.width );
You can use the View metadata page to examine all the metadata for a specific image. Typically, you access this page from the View album page by selecting the description link below a thumbnail image. You can also access this page by selecting the View metadata link from the navigation bar. The View metadata page displays the thumbnail version of the image. To the right of the thumbnail image, there is a list of the metadata documents for this image. Each entry in the list is a link that takes you to the metadata document on the View metadata page.
At the top of the View metadata page, there is a navigation bar, which includes links to other photo album pages. From the View metadata page, you can return to the View album page, or select any of the View entry, Write metadata, Search metadata, or Upload photo pages. These pages are described in Section 3.1.2.1, Section 3.1.2.4, Section 3.1.2.6, Section 3.1.2.7, and Section 3.1.2.2, respectively.
Figure 3-5 shows a View metadata page that contains two types of metadata (XMP and ORDIMAGE) for an image.
Figure 3-5 View metadata Page with Metadata for an Uploaded Image
The PL/SQL procedures view_metadata and print_metadata are the primary application components that implement the View metadata page. The procedure view_metadata is passed the argument entry_id, which uniquely identifies the image in the photos table. A SELECT statement retrieves all the XMLtype metadata columns for the specified entry. If the metadata column is not NULL, procedure print_metadata is called to display the XML document inside an HTML <pre> tag.
Example 3-8 contains some relevant lines of code in the view_metadata procedure.
Example 3-8 Procedure view_metadata
--
-- Fetch the row.
--
SELECT metaOrdImage, metaEXIF, metaIPTC, metaXMP
INTO metaO, metaE, metaI, metaX
FROM photos
WHERE id = entry_id;
-- display the EXIF metadata
IF metaE IS NOT NULL THEN
htp.print( '<span class="bigBlue" id="exifMetadata">EXIF</span>' );
htp.print( '<br><pre>' );
print_metadata( metaE ); htp.print( '</pre>' );
END IF;
The print_metadata procedure accepts an XMLType document as an argument. It uses the getClobVal( ) method to access the document as a CLOB. The content of the CLOB is read in a loop and formatted in the HTML page using the htp.prints procedure. The htp.prints procedure escapes the '<' and '>' characters so that they are rendered properly by the Web browser.
Example 3-9 contains some relevant lines of code in the print_metadata procedure.
You can use the Write XMP metadata page to write new or replace existing XMP metadata in an image. Oracle Multimedia provides support for writing XMP metadata only. You can access the Write XMP metadata page by selecting the Write metadata link in the navigation bar from either the View entry page or the View metadata page.
The Write XMP metadata page displays the thumbnail version of the image to be modified. The page also displays an input form to collect metadata attributes in these five text entry fields:
Title: Specify a title for the photograph.
Creator: Enter the name of the person who took the photograph. This field is optional.
Date: Enter the date the photograph was taken. This field is optional.
Description: Enter a description, such as the subject of the photograph. This field is optional.
Copyright: Enter the month and year when the photograph was taken. This field is optional.
Click Write it! to send the form to the application and embed the metadata in XMP format in the image.
At the top of the Write XMP metadata page, there is a navigation bar, which includes links to other photo album pages. From the Write XMP metadata page, you can return to the View album page, or select any of the View entry, View metadata, Search metadata, or Upload photo pages. These pages are described in Section 3.1.2.1, Section 3.1.2.4, Section 3.1.2.5, Section 3.1.2.7, and Section 3.1.2.2, respectively.
Figure 3-6 shows a Write XMP metadata page with completed entries for an image.
Figure 3-6 Completed Write XMP metadata Page with XMP Metadata for an Uploaded Image
The PL/SQL procedure write_metadata receives the form input fields from the browser. The procedure creates an XML document (as a string buffer) that is valid to the Oracle Multimedia XMP schema http://xmlns.oracle.com/ord/meta/xmp. The string buffer is used to create an XMLType object.
A SELECT FOR UPDATE statement retrieves the image to be modified. The Oracle Multimedia method putMetadata( ) is called to embed the XML document into the image. The modified image is stored back to the photos table. Finally, procedure sync_indexes is called to update the text indexes.
Example 3-10 contains some relevant lines of code in the write_metadata procedure.
Example 3-10 Procedure write_metadata
-- Create the XMP packet it must be schema valid
-- to "http://xmlns.oracle.com/ord/meta/xmp"
-- and contain an <RDF> element. This example uses
-- the Dublin Core schema as implemented by Adobe XMP
buf := '<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp"
xsi:schemaLocation="http://xmlns.oracle.com/ord/meta/xmp
http://xmlns.oracle.com/ord/meta/xmp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title>' || htf.escape_sc(title) || '</dc:title>';
IF c_creator IS NOT NULL THEN
buf := buf || '<dc:creator>' || htf.escape_sc(c_creator)
|| '</dc:creator>';
END IF;
IF c_date IS NOT NULL THEN
buf := buf || '<dc:date>' || htf.escape_sc(c_date)
|| '</dc:date>';
END IF;
IF c_description IS NOT NULL THEN
buf := buf || '<dc:description>' || htf.escape_sc(c_description)
|| '</dc:description>';
END IF;
IF c_copyright IS NOT NULL THEN
buf := buf || '<dc:copyright>' || htf.escape_sc(c_copyright)
|| '</dc:copyright>';
END IF;
buf := buf || '
</rdf:Description>
</rdf:RDF>
</xmpMetadata>';
xmp := XMLType.createXML(buf, 'http://xmlns.oracle.com/ord/meta/xmp');
-- -- select image for update
-- description is selected to force update of CTX index
--
SELECT image, description
INTO img, des
FROM photos
WHERE id = entry_id
FOR UPDATE;
--
-- write the metadata
--
img.putMetadata( xmp, 'XMP' );
--
-- save updated image and new metadata to table
-- description updated to force update of CTX index
--
UPDATE photos
SET image = img,
metaXMP = xmp,
description = des
WHERE id = entry_id;
-- update the text indexes
sync_indexes;
The input data shown in Example 3-10 would result in the storage of the following metadata in the image:
<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp"
xsi:schemaLocation="http://xmlns.oracle.com/ord/meta/xmp
http://xmlns.oracle.com/ord/meta/xmp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title>Story time</dc:title>
<dc:creator>father</dc:creator>
<dc:date>July 4, 2001</dc:date>
<dc:description>family reading</dc:description>
<dc:copyright>mother</dc:copyright>
</rdf:Description>
</rdf:RDF>
</xmpMetadata>
You can use the Search metadata page to search a specific metadata type and to limit your search to a specific tag within a metadata document. You can access the Search metadata page by selecting the Search metadata link in the navigation bar of any photo album application Web page.
The Search metadata page displays a form with four fields to define how the search is to be performed. Use the menu in the Search in metadata: field to select the type of metadata (EXIF, IPTC, or XMP) to be searched. When this field is changed, the fields Search in tag: and Search method: are initialized with values that are appropriate to the type of metadata search.
Use the drop-down list in the Search in tag: field to limit the search to a specific XML element within a metadata document. The list is populated with element names that are appropriate for the selected metadata type. When the value --Any tag-- is showing, the search looks at all elements within the document type. When the XMP metadata type is selected, searches are limited to Description elements within the parent RDF element. If the metadata document is properly constructed, selecting RDF/Description in this field searches all relevant metadata within XMP documents.
In the Search method: field, select Contains to specify a search where an element contains the search string. Select Equals to specify a search where element values are matched exactly to the search string. For searches in XMP metadata, only the Contains search method is available.
Finally, enter a keyword or phrase in the Search string: field and click Search. If the search is successful, the thumbnail versions of the matching images are displayed in a four-column table. Select the thumbnail image to view the full-size version of an image. Or, select the description link below the thumbnail image to view the metadata for the image. If the search fails, the message "No photos matched the search criteria." is displayed.
At the top of the Search metadata page, there is a navigation bar, which includ es links to other photo album pages. From the Search metadata page, you can return to the View album page or select the Upload photo page. These pages are described in Section 3.1.2.1 and Section 3.1.2.2, respectively.
Figure 3-7 shows a Search metadata page that contains sample search criteria and results from a successful search operation.
Figure 3-7 Completed Search metadata Page for an Uploaded Image
The PL/SQL procedure search_metadata receives the form input fields from the Web browser. The search parameters are used to build a query to find images that contain the desired metadata. The search is accomplished using the SQL function XMLExists. The XMLExists function is used to search an XML document for content that matches a given XQuery expression. The function returns TRUE if the document matched the search, and FALSE otherwise.
For example, assume that the search_metadata procedure receives input that specifies to search the caption tag in IPTC metadata for an exact match of the word "farm". The query to accomplish this search is as follows:
SELECT id, description, thumb
FROM photos
WHERE xmlexists('declare default element namespace ' ||
' "http://xmlns.oracle.com/ord/meta/iptc"; $x' ||
'/iptcMetadata[//caption="farm"]' passing metaIptc as "x");
The XPath component of the XQuery expression, '/iptcMetadata[//caption="farm"]', specifies a search for all <caption> elements under the root element <iptcMetadata> where the <caption> content is "farm".
Example 3-11 contains some relevant lines of code in the search_metadata procedure.
Example 3-11 Procedure search_metadata
-- Set up search variables for EXIF documents.
IF mtype = 'exif' THEN
IF op = 'equals' THEN
xpath := '/exifMetadata[//' || tag || '="' || c_search || '"]';
ELSE -- default to contains
xpath := '/exifMetadata//' || tag ||
'[contains(., "' || c_search || '")]';
END IF;
xquery := 'declare default element namespace ' ||
' "http://xmlns.oracle.com/ord/meta/exif"; $x' || xpath;
OPEN album_cur FOR
SELECT id, description, thumb
FROM photos
WHERE xmlexists(xquery passing metaExif as "x");
-- Set up search variables for IPTC documents.
ELSIF mtype = 'iptc' THEN
IF op = 'equals' THEN
xpath := '/iptcMetadata[//' || tag || '="' || c_search || '"]';
ELSE -- default to contains
xpath := '/iptcMetadata//' || tag ||
'[contains(., "' || c_search || '")]';
END IF;
xquery := 'declare default element namespace ' ||
' "http://xmlns.oracle.com/ord/meta/iptc"; $x' || xpath;
OPEN album_cur FOR
SELECT id, description, thumb
FROM photos
WHERE xmlexists(xquery passing metaIptc as "x");
-- Set up search variables for XMP documents.
ELSIF mtype = 'xmp' THEN
-- default to contains
xpath := '//rdf:Description//*[contains(., "'
|| c_search || '")]';
-- Add rdf namespace prefix.
xquery := 'declare namespace rdf = ' ||
' "http://www.w3.org/1999/02/22-rdf-syntax-ns#"; ' ||
'declare default element namespace ' ||
' "http://xmlns.oracle.com/ord/meta/xmp"; $x' || xpath;
OPEN album_cur FOR
SELECT id, description, thumb
FROM photos
WHERE xmlexists(xquery passing metaXMP as "x");
ELSE
errorMsg := 'Search domain is invalid: ' || htf.escape_sc(mtype);
END IF;
print_search_form( mtype, tag, op, c_search );
htp.print('<hr size="-1">');
print_album( album_cur, 'No photos matched the search criteria.' );
The Oracle Multimedia Java Servlet Photo Album sample application demonstrates the use of the Oracle Multimedia Servlets and JSP Java API to upload and retrieve multimedia data to and from the database. Users access this photo album application to view the contents of the photo album, including thumbnail versions of each photograph, to view the full-size version of any photograph, and to upload new photographs into the album.
This photo album application demonstrates the use of the Oracle Multimedia image object type to upload and retrieve media data stored in Oracle Database.
When installed, this photo album application creates a table named photos and a sequence named photos_sequence.
The photos table is described by the following CREATE TABLE statement:
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;
The data type for the image and thumb columns are defined as Oracle Multimedia image object types to store the full-size images and the generated thumbnail images.
The photos_sequence sequence is defined by the following CREATE SEQUENCE statement:
CREATE SEQUENCE photos_sequence;
After installing the Oracle Database Examples media, the sample application files and README.txt file are located at:
<ORACLE_HOME>/ord/http/demo/servlet (on Linux and UNIX)
<ORACLE_HOME>\ord\http\demo\servlet (on Windows)
See the README.txt file for additional requirements and instructions on installing and using this sample application.
The following subsections provide more information about 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
In the <protocol> field, enter http://.
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.
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 Also: 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:
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.
The Oracle Multimedia JSP Photo Album sample application is a JavaServer Pages (JSP) application that demonstrates the use of the Oracle Multimedia Servlets and JSP Java API to upload and retrieve multimedia data to and from a database. Users access the JSP files that constitute the application to view the contents of the photo album, including thumbnail versions of each photograph, to view the full-size version of any photograph, and to upload new photographs into the album.
This photo album application demonstrates the use of the Oracle Multimedia image object type to upload and retrieve media data stored in Oracle Database.
This photo album application, when installed, creates a table named photos and a sequence named photos_sequence.
The photos table is described by the following CREATE TABLE statement:
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;
The data type for the image and thumb columns are defined as Oracle Multimedia image object types to store the full-size images and the generated thumbnail images.
The photos_sequence sequence is defined by the following CREATE SEQUENCE statement:
CREATE SEQUENCE photos_sequence;
After installing the Oracle Database Examples media, the sample application files and README.txt file are located at:
<ORACLE_HOME>/ord/http/demo/jsp (on Linux and UNIX)
<ORACLE_HOME>\ord\http\demo\jsp (on Windows)
See the README.txt file for additional requirements and instructions on installing and using this sample application.
The following subsections provide more information about 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
In the <protocol> field, enter http://.
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.
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:
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.
gp{"
h~w,!o|n*L+AzuL
0
p>JX_ {j^>! ǜ>ǡp
~Ĥ>JX惮cm
gNǜoN d~0A rQ%t!`H;6 66Eptkj*oY HQ0_-+e" 6ܲB2@JK!"PP?#r₃ K n%MҎC6ey|: ]#jG6Rdף%VGɝ$1azD 0Nq9 HI ,9?ؗ0%5=W$g ∅02"# $HI(4% 'n
>,'c߂jb+"kF
ֲFqǶ / +1~l&
4(r*31 zj\60(TB7*)@:>w 0`
,hˡ@HUtRI YXM/TJIT.҉-\Yaɼ[@WAn)bn6ccqYJ(
F QQ } Hp%rp}t jIv%)w*뵷Rڨo
HvMy;cNN)Ϝ$O Л@DUyTCUy\բG5uU#YfS5
*hB[!^çGV9ksLeʫ(6FKƲ:Y[ˮou{H#|/uVw]vN'Jk˂,ؠ vm
R8m"2ߞBvsGg8̛:q劻uؑ>eJuWw~x7^*(u uz>ewnX ٪zh
qL;qst,Ϗmގ柛{I^P# N 9.eaYR`4*h, #
YPqn丅a
XX^Q2c
@@P;aU&)}
` q w ]hYW%}ki_{t$ n`ԋ?4I `U@8+ 78,Y
"W|))]"u94Vh`чd'=)d .xwxP)NDIܰ5&VwEZ$؇-m x$r fK?˸QTc5GSYJZ$ؘ@ZaM I{\n WN,T
RFd)f<4$Z p- zKUN YNF o(Fo3ץX&q%-ƙh& yS(iy$ Om
!)H٣.]K!
N|y=ejQj:fxhY;IHUF ! VƬf eemk&k75ʌ)HU +nV\NRO\/]&3Ӆ7&k3)N=8
W&PYkԟC( l@!MЃU]
1ƀ`8WSxd?ܡJKZJCF} xV.V6&deZ6Ҩ.nkg
|&X fpp5- OBS9
8IPeA
6{bs ڔstܘ !(@q}|ul+0˹PV/.K
Į XS^Ag|gY[ƣI)3"!Iբҥr :0ţb 1|SaU} P31K @ֱ}Z[_ӷ@<00`.= V -h\
c 4"Ȁ{ ! /% v /! E@ڍ"M6M~`
h@FUZ@@lb&C %fbi"&D@
.`RUo\ hMro /
v`2@\X h@ 0@tj~c
Ѐ6`JDG ``WblpD(oA
de B"A 0@
h ! A
$ ;!>06 )cZC%6\dh%d+&z1D @ `| :
K 1 P`
j/\jh 1ܐ ~` ,rk>v v@\$dbb0>+ f
eq"#a'P
i:m /"h # @>&l$~Zxqee Ȯ M P
(
+M"*#
ot/o~ H
Ql`r`~M r+a6 Z`< D `v`lfE&4r#p˲L$ NK2=gSj r~ '|2g-8h0$eb&v>l2 P8sE(R)
){O*M:S+w l@-@ cF/PHTL
X_v@~
&gD7S= h' `pvp Bg5B+ A~ A L@ PX4 ba
%$fPcp%nG-6ekUt*JS8/@f
S::Ks@F
i|/|N2o`_
а=pTLaC Q!s`
$? ^A 2_(SS5uD
UEF_CFQr
ff6sS%:5C@:k> .&T P:%H Дt*ۀB R
ZtKK5Ll0b2
}/ ``_U># Nh |\.
t` @ $V4 r;808c
L+y
. X!\/ )5US
Ԁq?%߀56-~v&&\ "uiYiZOiY6kS\a ]Дb_TO#_ "`TX " ؠ kB A1u4SNc .c pl9@Zv!^..@`FYr0'lNjckrT8 &~ggo,iѣw}w7xl/"k[&wO
O "% ^ߖ_"B\р6H ob ApC9d8t Wcz46V~M~_$s!btU3
FЍH`ތVM&.g?uR7oWwˋwxxCXxvjc|dwilKLE_)"^ _ov|7UX(}EqXqO0 h 0Z"]'\ 1c&E4@HC.Ft DD[@9\B#.X;WG%%
(gVmF@X\[:U* "K 9iSxgdy%DXǯlO"b nSmtn
ْ)7>X'b wXׂZǶc 1M3
Fd@sH??*~<`h79F6߬Wb͌֒عY83TKo`:K:+a7JN3Y40q
JLzVJjV\|G>j Glr0@S Ci` $cD@9#W?IT%u{߶^y4ܙYЊSsӞu'ZAXX3 CX9W
58j.ec z%Ƣe{
qx sTL4LYciAsG.n4D@@DjΉuI[uucU*)U8xګӫ
S34\O ĚeWGX(Oؠ¨G4HWmMc@AR4@ iٽ%G6[F
6@?&(T$̴OkX7jH0)4\j@Yk:RP
S6;7lQeﬣj#jCTc<"|\^V
/ 0Zbԕ]i` bw%Q7z]4[z`vʛTi8\?^@9pgU\"m-M.PKAD|K\[39?GͿ jL+jP=Fv'0ÐA%dk@x\1 C&GE@` !;;
G] zq7'oW]X߈gc"Sio[I \Q`k/]y :I9՜%-}sG \:{-:͒l@`Xk Au*i<#]fᅴ$Q#^UZ%] \ϥ ]\K]WzMؠoxͺ3ޒ+1<}ͥ|ĈxGUIjqs ^co7h#2 % !9ݐEU~.:[ޠk^=Ͻ҇7#8}0GxGX\^ kZ/:Xi aD`79`I Q?UY? W `im!y'پ~? ` W (*?*-` ^?4 w?" < B :|1ĉ+Z1ƍ ;z2ȑ$K<2Å U| 3̙4kڼ3Ν
Y 4СD=ԦϘ68 cԤ4:jpjTY=:
ဦX%5eڰ@ 5Ds}kqLRpmJoƴc H@.Dt9
` f NfWuIWM _m=yב[^st']ՙZsiyDAZ ϞuI>gJim e֕--:Xl^#x+}w\ f8nf>nb[>P {x sl]CK Q$~_o v)a q'& 9/_ X"AM]yV7$86wo_eXrCca1WזՑ*k]+']#.ҝ1 \I=Ctuu!;º(VVjpw8P=rx~6*n.6zwk =A8cxq^ .6I鿆c=۠'s*1)ٌ]S~UR7#Az: ayi࿋=\ me=g[^soXL_&}C5;qR
DD"v_,/T Sǒ>˵1 u/8y 6o:8dQ
PL*źP S2JBhEo gFBbH!Sw ytV v4
3GD003 ѐ
2}s`/NefOǂWi;NȽxO&"
@@B#B1BoKb y\3|ᇢyB
Colh.نwc%&`JT( Q ^.1kB{0)~ɏO ?aQb {
j@
^p1~ ~K|G@qP跄v7xڇ{xy P{w }+x
}ҷ+qw7y Gy'ǂ+ၟ{W~,p#0xX0|>H4Hy&Hy<2xw|' w~E{G+ ?3x8(& s'r() Wx*xWxi(|px
nh+
sHLj+p~X{}fȅx~Xݰ0`z0xzzȊ+ W8( {}(yW8(@Xq{!8xX Hv)'8ЊMH ~H}g~zWz~9,X}g|jXh x|'~Ɍi7|Yx)؊-1uwsz(
;w]{#;95Hٓ$pøGH72i[ȅ Ny )aYW
ayQ{ X'((YYDvj1~` [HGjَyj88)I7xbX~b,Q3Hi9ؓdg~m9^u'z,Iw}醇Y.Pg9N 7G~ȉ GyyŹܠp{IЖ㹑尞`yh=@ ⹐:Y߉Xw|
({Ȅ)%ixz1iחW~x#}ЅyHG+h@xg 9z
G~:CJ Xمw':x)
3كRF<9>Z fiG:'hH,ڥ_ZSz
7
Ue/=gv
Ze/q}xw)vwzʩ:G꩝zvu:u:b
ګ:ZzȚʺڬ:ʫzJvsڭZsrZzr皮
rڮqZZگ s[{v r ۰vZr ۱ ; $ks[(+#$, . +r \7
:<;B+>+yEG 0
2ѴCP
UxNR5 S۳?+] p j bKq; 9a ox;<;A7`,{{~ m [G
s[f+=h +31 gP6\E;˴~ W\˳ @۹,5_;WK
~ mk-w M 8{{ Z k y 拼}++k[ ,ѽʛ j[:x0{+B
+ 2BK ,q K\O 5z0(, KKL&,PT!r뿧 el oy+i
A ?a &JZ!
ʦAң
09QlO:PL3?Kʭ
# )j91Aa5>=AAg1 6 6* Р>Z"P ۊZ_ % ;X{>* ʲAT>K={:z+𩃋 0 K;yd:Q{* { y+KGۡ~
I 0˵A
I'۵ʱ): 8 P˺ 8Aau 멂˳<+6 :`~K Z ;Z: j 37i6`Y
`ij [ Q˦"6P
Oj6i
/ {!sK.{9! k* 7kJB˷= 6\6\uEβ6!ZR{Uߺ
dg -+6@ @. p qak W J2l@7l=<ÄlZ>+=|75 K\E
`
c*
$ 6jY{JjJcJ#z
Pp,˲Z {ͳDKٛ{ʽ` +A[D뼦J))|ll, !
킠 ii{E@CiѹD;$}%(
)}*OҘ2m&+M7-=0ڞiB
ﮆDb+_,Nn#J"U
/UspCY.|v:1c}45w3x^]躣\:`۶}*'6&%X@̃GZ<
w.݄̓JYeT 03\X{⽪wKEldHlT[^E')J>}G,!,g=f uy3py7gvEgq/](p:pd`Q肠5p W`88x;C}7 -ǭ\/?H*)(:hg|.Pg@@ "'B LH : :Tq#ƌ
sB
yqG.Yy)% /vl9RfNh'&ТF-jQ;Nu:tRTV:iԬO~uH,X;)J(Th*6-ݺuK^Eya2x1ČK2 ʌ*cάy$D; `4ЦONz5֮Q8*{7o6Pz6m@x 鎛5n@ϝN w'3|߃' xD@!_>ӟ?}|קI$U z F0!P RORNqDF!M "< 'b~XFvt sQJbH/9҈N2uHPf2ROҤF.D0
UoOaUR@q$WUYv唘N9f[b[uVyu^~I^x 1BcAeMfei a "|Xb hjlTF*RE[qy Gvnx]uݡ$z` g! 'z"`{|A^ z.z* sQ ȑ&YJ2bG0*$Q!|B" (tFo8 P0F"^4!P Y#O<.eOQ5uY hq&Ul`eVeZdIu^oZ`X=jƱ NPb b#3pL<8\";zoBVz։(N5
;:c\n J%N~)dnQMzo[.HrFPPDԪ@" #Bf,!ryQNj3Jkq/4ڮ5L/-0HP
8< 2:˚EJD@c?| a@"d|3[ A GdF3
pI$t iH% cN2n7G.6;9#͘:dDpBP!0MH:n2pƣp'E`;k(ňRn
* '"80?-n"+ $2RHڌAw"qBR2#JWhm$Ć/RdDV 8=C?LE$2