2.1 Examples for Common Methods

The examples in this chapter use the ONLINE_MEDIA table in the Product Media (PM) sample schema. These examples assume that the table has been populated as shown in the examples in Chapter 3, Chapter 4, Chapter 5, and Chapter 6.

Note:

The Oracle Multimedia methods are designed to be internally consistent. If you use Oracle Multimedia methods (such as import( ) or image process( )) to modify the media data, Oracle Multimedia ensures that object attributes remain synchronized with the media data. However, if you manipulate the 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 data.

2.2 Embedded ORDSource Object

The ORDSource object is embedded within the ORDAudio, ORDDoc, ORDImage, and ORDVideo object types. The ORDSource object type supports access to a variety of sources of multimedia data. It supports access to data sources locally in a BLOB within Oracle Database, externally from a BFILE on a local file system, externally from a URL on an HTTP server, or externally from a user-defined source on another server.

If the data is stored locally in a BLOB within Oracle Database, the localData attribute is used to find the media data, and the local flag indicates that the data is local. The srcType, srcLocation, and srcName attributes are not used.

If the data is stored externally in a BFILE, a URL, or a user-defined source, the srcType, srcLocation, and srcName attributes are used to find the media data, and the local flag indicates that the data is external.

See ORDSource Object Type for details on how the ORDSource object type is defined, including these ORDSource attributes:

localData: the locally stored multimedia data stored as a BLOB within the object.

2.2.1 Definition of the srcType Attribute

The srcType value FILE is a reserved word for the BFILE source plug-in provided by Oracle. To implement your own file plug-in, select a different name (for example: MYFILE).

HTTP

The srcType value HTTP is a reserved word for the HTTP source plug-in provided by Oracle.

2.2.2 Definition of the srcLocation Attribute

The valid values for the srcLocation attribute, for the corresponding srcType values, are listed in Table 2-2.

Table 2-2 srcLocation Values for Corresponding srcType Values

srcType

Location Value

FILE

The name of the database directory object

HTTP

The base URL to locate the media directory (the prefix http:// is not required)

<name>

An identifier string required to access a user-defined source

2.2.3 Definition of the srcName Attribute

The valid values for the srcName attribute, for the corresponding srcType values, are listed in Table 2-3.

Table 2-3 srcName Values for Corresponding srcType Values

srcType

Location Name

FILE

The name of the file

HTTP

The name of the object

<name>

The name of the object

2.3 Important Notes for Common Methods

Methods invoked at the ORDSource level that are handed off to a 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 at the ORDAudio, ORDDoc, or ORDVideo level that are handed off to a 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.

For ORDAudio, ORDDoc, or ORDVideo object types, use any of the individual set methods to set the attribute value for an object for formats that are not natively supported; or write a format plug-in, set the format, and call the setProperties( ) method to invoke the new format plug-in. Otherwise, for formats that are natively supported, use the setProperties( ) method to populate the attributes of the object.

For ORDImage object types, use the setProperties( ) method to populate the attributes of the object. Use the setProperties( ) for foreign images method for formats that are not natively supported.

2.4 Important Installation and Upgrade Considerations

A new database security measure introduced in Oracle Database 11g Release 2 (11.2) requires additional configuration steps for Oracle Multimedia applications using HTTP sources for media content. You can use the following query to determine if a media column contains HTTP sources. The query assumes that the table name is MEDIA_TABLE and the column name is MEDIA_COLUMN.

SELECT count(*)
FROM MEDIA_TABLE m
WHERE m.MEDIA_COLUMN.source.srcType = 'HTTP'
AND m.MEDIA_COLUMN.source.local IS NOT NULL
AND m.MEDIA_COLUMN.source.local <> 1

Oracle Multimedia uses the PL/SQL package UTL_HTTP to access media content for HTTP sources. Application users must have the appropriate permissions to connect to the remote host. For example, to grant the user SCOTT permission to access HTTP content located at the host wwww.oracle.com:80, the database administrator must execute the following commands:

clearLocal( )

Format

clearLocal( );

Description

Resets the source.local attribute (of the embedded ORDSource object) to indicate that the data is stored externally. When the source.local attribute is set to 0, media methods look for corresponding data using the source.srcLocation, source.srcName, and source.srcType attributes.

Parameters

None.

Usage Notes

This method sets the source.local attribute to 0, meaning the data is stored externally outside the database.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

closeSource( )

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

Usage Notes

The RETURN INTEGER is 0 (zero) for success and greater than 0 (for example, 1) for failure. The exact number and the meaning for that number is plug-in defined. For example, for the file plug-in, 1 might mean "File not found," 2 might mean "No such directory," and so on.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the closeSource( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the closeSource( ) method and this method is not supported by the source plug-in being used.

deleteContent( )

Format

deleteContent( );

Description

Deletes the BLOB from the source.localData attribute (of the embedded ORDSource object), sets the source.local attribute to zero (to indicate that data is not local), and updates the source.updateTime attribute.

Parameters

None.

Usage Notes

This method can be called after you export the data from the local source to an external data source and you no longer need this data in the local source.

Call this method when you want to update the object with a new object.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

export( )

Copies data from the BLOB in the source.localData attribute (of the embedded ORDSource object) to a corresponding external data source.

Note:

The export( ) method provides native support only when the value of the source_type parameter is FILE. In this case, the data is written to a file within a directory that is accessible to Oracle Database. User-defined sources may support the export( ) method to provide WRITE access to other types of data stores.

The type of the external source data. This parameter is not case sensitive. (See Table 2-1.)

source_location

The location to which the source data is to be exported. (See Table 2-2.)

source_name

The name of the object to which the data is to be exported. (See Table 2-3.)

Usage Notes

After data is exported, all attributes remain unchanged and source.srcType, source.srcLocation, and source.srcName are updated with input values. After calling the export( ) method, you can call the clearLocal( ) method to indicate the data is stored outside the database and call the deleteContent( ) method to delete the content of the source.localData attribute.

When the source_type parameter has a value of FILE, the source_location parameter specifies the name of an Oracle directory object, and the source_name parameter specifies the name of the file in which the data is to be contained.

The export( ) method writes only to 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 and WRITE access.

For example, the following SQL*Plus commands create a directory object and grant the user ron permission to read and write any file within the directory c:\mydir\work:

-- Create the directory to which you want users to export data. Then,
-- grant read and write access to the directory for the user who will
-- be doing the exporting, in this case the user is ron.
CONNECT sys as sysdba
CREATE OR REPLACE DIRECTORY FILE_DIR as 'c:\mydir\work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO 'ron';
BEGIN
-- Connect as the user ron:
CONNECT ron
Enter password: password
set serveroutput on;
set echo on;
DECLARE
obj ORDSYS.ORDImage;
ctx RAW(64) :=NULL;
BEGIN
SELECT product_photo INTO obj FROM pm.online_media
WHERE product_id = 3515;
obj.export(ctx,'file','FILE_DIR','testimg.jpg');
COMMIT;
EXCEPTION
WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
DBMS_OUTPUT.PUT_LINE('Source METHOD_NOT_SUPPORTED caught');
WHEN OTHERS THEN
DBMS_OUTPUT.PUT_LINE('OTHER EXCEPTION caught');
END;
/

getBFile( )

Format

getBFile( ) RETURN BFILE;

Description

Returns the LOB locator of the BFILE containing the media.

Parameters

None.

Usage Notes

This method constructs and returns a BFILE using the stored source.srcLocation and source.srcName attribute information (of the embedded ORDSource object). The source.srcLocation attribute must contain a defined directory object. The source.srcName attribute must be a valid file name and source.srcType must be FILE.

Pragmas

PRAGMA RESTRICT_REFERENCES(getBFile, WNDS, WNPS, RNDS, RNPS)

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if the value of the source.srcType attribute is NULL.

ORDSourceExceptions.INVALID_SOURCE_TYPE

This exception is raised if the value of the source.srcType attribute is other than FILE.

getMimeType( )

Format

getMimeType( ) RETURN VARCHAR2;

Description

Returns the MIME type for the data. This is a simple access method that returns the value of the mimeType attribute.

Parameters

None.

Usage Notes

If the source is an HTTP server, the MIME type information is read from the HTTP header information when the media is imported and stored in the object attribute. If the source is a file or BLOB, the MIME type information is extracted when the setProperties( ) method is called.

For unrecognized file formats, users must call the setMimeType( ) method and specify the MIME type.

Use this method rather than accessing the mimeType attribute directly to protect yourself from potential changes to the internal representation of the object.

getSource( )

Format

getSource( ) RETURN VARCHAR2;

Description

Returns information about the external location of the data in URL format. (This information is the source.srcType, source.srcLocation, and source.srcName attribute values of the embedded ORDSource object.)

Parameters

None.

Usage Notes

Possible return values are:

FILE://<DIR OBJECT NAME>/<FILE NAME> for a file source

HTTP://<URL> for an HTTP source

User-defined source; for example:

TYPE://<USER-DEFINED SOURCE LOCATION>/<USER-DEFINED SOURCE NAME>

Pragmas

PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS)

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

isLocal( )

Format

isLocal( ) RETURN BOOLEAN;

Description

Returns TRUE if the value of the source.local attribute (of the embedded ORDSource object) is 1, and returns FALSE if the value of the source.local attribute is 0. In other words, returns TRUE if the data is stored in a BLOB in the source.localData attribute or FALSE if the data is stored externally.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS)

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

The return INTEGER is 0 (zero) for success and greater than 0 (for example, 1) for failure. The exact number and the meaning for that number is plug-in defined. For example, for the file plug-in, 1 might mean "File not found," 2 might mean "No such directory," and so on.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the openSource( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the openSource( ) method and this method is not supported by the source plug-in being used.

readFromSource( )

Lets you read a buffer of n bytes from a source beginning at a start position.

Parameters

ctx

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

startPos

The start position in the data source.

numBytes

The number of bytes to be read from the data source.

buffer

The buffer into which the data is to be read.

Usage Notes

This method is not supported for HTTP sources.

To successfully read HTTP source types, you must request that the entire URL source be read. To implement a read method for an HTTP source type, you must provide your own implementation for this method in the modified source plug-in for the HTTP source type.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the readFromSource( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the readFromSource( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the readFromSource( ) method and the value of source.local is 1 or NULL (TRUE), but the value of the source.localData attribute is NULL.

setLocal( )

Format

setLocal( );

Description

Sets the source.local attribute (of the embedded ORDSource object) to indicate that the data is stored internally in a BLOB. When the source.local attribute is set, methods look for corresponding data in the source.localData attribute.

Parameters

None.

Usage Notes

This method sets the source.local attribute to 1, meaning the data is stored locally in the source.localData attribute.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_LOCAL_DATA

This exception is raised if you call the setLocal( ) method and the value of the source.localData attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

setUpdateTime( )

Format

setUpdateTime(current_time DATE);

Description

Sets the time when the data was last updated (the source.srcUpdateTime attribute of the embedded ORDSource object). Use this method whenever you modify the data. Methods that modify the object attributes and all set media access methods call this method implicitly. For example, the methods setMimeType( ), setSource( ), and deleteContent( ) call this method explicitly.

Parameters

current_time

The time stamp to be stored. Defaults to SYSDATE.

Usage Notes

You must invoke this method whenever you modify the data without using object methods.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

trimSource( )

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

newlen

The trimmed new length.

Usage Notes

The return INTEGER is 0 (zero) for success and greater than 0 (for example, 1) for failure. The exact number and the meaning for that number is plug-in defined. For example, for the file plug-in, 1 might mean "File not found," 2 might mean "No such directory," and so on.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the trimSource( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the trimSource( ) method and this method is not supported by the source plug-in being used.

writeToSource( )

Lets you write a buffer of n bytes to a source beginning at a start position.

Parameters

ctx

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

startPos

The start position in the source to where the buffer is to be copied.

numBytes

The number of bytes to be written to the source.

buffer

The buffer of data to be written.

Usage Notes

This method assumes that the source lets you write n number of bytes starting at a random byte location. The FILE and HTTP source types do not permit you to write, and do not support this method. This method works if data is stored in a local BLOB or is accessible through a user-defined source plug-in.

Pragmas

None.

Exceptions

<object-type>Exceptions.NULL_SOURCE

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the writeToSource( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the writeToSource( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the writeToSource( ) method and the value of source.local is 1 or NULL (TRUE), but the value of the source.localData attribute is NULL.