2 Common Methods and Notes for Oracle Multimedia Object Types

This chapter provides reference and other information about the common methods used for these Oracle Multimedia object types:

ORDAudio
ORDDoc
ORDImage
ORDVideo

This chapter includes these sections:

Examples for Common Methods
Embedded ORDSource Object
Important Notes for Common Methods
Important Installation and Upgrade Considerations
Common Methods

See Also:

Oracle Multimedia DICOM Developer's Guide for information about the ORDDicom object type and methods for storing, managing, and manipulating DICOM format medical images and other data

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.

See Also:

Oracle Database Sample Schemas for information about the PM and other sample schemas

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.
srcType: the data source type. (See Section 2.2.1.)
srcLocation: the place where data can be found based on the srcType value. (See Section 2.2.2.)
srcName: the data object name. (See Section 2.2.3.)
updateTime: the time at which the data was last updated.
local: a flag that indicates whether the data is local or external.

Note:

For HTTP sources, the srcLocation and srcName attributes are concatenated to construct a URL to locate the media object. For example:

If srcType is HTTP, srcLocation is www.example.com/images/, and srcName is example.jpg, then the URL to locate the media is http://www.example.com/images/example.jpg.

2.2.1 Definition of the srcType Attribute

The valid values for the srcType attribute are listed in Table 2-1.

Table 2-1 srcType Values

Value	Description
`FILE`	A BFILE on a local file system
`HTTP`	An HTTP server
`<name>`	User-defined

FILE

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:

SQL> REM Creates a new ACL and adds SCOTT the privilege to the ACL to make 
SQL> REM TCP connections
SQL> EXECUTE DBMS_NETWORK_ACL_ADMIN.CREATE_ACL('acl_for_oracle.xml', -
> 'ACL for www.oracle.com', 'SCOTT', TRUE, 'connect')
 
SQL> REM Assigns the new ACL to www.oracle.com for TCP/IP port 80 (HTTP)
SQL> EXECUTE DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL('acl_for_oracle.xml', -
> 'www.oracle.com', 80)
 
SQL> REM Commits to make the ACL take effect
SQL> COMMIT

See Also:

Oracle Database PL/SQL Packages and Types Reference for more information about configuring privileges for network access using the DBMS_NETWORK_ACL_ADMIN package
Oracle Database PL/SQL Packages and Types Reference for more information about configuring privileges for network access using the UTL_HTTP package

Common Methods

This section presents reference information about the Oracle Multimedia methods that are common to these Oracle Multimedia object types: ORDAudio, ORDDoc, ORDImage, and ORDVideo.

Note:

In this section, <object-type> represents exceptions that can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the appropriate object type.

Oracle Multimedia methods that are particular to an object type or implemented differently for each object type, are described in these chapters:

This section describes these methods:

clearLocal( )
closeSource( )
deleteContent( )
export( )
getBFile( )
getContent( )
getMimeType( )
getSource( )
getSourceLocation( )
getSourceName( )
getSourceType( )
getUpdateTime( )
isLocal( )
openSource( )
processSourceCommand( )
readFromSource( )
setLocal( )
setMimeType( )
setSource( )
setUpdateTime( )
trimSource( )
writeToSource( )

See Also:

Oracle Database Concepts for more information about object types and methods

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

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.

See Appendix G for more information about these exceptions.

Examples

Clear the value of the local flag for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT product_audio INTO obj FROM pm.online_media WHERE product_id=1733 
  FOR UPDATE;
 obj.clearLocal();
 UPDATE pm.online_media SET product_audio=obj WHERE product_id=1733;
 COMMIT;
 END;
 /

closeSource( )

Format

closeSource(ctx IN OUT RAW) RETURN INTEGER;

Description

Closes a data source.

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

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

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.

See Appendix G for more information about these exceptions.

Examples

Close an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT product_audio INTO obj FROM pm.online_media WHERE product_id=1733
  FOR UPDATE;
 res := obj.closeSource(ctx);
 UPDATE pm.online_media SET product_audio=obj WHERE product_id=1733;
 COMMIT;
 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;
/

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

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.

See Appendix G for more information about these exceptions.

Examples

Delete the local data from the current local source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO image FROM pm.online_media WHERE product_id = 3515 FOR UPDATE;
 -- Delete the local content of the image:
 image.deleteContent();
COMMIT;
END;
/

export( )

Format

export(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

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.

Parameters

ctx: The source plug-in context information. (See Section 2.3.)
source_type: 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:

CONNECT sys as sysdba
Enter password: password
CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO ron;

Now, the user ron can export an image to the testimg.jpg file in this directory using the export( ) method of the ORDImage object:

img.export('FILE', 'FILE_DIR', testimg.jpg');

See Section 2.1 for more information about directory and table definitions.

Invoking this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

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 export( ) method and the value of the source_type parameter is NULL.

ORDSourceExceptions.IO_ERROR

This exception is raised if the export( ) method encounters an error writing the BLOB data to the specified operating system file.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

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

See Appendix G for more information about these exceptions.

Examples

Export data from a local source to an external data source:

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

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.

See Appendix G for more information about these exceptions.

Examples

Return the BFILE for the stored source directory and file name attributes:

DECLARE
 obj ORDSYS.ORDVideo;
 videobfile BFILE;
BEGIN
 SELECT product_video INTO obj FROM pm.online_media
  WHERE product_id = 2030;
 -- Get the video BFILE.
 videobfile := obj.getBFile();
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('The source.srcType attribute value is NULL');
  WHEN ORDSYS.ORDSourceExceptions.INVALID_SOURCE_TYPE THEN
   DBMS_OUTPUT.PUT_LINE('The value of srcType is not file');
END;
/

getContent( )

Format

getContent( ) RETURN BLOB;

Description

Returns the BLOB handle to the source.localData attribute (of the embedded ORDSource object).

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

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.

See Appendix G for more information about these exceptions.

Examples

Access video data to be put on a Web-based player:

DECLARE
 obj ORDSYS.ORDVideo;
 ctx RAW(64) := NULL;
BEGIN
 SELECT product_video INTO obj FROM pm.online_media WHERE product_id = 2030 FOR UPDATE;
 -- import data
 obj.importFrom(ctx,'file','FILE_DIR','printer.rm');
 -- check size
 DBMS_OUTPUT.PUT_LINE('Length is 
  '||TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent())); DBMS_OUTPUT.PUT_LINE(obj.getSource());
 COMMIT;
END;
/

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.

Pragmas

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

Exceptions

None.

Examples

Get the MIME type for some stored image data:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p 
  WHERE product_id = 3515;
 DBMS_OUTPUT.PUT_LINE('writing mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 DBMS_OUTPUT.PUT_LINE(image.getMimeType());
 COMMIT;
END;
/

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

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.

See Appendix G for more information about these exceptions.

Examples

Get the source of the image data:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source information:
 DBMS_OUTPUT.PUT_LINE(image.getSource());
 COMMIT;
END;
/

getSourceLocation( )

Format

getSourceLocation( ) RETURN VARCHAR2;

Description

Returns a string containing the value of the external data source location (the value of the source.srcLocation attribute of the embedded ORDSource object).

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the value of the external data location, for example BFILEDIR.

Pragmas

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

Exceptions

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_LOCATION

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

See Appendix G for more information about these exceptions.

Examples

Get the source location information about an image data source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source location.
 DBMS_OUTPUT.PUT_LINE('Source location is ' || image.getSourceLocation());
 COMMIT;
END;
/

getSourceName( )

Format

getSourceName( ) RETURN VARCHAR2;

Description

Returns a string containing of the name of the external data source (the value of the source.srcName attribute of the embedded ORDSource object).

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the name of the external data source, for example testimg.dat.

Pragmas

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

Exceptions

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_NAME

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

See Appendix G for more information about these exceptions.

Examples

Get the source name information about an image data source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source name.
 DBMS_OUTPUT.PUT_LINE('Source name is ' ||image.getSourceName());
 COMMIT;
END;
/

getSourceType( )

Format

getSourceType( ) RETURN VARCHAR2;

Description

Returns a string containing the type of the external data source (the value of the source.srcType attribute of the embedded ORDSource object).

Parameters

None.

Usage Notes

Returns a VARCHAR2 string containing the type of the external data source, for example file.

Pragmas

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

Exceptions

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.

See Appendix G for more information about these exceptions.

Examples

Get the source type information about a media data source:

DECLARE
 obj ORDSYS.ORDDoc;
BEGIN
 SELECT p.product_testimonials INTO obj FROM pm.online_media p 
  WHERE p.product_id= 3060;
 DBMS_OUTPUT.PUT_LINE('setting and getting source');
 DBMS_OUTPUT.PUT_LINE('--------------------------');
 -- set source to a file
 obj.setSource('file','FILE_DIR','speaker.wav');
 -- get source information
 DBMS_OUTPUT.PUT_LINE('Source is ' || obj.getSource());
 DBMS_OUTPUT.PUT_LINE('Source type is ' || obj.getSourceType());
 DBMS_OUTPUT.PUT_LINE('Source location is ' || obj.getSourceLocation());
 DBMS_OUTPUT.PUT_LINE('Source name is ' || obj.getSourceName());
 COMMIT;
END;
/

getUpdateTime( )

Format

getUpdateTime( ) RETURN DATE;

Description

Returns the time when the object was last updated (the value of the source.updateTime of the embedded ORDSource object).

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

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.

See Appendix G for more information about these exceptions.

Examples

Get the updated time of some audio data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id  = 1733;
 DBMS_OUTPUT.PUT_LINE('Update time is:');
 DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getUpdateTime(),'MM-DD-YYYY HH24:MI:SS'));
 COMMIT;
END;
/

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

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.

See Appendix G for more information about these exceptions.

Examples

Determine whether the audio data is local:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
   WHERE p.product_id = 1733;
 IF (obj.isLocal() = TRUE) THEN  DBMS_OUTPUT.PUT_LINE('local is set true');
 ELSE  DBMS_OUTPUT.PUT_LINE('local is set false');
 END IF;
 COMMIT;
END;
/

openSource( )

Format

openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER;

Description

Opens a data source.

Parameters

userArg: The user argument. This parameter can be used by user-defined source plug-ins.
ctx: The source plug-in context information. (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

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.

See Appendix G for more information about these exceptions.

Examples

Open an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
 userArg RAW(64);
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733;
 res := obj.openSource(userArg, ctx);
 COMMIT;
 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;
/

processSourceCommand( )

Format

processSourceCommand(ctx IN OUT RAW,

cmd IN VARCHAR2,

arguments IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Lets you send any command and its arguments to the source plug-in. This method is available only for user-defined source plug-ins.

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.)
cmd: Any command recognized by the source plug-in.
arguments: The arguments of the command.
result: The result of calling this method returned by the source plug-in.

Usage Notes

Use this method to send any command and its respective arguments to the source plug-in. Commands are not interpreted; they are just taken and passed through to be processed.

Pragmas

None.

Exceptions

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 processSourceCommand( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

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

See Appendix G for more information about these exceptions.

Examples

None.

readFromSource( )

Format

readFromSource(ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer OUT RAW);

Description

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

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.

See Appendix G for more information about these exceptions.

Examples

Read a buffer from the source:

DECLARE
 obj ORDSYS.ORDAudio;
 buffer RAW(4000);
 i INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 i := 20;
 SELECT p.product_audio into obj from pm.online_media p 
  WHERE p.product_id = 1733;
 obj.readFromSource(ctx,1,i,buffer);
 DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
 COMMIT;
 EXCEPTION
 WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
 WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
 caught');
 WHEN ORDSYS.ORDSourceExceptions.NULL_SOURCE THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.NULL_SOURCE caught');
 WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

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

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.

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.

See Appendix G for more information about these exceptions.

Examples

Set the flag to local for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT product_audio INTO obj FROM online_media WHERE product_id = 1733;
 obj.setLocal;
 UPDATE online_media SET product_audio = obj WHERE product_id = 1733;
 COMMIT;
END;
/

setMimeType( )

Format

setMimeType(mime IN VARCHAR2);

Description

Lets you set the MIME type of the data.

Parameters

mime: The MIME type.

Usage Notes

You can override the automatic setting of MIME information by calling this method with a specified MIME value.

Calling this method implicitly calls the setUpdateTime( ) method.

The method setProperties( ) calls this method implicitly.

For image objects, the methods process( ) and processCopy( ) also call this method implicitly.

Pragmas

None.

Exceptions

This exception is raised if you call the setMimeType( ) method and the value of the mime parameter is NULL.

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

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.

See Appendix G for more information about these exceptions.

Examples

Set the MIME type for some stored data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 DBMS_OUTPUT.PUT_LINE('writing current mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 DBMS_OUTPUT.PUT_LINE(obj.getMimeType());
 DBMS_OUTPUT.PUT_LINE('setting and writing new mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 obj.setMimeType('audio/basic');
 DBMS_OUTPUT.PUT_LINE(obj.getMimeType());
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
END;
/

setSource( )

Format

setSource(source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Sets or alters information about the external source of the data.

Parameters

source_type: The type of the external source data. (See Table 2-1.)
source_location: The location of the external source data. (See Table 2-2.)
source_name: The name of the external source data. (See Table 2-3.)

Usage Notes

Users can use this method to set the data source to a new file or URL.

You must ensure that the directory indicated by the source_location parameter exists or is created before you use this method.

Calling this method implicitly calls the source.setUpdateTime( ) method and the clearLocal( ) method.

Pragmas

None.

Exceptions

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 setSource( ) method and the value of the source.srcType attribute is NULL.

See Appendix G for more information about these exceptions.

Examples

Set the source of the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 DBMS_OUTPUT.PUT_LINE('setting and getting source');
 DBMS_OUTPUT.PUT_LINE('--------------------------');
 obj.setSource('file','FILE_DIR','audio.au');
 DBMS_OUTPUT.PUT_LINE(obj.getSource());
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
END;
/

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

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.

See Appendix G for more information about these exceptions.

Examples

Set the updated time of some data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
SELECT p.product_audio INTO obj FROM pm.online_media p
 WHERE p.product_id = 1733 FOR UPDATE;
DBMS_OUTPUT.PUT_LINE('current update time:');
DBMS_OUTPUT.PUT_LINE(obj.getUpdateTime());
DBMS_OUTPUT.PUT_LINE('set and get new update time:');
 obj.setUpdateTime(SYSDATE);
 DBMS_OUTPUT.PUT_LINE(obj.getUpdateTime());
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
END;
/

trimSource( )

Format

trim(ctx IN OUT RAW,

newlen IN INTEGER) RETURN INTEGER;

Description

Trims a data source.

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.)
newlen: The trimmed new length.

Usage Notes

Pragmas

None.

Exceptions

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.

See Appendix G for more information about these exceptions.

Examples

Trim an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 res := obj.trimSource(ctx,0);
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
 WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION caught');
 WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

writeToSource( )

Format

writeToSource(

ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer IN RAW);

Description

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

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.

See Appendix G for more information about these exceptions.

Examples

Write a buffer to the source:

DECLARE
 obj ORDSYS.ORDAudio;
 n INTEGER := 6;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1743 FOR UPDATE;
 obj.writeToSource(ctx,1,n,UTL_RAW.CAST_TO_RAW('helloP'));
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1743;
 DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
 -- Roll back the transaction to keep the sample schema unchanged.
 ROLLBACK;
 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;
/