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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the close( ) method and the value for the srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the close( ) 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 close( ) method and the source plug-in raises an exception.

Examples

None.

deleteLocalContent( )

Format

deleteLocalContent( );

Description

Deletes the local data from the localData 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.

Pragmas

None.

Exceptions

None.

Examples

None.

export( )

Format

export(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Copies data from the localData attribute within the database to an external data source.

Note:

The export( ) method natively supports only sources of source type "file". User-defined sources may support the export( ) method.

Parameters

ctx

The source plug-in context information.

source_type

The type of the source data to be exported.

source_location

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

source_name

The name of the object to which the source data is to be exported.

Usage Notes

This method exports data out of the localData attribute to another source.

After exporting data, the srcType, srcLocation, and srcName attributes are updated with input parameter values. After calling the export( ) method, call the clearLocal( ) method to indicate the data is stored outside the database and call the deleteLocalContent( ) method if you want to delete the content of the local data.

This method is also available for user-defined sources that can support the export( ) method.

The only server-side native support for the export method is for the srcType file.

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

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

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.

This exception is raised if you call the export( ) method and the value of the srcType attribute 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.

Examples

None.

getBFile( )

Format

getBFile( ) RETURN BFILE;

Description

Returns a BFILE handle, if the srcType attribute value is "file".

Parameters

None.

Usage Notes

This method can be used only for a srcType of "file".

Pragmas

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

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.INVALID_SOURCE_TYPE

This exception is raised if you call the getBFile( ) method and the value of the srcType attribute is other than "file".

Examples

None.

getContentInTempLob( )

Format

getContentInTempLob(ctx IN OUT RAW,

tempLob IN OUT NOCOPY BLOB,

mimeType OUT VARCHAR2,

format OUT VARCHAR2,

duration IN PLS_INTEGER := 10,

cache IN BOOLEAN := TRUE);

Description

Transfers data from the current data source into a temporary LOB, which will be allocated and initialized as a part of this call.

Parameters

ctx

The source plug-in context information.

tempLob

An uninitialized BLOB locator, which will be allocated in this call.

mimeType

An output parameter to receive the MIME type of the data, for example, 'audio/basic'.

format

An output parameter to receive the format of the data, for example, 'AUFF'.

duration

The life of the temporary LOB to be allocated. The life of the temporary LOB can be for the duration of the call, the transaction, or for the session. The default is DBMS_LOB.SESSION. Valid values for each duration state are as follow:

DBMS_LOB.CALL

DBMS_LOB.TRANSACTION

DBMS_LOB.SESSION

cache

Whether or not you want to keep the data cached. The value is either TRUE or FALSE. The default is TRUE.

Usage Notes

None.

Pragmas

None.

Exceptions

NO_DATA_FOUND

This exception is raised if you call the getContentInLob( ) method when working with temporary LOBs for looping read operations that reach the end of the LOB, and there are no more bytes to be read from the LOB. (There is no ORD<object-type>Exceptions prefix to this exception because it is a predefined PL/SQL exception.)

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getContentLength( )

Format

getContentLength(ctx IN OUT RAW) RETURN INTEGER;

Description

Returns the length of the data content stored in the source. For a file source and for data in the localData attribute, the length is returned as a number of bytes. The unit type of the returned value is defined by the plug-in that implements this method.

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

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getLocalContent( )

Format

getLocalContent( ) RETURN BLOB;

Description

Returns the content or BLOB handle of the localData attribute.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

None.

getSourceAddress( )

Format

getSourceAddress(ctx IN OUT RAW,

userData IN VARCHAR2) RETURN VARCHAR2;

Description

Returns the source address for data located in an external data source. This method is implemented only for user-defined sources.

Parameters

ctx

The source plug-in context information.

userData

User input needed by some sources to obtain the desired source address.

Usage Notes

Use this method to return the address of an external data source when the source needs to format this information in some unique way. For example, call the getSourceAddress( ) method to obtain the address for RealNetworks server sources or URLs containing data sources located on Oracle Application Server.

This method uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.

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

ORDSourceExceptions.NULL_SOURCE

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the import( ) 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 import( ) method and the source plug-in raises an exception.

Examples

None.

importFrom( )

Format

importFrom(ctx IN OUT RAW,

mimeType OUT VARCHAR2,

format OUT VARCHAR2

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers data from the specified external data source (type, location, name) to a the localData attribute within the database, and resets the source attributes and the timestamp.

Parameters

ctx

The source plug-in context information. This information is passed along uninterpreted to the source plug-in handling the importFrom( ) call.

mimeType

The output parameter to receive the MIME type of the data, if any, for example, audio/basic.

format

The output parameter to receive the format of the data, if any, for example, AUFF.

source_type

The type of the source data to be imported. This also sets the srcType attribute.

source_location

The location from which the source data is to be imported. This also sets the srcLocation attribute.

source_name

The name of the source data to be imported. This also sets the srcName attribute.

Usage Notes

This method describes where the data source is located by specifying values for the type, location, and name parameters, which set the srcType, srcLocation, and srcName attribute values, respectively, after the importFrom( ) operation succeeds.

This method is a combination of a setSourceInformation( ) call followed by an import( ) call.

This method uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.

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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the open( ) method and the value for the srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the open( ) 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 open( ) method and the source plug-in raises an exception.

Examples

None.

processCommand( )

Format

processCommand(ctx IN OUT RAW,

command IN VARCHAR2,

arglist IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Lets you send commands and related arguments to the source plug-in. This method is supported only for user-defined sources.

Parameters

ctx

The source plug-in context information.

command

Any command recognized by the source plug-in.

arglist

The arguments for the command.

result

The result of calling this method returned by the plug-in.

Usage Notes

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

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the processCommand( ) 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 processCommand( ) method and the source plug-in raises an exception.

Examples

None.

read( )

Format

read(ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer OUT RAW);

Description

Lets you read a buffer of numBytes from a source beginning at a start position (startPos).

Parameters

ctx

The source plug-in context information.

startPos

The start position in the data source.

numBytes

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

buffer

The buffer to where the data will be read.

Usage Notes

This method is not supported for HTTP sources.

To successfully read HTTP source types, the entire URL source must be requested to 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.

Before you call the import( ) method, you must call the setSourceInformation( ) method to set the srcType, srcLocation, and srcName attribute information to describe where the data source is located. If you call the importFrom( ) or the export( ) method, then these attributes are set after the importFrom( ) or export( ) call succeeds.

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the setSourceInformation( ) method and the value for the source_type parameter is NULL.

Examples

None.

setUpdateTime( )

Format

setUpdateTime(current_time DATE);

Description

Sets the value of the updateTime attribute to the time you specify.

Parameters

current_time

The update time.

Usage Notes

If current_time is NULL, updateTime is set to SYSDATE (the current time).

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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the trim( ) method and the value for the srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the trim( ) 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 trim( ) method and the source plug-in raises an exception.

Examples

None.

write( )

Format

write(ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer IN RAW);

Description

Lets you write a buffer of numBytes to a source beginning at a start position (startPos).

Parameters

ctx

The source plug-in context information.

startPos

The start position in the source to where the buffer should 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 numBytes at a random byte location. For example, the file and HTTP source types cannot be written to and do not support this method.