oracle.ord.im
Class OrdImage

oracle.ord.im.OrdImage

public class OrdImage

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

Users of this class are assumed to be familiar with Oracle interMedia Java Classes User's Guide and Reference and Oracle interMedia User's Guide and Reference.

All methods operate on the attributes of the OrdImage Java object in the application with the exception of those methods that access the image data for read or write purposes.

• Methods that operate on the database BLOB specified by the localData attribute, read and write data stored in the database BLOB.
• Methods that operate on the database BFILE specified by the srcLocation and srcName attributes when the srcType attribute is "FILE", read data from the specified file at the database server.
• Methods that operate on the URL specified by the srcType, srcLocation, and srcName attributes when the srcType attribute is "HTTP", read data from the resource at the specified URL.

If your application modifies the OrdImage Java object, or the image data in the database, you must update the ORDImage SQL object in the database to make those changes permanent.

Some methods in the OrdImage Java class are handed off to a database source 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. For example, a plug-in may initialize the context information in one call and use that information in a subsequent call. Note that 64 bytes should be sufficient for most plug-ins, however, some user-defined plug-ins may need additional space. The following example illustrates how to allocate the array:

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

OrdImage

public OrdImage()

Internal constructor used only by the Oracle ORAData interface factory method to create an instance of the class. Applications should not use this constructor.

isLocal

public boolean isLocal()
                throws java.sql.SQLException

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

Returns:

true if the data is stored locally in the database in a BLOB, false otherwise.

Throws:

java.sql.SQLException - if an error occurs accessing the local attribute.

setLocal

public void setLocal()
              throws java.sql.SQLException

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

Throws:

java.sql.SQLException - if an error occurs accessing the local attribute.

clearLocal

public void clearLocal()
                throws java.sql.SQLException

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

Throws:

java.sql.SQLException - if an error occurs accessing the local attribute.

getSourceType

public java.lang.String getSourceType()
                               throws java.sql.SQLException

Returns the srcType attribute. For example, "FILE" or "HTTP".

Returns:

the srcType attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the srcType attribute.

getSourceLocation

public java.lang.String getSourceLocation()
                                   throws java.sql.SQLException

Returns the srcLocation attribute. For example, IMAGES_DIR or www.xyzcoimages.com/public.

Returns:

the srcLocation attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the srcLocation attribute.

getSourceName

public java.lang.String getSourceName()
                               throws java.sql.SQLException

Returns the srcName attribute. For example, scenery1.jpg.

Returns:

the srcName attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the srcName attribute.

getSource

public java.lang.String getSource()
                           throws java.sql.SQLException

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

Returns:

the source information as a String.

Throws:

java.sql.SQLException - if an error occurs executing the correspoding getSource method in the database.

setSource

public void setSource(java.lang.String srcType,
                      java.lang.String srcLocation,
                      java.lang.String srcName)
               throws java.sql.SQLException

Sets the srcType, srcLocation, and srcName attributes.

Parameters:

srcType - the source type, for example, "FILE", "HTTP".

srcLocation - the source location, for example, IMAGES_DIR, www.xyzcoimages.com/public.

srcName - the source name, for example, scenery1.jpg

Throws:

java.sql.SQLException - if an error occurs accessing the srcType, srcLocation, or srcName attributes.

getUpdateTime

public java.sql.Timestamp getUpdateTime()
                                 throws java.sql.SQLException

Returns the updateTime attribute.

Returns:

the lastUpdate attribute as a java.sql.Timestamp.

Throws:

java.sql.SQLException - if an error occurs accessing the updateTime attribute.

setUpdateTime

public void setUpdateTime(java.sql.Timestamp currentTime)
                   throws java.sql.SQLException

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

Parameters:

currentTime - the update time in a java.sql.Timestamp, or null to set the update time to the database server's current SYSDATE time.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding setUpdateTime method in the database.

getContent

public oracle.sql.BLOB getContent()
                           throws java.sql.SQLException

Returns the BLOB locator from the localData attribute.

Returns:

an oracle.sql.BLOB.

Throws:

java.sql.SQLException - if an error occurs accessing the localData attribute.

getBFILE

public oracle.sql.BFILE getBFILE()
                          throws java.sql.SQLException

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.

Returns:

an oracle.sql.BFILE.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding getBFILE method in the database.

getHeight

public int getHeight()
              throws java.sql.SQLException

Returns the height attribute.

Returns:

the height attribute as an int.

Throws:

java.sql.SQLException - if an error occurs accessing the height attribute.

setHeight

public void setHeight(int height)
               throws java.sql.SQLException

Sets the height attribute. Note

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

Parameters:

height - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the height attribute.

getWidth

public int getWidth()
             throws java.sql.SQLException

Returns the width attribute.

Returns:

the width attribute as an int.

Throws:

java.sql.SQLException - if an error occurs accessing the width attribute.

setWidth

public void setWidth(int width)
              throws java.sql.SQLException

Sets the width attribute. Note

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

Parameters:

width - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the width attribute.

getContentLength

public int getContentLength()
                     throws java.sql.SQLException

Returns the contentLength attribute.

Returns:

the contentLength attribute as an int.

Throws:

java.sql.SQLException - if an error occurs accessing the contentLength attribute.

setContentLength

public void setContentLength(int contentLength)
                      throws java.sql.SQLException

Sets the contentLength attribute. Note

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

Parameters:

contentLength - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the contentLength attribute.

getFormat

public java.lang.String getFormat()
                           throws java.sql.SQLException

Returns the fileFormat attribute.

Returns:

the fileFormat attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the fileFormat attribute.

setFormat

public void setFormat(java.lang.String fileFormat)
               throws java.sql.SQLException

Sets the fileFormat attribute. Note

setProperties sets this attribute automatically for certain media formats; use this method only if you are not using setProperties. This method sets the attribute value only; it does not modify the media data itself. Set the fileFormat attribute to a String beginning with "OTHER" to disable the automatic call to setProperties by the importData and importFrom methods.

Parameters:

fileFormat - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the fileFormat attribute.

getContentFormat

public java.lang.String getContentFormat()
                                  throws java.sql.SQLException

Returns the contentFormat attribute.

Returns:

the contentFormat attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the contentFormat attribute.

setContentFormat

public void setContentFormat(java.lang.String contentFormat)
                      throws java.sql.SQLException

Sets the contentFormat attribute. Note

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

Parameters:

contentFormat - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the contentFormat attribute.

getCompressionFormat

public java.lang.String getCompressionFormat()
                                      throws java.sql.SQLException

Returns the compressionFormat attribute.

Returns:

the compressionFormat attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the compressionFormat attribute.

setCompressionFormat

public void setCompressionFormat(java.lang.String compressionFormat)
                          throws java.sql.SQLException

Sets the compressionFormat attribute. Note

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

Parameters:

compressionFormat - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the compressionFormat attribute.

getMimeType

public java.lang.String getMimeType()
                             throws java.sql.SQLException

Returns the mimeType attribute.

Returns:

the mimeType attribute as a String.

Throws:

java.sql.SQLException - if an error occurs accessing the mimeType attribute.

setMimeType

public void setMimeType(java.lang.String mimeType)
                 throws java.sql.SQLException

Sets the mimeType attribute. Note

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

Parameters:

mimeType - the new attribute value.

Throws:

java.sql.SQLException - if an error occurs accessing the mimeType attribute.

loadDataFromFile

public boolean loadDataFromFile(java.lang.String filename)
                         throws java.sql.SQLException,
                                java.io.IOException

Loads data from a file into the database BLOB specified by the localData attribute. Before loading the data, this method calls the following methods:

• deleteContent(), to delete any existing data in the BLOB.
• setLocal(), to set the local flag.
• setUpdateTime(), to set the updateTime attribute to the database server's current SYSDATE time.

Parameters:

filename - name of the file from which to load data.

Returns:

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

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute or if an error occurs executing a method in the database.

java.io.IOException - if an error occurs reading the data file.

loadDataFromInputStream

public boolean loadDataFromInputStream(java.io.InputStream inpStream)
                                throws java.sql.SQLException,
                                       java.io.IOException

Loads data from an InputStream into the database BLOB specified by the localData attribute. Before loading the data, this method calls the following methods:

• deleteContent(), to delete any existing data in the BLOB.
• setLocal(), to set the local flag.
• setUpdateTime(), to set the updateTime attribute to the database server's current SYSDATE time.

Parameters:

inpStream - the InputStream from which to load data.

Returns:

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

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute or if an error occurs executing a method in the database.

java.io.IOException - if an error occurs reading the InputStream.

loadDataFromByteArray

public boolean loadDataFromByteArray(byte[] byteArr)
                              throws java.sql.SQLException,
                                     java.io.IOException

Loads data from a byte array into the database BLOB specified by the localData attribute. Before loading the data, this method calls the following methods:

• deleteContent(), to delete any existing data in the BLOB.
• setLocal(), to set the local flag.
• setUpdateTime(), to set the updateTime attribute to the database server's current SYSDATE time.

Parameters:

byteArr - a byte[] arrary from which to load data.

Returns:

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

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute or if an error occurs executing a method in the database.

java.io.IOException - if an error occurs reading the byte array.

getDataInFile

public boolean getDataInFile(java.lang.String filename)
                      throws java.sql.SQLException,
                             java.io.IOException

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

Parameters:

filename - name of the file to which the data is to be written.

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.

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute.

java.io.IOException - if an error occurs reading the data from the BLOB or writing the data to the output file.

getDataInStream

public java.io.InputStream getDataInStream()
                                    throws java.sql.SQLException

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

Returns:

an InputStream from which the data can be read.

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute.

getDataInByteArray

public byte[] getDataInByteArray()
                          throws java.sql.SQLException,
                                 java.io.IOException,
                                 java.lang.OutOfMemoryError

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

Returns:

a byte[] array containing the data.

Throws:

java.sql.SQLException - if an error occurs accessing an object attribute.

java.io.IOException - if an error occurs reading the data from the BLOB.

java.lang.OutOfMemoryError - if sufficient memory cannot be allocated to hold the data.

deleteContent

public void deleteContent()
                   throws java.sql.SQLException

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

Throws:

java.sql.SQLException - if an error occurs executing the corresponding deleteContent method in the database.

importData

public void importData(byte[][] ctx)
                throws java.sql.SQLException

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. After importing the image data, by default, this method automatically calls the setProperties method in the database to set the property attributes. If you are importing a foreign image whose format is not understood by interMedia, call setFormat to set the fileFormat to a String beginning with "OTHER" to disable the automatic call to setProperties.

Parameters:

ctx - the source plug-in context information.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding import method or the setProperties method in the database.

importFrom

public void importFrom(byte[][] ctx,
                       java.lang.String srcType,
                       java.lang.String srcLocation,
                       java.lang.String srcName)
                throws java.sql.SQLException

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. After importing the image data, by default, this method automatically calls the setProperties method in the database to set the property attributes. If you are importing a foreign image whose format is not understood by interMedia, call setFormat to set the fileFormat to "OTHER" to disable the automatic call to setProperties.

Parameters:

ctx - the source plug-in context information.

srcType - the source type, for example, "FILE", "HTTP".

srcLocation - the source location, for example, IMAGES_DIR, www.xyzcoimages.com/public.

srcName - the source name, for example, scenery1.jpg.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding importFrom method or the setProperties method in the database.

export

public void export(byte[][] ctx,
                   java.lang.String srcType,
                   java.lang.String srcLocation,
                   java.lang.String srcName)
            throws java.sql.SQLException

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

Not all source plug-ins support the export method. For example, the "FILE" source type is the only Oracle-supplied source type that supports the export method. In addition, this method is supported only by Oracle database server release 8.1.7 or later.

The remainder of this description illustrates the use of the export method and the Oracle-supplied "FILE" source plug-in. User-written plug-ins will have different behaviors.

The export method implemented by the Oracle-supplied "FILE" source plug-in copies the image data from the BLOB specified by the localData attribute, but does not modify the image data stored in the database BLOB in any way.

After exporting the image data, all the image 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 image data within the database, call the clearLocal() method to indicate the image data is stored outside the database and call the deleteContent() method to delete the image data stored in the database BLOB.

The export method in the database writes only to a database directory object that the user has privilege to access. That is, you can access a directory that you have created using the SQL CREATE DIRECTORY statement, or one to which you have been granted READ access. To execute the CREATE DIRECTORY statement, you must have the CREATE ANY DIRECTORY privilege. In addition, you must use the DBMS_JAVA.GRANT_PERMISSION 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 scenery1.jpg.

 CALL DBMS_JAVA.GRANT_PERMISSION(
     'MEDIAUSER',
     'java.io.FilePermission',
     '/images/outdoors/scenery1.jpg',
     'write');

The previous example illustrates 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 "/*" (where "/" is the operating-system dependent file separator character) indicates all the files contained in the specified directory. A path specification that ends with "/-" indicates all files contained in the specified directory and all its subdirectories. A pathname consisting of the special token "<<ALL FILES>>" authorizes access to any file.

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

Parameters:

ctx - the source plug-in context information.

srcType - the source type, for example, "FILE".

srcLocation - the source location, for example, IMAGES_DIR.

srcName - the source name, for example, scenery1.jpg.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding export method in the database.

setProperties

public void setProperties()
                   throws java.sql.SQLException

Parses the image data properties and sets the attributes in the OrdImage Java object. This method sets the height, width, contentLength, fileFormat, contentFormat, compressionFormat, and mimeType attributes. An attribute is set to null if the corresponding property cannot be extracted for a specific image format. This method throws a SQLException if the image format is not recognized.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding setProperties method in the database.

setProperties

public void setProperties(java.lang.String description)
                   throws java.sql.SQLException

Writes the characteristics of a foreign image into the appropriate attribute fields. This method sets various attributes of the OrdImage object based on a set of characteristics that describe the image properties. With this information, Oracle interMedia is able to process certain foreign image formats. See Oracle interMedia User's Guide and Reference for more information on setting image characteristics for foreign images.

Parameters:

description - a String that specifies the image characteristics to set for the foreign image.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding setProperties method in the database.

checkProperties

public boolean checkProperties()
                        throws java.sql.SQLException

Checks if the properties of the image data are consistent with the attributes of the OrdImage Java object.

Returns:

true if the properties of the image data are consistent with the attributes of the OrdImage Java object; false otherwise.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding checkProperties method in the database.

process

public void process(java.lang.String cmd)
             throws java.sql.SQLException

Performs one or more image processing operations on the image data in the database BLOB specified by the localData attribute. This method calls the corresponding process method in the database to perform the image processing operations specified by the cmd parameter. See Oracle interMedia User's Guide and Reference for more information on the various image processing operations that can be performed on an image.

Parameters:

cmd - a String that specifies a list of image processing operations to perform on the image.

Throws:

java.sql.SQLException - if an error occurs executing the corresponding process method in the database.

copy

public void copy(OrdImage dest)
          throws java.sql.SQLException

Copies an OrdImage Java object. This method calls the corresponding copy method in the database. The copy method copies all the attributes of the current OrdImage object to the destination OrdImage object with the exception of the BLOB specified by the localData attribiute. If the image data is stored locally in the database, then the data is copied from the BLOB specified by localData attribute in the current OrdImage object to the BLOB specified by the localData attribute in the destination object.

Parameters:

dest - the destination OrdImage object.

Throws:

java.sql.SQLException - if an error occurs calling the corresponding copy method in the database.

processCopy

public void processCopy(java.lang.String cmd,
OrdImage dest)
                 throws java.sql.SQLException

Copies the image data to the destination object and performs one or more image processing operations on the image data. If the source image data is stored externally to the database, then it is imported into the database BLOB specified by the localData attribute in the destination OrdImage object. Otherwise, the image data is copied from the BLOB specified by localData attribute in the current OrdImage object to the BLOB specified by the localData attribute in the destination object.

Parameters:

cmd - a String that specifies a list of image processing operations to perform on the image.

dest - the destination OrdImage object.

Throws:

java.sql.SQLException - if an error occurs calling the corresponding processCopy method in the database.

getORADataFactory

public static oracle.sql.ORADataFactory getORADataFactory()

Returns the OrdImage ORADataFactory for use by the getORAData method. Specify this method as the factory parameter of the getORAData method when retrieving an OrdImage object from an OracleResultSet or OracleCallableStatement. For example:

  OrdImage img = (OrdImage)rset.getORAData( 1, OrdImage.getORADataFactory() );

Returns:

the OrdImage implementation of the ORADataFactory interface.

getFactory

public static oracle.sql.CustomDatumFactory getFactory()

Deprecated. CustomDatumFactory method. New applications should use the ORADataFactory interface

create

public oracle.sql.CustomDatum create(oracle.sql.Datum d,
                                     int sqlType)
                              throws java.sql.SQLException

Internal method used only by the Oracle CustomDatum interface. Applications should not call this method.