Skip Headers

Oracle® interMedia Java Classes User's Guide and Reference
Release 9.2
Part No. A96121-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Previous Next

3
OrdAudio Reference Information

The OrdAudio class is used to represent an instance of the ORDSYS.ORDAudio database type in a Java application. The OrdAudio class includes a set of methods to get and set various object attributes, as well as a set of methods that perform various operations on an OrdAudio Java object.

Almost all methods operate on the attributes of the OrdAudio Java object in the application. The exceptions are those methods that access the audio data for read or write purposes, which are described in the following list:

If your application modifies the OrdAudio Java object or the audio data in the database, you must update the ORDAudio SQL object in the database to make those changes permanent.

Some methods in the OrdAudio Java class are handed off to a database source plug-in or database format plug-in for processing; these methods have byte [ ] [ ] ctx as a context parameter. Applications should allocate a 64-byte array to hold any context information that may be required by a source plug-in or a format plug-in. For example, a plug-in may initialize the context information in one call and use that information in a subsequent call. The source plug-in context requires one array; the format plug-in context requires another array. For most plug-ins, 64 bytes should be sufficient. Some user-defined plug-ins may need additional space. The following example shows how to allocate a plug-in context information array:

byte [] [] ctx = new byte[1][64];


Note:

In the current release, no Oracle-supplied source plug-ins or format plug-ins maintain context. Also, not all user-written source plug-ins or format plug-ins maintain context. However, if you include the context parameter as described, your application should work with any current or future source plug-ins or format plug-ins.

See Oracle interMedia User's Guide and Reference for more information about plug-ins.

3.1 Prerequisites

You will need to include the following import statements in your Java file in order to run interMedia methods:

import java.sql.*;
import java.io.*;
import oracle.jdbc.driver.*;
import oracle.sql.*;
import oracle.ord.im.*;

The examples in this reference chapter are based on the assumption that the following operations have already been performed:

For examples of making a connection and populating a local object, see Section 2.1.2.

3.2 Reference Information

This section presents reference information on the methods that operate on OrdAudio objects.


checkProperties( )

Format

public boolean checkProperties(byte[ ] [ ] ctx )

Description

Checks if the properties of the audio data are consistent with the attributes of the OrdAudio Java object.

Parameters

ctx

The format plug-in context information.

Return Value

This method returns true if the properties of the audio data are consistent with the attributes of the OrdAudio Java object; false otherwise.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding checkProperties( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
if(audObj.checkProperties(ctx))
     System.out.println("checkProperties successful");

where:


clearLocal( )

Format

public void clearLocal( )

Description

Clears the local attribute to indicate that the audio data is stored externally.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the local attribute.

Examples

audObj.clearLocal( )

closeSource( )

Format

public int closeSource(byte[ ] [ ] ctx)

Description

Closes a data source.

Parameters

ctx

The source plug-in context information.

Return Value

This method returns the status as an integer, where zero indicates success and a non-zero value indicates a failure code specific to the source plug-in.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding closeSource( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
int i = audObj.closeSource(ctx);
if(i == 0)
     System.out.println("Source close successful");
else
     System.out.println("Source close unsuccessful");

where:


deleteContent( )

Format

public void deleteContent( )

Description

Deletes any data stored in the database BLOB specified by the localData attribute.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding deleteContent( ) method in the database.

Examples

audObj.deleteContent( );

export( )

Format

public void export (byte[ ] [ ] ctx, String srcType, String srcLocation, String srcName)

Description

Exports the data from the BLOB specified by the localData attribute. This method calls the corresponding export( ) method in the database to export the audio data to a location specified by the srcType, srcLocation, and srcName parameters.

Not all source plug-ins support this method. Only the "file" source type is natively supported.

This method will work only if you are running Oracle database server release 8.1.7 or later.

The remainder of this description describes the use of the export( ) method and the Oracle-supplied "file" source plug-in. User-written plug-ins will behave differently.

The export( ) method implemented by the "file" source plug-in copies, but does not modify, the audio data stored in the database BLOB specified by the localData attribute.

After exporting the audio data, all the audio property attributes remain unchanged. However, the srcType, srcLocation, and srcName attributes are updated with values of the srcType, srcLocation, and srcName parameters passed to the export( ) method. After calling the export( ) method, if you no longer intend to manage the audio data within the database, call the clearLocal( ) method to indicate that the audio data is stored outside the database, and call the deleteContent( ) method to delete the audio data stored in the database BLOB.

The export( ) method in the database writes only to a database directory object that the user has privileges 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 method to specify which files can be written.

For example, the following SQL*Plus command grants the user, MEDIAUSER, the permission to write to the file named filmtrack1.au:

  CALL DBMS_JAVA.GRANT.PERMISSION(
'MEDIAUSER',
'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 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 Oracle9i Java Developer's Guide and the java.io.FilePermission class in the Java API for more information about security and performance. See Oracle interMedia User's Guide and Reference for more information about the required privileges.

Parameters

ctx

The source plug-in context information.

srcType

The source type to which the content will be exported.

srcLocation

The source location to which the content will be exported.

srcName

The source name to which the content will be exported.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding export( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
audObj.export(ctx,"file","AUDIODIR","complete.wav");

where:


getAllAttributes( )

Format

public CLOB getAllAttributes(byte[ ] [ ] ctx)

Description

Returns the values of the audio properties in a temporary CLOB in a form defined by the format plug-in. For natively supported formats, the information is presented as a comma-separated list of attributes. The list of attributes is of the form attributeName=attributeValue, where the list contains the following attributes: format, mimeType, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration. For user-defined formats, the information is presented in a form defined by the format plug-in.


Note:

The application must free the temporary CLOB after reading the information it contains.

Parameters

ctx

The format plug-in context information.

Return Value

This method returns the values of the attributes as a temporary oracle.sql.CLOB.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getAllAttributes( ) method in the database.

Examples

byte [ ] ctx[ ] = new byte[1][64];
CLOB attributes = audObj.getAllAttributes(ctx);

where:


getAttribute( )

Format

public String getAttribute(byte[ ] [ ] ctx, String name)

Description

Returns the value of the requested audio property. This method is used by user-defined format plug-ins to return the value of an audio property that is not available as an attribute of the OrdAudio Java object. This method is not implemented by any Oracle-supplied format plug-ins.

Parameters

ctx

The format plug-in context information.

name

The property or attribute name.

Return Value

This method returns the value of the attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getAttribute( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
int attribute = audObj.getAttribute(ctx,"numberOfChannels")

where:


getAudioDuration( )

Format

public int getAudioDuration( )

Description

Returns the value of the audioDuration attribute.

Parameters

None.

Return Value

This method returns the value of the audioDuration attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the audioDuration attribute.

Examples

int audioDuration = audObj.getAudioDuration( );

getBFILE( )

Format

public oracle.sql.BFILE getBFILE( )

Description

Returns a BFILE locator from the database when the srcType attribute is "file." This method calls the corresponding getBFILE( ) method in the database, which creates the BFILE using the srcLocation and srcName attributes.

Parameters

None.

Return Value

This method returns an oracle.sql.BFILE locator.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getBFILE( ) method in the database.

Examples

BFILE audioBFILE = audObj.getBFILE( );

getComments( )

Format

public oracle.sql.CLOB getComments( )

Description

Returns the CLOB locator from the comments attribute.

Parameters

None.

Return Value

This method returns the value of the comments attribute as an oracle.sql.CLOB locator.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the comments attribute.

Examples

CLOB comments = audObj.getComments( )

getCompressionType( )

Format

public String getCompressionType( )

Description

Returns the value of the compressionType attribute.

Parameters

None.

Return Value

This method returns the value of the compressionType attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the compressionType attribute.

Examples

String compressionType = audObj.getCompressionType( );

getContent( )

Format

public oracle.sql.BLOB getContent( )

Description

Returns the BLOB locator from the localData attribute.

Parameters

None.

Return Value

This method returns an oracle.sql.BLOB locator.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the localData attribute.

Examples

BLOB localContent = audObj.getContent( );

getContentInLob( )

Format

public oracle.sql.BLOB getContentInLob(byte[ ] [ ] ctx, String mimetype[ ], String format[ ])

Description

Returns the data from the BLOB specified by the localData attribute in a temporary BLOB in the database. This method creates a temporary BLOB in the database, reads the data from the BLOB specified by the localData attribute, writes the data to the temporary BLOB, then returns the temporary BLOB locator to the caller.


Note:

The application must free the temporary BLOB after accessing the data it contains.

Parameters

ctx

The format plug-in context information.

mimetype

A String array, 1 element in length, into which the mimeType attribute is written as element 0.

format

A String array, 1 element in length, into which the format attribute is written as element 0.

Return Value

This method returns the audio data in a temporary oracle.sql.BLOB locator.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs creating the temporary BLOB or executing the corresponding getContentInLob( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
String mimetype[ ] = new String[1];
String format[ ] = new String[1];
BLOB localContent = audObj.getContentInLob(ctx,mimetype,format);

where:


getContentLength( )

Format

public int getContentLength( )

Description

Returns the length of the audio data. This method calls the corresponding getContentLength( ) method in the database.

This method is not supported for all source types. For example, the "http" source type does not support this method.

Parameters

None.

Return Value

This method returns the value of the contentLength attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getContentLength( ) method in the database.

Examples

int contentLength = audObj.getContentLength( );

getContentLength(byte[ ][ ])

Format

public int getContentLength(byte[ ] [ ] ctx)

Description

Returns the length of the audio data using source plug-in context information. This method calls the corresponding getContentLength( ) method in the database.

This method is not supported for all source types. For example, the "http" source type does not support this method.

Parameters

ctx

The source plug-in context information.

Return Value

This method returns the value of the contentLength attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getContentLength( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
int contentLength = audObj.getContentLength(ctx);

where:


getDataInByteArray( )

Format

public byte[ ] getDataInByteArray( )

Description

Returns a byte array containing the data from the database BLOB specified by the localData attribute.

Parameters

None.

Return Value

This method returns the byte array containing the data.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute.

java.io.IOException

This exception is thrown if an error occurs reading the data from the BLOB.

java.lang.OutOfMemoryError

This exception is thrown if sufficient memory cannot be allocated to hold the data.

Examples

byte[ ] byteArr = audObj.getDataInByteArray( );

getDataInFile( )

Format

public boolean getDataInFile(String filename)

Description

Writes the data from the database BLOB specified by the localData attribute to a local file.

Parameters

filename

The name of the file to which the data will be written.

Return Value

This method returns true if the data is written to the file successfully; otherwise, an exception is raised if an error occurs. This method never returns false.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute.

java.io.IOException

This exception is thrown if an error occurs reading the data from the BLOB or writing the data to the output file.

Examples

boolean load = audObj.getDataInFile("output1.dat");
if(load)
     System.out.println("getDataInFile completed successfully");
else
     System.out.println("Error in getDataInFile");

where:


getDataInStream( )

Format

public InputStream getDataInStream( )

Description

Returns an InputStream object from which the data in the database BLOB specified by the localData attribute can be read.

Parameters

None.

Return Value

This method returns an InputStream object from which the data will be read.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute.

Examples

InputStream inpStream = audObj.getDataInStream( );

getDescription( )

Format

public String getDescription( )

Description

Returns the value of the description attribute.

Parameters

None.

Return Value

This method returns the value of the description attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the description attribute.

Examples

String desc = audObj.getDescription( );

getEncoding( )

Format

public String getEncoding( )

Description

Returns the value of the encoding attribute.

Parameters

None.

Return Value

This method returns the value of the encoding attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the encoding attribute.

Examples

String encoding = audObj.getEncoding( );


getFactory( )

Format

public static oracle.sql.CustomDatumFactory getFactory( )

Description

Returns the OrdAudio CustomDatumFactory interface for use by the getCustomDatum( ) method. Specify the getFactory( ) method as the factory parameter of the getCustomDatum( ) method when retrieving an OrdAudio object from an OracleResultSet or OracleCallableStatement object.

Parameters

None.

Return Value

This method returns the OrdAudio implementation of the CustomDatumFactory interface.

Exceptions

None.

Examples

OrdAudio aud = (OrdAudio)rset.getCustomDatum( 1, OrdAudio.getFactory() );


getFormat( )

Format

public String getFormat( )

Description

Returns the value of the format attribute.

Parameters

None.

Return Value

This method returns the value of the format attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the format attribute.

Examples

String format = audObj.getFormat( );

getMimeType( )

Format

public String getMimeType( )

Description

Returns the value of the mimeType attribute.

Parameters

None.

Return Value

This method returns the value of the mimeType attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the mimeType attribute.

Examples

String mimeType = audObj.getMimeType( );

getNumberOfChannels( )

Format

public int getNumberOfChannels( )

Description

Returns the value of the numberOfChannels attribute.

Parameters

None.

Return Value

This method returns the value of the numberOfChannels attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the numberOfChannels attribute.

Examples

int channels = audObj.getNumberOfChannels( );

getSampleSize( )

Format

public int getSampleSize( )

Description

Returns the value of the sampleSize attribute.

Parameters

None.

Return Value

This method returns the value of the sampleSize attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the sampleSize attribute.

Examples

int sampleSize = audObj.getSampleSize( );


getSamplingRate( )

Format

public int getSamplingRate( )

Description

Returns the value of the samplingRate attribute.

Parameters

None.

Return Value

This method returns the value of the samplingRate attribute, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the samplingRate attribute.

Examples

int samplingRate = audObj.getSamplingRate( );

getSource( )

Format

public String getSource( )

Description

Returns the source information in the form: srcType://srcLocation/srcName.

Parameters

None.

Return Value

This method returns the source information, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding getSource( ) method in the database.

Examples

String source = audObj.getSource( );

getSourceLocation( )

Format

public String getSourceLocation( )

Description

Returns the value of the srcLocation attribute.

Parameters

None.

Return Value

This method returns the value of the srcLocation attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the srcLocation attribute.

Examples

String location = audObj.getSourceLocation( );

getSourceName( )

Format

public String getSourceName( )

Description

Returns the value of the srcName attribute.

Parameters

None.

Return Value

This method returns the value of the srcName attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the srcName attribute.

Examples

String name = audObj.getSourceName( );

getSourceType( )

Format

public String getSourceType( )

Description

Returns the value of the srcType attribute.

Parameters

None.

Return Value

This method returns the value of the srcType attribute, as a String.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the srcType attribute.

Examples

String type = audObj.getSourceType( );

getUpdateTime( )

Format

public java.sql.Timestamp getUpdateTime( )

Description

Returns the value of the updateTime attribute.

Parameters

None.

Return Value

This method returns the value of the updateTime attribute as a java.sql.Timestamp object.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the updateTime attribute.

Examples

Timestamp time = audObj.getUpdateTime( );

importData( )

Format

public void importData(byte[ ] [ ] ctx)

Description

Imports data from an external source into the database BLOB specified by the localData attribute. The external data source is specified by the srcType, srcLocation, and srcName attributes.

Parameters

ctx

The source plug-in context information.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding import( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
audObj.importData(ctx);

where:


importFrom( )

Format

public void importFrom(byte[ ] [ ] ctx, String srcType, String srcLocation, String srcName)

Description

Imports data from an external source into the database BLOB specified by the localData attribute. The external data source is specified by the srcType, srcLocation, and srcName parameters. The srcType, srcLocation, and srcName attributes are updated with values of the srcType, srcLocation, and srcName parameters passed to the importFrom( ) method.

Parameters

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

srcType

The source type from which the data will be imported.

srcLocation

The source location from which the data will be imported.

srcName

The source name from which the data will be imported.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding importFrom( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
audObj.importFrom("file","AUDIODIR","testaud.dat");

where:


isLocal( )

Format

public boolean isLocal( )

Description

Indicates if the audio data is stored locally in the database in a BLOB specified by the localData attribute.

Parameters

None.

Return Value

This method returns true if the data is stored locally in the database in a BLOB; false otherwise.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the localData attribute.

Examples

if(audObj.isLocal( ))
     System.out.println("local attribute is set to true");
else
     System.out.println("local attribute is set to false");

loadDataFromByteArray( )

Format

public boolean loadDataFromByteArray(byte[ ] byteArr)

Description

Loads data from a byte array into the database BLOB specified by the localData attribute. Before loading the data, this method calls the deleteContent( ) method to delete any existing data in the BLOB. It also calls the setLocal( ) method to set the local flag. In addition, this method calls the setUpdateTime( ) method to set the updateTime attribute to the database server's current SYSDATE time.

Parameters

byteArr

A byte array from which the data will be loaded.

Return Value

This method returns true if the data is loaded successfully; otherwise, an exception is raised if an error occurs. This method never returns false.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute or executing a method in the database.

java.io.IOException

This exception is thrown if an error occurs reading the byte array.

Examples

byte[ ] data = new byte[32000];
FileInputStream fStream = new FileInputStream("testaud.dat");
fStream.read(data,0,32000);
boolean success = audObj.loadDataFromByteArray(data);
if(success)
     System.out.println("loadDataFromByteArray was successful");
else
     System.out.println("loadDataFromByteArray was unsuccessful");
 

where:


loadDataFromFile( )

Format

public boolean loadDataFromFile(String filename)

Description

Loads data from a file into the database BLOB specified by the localData attribute. Before loading the data, this method calls the deleteContent( ) method to delete any existing data in the BLOB. It also calls the setLocal( ) method to set the local flag. In addition, this method calls the setUpdateTime( ) method to set the updateTime attribute to the database server's current SYSDATE time.

Parameters

filename

The name of the file from which the data will be loaded.

Return Value

This method returns true if the data is loaded successfully; otherwise, an exception is raised if an error occurs. This method never returns false.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute or executing a method in the database.

java.io.IOException

This exception is thrown if an error occurs reading the data file.

Examples

audObj.loadDataFromFile("testaud.dat");

where:


loadDataFromInputStream( )

Format

public boolean loadDataFromInputStream(InputStream inpStream)

Description

Loads data from an InputStream object into the database BLOB specified by the localData attribute. Before loading the data, this method calls the deleteContent( ) method to delete any existing data in the BLOB. It also calls the setLocal( ) method to set the local flag. In addition, this method calls the setUpdateTime( ) method to set the updateTime attribute to the database server's current SYSDATE time.

Parameters

inpStream

The InputStream object from which the data will be loaded.

Return Value

This method returns true if the data is loaded successfully; otherwise, an exception is raised if an error occurs. This method never returns false.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing an object attribute or executing a method in the database.

java.io.IOException

This exception is thrown if an error occurs reading the InputStream object.

Examples

FileInputStream fStream = new FileInputStream("testaud.dat");
audObj.loadDataFromInputStream(fStream);

where:


openSource( )

Format

public int openSource(byte[ ] userarg, byte[ ] [ ] ctx)

Description

Opens a data source.

Parameters

userarg

Additional source plug-in information that may be required by user-defined source plug-ins.

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

Return Value

This method returns the status as an integer, where zero indicates success and a non-zero value indicates a failure code specific to the source plug-in.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding openSource( ) method in the database.

Examples

byte[ ] userarg = new byte[64];
byte [ ] [ ] ctx = new byte[1][64];
int i = audObj.openSource(userarg,ctx);
if(i == 0)
     System.out.println("openSource successful");
else
     System.out.println("openSource unsuccessful");

where:


processAudioCommand( )

Format

public byte[ ] processAudioCommand(byte[ ] [ ] ctx, String cmd, String args, byte[ ] [ ] result)

Description

Calls the format plug-in in the database to execute a command. This method is used with user-written format plug-ins only; it raises an exception if used with the format plug-ins supplied by Oracle.

Parameters

ctx

The format plug-in context information.

cmd

The command to be executed by the format plug-in.

args

The arguments of the command.

result

A byte array of the form [1][n] into which the result of the command execution is written.

Return Value

This method returns the results of executing the command.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding processAudioCommand( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64]
String cmd;
String args;
byte [ ] [ ] result;
//assign a command value to cmd
//assign any arguments to args
byte[ ] commandResults = audObj.processAudioCommand(ctx,cmd,
     args,result);

where:


processSourceCommand( )

Format

public byte[ ] processSourceCommand(byte[ ] [ ] ctx, String cmd, String args, byte[ ] [ ] result)

Description

Calls the source plug-in in the database to execute a command. This method is used with user-written plug-ins only; it raises an exception if used with the source plug-ins supplied by Oracle.

Parameters

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

cmd

The command to be executed by the source plug-in.

args

The arguments of the command.

result

A byte array of the form [1][n] into which the result of the command execution is written.

Return Value

This method returns the results of executing the command.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding processSourceCommand( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
String cmd;
String args;
byte [ ] [ ] result;
//assign a command value to cmd
//assign any arguments to args
byte[ ] commandResults = audObj.processSourceCommand(ctx,cmd,
     args,result);

where:


readFromSource( )

Format

public int readFromSource(byte[ ] [ ] ctx, int startpos, int numbytes, byte[ ] [ ] buffer)

Description

Reads data from the data source. This method reads the specified number of bytes into the application buffer from the data source, starting at the specified position in the data source.

Not all source plug-ins require that the data source be opened before it can be read. However, to ensure that an application will work with any current or future source plug-ins, call the openSource( ) method before calling this method.

Parameters

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

startpos

The start position in the data source.

numbytes

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

buffer

A byte array of the form [1][n], where n is greater than or equal to numbytes.

Return Value

This method returns the number of bytes read, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding readFromSource( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
byte [ ] [ ] commentBuffer = new byte[12];
int i = audObj.readFromSource(ctx,0,12,commentBuffer);

where:


setAudioDuration( )

Format

public void setAudioDuration(int audioDuration)

Description

Sets the value of the audioDuration attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

audioDuration

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the audioDuration attribute.

Examples

audObj.setAudioDuration(16);

where:


setComments( )

Format

public void setComments(oracle.sql.CLOB comments)

Description

Sets the value of the comments attribute.

The comments attribute is reserved for use by interMedia. You can set your own value, but it could be overwritten by Oracle interMedia Annotator or by the setProperties( ) method.

Parameters

comments

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the comments attribute.

Examples

audObj.setComments(commentsData);

where:


setCompressionType( )

Format

public void setCompressionType(String compressionType)

Description

Sets the value of the compressionType attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

compressionType

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the compressionType attribute.

Examples

audObj.setCompressionType("8BITMONOAUDIO");

where:


setDescription( )

Format

public void setDescription(String description)

Description

Sets the value of the description attribute.

Parameters

description

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the description attribute.

Examples

audObj.setDescription("My audio file");

where:


setEncoding( )

Format

public void setEncoding(String encoding)

Description

Sets the value of the encoding attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

encoding

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the encoding attribute.

Examples

audObj.setEncoding("MULAW");

where:


setFormat( )

Format

public void setFormat(String format)

Description

Sets the value of the format attribute.

The format attribute determines which format plug-in is used to handle calls to methods that operate on the audio data. In particular, the setProperties( ) method uses the format attribute to determine which format plug-in to call to parse the audio data properties. See the setProperties( ) method for more information on how to initialize the format attribute before calling the setProperties( ) method, and for information on how the setProperties( ) method in the default, Oracle-supplied plug-in, sets the value of the format attribute. Calling the setFormat( ) method sets only the attribute value; it does not modify the audio data itself.

Parameters

format

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the format attribute.

Examples

audObj.setFormat("AUFF");

where:


setKnownAttributes( )

Format

public void setKnownAttributes(String format, String encoding,
int numberOfChannels, int samplingRate,
int sampleSize, String compressionType,
int audioDuration)

Description

Sets the values of the known attributes of the OrdAudio Java object.

The setProperties( ) method sets the following attributes automatically for certain audio formats: format, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration. Use this method only if you are not using the setProperties( ) method. This method sets only the specified attribute values; it does not modify the audio data itself.

Parameters

format

The new attribute value, as a String.

encoding

The new attribute value, as a String.

numberOfChannels

The new attribute value, as an integer.

samplingRate

The new attribute value, as an integer.

sampleSize

The new attribute value, as an integer.

compressionType

The new attribute value, as a String.

audioDuration

The new attribute value, as an integer.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding setKnownAttributes( ) method in the database.

Examples

audObj.setKnownAttributes("AUFF","MULAW",1,8,8,"8BITMONOAUDIO",16);

where:


setLocal( )

Format

public void setLocal( )

Description

Sets the value of the local attribute to indicate that the audio data is stored locally in the database in a BLOB specified by the localData attribute.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the localData attribute.

Examples

audObj.setLocal( );


setMimeType( )

Format

public void setMimeType(String mimeType)

Description

Sets the value of the mimeType attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

mimeType

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the mimeType attribute.

Examples

audObj.setMimeType("audio/basic");

where:


setNumberOfChannels( )

Format

public void setNumberOfChannels(int numberOfChannels)

Description

Sets the value of the numberOfChannels attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

numberOfChannels

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the numberOfChannels attribute.

Examples

audObj.setNumberOfChannels(1);

where:


setProperties(byte[ ][ ])

Format

public void setProperties(byte[ ] [ ] ctx)

Description

Parses the audio data properties and sets the values of the attributes in the OrdAudio Java object. This method sets the values of the format, mimeType, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration attributes. An attribute is set to null if the corresponding property cannot be extracted for a specific audio format. This method throws a SQLException error if the audio format is not recognized.

The format attribute determines which format plug-in is used to parse the audio data properties. If the format attribute is null when the setProperties( ) method is called, then the default, Oracle-supplied, format plug-in is used to parse the audio data properties and fill in various attributes, including the actual audio data format, for supported audio formats. See Oracle interMedia User's Guide and Reference for information on the audio formats supported by the Oracle-supplied format plug-ins. Note that the ORDAudio.init methods in the database always set the value of the format attribute to null. If the format attribute is not null, then the format plug-in specified by the format attribute will be called when the setProperties( ) method is called.

Parameters

ctx

The format plug-in context information.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding setProperties( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
audObj.setProperties(ctx);

where:


setProperties(byte[ ][ ], boolean)

Format

public void setProperties(byte[ ] [ ] ctx, boolean setComments)

Description

Parses the audio data properties, sets the values of the attributes in the OrdAudio Java object, and optionally populates the CLOB specified by the comments attribute. This method sets the values of the format, mimeType, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration attributes. An attribute is set to null if the corresponding property cannot be extracted for a specific audio format. If the setComments parameter is true, this method also populates the CLOB specified by the comments attribute with all extracted properties in XML form. If the setComments parameter is false, the comments attribute is not modified. This method throws a SQLException error if the audio format is not recognized.

The format attribute determines which format plug-in is used to parse the audio data properties. If the format attribute is null when the setProperties( ) method is called, then the default, Oracle-supplied, format plug-in is used to parse the audio data properties and fill in various attributes, including the actual audio data format, for supported audio formats. See Oracle interMedia User's Guide and Reference for information on the audio formats supported by the Oracle-supplied format plug-ins. Note that the ORDAudio.init methods in the database always set the value of the format attribute to null. If the format attribute is not null, then the format plug-in specified by the format attribute will be called when the setProperties( ) method is called.

Parameters

ctx

The format plug-in context information.

setComments

A Boolean value that specifies whether or not to populate the CLOB specified by the comments attribute.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding setProperties( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
audObj.setProperties(ctx,true);

where:


setSampleSize( )

Format

public void setSampleSize(int sampleSize)

Description

Sets the value of the sampleSize attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

sampleSize

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the sampleSize attribute.

Examples

audObj.setSampleSize(8);

where:


setSamplingRate( )

Format

public void setSamplingRate(int samplingRate)

Description

Sets the value of the samplingRate attribute.

The setProperties( ) method sets this attribute automatically for certain audio formats; use this method only if you are not using the setProperties( ) method. This method sets only the attribute value; it does not modify the audio data itself.

Parameters

samplingRate

The new attribute value.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the samplingRate attribute.

Examples

audObj.setSamplingRate(8);

where:


setSource( )

Format

public void setSource(String srcType, String srcLocation, String srcName)

Description

Sets the values of the srcType, srcLocation, and srcName attributes.

Parameters

srcType

The type of the source.

srcLocation

The location of the source.

srcName

The name of the source.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs accessing the srcType, srcLocation, or srcName attributes.

Examples

audObj.setSource("file","AUDIODIR","audio.au");

where:


setUpdateTime( )

Format

public void setUpdateTime(java.sql.Timestamp currentTime)

Description

Sets the value of the updateTime attribute. This method sets the value of the updateTime attribute to the specified time, or to the database server's current SYSDATE time if the currentTime attribute is specified as null.

Parameters

currentTime

The update time, or the null value, used to set the value of the updateTime attribute to the database server's current SYSDATE time.

Return Value

None.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding setUpdateTime( ) method in the database.

Examples

audObj.setUpdateTime(null);


trimSource( )

Format

public int trimSource(byte[ ] [ ] ctx, int newLen)

Description

Trims the data to the specified length.

Not all source plug-ins support trim operations. For example, applications can trim the data stored in a BLOB specified by the localData attribute; however, the "file" and "http" data source types do not support write access, and so do not support this method. Furthermore, those source plug-ins that do support write access may not support the trim operation.

Not all source plug-ins require that the data source be opened before it can be modified. However, to ensure that an application will work with any current or future source plug-ins, call the openSource( ) method before calling this method.

Parameters

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

newLen

The length to which the data is to be trimmed.

Return Value

This method returns the status as an integer, where zero indicates success and a non-zero value indicates a failure code specific to the source plug-in.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding
trimSource( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
int i = audObj.trimSource(ctx,10);
if (i == 0)
     System.out.println("trimSource successful");
else
     System.out.println("trimSource unsuccessful");

where:


writeToSource( )

Format

public int writeToSource(byte[ ] [ ] ctx, int startpos, int numbytes, byte[ ] buffer)

Description

Writes data to the data source. This method writes the specified number of bytes from the application buffer to the data source, starting at the specified position in the data source.

Not all source plug-ins support write operations. For example, applications can write to a BLOB specified by the localData attribute; however, the "file" and "http" data source types do not support write access, and so do not support this method. Furthermore, those source plug-ins that do support write access may support only sequential write access, and may not support write access to arbitrary starting positions within the data source.

Not all source plug-ins require that the data source be opened before it can be written. However, to ensure that an application will work with any current or future source plug-ins, call the openSource( ) method before calling this method.

Parameters

ctx

The source plug-in context information. See Oracle interMedia User's Guide and Reference for more information.

startpos

The start position in the data source.

numbytes

The number of bytes to be written to the data source.

buffer

A byte array containing the data to be written.

Return Value

This method returns the number of bytes written, as an integer.

Exceptions

java.sql.SQLException

This exception is thrown if an error occurs executing the corresponding writeToSource( ) method in the database.

Examples

byte [ ] [ ] ctx = new byte[1][64];
byte[ ] data = new byte[20];
//populate data with 20 bytes of content
int i = audObj.writeToSource(ctx,1,20,data);

where:




Go to previous page Go to next page
Oracle Logo
Copyright © 1999, 2002 Oracle Corporation

All rights reserved
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback