7 Extending Oracle interMedia

Oracle interMedia can be extended to support:

Other external sources of media data not currently supported (see Section 7.1)
Other media data formats not currently supported (see Section 7.2)
A new object type (see Section 7.3)
Media (audio and video) data processing (see Section 7.4)

For each unique external media data source or each unique ORDAudio, ORDDoc, or ORDVideo data format that you want to support, you must:

Design your new data source or new ORDAudio, ORDDoc, or ORDVideo data format.
Implement your new data source or new ORDAudio, ORDDoc, or ORDVideo data format.
Install your new plug-in in the ORDPLUGINS schema.
Grant EXECUTE privileges on your new plug-in to PUBLIC.

7.1 Supporting Other External Sources

To implement your new data source, you must implement the required interfaces in the ORDX_<srcType>_SOURCE package in the ORDPLUGINS schema (where <srcType> represents the name of the new external source type). Use the package body example in Section 7.1.1.3 as a template to create the package body. Then, set the source type parameter in the setSourceInformation( ) call to the appropriate source value to indicate to the ORDAudio, ORDImage, ORDDoc, or ORDVideo object that package ORDPLUGINS.ORDX_<srcType>_SOURCE is available as a plug-in. Use the ORDPLUGINS.ORDX_FILE_SOURCE and ORDPLUGINS.ORDX_HTTP_SOURCE packages as guides when you extend support to other external audio, image, video, or other heterogeneous media data sources.

See Section 7.1.1.1, Section 7.1.1.2, and Section 7.1.1.3 for examples and for more information on extending the supported external sources of audio, image, video, or other heterogeneous media data.

7.1.1 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided.

Any method invoked from a source plug-in call has the first argument as obj (ORDSource) and the second argument as ctx (RAW).

Plug-ins must be named as ORDX_<name>_<module_name> where the <module_name> is SOURCE for ORDSource. For example, the file plug-in described in Section 7.1.1.1, is named ORDX_FILE_SOURCE and the HTTP plug-in described in Section 7.1.1.2, is named ORDX_HTTP_SOURCE and <name> is the source type. Both source type names, FILE and HTTP, are reserved to Oracle.

Use the ORDPLUGINS.ORDX_FILE_SOURCE and ORDPLUGINS.ORDX_HTTP_SOURCE packages as a guide in developing your new source type package.

7.1.1.1 ORDPLUGINS.ORDX_FILE_SOURCE Package

The ORDPLUGINS.ORDX_FILE_SOURCE package or PL/SQL plug-in provides support for multimedia stored in the local file system external to the database.

CREATE OR REPLACE PACKAGE ORDX_FILE_SOURCE AS
  -- functions/procedures
  FUNCTION processCommand(obj     IN OUT NOCOPY ORDSYS.ORDSource,
                          ctx     IN OUT RAW,
                          cmd     IN VARCHAR2,
                          arglist IN VARCHAR2,
                          result  OUT RAW)
           RETURN RAW;
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   dlob     IN OUT NOCOPY BLOB,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       dlob     IN OUT NOCOPY BLOB,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE export(obj  IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx  IN OUT RAW,
                   slob IN OUT NOCOPY BLOB,
                   loc  IN VARCHAR2,
                   name IN VARCHAR2);
  FUNCTION  getContentLength(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW),
            RETURN INTEGER;
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS);
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2)
            RETURN VARCHAR2;
  PRAGMA RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS);
  
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, 
           userArg IN RAW, 
           ctx OUT RAW) RETURN INTEGER;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW) 
         RETURN INTEGER;
  FUNCTION trim(obj IN OUT NOCOPY ORDSYS.ORDSource, 
                ctx IN OUT RAW,
                newlen IN INTEGER) RETURN INTEGER;
PROCEDURE read(obj     IN OUT NOCOPY ORDSYS.ORDSource,
               ctx      IN OUT RAW,
               startPos IN INTEGER,
               numBytes IN OUT INTEGER,
               buffer   OUT RAW);
PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                ctx      IN OUT RAW,
                startPos IN INTEGER,
                numBytes IN OUT INTEGER,
                buffer   OUT RAW);
END ORDX_FILE_SOURCE;
/

Table 7-1 shows the methods supported in the ORDX_FILE_SOURCE package and the exceptions raised if you call a method that is not supported.

Table 7-1 Methods Supported in the ORDPLUGINS.ORDX_FILE_SOURCE Package

Name of Method	Level of Support
processCommand	Not supported - raises exception: METHOD_NOT_SUPPORTED
import	Supported
import	Supported
importFrom	Supported
importFrom	Supported
export	Supported
getContentLength	Supported
getSourceAddress	Supported
open	Supported
close	Supported
trim	Not supported - raises exception: METHOD_NOT_SUPPORTED
read	Supported
write	Not supported - raises exception: METHOD_NOT_SUPPORTED

7.1.1.2 ORDPLUGINS.ORDX_HTTP_SOURCE Package

The ORDPLUGINS.ORDX_HTTP_SOURCE package or PL/SQL plug-in provides support for multimedia stored in any HTTP server and accessed through a URL.

CREATE OR REPLACE PACKAGE ORDX_HTTP_SOURCE AS
  -- functions/procedures
  FUNCTION processCommand(obj     IN OUT NOCOPY ORDSYS.ORDSource,
                          ctx     IN OUT RAW,
                          cmd     IN VARCHAR2,
                          arglist IN VARCHAR2,
                          result  OUT RAW)
           RETURN RAW;
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   dlob     IN OUT NOCOPY BLOB,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       dlob     IN OUT NOCOPY BLOB,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE export(obj  IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx  IN OUT RAW,
                   dlob IN OUT NOCOPY BLOB,
                   loc  IN VARCHAR2,
                   name IN VARCHAR2);
  FUNCTION  getContentLength(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW)
            RETURN INTEGER;
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS);
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2) 
            RETURN VARCHAR2;
  PRAGMA RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS);
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, userArg IN RAW,
           ctx OUT RAW) RETURN INTEGER;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW) 
           RETURN INTEGER;
  FUNCTION trim(obj IN OUT NOCOPY ORDSYS.ORDSource, 
           ctx IN OUT RAW,
           newlen IN INTEGER) RETURN INTEGER;
  PROCEDURE read(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                 ctx      IN OUT RAW,
                 startPos IN INTEGER,
                 numBytes IN OUT INTEGER,
                 buffer   OUT RAW);
  PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                  ctx      IN OUT RAW,
                  startPos IN INTEGER,
                  numBytes IN OUT INTEGER,
                  buffer   OUT RAW);
END ORDX_HTTP_SOURCE;
/

Table 7-2 shows the methods supported in the ORDX_HTTP_SOURCE package and the exceptions raised if you call a method that is not supported.

Table 7-2 Methods Supported in the ORDPLUGINS.ORDX_HTTP_SOURCE Package

Name of Method	Level of Support
processCommand	Not supported - raises exception: METHOD_NOT_SUPPORTED
import	Supported
import	Supported
importFrom	Supported
importFrom	Supported
export	Not supported - raises exception: METHOD_NOT_SUPPORTED
getContentLength	Supported
getSourceAddress	Supported
open	Supported
close	Supported
trim	Not supported - raises exception: METHOD_NOT_SUPPORTED
read	Not supported - raises exception: METHOD_NOT_SUPPORTED
write	Not supported - raises exception: METHOD_NOT_SUPPORTED

7.1.1.3 Extending interMedia to Support a New Data Source

Extending interMedia to support a new data source consists of the following steps:

Design your new data source.
Implement your new data source and name it, for example, ORDX_MY_SOURCE.SQL.
Install your new ORDX_MY_SOURCE.SQL plug-in in the ORDPLUGINS schema.
Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_SOURCE.SQL plug-in to PUBLIC.
Set the srctype to my to cause your plug-in to be invoked.

A package body listing is provided in Example 7-1 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

Example 7-1 Show the Package Body for Extending Support to a New Data Source

CREATE OR REPLACE PACKAGE BODY ORDX_MY_SOURCE
AS
  -- functions/procedures
  FUNCTION processCommand(
                    obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    cmd  IN VARCHAR2,
                    arglist IN VARCHAR2,
                    result OUT RAW)
  RETURN RAW
  IS
   --Your variables go here.
  BEGIN
  --Your code goes here.
  END processCommand;
  PROCEDURE import( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    mimetype OUT VARCHAR2,
                    format   OUT VARCHAR2)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END import;
  PROCEDURE import( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    dlob IN OUT NOCOPY BLOB,
                    mimetype OUT VARCHAR2,
                    format   OUT VARCHAR2)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END import;
  PROCEDURE importFrom( obj      IN OUT NOCOPY ORDSYS.ORDSource,
                        ctx      IN OUT RAW,
                        mimetype OUT VARCHAR2,
                        format   OUT VARCHAR2,
                        loc      IN VARCHAR2,
                        name     IN VARCHAR2)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END importFrom;
  PROCEDURE importFrom( obj      IN OUT NOCOPY ORDSYS.ORDSource,
                        ctx      IN OUT RAW,
                        dlob     IN OUT NOCOPY BLOB,
                        mimetype OUT VARCHAR2,
                        format   OUT VARCHAR2,
                        loc      IN VARCHAR2,
                        name     IN VARCHAR2)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END importFrom;
  PROCEDURE export( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    dlob IN OUT NOCOPY BLOB,
                    loc  IN VARCHAR2,
                    name IN VARCHAR2)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END export;
  
  FUNCTION  getContentLength( obj  IN ORDSYS.ORDSource,
                              ctx  IN OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END getContentLength;
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2)
  RETURN VARCHAR2
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END getSourceAddress;
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, userArg IN RAW, ctx OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END open;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END close;
  FUNCTION trim(obj    IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx    IN OUT RAW,
                       newlen IN INTEGER)
  RETURN INTEGER
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END trim;
  PROCEDURE read(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                 ctx      IN OUT RAW,
                 startPos IN INTEGER,
                 numBytes IN OUT INTEGER,
                 buffer   OUT RAW)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END read;
  PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                  ctx      IN OUT RAW,
                  startPos IN INTEGER,
                  numBytes IN OUT INTEGER,
                  buffer   OUT RAW)
  IS
  --Your variables go here.
  BEGIN
  --Your code goes here.
  END write;
END ORDX_MY_SOURCE;
/
show errors;

7.2 Supporting Other Media Data Formats

To implement your new ORDAudio, ORDDoc, or ORDVideo data format, you must implement the required interfaces in the ORDPLUGINS.ORDX_<format>_<media> package in the ORDPLUGINS schema (where <format> represents the name of the new audio or video, or other heterogeneous media data format and <media> represents the type of media ("AUDIO" or "VIDEO", or "DOC"). Use the ORDPLUGINS.ORDX_DEFAULT_<media> package as a guide when you extend support to other audio or video data formats or other heterogeneous media data formats. Use the package body examples in Section 7.2.1.2, Section 7.2.2.2 and Section 7.2.3.2 as templates to create the audio or video, or other heterogeneous media data package body, respectively. Then, set the new format parameter in the setFormat( ) call to the appropriate format value to indicate to the ORDAudio, ORDDoc, or ORDVideo object that package ORDPLUGINS.ORDX_<format>_<media> is available as a plug-in and should be used for method invocation.

See Section A.1 and Section A.4 for more information on installing your own format plug-in and running the sample scripts provided.

See Section 7.2.1.2, Section 7.2.2.2, and Section 7.2.3.2 for examples and for more information on extending the supported audio and video, or other heterogeneous media data formats. See Oracle interMedia Reference for more examples.

7.2.1 Supporting Other ORDAudio Data Formats

Section 7.2.1.1, Section 7.2.1.2, and Section 7.2.1.3 describe support for other ORDAudio data formats.

7.2.1.1 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided for the ORDAudio type. Table 7-3 describes the PL/SQL plug-in packages provided in the ORDPLUGINS schema.

Table 7-3 ORDAudio PL/SQL Plug-ins Provided in the ORDPLUGINS Schema

PL/SQL Plug-in Packages	Audio Format	MIME Type
`ORDPLUGINS.ORDX_DEFAULT_AUDIO`	<format>	Dependent on file format
`ORDPLUGINS.ORDX_AUFF_AUDIO`	AUFF	audio/basic
`ORDPLUGINS.ORDX_AIFF_AUDIO`	AIFF	audio/x-aiff
`ORDPLUGINS.ORDX_AIFC_AUDIO`	AIFC	audio/x-aiff
`ORDPLUGINS.ORDX_WAVE_AUDIO`	WAVE	audio/x-wave
`ORDPLUGINS.ORDX_MPGA_AUDIO`	MPGA	audio/mpeg
`ORDPLUGINS.ORDX_ASF_AUDIO`	ASF	audio/x-ms-wma
`ORDPLUGINS.ORDX_MP4_AUDIO`	MP4	application/mpeg4

Section 7.2.1.2 describes the ORDPLUGINS.ORDX_DEFAULT_AUDIO package, the methods supported, and the level of support. Note that the methods supported and the level of support for the other PL/SQL plug-in packages described in Table 7-3 are identical for all plug-in packages, therefore, refer to Section 7.2.1.2.

7.2.1.2 ORDPLUGINS.ORDX_DEFAULT_AUDIO Package

Use the following ORDPLUGINS.ORDX_DEFAULT_AUDIO package provided as a guide in developing your own ORDPLUGINS.ORDX_<format>_AUDIO audio format package. This package sets the mimeType field in the setProperties( ) method with a MIME type value that is dependent on the file format.

Note:

The ORDPLUGINS.ORDX_DEFAULT_AUDIO package specification includes a number of methods deprecated beginning with release 8.1.6, which have been removed in the following listing. Do not implement these deprecated methods; they are there only for backward compatibility.

CREATE OR REPLACE PACKAGE ORDX_DEFAULT_AUDIO
authid current_user
AS 
--AUDIO ATTRIBUTES ACCESSORS

PROCEDURE setProperties(ctx IN OUT RAW, 
                        obj IN OUT NOCOPY ORDSYS.ORDAudio,
                        setComments IN NUMBER := 0);
FUNCTION checkProperties(ctx IN OUT RAW, obj IN OUT ORDSYS.ORDAudio)
                RETURN NUMBER;
FUNCTION getAttribute(ctx IN OUT RAW,
                      obj IN ORDSYS.ORDAudio,
                      name IN VARCHAR2) RETURN VARCHAR2;
PROCEDURE getAllAttributes(ctx IN OUT RAW, 
                           obj IN ORDSYS.ORDAudio, 
                           attributes IN OUT NOCOPY CLOB);
--AUDIO PROCESSING METHODS
FUNCTION processCommand(ctx       IN OUT RAW,
                        obj       IN OUT NOCOPY ORDSYS.ORDAudio,
                        cmd       IN VARCHAR2,
                        arguments IN VARHAR2,
                        result    OUT RAW)
         RETURN RAW;

END;
/

Table 7-4 shows the methods supported in the
ORDPLUGINS.ORDX_DEFAULT_AUDIO package and the exceptions raised if you call a method that is not supported.

Table 7-4 Methods Supported in the ORDPLUGINS.ORDX_DEFAULT_AUDIO Package

Name of Method	Level of Support
setProperties	Supported; if the source is local, extract attributes from the local data and set the properties, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then extract attributes from the BFILE and set the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, extract attributes from the data, and set the properties.
checkProperties	Supported; if the source is local, extract the attributes from the local data and compare them with the attribute values of the object, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, extract the attributes from the BFILE and compare them with the attribute values of the object; if the source is neither local nor a BFILE, get the media content into a temporary LOB, extract the attributes from the media content and compare them with the attribute values of the object.
getAttribute	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and AUDIO_PLUGIN_EXCEPTION.
getAllAttributes	Supported; if the source is local, get the attributes and return them, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
processCommand	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and AUDIO_PLUGIN_EXCEPTION.

7.2.1.3 Extending interMedia to Support a New Audio Data Format

Extending interMedia to support a new audio data format consists of the following steps:

Design your new audio data format.
1. To support a new audio data format, implement the required interfaces in the ORDX_<format>_AUDIO package in the ORDPLUGINS schema (where <format> represents the name of the new audio data format). See Section 7.2.1.2 for a complete description of the interfaces for the ORDX_DEFAULT_AUDIO package. Use the package body example in Example 7-2 as a template to create the audio package body.
2. Then, set the new format parameter in the setFormat( ) call to the appropriate format value to indicate to the audio object that package ORDPLUGINS.ORDX_<format>_AUDIO is available as a plug-in.
Implement your new audio data format and name it, for example, ORDX_MY_AUDIO.SQL.
Install your new ORDX_MY_AUDIO.SQL plug-in in the ORDPLUGINS schema.

See Section A.1 for more information on installing your own format plug-in and running the sample scripts provided. See the fplugins.sql and fpluginb.sql files that are installed in the $ORACLE_HOME/ord/aud/demo/ directory. These are demonstration (demo) plug-ins that you can use as a guideline to write any format plug-in that you want to support. See the auddemo.sql file in this same directory to learn how to install your own format plug-in.
Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_AUDIO.SQL plug-in, to PUBLIC.
In an application, set the format attribute to my to cause your plug-in to be invoked.

A package body listing is provided in Example 7-2 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

See Section A.1 for more information on installing your own audio format plug-in and running the sample scripts provided.

Example 7-2 Show the Package Body for Extending Support to a New Audio
Data Format

CREATE OR REPLACE PACKAGE BODY ORDX_MY_AUDIO
AS
  --AUDIO ATTRIBUTES ACCESSORS
  PROCEDURE setProperties(ctx IN OUT RAW,
                          obj IN OUT NOCOPY ORDSYS.ORDAudio,
                          setComments IN NUMBER :=0)
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  FUNCTION checkProperties(ctx IN OUT RAW, obj IN OUT ORDSYS.ORDAudio)
  RETURN NUMBER
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  FUNCTION  getAttribute(ctx IN OUT RAW,
                         obj IN ORDSYS.ORDAudio,
                         name IN VARCHAR2)
  RETURN VARCHAR2
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  PROCEDURE getAllAttributes(ctx IN OUT RAW,
                             obj IN ORDSYS.ORDAudio,
                             attributes IN OUT NOCOPY CLOB)
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  -- AUDIO PROCESSING METHODS
  FUNCTION  processCommand(
                                 ctx       IN OUT RAW,
                                 obj       IN OUT NOCOPY ORDSYS.ORDAudio,
                                 cmd       IN VARCHAR2,
                                 arguments IN VARCHAR2,
                                 result    OUT RAW)
  RETURN RAW
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
END;
/
show errors;

7.2.2 Supporting Other ORDDoc Data Formats

Section 7.2.2.1, Section 7.2.2.2, and Section 7.2.2.3 describe support for other ORDDoc data formats.

7.2.2.1 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided for the ORDDoc type. Table 7-5 describes the PL/SQL plug-in packages provided in the ORDPLUGINS schema.

Table 7-5 ORDDoc PL/SQL Plug-ins Provided in the ORDPLUGINS Schema

PL/SQL Plug-in Packages	Media Format	MIME Type
`ORDPLUGINS.ORDX_DEFAULT_DOC`	<format>	Dependent on file format

Section 7.2.2.2 describes the ORDPLUGINS.ORDX_DEFAULT_DOC package, the methods supported, and the level of support. The method supported and the level of support for the PL/SQL plug-in package is described in Table 7-6.

7.2.2.2 ORDPLUGINS.ORDX_DEFAULT_DOC Package

Use the following ORDPLUGINS.ORDX_DEFAULT_DOC package provided as a guide in developing your own ORDPLUGINS.ORDX_<format>_DOC media format package. This package sets the mimeType field in the setProperties( ) method with a MIME type value that is dependent on the file format.

CREATE OR REPLACE PACKAGE ORDX_DEFAULT_DOC
authid current_user
AS 

PROCEDURE setProperties(ctx IN OUT RAW, 
                        obj IN OUT NOCOPY ORDSYS.ORDDoc,
                        setComments IN NUMBER := 0);

END;
/

Table 7-6 shows the method supported in the ORDPLUGINS.ORDX_DEFAULT_DOC package and the exception raised if the source is NULL.

Table 7-6 Method Supported in the ORDPLUGINS.ORDX_DEFAULT_DOC Package

Name of Method Level of Support

setProperties Supported; if the source is local, extract attributes from the local data and set the properties, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then extract attributes from the BFILE and set the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, extract attributes from the data, and set the properties.

7.2.2.3 Extending interMedia to Support a New Media Data Format

Extending interMedia to support a new media data format consists of the following steps:

Design your new media data format.
1. To support a new media data format, implement the required interfaces in the ORDX_<format>_DOC package in the ORDPLUGINS schema (where <format> represents the name of the new media data format). See Section 7.2.2.2 for a complete description of the interfaces for the ORDX_DEFAULT_DOC package. Use the package body example in Example 7-3 as a template to create the media package body.
2. Then, set the new format parameter in the setFormat( ) call to the appropriate format value to indicate to the media object that package ORDPLUG-INS.ORDX_<format>_DOC is available as a plug-in.
Implement your new media data format and name it, for example, ORDX_MY_DOC.SQL.
Install your new ORDX_MY_DOC.SQL plug-in in the ORDPLUGINS schema.
Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_DOC.SQL plug-in, to PUBLIC.
In an application, set the format to my to cause your plug-in to be invoked.

A package body listing is provided in Example 7-3 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

See Section A.2 for more information on installing your own media format plug-in and running the sample scripts provided.

Example 7-3 Show the Package Body for Extending Support to a New Media
Data Format

CREATE OR REPLACE PACKAGE BODY ORDX_MY_DOC
AS
  --DOCUMENT ATTRIBUTES ACCESSORS
  PROCEDURE setProperties(ctx IN OUT RAW,
                          obj IN OUT NOCOPY ORDSYS.ORDDoc,
                          setComments IN NUMBER :=FALSE)
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
END;
/
show errors;

7.2.3 Supporting Other Video Data Formats

Section 7.2.3.1, Section 7.2.3.2, and Section 7.2.3.3 describe support for other video data formats.

7.2.3.1 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided with the ORDVideo object. Table 7-7 describes the PL/SQL plug-in packages provided in the ORDPLUGINS schema.

Table 7-7 ORDVideo PL/SQL Plug-ins Provided in the ORDPLUGINS Schema

PL/SQL Plug-in Packages	Video Format	MIME Type
`ORDPLUGINS.ORDX_DEFAULT_VIDEO`	<format>	Dependent on file format
`ORDPLUGINS.ORDX_AVI_VIDEO`	AVI	video/x-msvideo
`ORDPLUGINS.ORDX_MOOV_VIDEO`	MOOV	video/quicktime
`ORDPLUGINS.ORDX_RMFF_VIDEO`	RMFF	audio/x-pn-realaudio
`ORDPLUGINS.ORDX_MPEG_VIDEO`	MPG	video/mpeg
`ORDPLUGINS.ORDX_MP4_VIDEO`	MP4	Application/mpeg4
`ORDPLUGINS.ORDX_ASF_VIDEO`	ASF	video/x-ms-wvm

Section 7.2.3.2 describes the ORDPLUGINS.ORDX_DEFAULT_VIDEO package, the methods supported, and the level of support. Note that the methods supported and the level of support for the other PL/SQL plug-in packages described in Table 7-7 are identical for all plug-in packages, therefore, refer to Section 7.2.3.2.

7.2.3.2 ORDPLUGINS.ORDX_DEFAULT_VIDEO Package

Use the following ORDPLUGINS.ORDX_DEFAULT_VIDEO package provided as a guide in developing your own ORDPLUGINS.ORDX_<format>_VIDEO video format package. This package sets the mimeType field in the setProperties( ) method with a MIME type value that is dependent on the file format.

Note:

The ORDPLUGINS.ORDX_DEFAULT_VIDEO package specification includes a number of methods deprecated beginning with release 8.1.6, which have been removed in the following listing. Do not implement these deprecated methods; they are there only for backward compatibility.

CREATE OR REPLACE PACKAGE ORDX_DEFAULT_VIDEO
authid current_user
AS
--VIDEO ATTRIBUTES ACCESSORS
FUNCTION  getAttribute(ctx IN OUT RAW,
                       obj IN ORDSYS.ORDVideo,
                       name IN VARCHAR2) 
          RETURN VARCHAR2;
PROCEDURE setProperties(ctx IN OUT RAW, 
                        obj IN OUT NOCOPY ORDSYS.ORDVideo,
                        setComments IN NUMBER := 0);
FUNCTION checkProperties(ctx IN OUT RAW,obj IN ORDSYS.ORDVideo) RETURN NUMBER;

-- must return name=value; name=value; ...  pairs
PROCEDURE getAllAttributes(ctx IN OUT RAW,
                           obj IN ORDSYS.ORDVideo,
                           attributes IN OUT NOCOPY CLOB);
-- VIDEO PROCESSING METHODS
FUNCTION  processCommand(
                         ctx       IN OUT RAW,
                         obj       IN OUT NOCOPY ORDSYS.ORDVideo,
                         cmd       IN VARCHAR2,
                         arguments IN VARCHAR2,
                         result    OUT RAW)
         RETURN RAW;

END;
/

Table 7-8 shows the methods supported in the ORDPLUGINS.ORDX_DEFAULT_VIDEO package and the exceptions raised if you call a method that is not supported.

Table 7-8 Methods Supported in the ORDPLUGINS.ORDX_DEFAULT_VIDEO Package

Name of Method	Level of Support
getAttribute	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and VIDEO_PLUGIN_EXCEPTION
setProperties	Supported; if the source is local, extract attributes from the local data and set the properties, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then extract attributes from the BFILE and set the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, extract attributes from the data, and set the properties.
checkProperties	Supported; if the source is local, extract attributes from the local data and compare them with the attribute values of the object, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then extract attributes from the BFILE data and compare them with the attribute values of the object; if the source is neither local nor a BFILE, get the media content into a temporary LOB, extract attributes from the media content and compare them with the attribute values of the object.
getAllAttributes	Supported; if the source is local, get the attributes and return them, but if the source is `NULL`, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDVideoExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
processCommand	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and VIDEO_PLUGIN_EXCEPTION

7.2.3.3 Extending interMedia to Support a New Video Data Format

Extending interMedia to support a new video data format consists of the following steps:

Design your new video data format.
1. To support a new video data format, implement the required interfaces in the ORDX_<format>_VIDEO package in the ORDPLUGINS schema (where <format> represents the name of the new video data format). See Section 7.2.3.2 for a complete description of the interfaces for the ORDX_DEFAULT_VIDEO package. Use the package body example in Example 7-4 as a template to create the video package body.
2. Then, set the new format parameter in the setFormat( ) call to the appropriate format value to indicate to the video object that package ORDPLUGINS.ORDX_<format> _VIDEO is available as a plug-in.
Implement your new video data format and name it, for example, ORDX_MY_VIDEO.SQL.
Install your new ORDX_MY_VIDEO.SQL plug-in in the ORDPLUGINS schema.

See Section A.4 for more information on installing your own format plug-in and running the sample scripts provided. See the fplugins.sql and fpluginb.sql files that are installed in the $ORACLE_HOME/ord/vid/demo/ directory. These are demonstration (demo) plug-ins that you can use as a guideline to write any format plug-in that you want to support. See the viddemo.sql file in this same directory to learn how to install your own format plug-in.
Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_VIDEO.SQL plug-in, to PUBLIC.
In an application, set the video format to my to cause your plug-in to be invoked.

A package body listing is provided in Example 7-4 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

See Section A.4 for more information on installing your own video format plug-in and running the sample scripts provided.

Example 7-4 Show the Package Body for Extending Support to a New Video
Data Format

CREATE OR REPLACE PACKAGE BODY ORDX_MY_VIDEO
AS
  --VIDEO ATTRIBUTES ACCESSORS
  FUNCTION  getAttribute(ctx IN OUT RAW,
                         obj IN ORDSYS.ORDVideo,
                         name IN VARCHAR2)
  RETURN VARCHAR2
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  PROCEDURE setProperties(ctx IN OUT RAW, 
          obj IN OUT NOCOPY ORDSYS.ORDVideo,
          setComments IN NUMBER :=0)
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  FUNCTION checkProperties(ctx IN OUT RAW, obj IN ORDSYS.ORDVideo) RETURN NUMBER
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  PROCEDURE getAllAttributes(ctx IN OUT RAW,
                             obj IN ORDSYS.ORDVideo,
                             attributes IN OUT NOCOPY CLOB)
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
  -- VIDEO PROCESSING METHODS
  FUNCTION  processCommand(
                                 ctx       IN OUT RAW,
                                 obj       IN OUT NOCOPY ORDSYS.ORDVideo,
                                 cmd       IN VARCHAR2,
                                 arguments IN VARCHAR2,
                                 result OUT RAW)
  RETURN RAW
  IS
--Your variables go here.
  BEGIN
--Your code goes here.
  END;
END;
/
show errors;

7.2.4 Supporting Other Image Data Formats

Oracle interMedia supports certain other image formats through the setProperties( ) method for foreign images. This method allows other image formats to be recognized by writing the values supplied to the setProperties( ) method for foreign images to the existing ORDImage data attributes. See the setProperties( ) for foreign images method in Oracle interMedia Reference for more information and to determine the type of images that can are supported this way.

7.3 Extending interMedia with a New Type

You can use any of the interMedia objects types as the basis for a new type of your own creation as shown in Example 7-5 for the ORDImage object type.

Note:

When a type is altered, any dependent type definitions are invalidated. You will encounter this problem if you define a new type that includes an interMedia object type attribute and the interMedia object type is altered, which always occurs during an interMedia installation upgrade.

A workaround to this problem is to revalidate all invalid type definitions with the following SQL statement:

SQL> ALTER TYPE <type-name> COMPILE;

Example 7-5 Extend Oracle interMedia ORDImage with a New Object Type

CREATE TYPE AnnotatedImage AS OBJECT
    ( image ORDSYS.ORDImage,
      description VARCHAR2(2000),
      MEMBER PROCEDURE SetProperties(SELF IN OUT AnnotatedImage),
      MEMBER PROCEDURE Copy(dest IN OUT AnnotatedImage),
      MEMBER PROCEDURE ProcessCopy(command IN VARCHAR2,
                                   dest IN OUT AnnotatedImage)
    );
/

CREATE TYPE BODY AnnotatedImage AS
  MEMBER PROCEDURE SetProperties(SELF IN OUT AnnotatedImage) IS
  BEGIN
    SELF.image.setProperties();
    SELF.description :=
        'This is an example of using Image object as a subtype';
  END SetProperties;
  MEMBER PROCEDURE Copy(dest IN OUT AnnotatedImage) IS
  BEGIN
    SELF.image.copy(dest.image);
    dest.description := SELF.description;
  END Copy;
  MEMBER PROCEDURE ProcessCopy(command IN VARCHAR2,
                               dest IN OUT AnnotatedImage) IS
  BEGIN
    SELF.Image.processCopy(command,dest.image);
    dest.description := SELF.description;
  END ProcessCopy;
END;
/

After creating the new type, you can use it as you would any other type. For example:

CREATE OR REPLACE DIRECTORY ORDIMGDIR AS 'C:\TESTS';

CREATE TABLE my_example(id NUMBER, an_image AnnotatedImage);
INSERT INTO my_example VALUES (1,
    AnnotatedImage(
        ORDSYS.ORDImage.init('file','ORDIMGDIR','plaid.gif'));
COMMIT;
DECLARE
    myimage AnnotatedImage;
BEGIN
    SELECT an_image INTO myimage FROM my_example;
    myimage.SetProperties;
    DBMS_OUTPUT.PUT_LINE('This image has a description of ');
    DBMS_OUTPUT.PUT_LINE(myimage.description);
    UPDATE my_example SET an_image = myimage;
END;
/

7.4 Supporting Media Data Processing

Section 7.4.1 and Section 7.4.2 describe support for audio and video data processing.

7.4.1 Supporting Audio Data Processing

To support audio data processing, that is, the passing of an audio processing command and set of arguments to a format plug-in for processing, use the
processAudioCommand( ) method. This method is available only for user-defined formats.

See the processAudioCommand( ) method in Oracle interMedia Reference for a description.

7.4.2 Supporting Video Data Processing

To support video data processing, that is, the passing of a command and set of arguments to a format plug-in for processing, use the processVideoCommand( ) method. This method is only available for user-defined formats.

See the processVideoCommand( ) method in Oracle interMedia Reference for a description.