Oracle Multimedia provides the ORDDoc object type, which supports the storage and management of any media data including image, audio, and video.
The ORDDoc object type is defined in the orddspec.sql file. After installation, this file is available in the Oracle home directory at:
<ORACLE_HOME>\ord\im\admin (on Windows)
<ORACLE_HOME>/ord/im/admin (on Linux and UNIX)
This chapter contains these sections:
The examples in this chapter use the ONLINE_MEDIA table in the Product Media (PM) sample schema. To replicate the examples on your computer, begin with the examples shown in the reference pages for the ORDDoc constructors and the import( ) and importFrom( ) methods. Then, substitute your media files for those in the examples.
The example for the constructor ORDDoc for BLOBs uses the test document table TDOC. (See Section 7.2.3 for the definition of this table.)
Note:
If you manipulate the media data itself (by either directly modifying the BLOB or changing the external source), you must ensure that the object attributes stay synchronized and the update time is modified; otherwise, the object attributes will not match the media data.See Also:
Oracle Database Sample Schemas for more information about the PM schema
Issue the following statements before executing the examples, where c:\mydir\work is the directory where the user ron can find the image, audio, and video data:
CONNECT sys as sysdba CREATE OR REPLACE DIRECTORY FILE_DIR as 'c:\mydir\work'; GRANT READ ON DIRECTORY FILE_DIR TO 'ron';
Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx (RAW) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure, initialize it to NULL, and invoke the openSource( ) method. At this point, the source plug-in can initialize context for this client. When processing is complete, the client must invoke the closeSource( ) method.
Methods invoked from a source plug-in call have the first argument as ctx (RAW).
Methods invoked at the ORDDoc level that are handed off to the format plug-in for processing have ctx (RAW) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure and initialize it to NULL.
Note:
In the current release, none of the plug-ins provided by Oracle and not all source or format plug-ins use the ctx argument, but if you code as previously described, your application should work with current or future source or format plug-ins.Use any of the individual set methods to set the attribute value for an object for formats not natively supported; otherwise, for formats natively supported, use the setProperties( ) method to populate the attributes of the object or write a format plug-in.
The ORDDoc object type supports the storage and management of any media data including image, audio, and video. The attributes for this object type are defined as follows in the orddspec.sql file:
------------------- -- TYPE ATTRIBUTES ------------------- source ORDSource, format VARCHAR(80), mimeType VARCHAR(80), contentLength INTEGER, comments CLOB,
where:
source: the ORDSource where the media data is found.
format: the format in which the media data is stored.
mimeType: the MIME type information.
contentLength: the length of the media data stored in the source.
comments: the metadata information of the media object.
Note:
The comments attribute is populated by the setProperties( ) method when the setComments parameter is TRUE. Oracle recommends that you not write to this attribute directly.This section describes these ORDDoc constructor functions:
ORDDoc(SELF IN OUT NOCOPY ORDSYS.ORDDoc,
data IN BLOB,
setproperties IN INTEGER DEFAULT 0)
RETURN SELF AS RESULT
Constructs an ORDDoc object from a BLOB. The data stored in the BLOB is copied into the ORDDoc object when the constructed ORDDoc object is inserted or updated into a table.
Media content stored in a BLOB.
Indicator flag that determines whether the setProperties( ) method is called in the constructor. If the value is 1, the setProperties( ) method is called. If the value is 0, the method is not called. The default is 0.
Use this constructor to create an ORDDoc object when the media content is stored in either a temporary or a persistent BLOB.
Create an ORDDoc object from a BLOB object and insert it into the table.
Note:
The user who runs this statement must have the SELECT privilege on the tabletdoc created by the user mediauser.
See Section 7.2.3 for a definition of the test document table TDOC.
INSERT INTO pm.online_media (product_id, product_testimonials) SELECT 2808, ORDSYS.ORDDoc(t.document) FROM mediauser.tdoc t WHERE t.n = 1;
ORDDoc( SELF IN OUT NOCOPY ORDSYS.ORDDoc,
source_type IN VARCHAR2 DEFAULT 'LOCAL',
source_location IN VARCHAR2 DEFAULT NULL,
source_name IN VARCHAR2 DEFAULT NULL,
setproperties IN INTEGER DEFAULT 0
) RETURN SELF AS RESULT
Constructs an ORDDoc object from a specific source. By default, an empty object with a local source is constructed.
The type of the source media data. Valid values are: FILE, HTTP, LOCAL, or user-defined. The default is LOCAL.
The parameter value LOCAL indicates that the data is stored in Oracle Database. The parameter value LOCAL is never stored in the srcType attribute. Rather, this parameter value indicates that the data is stored in Oracle Database in the localData attribute. (See Section 2.2 for a description of the ORDSource object.)
The location from which the source media data is to be imported. (See Table 2-2.)
The name of the source media data. (See Table 2-3.)
Indicator flag that determines whether the setProperties( ) method is called in the constructor. If the value is 1, the setProperties( ) method is called. If the value is 0, the method is not called. The default is 0.
Use this constructor to create an ORDDoc object when the media content is not already stored in a BLOB, as in any of these situations:
Create an ORDDoc object from a specified source:
-- Construct an ORDDoc object from an external file and insert it into the table.
INSERT INTO pm.online_media (product_id, product_testimonials)
VALUES (2999, ORDSYS.ORDDoc('FILE', 'FILE_DIR', 'modem.jpg'));
-- Initialize an ORDDoc object in the table.
INSERT INTO pm.online_media (product_id, product_testimonials)
VALUES(2808, ORDSYS.ORDDoc());
This section presents reference information about the Oracle Multimedia methods used specifically for media data manipulation.
Chapter 2 presents reference information about the Oracle Multimedia methods that are common to ORDAudio, ORDDoc, ORDImage, and ORDVideo. Use the methods presented in both chapters to get and set attributes, and to perform metadata extractions.
This section describes these methods:
See Also:
Oracle Database Concepts for more information about object types and methods
getContentInLob(ctx IN OUT RAW,
dest_lob IN OUT NOCOPY BLOB,
mimeType OUT VARCHAR2,
format OUT VARCHAR2);
Copies data from a data source into the specified BLOB. The BLOB must not be the BLOB in the source.localData attribute (of the embedded ORDSource object).
The source plug-in context information. (See Section 4.2.)
The LOB in which to receive data.
The MIME type of the data; this may or may not be returned.
The format of the data; this may or may not be returned.
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
ORDSourceExceptions.METHOD_NOT_SUPPORTED
This exception is raised if you call the getContentInLob( ) method and this method is not supported by the source plug-in being used.
See Appendix G for more information about these exceptions.
Get data from a data source and put it into the specified BLOB:
DECLARE
obj ORDSYS.ORDDoc;
tempBLob BLOB;
mimeType VARCHAR2(4000);
format VARCHAR2(31);
ctx RAW(64) :=NULL;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2808 ;
IF (obj.isLocal()) THEN
DBMS_OUTPUT.put_line('Local is true');
END IF;
DBMS_LOB.CREATETEMPORARY(tempBLob, true, 10);
obj.getContentInLob(ctx,tempBLob, mimeType,format);
DBMS_OUTPUT.PUT_LINE('Length: ' || TO_CHAR(DBMS_LOB.getLength(tempBLob)));
EXCEPTION
WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
DBMS_OUTPUT.put_line('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
WHEN OTHERS THEN
DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
See Appendix G for more information about this exception.
Get the content length of the media data:
DECLARE
obj ORDSYS.ORDDoc;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2808 ;
IF (obj.isLocal()) THEN
DBMS_OUTPUT.put_line('Local is true');
END IF;
DBMS_OUTPUT.PUT_LINE('Content length is ' || TO_CHAR(obj.getContentLength()));
END;/
ORDDocExceptions.INVALID_FORMAT_TYPE
This exception is raised if you call the getFormat( ) method and the value of the format attribute is NULL.
See Appendix G for more information about this exception.
See the example in setFormat( ).
Transfers media data from an external media data source to the source.localData attribute (of the embedded ORDSource object) within the database.
The source plug-in context information. This parameter must be allocated and initialized to NULL. If you are using a user-defined source plug-in, call the openSource( ) method. (See Section 4.2.)
A value that determines whether the setProperties( ) method is called. If the value of this parameter is TRUE, then the setProperties( ) method is called to read the media data to get the values of the object attributes and store them in the object attributes; otherwise, if the value is FALSE, the setProperties( ) method is not called. The default value is FALSE.
Use the setSource( ) method to set the source.srcType, source.srcLocation, and source.srcName attributes (of the embedded ORDSource object) for the external source before calling the import( ) method.
After importing data from an external media data source to a local source (within Oracle Database), the source information remains unchanged (that is, pointing to the source from where the data was imported).
Invoking this method implicitly calls the setUpdateTime( ) and setLocal( ) methods.
If the value of the source.srcType attribute is FILE, the source.srcLocation attribute contains the name of a database directory object that contains the file to be imported, and the source.srcName attribute contains the name of the file to be imported. You must ensure that the directory for the external source location exists or is created before you use this method.
The import( ) method reads only from a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ access.
For example, the following SQL*Plus commands create a directory object and grant the user ron permission to read any file within the directory c:\mydir\work:
CONNECT sys as sysdba
Enter password: password
CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY FILE_DIR TO ron;
See Section 4.1 for more information about directory and table definitions.
If the value of the source.srcType attribute is HTTP, the source.srcLocation attribute contains the base URL needed to find the directory that contains the object to be imported, and the source.srcName attribute contains the name of the object to be imported.
This method uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on Linux and UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package must use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server not be used for URLs in the specified domain.
See Also:
Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP package
If the value of the source.srcType attribute is a user-defined name, the source.srcLocation attribute contains an identifier string required to access the user-defined object to be imported, and the source.srcName attribute contains the name of the object to be imported.
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
This exception is raised if you call the import( ) method and the value of the source.srcType attribute is NULL.
ORDSourceExceptions.METHOD_NOT_SUPPORTED
This exception is raised if you call the import( ) method and the import( ) method is not supported by the source plug-in being used.
ORDSourceExceptions.NULL_SOURCE
This exception is raised if you call the import( ) method and the value of the source.localData attribute is NULL.
ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION
This exception is raised if you call the import( ) method and the setProperties( ) method raises an exception from within the media plug-in.
See Appendix G for more information about these exceptions.
Import media data from an external media data source into the local source:
DECLARE
obj ORDSYS.ORDDoc;
ctx RAW(64) :=NULL;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2808 FOR UPDATE;
DBMS_OUTPUT.PUT_LINE('setting and getting source');
DBMS_OUTPUT.PUT_LINE('--------------------------');
-- set source to a file
obj.setSource('file','FILE_DIR','printer.rm');
-- get source information
DBMS_OUTPUT.PUT_LINE(obj.getSource());
-- import data
obj.import(ctx,FALSE);
-- check size
DBMS_OUTPUT.PUT_LINE('Length:' ||TO_CHAR(DBMS_LOB.getLength(obj.getContent())));
UPDATE pm.online_media SET product_testimonials=obj WHERE product_id=2808;
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
END;
/
importFrom(ctx IN OUT RAW,
source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2
set_prop IN BOOLEAN);
Transfers media data from the specified external media data source to the source.localData attribute (of the embedded ORDSource object) within the database.
The source plug-in context information. This parameter must be allocated and initialized to NULL. If you are using a user-defined source plug-in, call the openSource( ) method. (See Section 4.2.)
The type of the source media data. (See Table 2-1.)
The location from which the source media data is to be imported. (See Table 2-2.)
The name of the source media data. (See Table 2-3.)
A value that determines whether the setProperties( ) method is called. If the value of this parameter is TRUE, then the setProperties( ) method is called to read the media data to get the values of the object attributes and store them in the object attributes; otherwise, if the value is FALSE, the setProperties( ) method is not called. The default value is FALSE.
This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.
After importing data from an external media data source to a local source (within Oracle Database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.
Invoking this method implicitly calls the setUpdateTime( ) and setLocal( ) methods.
If the value of the source_type parameter is FILE, the source_location parameter contains the name of a database directory object that contains the file to be imported, and the source_name parameter contains the name of the file to be imported. You must ensure that the directory indicated by the source_location parameter exists or is created before you use this method.
The importFrom( ) method reads only from a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ access.
For example, the following SQL*Plus commands create a directory object and grant the user ron permission to read any file within the directory c:\mydir\work:
CONNECT sys as sysdba
Enter password: password
CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY FILE_DIR TO ron;
See Section 4.1 for more information about directory and table definitions.
If the value of the source_type parameter is HTTP, the source_location parameter contains the base URL needed to find the directory that contains the object to be imported, and the source_name parameter contains the name of the object to be imported.
This method uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on Linux and UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package must use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server not be used for URLs in the specified domain.
See Also:
Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP package
If the value of the source_type parameter is a user-defined name, the source_location parameter contains an identifier string required to access the user-defined object to be imported, and the source_name parameter contains the name of the object to be imported.
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
This exception is raised if you call the importFrom( ) method and the value of the source_type parameter is NULL.
ORDSourceExceptions.METHOD_NOT_SUPPORTED
This exception is raised if you call the importFrom( ) method and this method is not supported by the source plug-in being used.
ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION
This exception is raised if you call the importFrom( ) method and the setProperties( ) method raises an exception from within the media plug-in.
See Appendix G for more information about these exceptions.
Import media data from the specified external data source into the local source:
DECLARE
obj ORDSYS.ORDDoc;
ctx RAW(64) :=NULL;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id=2999 FOR UPDATE;
DBMS_OUTPUT.PUT_LINE('setting and getting source');
DBMS_OUTPUT.PUT_LINE('--------------------------');
-- set source to a file
-- import data
obj.importFrom(ctx,'file','FILE_DIR','modem.jpg',FALSE);
-- check size
DBMS_OUTPUT.PUT_LINE('Length: '||TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent())));
DBMS_OUTPUT.PUT_LINE(obj.getSource());
UPDATE pm.online_media SET product_testimonials=obj WHERE product_id=2999;
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
END;
/
ORDDocExceptions.NULL_INPUT_VALUE
This exception is raised if you call the setFormat( ) method and the value of the knownFormat parameter is NULL.
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
See Appendix G for more information about these exceptions.
Set the format for some media data:
DECLARE
obj ORDSYS.ORDDoc;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2808 FOR UPDATE;
obj.setFormat('PDF');
DBMS_OUTPUT.put_line('format: ' || obj.getformat());
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDDocExceptions.NULL_INPUT_VALUE THEN
DBMS_OUTPUT.put_line('ORDDocExceptions.NULL_INPUT_VALUE caught');
WHEN OTHERS THEN
DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/
Reads the media data to get the values of the object attributes and then stores them in the object attributes. This method sets the properties for these attributes of the media data: format, MIME type, and content length. It populates the comments field of the object with an extensive set of format and application properties in XML form if the value of the setComments parameter is TRUE.
Note:
This method works for only natively supported audio, image, and video formats. See Appendix A, Appendix B, and Appendix C, respectively, for information about these formats.The format plug-in context information. (See Section 4.2.)
A Boolean value that indicates whether the comments field of the object is populated. If the value is TRUE, then the comments field of the object is populated with an extensive set of format and application properties of the media object in XML form; otherwise, if the value is FALSE, the comments field of the object remains unpopulated. The default value is FALSE.
If the property cannot be extracted from the media source, then the respective attribute is set to NULL.
If the format attribute is set to NULL, then the setProperties( ) method uses the default format plug-in; otherwise, it uses the plug-in specified by the format.
ORDDocExceptions.DOC_PLUGIN_EXCEPTION
This exception is raised if you call the setProperties( ) method and the media plug-in raises an exception.
ORDDocExceptions.NULL_SOURCE
This exception is raised when the value of the ORDDoc.source attribute is NULL.
See Appendix G for more information about these exceptions.
Example 1:
Set the property information for known media attributes:
DECLARE
obj ORDSYS.ORDDoc;
ctx RAW(64) :=NULL;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2808 FOR UPDATE;
obj.setProperties(ctx,FALSE);
DBMS_OUTPUT.put_line('format: ' || obj.getformat());
UPDATE pm.online_media SET product_testimonials = obj
WHERE product_id=2808;
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
WHEN OTHERS THEN
DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/
Example 2:
Set the property information for known media attributes and store the format and application properties in the comments attribute. Create an extensible index on the contents of the comments attribute using Oracle Text:
DECLARE
obj ORDSYS.ORDDoc;
ctx RAW(64) :=NULL;
BEGIN
SELECT product_testimonials INTO obj FROM pm.online_media
WHERE product_id = 2999 FOR UPDATE;
obj.setProperties(ctx,TRUE);
DBMS_OUTPUT.put_line('format: ' || obj.getformat());
UPDATE pm.online_media SET product_testimonials = obj
WHERE product_id=2999;
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
WHEN OTHERS THEN
DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/