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.

Parameters

ctx

The source plug-in context information.

source_type

The type of the external source data.

source_location

The location to which the source data is to be exported.

source_name

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 is similar to a file copy operation in that the original data stored in the BLOB is not touched other than for reading purposes.

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.

The export( ) method writes only to a database directory object that the user has privilege to access. That is, you can access a directory that you have created using the SQL CREATE DIRECTORY statement, or one to which you have been granted READ access. To execute the CREATE DIRECTORY statement, you must have the CREATE ANY DIRECTORY privilege. In addition, you must use the DBMS_JAVA.GRANT_PERMISSION call to specify to which files the user and ORDSYS can write. The user must be granted the write permission so that he or she can write to the file; ORDSYS must be granted the write permission so that it can export the file on behalf of the user. (The installation procedure creates the ORDSYS user by default during installation. See Oracle interMedia User's Guide for more information.)

For example, the following SQL*Plus commands grant the user, MEDIAUSER, and ORDSYS the permission to write to the file named filmtrack1.au:

CALL DBMS_JAVA.GRANT_PERMISSION(
        'MEDIAUSER',
        'java.io.FilePermission',
        '/audio/movies/filmtrack1.au',
        'write');
CALL DBMS_JAVA.GRANT_PERMISSION(
        'ORDSYS',
        'java.io.FilePermission',
        '/audio/movies/filmtrack1.au',
        'write');

The previous example shows how to authorize access to write to a single file. In addition, there are various wildcard path specifications that authorize write access to multiple directories and file names. For example, a path specification that ends in a slash and asterisk (/*), where the slash is the file-separator character that is operating-system dependent, indicates all the files contained in the specified directory. A path specification that ends with a slash and a hyphen (/-) indicates all files contained in the specified directory and all its subdirectories. A path name consisting of the special token <<ALL FILES>> authorizes access to any file.

See Oracle Database Java Developer's Guide and the java.io.FilePermission class in the Java API for more information about security and performance.

Invoking this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

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

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the export( ) method and the source plug-in raises an exception.

See Appendix F for more information about these exceptions.

ORDSourceExceptions.IO_ERROR

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

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 ON DIRECTORY FILE_DIR TO PUBLIC WITH GRANT OPTION;
BEGIN
-- Grant permission to the user and ORDSYS.
 DBMS_JAVA.GRANT_PERMISSION(
  'RON', 
  'java.io.FilePermission', 
  '/images/testimg.jpg',
  'WRITE');
 DBMS_JAVA.GRANT_PERMISSION(
  'ORDSYS',
  'java.io.FilePermission',
  '/images/testimg.jpg',
  'write');
 COMMIT;
END;
/
-- 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 ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN
  DBMS_OUTPUT.PUT_LINE('SOURCE PLUGIN EXCEPTION caught');
 WHEN OTHERS THEN
  DBMS_OUTPUT.PUT_LINE('OTHER EXCEPTION caught');
END;
/