4
OrdDoc Reference Information

interMedia Java Classes describes the OrdDoc object type, which supports the storage and management of any multimedia data, including audio, image, text, and video data.

Some methods invoked at the OrdDoc level are handed off to the database source plug-in or database format plug-in for processing; these methods have byte[ ] ctx[ ] as a context parameter. In cases where a client system is connecting to a database server, the space for the parameter is created by the client (in the reference examples, 4000 bytes of space), but the content of the context parameter is generated by the server. The context parameter is passed from the client to the server for the processing of context information.

Note: In the current release, not all source plug-ins or format plug-ins will use or generate the context parameter, but if you include the parameter as previously 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.

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

• A connection has been made to a table that contains a column of type OrdDoc.

• A local OrdDoc object named docObj has been created and populated with data.

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

4.2 Reference Information

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

---

clearLocal( )

Format

public void clearLocal( )

Description

Clears the source local field of the application OrdDoc object.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.clearLocal( )

---

closeSource( )

Format

public int closeSource(byte[ ] ctx[ ])

Description

Closes the application OrdDoc file source.

Parameters

ctx[ ]

The source plug-in context information.

Return Value

This method returns 0 if the operation is successful, or an integer greater than 0 in case of failure.

Exceptions

java.sql.SQLException

Example

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

where:

• ctx: contains the source plug-in context information.

---

deleteContent( )

Format

public void deleteContent( )

Description

Deletes the multimedia data in the BLOB in the application OrdDoc object.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.deleteContent( );

---

export( )

Format

public void export (byte[ ] ctx[ ], String sourceType, String sourceLocation, String sourceName)

Description

Exports the data from the application OrdDoc object BLOB to the location specified in the parameters.

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

This method writes only to a 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. See Oracle interMedia User's Guide and Reference for more information about the required privileges.

Parameters

ctx[ ]

The source plug-in context information.

sourceType

The source type to which the content will be exported. Only "file" is natively supported.

sourceLocation

The location on the database server to which the content will be exported. It must be created with a SQL CREATE OR REPLACE DIRECTORY statement, as shown in step 2 of Example 2-19.

sourceName

The name of the source to which the content will be exported.

Return Value

None.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
docObj.export(ctx,"file","DOCDIR","complete.xml");

where:

• ctx: contains the source plug-in context information.

• file: is the source type to which the content will be exported.

• DOCDIR: is the location to which the content will be exported.

• complete.xml: is the file to which the content will be exported.

---

getBFILE( )

Format

public oracle.sql.BFILE getBFILE( )

Description

Generate a BFILE from the application OrdDoc object, if the value of srcType is "file." This method uses the srcLocation and srcName attributes to generate the BFILE.

Parameters

None.

Return Value

This method returns the BFILE.

Exceptions

java.sql.SQLException

Example

BFILE documentBFILE = docObj.getBFILE( );

---

getComments( )

Format

public oracle.sql.CLOB getComments( )

Description

Returns the comments CLOB from the application OrdDoc object.

Parameters

None.

Return Value

This method returns a CLOB that contains the comments from the OrdDoc object.

Exceptions

java.sql.SQLException

Example

CLOB comments = docObj.getComments( )

---

getContent( )

Format

public oracle.sql.BLOB getContent( )

Description

Gets the LOB locator from the application OrdDoc object.

Parameters

None.

Return Value

This method returns the LOB locator of the application OrdDoc object.

Exceptions

java.sql.SQLException

Example

BLOB localContent = docObj.getContent( );

---

getContentInLob( )

Format

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

Description

Gets the content of the application OrdDoc object and puts it in a BLOB.

Parameters

ctx[ ]

The source plug-in context information.

mimetype[ ]

The MIME type of the content returned, stored in mimetype[0].

format[ ]

The format of the content returned, stored in format[0].

Return Value

This method returns the LOB content of the application OrdDoc object in a LOB locator.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
String mimeType[ ] = new String[1];
String format[ ] = new String[1];
BLOB localContent = docObj.getContentInLob(ctx,mimeType,format);

where:

• ctx: contains the source plug-in context information.

• mimeType: is an array of Strings whose first value contains the MIME type of the LOB data. This value is generated by the server.

• format: is an array of Strings whose first value contains the format of the LOB data. This value is generated by the server.

---

getContentLength( )

Format

public int getContentLength( )

Description

Gets the content length of the data in the application OrdDoc object.

Parameters

None.

Return Value

This method returns the content length of the data.

Exceptions

java.sql.SQLException

Example

int contentLength = docObj.getContentLength( );

---

getDataInByteArray( )

Format

public byte[ ] getDataInByteArray( )

Description

Gets data from the LOB locator of the application OrdDoc object and puts it in a local byte array.

Parameters

None.

Return Value

This method returns the byte array from which the data will be read.

Exceptions

java.sql.SQLException

java.io.IOException

java.lang.OutOfMemoryError

Example

byte[ ] byteArr = docObj.getDataInByteArray( );

---

getDataInFile( )

Format

public boolean getDataInFile(String filename)

Description

Gets data from the LOB locator of the application OrdDoc object and puts it in a local file.

Parameters

filename

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

Return Value

This method returns true if loading is successful; false otherwise.

Exceptions

java.sql.SQLException

java.io.IOException

Example

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

where:

• output1.dat: is the file into which the data will be loaded.

---

getDataInStream( )

Format

public InputStream getDataInStream( )

Description

Gets data from the LOB locator of the application OrdDoc object and returns it as a local input stream.

Parameters

None.

Return Value

This method returns the input stream from which the data will be read.

Exceptions

java.sql.SQLException

java.io.IOException

Example

InputStream inpStream = docObj.getDataInStream( );

---

getFormat( )

Format

public String getFormat( )

Description

Gets the format attribute of the application OrdDoc object as a String.

Parameters

None.

Return Value

This method returns the format attribute as a String.

Exceptions

java.sql.SQLException

Example

String format = docObj.getFormat( );

---

getMimeType( )

Format

public String getMimeType( )

Description

Gets the MIME type of the application OrdDoc object as a String.

Parameters

None.

Return Value

This method returns the MIME type of the OrdDoc object as a String.

Exceptions

java.sql.SQLException

Example

String mimeType = docObj.getMimeType( );

---

getSource( )

Format

public String getSource( )

Description

Gets the object source information of the application OrdDoc object, including the source location, name, and type.

Parameters

None.

Return Value

This method returns a String containing the object source information.

Exceptions

java.sql.SQLException

Example

String source = docObj.getSource( );

---

getSourceLocation( )

Format

public String getSourceLocation( )

Description

Gets the source location of the application OrdDoc object as a String.

Parameters

None.

Return Value

This method returns a String containing the object source location.

Exceptions

java.sql.SQLException

Example

String location = docObj.getSourceLocation( );

---

getSourceName( )

Format

public String getSourceName( )

Description

Gets the source name of the application OrdDoc object as a String.

Parameters

None.

Return Value

This method returns a String containing the object source name.

Exceptions

java.sql.SQLException

Example

String name = docObj.getSourceName( );

---

getSourceType( )

Format

public String getSourceType( )

Description

Gets the source type of the application OrdDoc object as a String.

Parameters

None.

Return Value

This method returns a String containing the object source type.

Exceptions

java.sql.SQLException

Example

String type = docObj.getSourceType( );

---

getUpdateTime( )

Format

public java.sql.Timestamp getUpdateTime( )

Description

Gets a Timestamp object that contains information on when the application OrdDoc object was most recently updated.

Parameters

None.

Return Value

This method returns a Timestamp object that contains the time of the most recent update.

Exceptions

java.sql.SQLException

Example

Timestamp time = docObj.getUpdateTime( );

---

importData( )

Format

public void importData(byte[ ] ctx[ ])

Description

Imports data from an external source into the application OrdDoc object.

The srcType, srcLocation, and srcName attributes must all be set for this method to work. If srcType is "file," then srcLocation and srcName are values of a file local to the server.

Parameters

ctx[ ]

The source plug-in context information.

Return Value

None.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
docObj.importData(ctx);

where:

• ctx: contains the source plug-in information.

---

importFrom( )

Format

public void importFrom(byte[ ] ctx[ ], String sourceType, String sourceLocation, String sourceName)

Description

Imports data from an external source into the application OrdDoc object.

Parameters

ctx[ ]

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

sourceType

The source type from which the data will be imported.

sourceLocation

The source location on the database server from which the data will be imported. If sourceType is "file," the directory must be created with a SQL CREATE OR REPLACE DIRECTORY statement, as shown in step 2 of Example 2-19.

sourceName

The source name from which the data will be imported.

Return Value

None.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
docObj.importFrom("file","DOCDIR","testdoc.dat");

where:

• ctx: contains the source plug-in context information.

• file: is the type of the source from which the data will be imported.

• DOCDIR: is the location of the file on the database server from which the data will be imported.

• testdoc.dat: is the file from which the data will be imported.

---

isLocal( )

Format

public boolean isLocal( )

Description

Checks if the application OrdDoc object local attribute is set.

Parameters

None.

Return Value

This method returns true if the OrdDoc object local attribute is set; false otherwise.

Exceptions

java.sql.SQLException

Example

if(docObj.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 the local byte buffer into the database OrdDoc object LOB locator and into the application object. It also calls setLocal( ) (which sets the local field of the application OrdDoc object but not the database object), and setUpdateTime(null) (which sets the updateTime attribute to the SYSDATE of the database server).

Parameters

byteArr

The name of the local byte array from which the data will be loaded.

Return Value

This method returns true if loading is successful; false otherwise.

Exceptions

java.sql.SQLException

java.io.IOException

Example

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

where:

• data: is the local byte array from which the data will be loaded.

• testdoc.dat: is a local file that contains 32,300 bytes of data.

---

loadDataFromFile( )

Format

public boolean loadDataFromFile(String filename)

Description

Loads data from the local file into the database OrdDoc object LOB locator and into the application object. It also calls setLocal( ) (which sets the local field of the application OrdDoc object, but not the database object) and setUpdateTime(null) (which sets the updateTime attribute to the SYSDATE of the database server).

Parameters

filename

The name of the local file from which to load data.

Return Value

This method returns true if loading is successful; false otherwise.

Exceptions

java.sql.SQLException

java.io.IOException

Example

docObj.loadDataFromFile("testdoc.dat");

where:

• testdoc.dat: is a local file that contains multimedia data.

---

loadDataFromInputStream( )

Format

public boolean loadDataFromInputStream(InputStream inpStream)

Description

Loads data from the local input stream into the database OrdDoc object LOB locator and into the application object. It also calls setLocal( ) (which sets the local field of the application OrdDoc object, but not the database object) and setUpdateTime(null) (which sets the updateTime attribute to the SYSDATE of the database server).

Parameters

inpStream

The name of the local input stream from which to load data.

Return Value

This method returns true if loading is successful; false otherwise.

Exceptions

java.sql.SQLException

java.io.IOException

Example

FileInputStream fStream = new FileInputStream("testdoc.dat");
docObj.loadDataFromInputStream(fStream);

where:

• testdoc.dat: is a local file that contains multimedia data.

• fStream: is the local input stream that will load data into the OrdDoc object.

---

openSource( )

Format

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

Description

Opens the OrdDoc file source.

Parameters

userarg

Permission-related parameters that are supplied by the user, such as READONLY. These may be used 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 0 if the operation is successful, or an integer greater than 0 in case of failure.

Exceptions

java.lang.Exception

Example

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

where:

• userarg: contains permission-related parameters.

• ctx: contains the source plug-in context information.

---

processSourceCommand( )

Format

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

Description

Processes the specified command on the application OrdDoc object by calling the database processSourceCommand( ) method. This method is for use with user-written plug-ins only; this method will raise an exception if used with the default plug-in supplied by Oracle.

Parameters

ctx[ ]

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

command

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

args

The arguments of the command to be executed.

result[ ]

The results of the command.

Return Value

This method returns the results of executing the command.

Exceptions

java.sql.SQLException

Example

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

where:

• ctx: contains the source plug-in information.

• command: is the command to be run.

• arguments: contains any arguments required by the command.

• result: is the results of the command.

---

readFromSource( )

Format

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

Description

Reads data from the OrdSource localData field of the application OrdDoc object. into the first position of the buffer array.

Parameters

ctx[ ]

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

startpos

The initial position in the localData field.

numbytes

The number of bytes to be read.

buffer

The buffer into which to read the content.

Return Value

This method returns the number of bytes read.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
byte[ ] buffer[ ] = new byte[12][1];
int i = docObj.readFromSource(ctx,0,12,buffer);

where:

• ctx: contains the source plug-in context information.

• 0: is the position to begin reading from the localData field.

• 12: is the number of bytes to be read.

• buffer: is the buffer to which the data will be read. The data will be stored in buffer[0].

---

setComments( )

Format

public void setComments(oracle.sql.CLOB comments)

Description

Sets the comments in the application OrdDoc object.

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

Parameters

comments

A CLOB that contains attributes for the OrdDoc object.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.setComments(commentsData);

where:

• commentsData: is a CLOB that contains comments to be set.

---

setContentLength( )

Format

public void setContentLength(int newContentLength)

Description

Sets the content length of the data in the application OrdDoc object.

setProperties( ) will automatically set this attribute for known formats; use this method only if you are not using setProperties( ) or for unknown formats. Also, this method will set only the attribute value; it does not change the multimedia file itself.

Parameters

newContentLength

The new content length to be set, in bytes.

Return Value

None.

Exceptions

java.sql.SQLException

Example

None.

---

setFormat( )

Format

public void setFormat(String format)

Description

Sets the format attribute of the application OrdDoc object.

setProperties( ) will automatically set this attribute for known formats; use this method only if you are not using setProperties( ) or for unknown formats. Also, this method will set only the attribute value; it does not change the multimedia file itself.

Parameters

format

The format of the contents of the OrdDoc object, as a String.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.setFormat("AUFF");

where:

• AUFF: is the format to be set.

---

setLocal( )

Format

public void setLocal( )

Description

Sets the source local field of the application OrdDoc object.

Parameters

None.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.setLocal( );

---

setMimeType( )

Format

public void setMimeType(String MimeType)

Description

Sets the MIME type of the application OrdDoc object.

setProperties( ) will automatically set this attribute for known formats; use this method only if you are not using setProperties( ) or for unknown formats. Also, this method will set only the attribute value; it does not change the multimedia file itself.

Parameters

MimeType

The MIME type of the contents of the OrdDoc object, as a String.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.setMimeType("application/pdf");

where:

• application/pdf: is the MIME type to be set.

---

setProperties( )

Format

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

Description

Reads the multimedia data, extracts the properties, and sets the properties in the application OrdDoc object. This method will work for known audio, image, and video formats.

Parameters

ctx[ ]

The format plug-in context information.

setComments

A boolean value to determine whether or not to set the comments in the OrdDoc object. If true, the comments field is populated with a set of format and application properties of the object in XML. If false, the comments field remains unpopulated. The default value is false.

Return Value

None.

Exceptions

java.sql.SQLException

Example

byte[ ] ctx[ ] = new byte[4000][1];
docObj.setProperties(ctx,true);

where:

• ctx: contains the format plug-in context information.

• true: indicates that the comments field will be populated.

---

setSource( )

Format

public void setSource(String sourceType, String sourceLocation, String sourceName)

Description

Sets the application OrdDoc object source information.

Parameters

sourceType

The type of the source.

sourceLocation

The location of the source. If sourceType is "file," it must be created with a SQL CREATE OR REPLACE DIRECTORY statement, as shown in step 2 of Example 2-19.

sourceName

The name of the source.

Return Value

None.

Exceptions

java.sql.SQLException

Example

audObj.setSource("file","DOCDIR","sample.pdf");

where:

• file: is the source type.

• DOCDIR: is the source location.

• sample.pdf: is the source name.

---

setUpdateTime( )

Format

public void setUpdateTime(java.sql.Timestamp currentTime)

Description

Sets the update time in the application OrdDoc object to the current time.

setProperties( ) will automatically set this attribute for known formats; use this method only if you are not using setProperties( ) or for unknown formats. Also, this method will set only the attribute value; it does not change the multimedia file itself.

Parameters

currentTime

The current time, which will be set in the OrdDoc object. Setting this parameter to null will set the update time to the current SYSDATE of the database server.

Return Value

None.

Exceptions

java.sql.SQLException

Example

docObj.setUpdateTime(null);

---

trimSource( )

Format

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

Description

Trim the content source of the application OrdDoc object to the given length.

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 source will be trimmed.

Return Value

This method returns 0 if the operation is successful.

Exceptions

java.sql.SQLException

Example

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

where:

• ctx: contains the source plug-in context information.

• 10: is the new length of the source.

---

writeToSource( )

Format

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

Description

Writes data to the source localData field of the application OrdDoc object.

Parameters

ctx[ ]

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

startpos

The initial position in the localData field.

numbytes

The number of bytes to be written.

buffer

The buffer containing the content to be written.

Return Value

This method returns the number of bytes written.

Exceptions

java.sql.SQLException

Example

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

where:

• ctx: contains the source plug-in context information.

• 1: is the position in the localData field where writing will begin.

• 20: is the number of bytes to be written.

• data: contains the content to be written.