| Oracle® interMedia Reference 10g Release 2 (10.2) Part Number B14297-01 |
|
|
View PDF |
| Oracle® interMedia Reference 10g Release 2 (10.2) Part Number B14297-01 |
|
|
View PDF |
This chapter presents reference information on the common methods used for the following Oracle interMedia ("interMedia") object types:
ORDAudio
ORDDoc
ORDImage
ORDVideo
The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. The examples assume that the table has been populated as shown in examples in Chapter 3, Chapter 5, and Chapter 7.
See Oracle Database Sample Schemas for information about the sample schemas.
|
Note: The interMedia methods are designed to be internally consistent. If you use interMedia methods (such as import( ) or image process( )) to modify the media data, interMedia will ensure 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), then you must ensure that the object attributes stay synchronized and the update time is modified; otherwise, the object attributes will not match the data. |
The ORDSource object is embedded within the ORDAudio, ORDDoc, 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. See Chapter 9 for details on how the ORDSource object type is defined, including supported values for the ORDSource attributes, which are the following:
localData: the locally stored multimedia data stored as a BLOB within the object. Up to 4 gigabytes of data can be stored as a BLOB.
srcType: the data source type.
srcLocation: the place where data can be found based on the srcType value.
srcName: the data object name.
updateTime: the time at which the data was last updated.
local: a flag that indicates whether the data is local (1 or NULL) or external (0).
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 should 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 should 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 should 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 will 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, you should use any of the individual set methods to set the attribute value for an object for formats not natively supported, or write a format plug-in and call the setProperties( ) method; otherwise, for formats 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.
This section presents reference information on the interMedia methods that are common to all object types (except Still Image objects).
Other methods, which are particular to a given object type or are implemented differently for each object type, are described in ORDAudio Methods, ORDImage Methods, and ORDVideo Methods.
For more information about object types and methods, see Oracle Database Concepts.
The following methods are presented in this section:
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.
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; /
Format
closeSource(ctx IN OUT RAW) RETURN INTEGER;
Description
Closes a data source.
Parameters
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
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 forth.
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 for 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;
/
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.
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; /
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
The source plug-in context information.
The type of the external source data. This parameter is not case sensitive.
The location to which the source data is to be exported.
The name of the object to which the data is to be exported.
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 if you want to delete the content of the source.localData attribute.
This method is also available for user-defined sources that can support the export( ) method.
The export( ) method for a source type of FILE does not modify data stored in the BLOB.
The export( ) method is not an exact mirror operation to the import( ) method in that the clearLocal( ) method is not automatically called to indicate the data is stored outside the database, whereas the import( ) method automatically calls the setLocal( ) method.
Call the deleteContent( ) method after calling the export( ) method to delete the content from the database if you no longer intend to manage the multimedia data within the database.
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 that will contain the data.
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 CREATE DIRECTORY statement, 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, the permission to read and write any file within the directory /mydir/work:
CONNECT SYS/<password> AS SYSDBA CREATE OR REPLACE DIRECTORY FILE_DIR AS '/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');
Invoking this method implicitly calls the setUpdateTime( ) method.
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 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 write access to the directory for ORDSYS and the user who will be
-- doing the exporting, in this case the user is Ron.
connect /as sysdba
CREATE OR REPLACE DIRECTORY FILE_DIR as '/mydir/work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO 'RON';
BEGIN
-- Connect as the user Ron:
CONNECT RON/RON
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;
/
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 source.srcType attribute value 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;
/
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
<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.
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;
/
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;
/
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.
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; /
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
<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_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;
/
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
<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_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;
/
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
<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.
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;
/
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
<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.
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;
/
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.
See Appendix G for more information about these exceptions.
Examples
Determine whether or not 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;
/
Format
openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER;
Description
Opens a data source.
Parameters
The user argument. This may be used by user-defined source plug-ins.
The source plug-in context information.
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 forth.
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 for 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;
/
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
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
Any command recognized by the source plug-in.
The arguments of the command.
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
<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 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.
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
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
The start position in the data source.
The number of bytes to be read from the data source.
The buffer into which the data will 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. If you want 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.
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;
/
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 source.localData attribute value 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.
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; /
Format
setMimeType(mime IN VARCHAR2);
Description
Lets you set the MIME type of the data.
Parameters
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
<object-type>Exceptions.INVALID_MIME_TYPE
This exception is raised if you call the setMimeType( ) method and the value for 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.
<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.
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;
/
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
The type of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.
The location of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.
The name of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.
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
<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 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;
/
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
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.
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;
/
Format
trim(ctx IN OUT RAW,
newlen IN INTEGER) RETURN INTEGER;
Description
Trims a data source.
Parameters
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
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 forth.
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 for 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;
/
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
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
The start position in the source to where the buffer should be copied.
The number of bytes to be written to the source.
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 will not permit you to write, and do not support this method. This method will work 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.
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;
/
