com.jcorporate.expresso.core.dataobjects.jdbc
Class LobField

java.lang.Object
  com.jcorporate.expresso.core.dataobjects.jdbc.LobField

public class LobField

extends Object

This class provides a low level BLOB capability while still keeping the programmer isolated from SQL syntax details.

The general usage is as follows:
MyDBObject myObj.setField("key1",1);
LobField query = new LobField();
query.setCriteria(myObj);
java.io.InputStream inputStream = getBlobStream("blobFieldName"); //Do whatever you want with the stream
inputStream.flush(); inputStream.close(); query.close();

This class requires a JDBC 2 compliant driver for the BLOB/CLOB data types. Some drivers do not support these features, at which point you'll want to use the getBlobStream/getClobStream/getClobAsciiStream methods instead

Since:

$DatabaseSchema $Date: 2004/11/18 02:03:27 $

Author:

Michael Rimov

Field Summary

protected JDBCDataObject	criteria The dataobject to use to build the SQL search/update statements.
protected DBConnection	myConnection

Constructor Summary

LobField()
Default constructor.

Method Summary

void	close() Close the query resources held by the object.
protected void	finalize() Override of base object finalization to make sure that the database resources are closed if for some reason they haven't had this done to them already.
protected void	finalizeUpdate(DBConnection theConnection)
Blob	getBlob(String fieldName) Retrieves a java.sql.Blob object given the criteria object set previously.
InputStream	getBlobStream(String fieldName) Retrieve an input stream for a binary object stored in the database.
Clob	getClob(String fieldName) Retrieves a java.sql.Clob object given the criteria object set previously.
InputStream	getClobAsciiStream(String fieldName) Retrieve a java.io.InputStream a.k.a.
Reader	getClobStream(String fieldName) Retrieve a java.io.Reader a.k.a Unicode stream for a CLOB field.
String	getClobString(String fieldName) CLOB convenience method.
protected JDBCDataObject	getCriteria() Protected method to get at the criteria object from any derived classes
protected void	oraclePrepSelectForUpdate(JDBCDataObject baseObject, String fieldName, DBConnection theConnection) Internal helper function to prepare a BLOB update for Oracle.
protected void	prepSelectResultSet(JDBCDataObject baseObject, String fieldName, DBConnection theConnection) Internal helper function that does the guts of the work
protected PreparedStatement	prepUpdate(JDBCDataObject baseObject, String fieldName, DBConnection theConnection) Internal helper function to prepare a LOB update
void	saveBlob(String fieldName, Blob data) Saves a java.sql.Blob to the record matching the criteria earlier set.
void	saveBlob(String fieldName, InputStream data, int dataSize) Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).
void	saveClob(String fieldName, Clob data) Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).
void	saveClob(String fieldName, InputStream data, int length) Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).
void	saveClob(String fieldName, Reader data, int length) Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).
void	saveClob(String fieldName, String data) Saves a string to a CLOB field.
void	setCriteria(JDBCDataObject newCriteria) Set the search criteria for the blob.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

criteria

protected JDBCDataObject criteria

The dataobject to use to build the SQL search/update statements.

myConnection

protected DBConnection myConnection

Constructor Detail

LobField

public LobField()

Default constructor. Currently does nothing.

Method Detail

setCriteria

public void setCriteria(JDBCDataObject newCriteria)
                 throws DataException

Set the search criteria for the blob. All key fields must be present as this does a full retrieve() rather than a search on the data. Otherwise the object will throw an exception .

Parameters:

newCriteria - a filled out JDBCObject (DBObject derived classes work) with all keys present

Throws:

DataException - if all keys are not present.

getCriteria

protected JDBCDataObject getCriteria()

Protected method to get at the criteria object from any derived classes

Returns:

JDBCDataObject or null if no criteria has been set

getBlob

public Blob getBlob(String fieldName)
             throws DataException

Retrieves a java.sql.Blob object given the criteria object set previously.

Parameters:

fieldName - the name of the field to retrieve

Returns:

java.sql.Blob for the field

Throws:

DataException - if there is an error finding the object, an error retrieving the Blob from the system, or other database communication errors.

getClob

public Clob getClob(String fieldName)
             throws DataException

Retrieves a java.sql.Clob object given the criteria object set previously.

Parameters:

fieldName - the name of the field to retrieve

Returns:

java.sql.Clob for the field

Throws:

DataException - if there is an error finding the object, an error retrieving the Clob from the system, or other database communication errors.

getBlobStream

public InputStream getBlobStream(String fieldName)
                          throws DataException

Retrieve an input stream for a binary object stored in the database.

Parameters:

fieldName - the field name to retrieve.

Returns:

java.io.InputStream representing the BLOB object

Throws:

DataException - upon error

getClobStream

public Reader getClobStream(String fieldName)
                     throws DataException

Retrieve a java.io.Reader a.k.a Unicode stream for a CLOB field.

Parameters:

fieldName - the name of the field to retrieve.

Returns:

java.io.Reader for the Unicode CLOB stream stored in the database

Throws:

DataException - upon error retrieving the CLOB

getClobString

public String getClobString(String fieldName)
                     throws DataException

CLOB convenience method. Reads the entire stream into a string. Note that if your field is large, this may take large amounts of memory to perform this operation. It is recommended to use getClobStream() for most purposes.

Note that this method is not supported by InterBase/InterClient 2 which does not support Unicode streams. Use getClobAsciiStream instead

Parameters:

fieldName - the name of the field to retrieve

Returns:

java.lang.String containing the entire contents of the CLOB field.

Throws:

DataException - upon error.

getClobAsciiStream

public InputStream getClobAsciiStream(String fieldName)
                               throws DataException

Retrieve a java.io.InputStream a.k.a. ASCII stream for a CLOB field.

Parameters:

fieldName - the name of the field to retrieve.

Returns:

java.io.Reader for the ASCII CLOB stream stored in the database

Throws:

DataException - upon error retrieving the CLOB

saveBlob

public void saveBlob(String fieldName,
                     InputStream data,
                     int dataSize)
              throws DataException

Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).

Parameters:

fieldName - The name of the field to save the Stream to.

data - a java.io.InputStream object to save to the field. May be null if you want the field to be null.

dataSize - the length of the stream to save.

Throws:

DataException - upon database communications error.

IllegalArgumentException - if fieldName is null.

saveBlob

public void saveBlob(String fieldName,
                     Blob data)
              throws DataException

Saves a java.sql.Blob to the record matching the criteria earlier set.

Parameters:

fieldName - the name of the field to save to

data - the java.sql.Blob based object to save to the database.

Throws:

DataException - upon database communication error

IllegalArgumentException - if data is null

saveClob

public void saveClob(String fieldName,
                     InputStream data,
                     int length)
              throws DataException

Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).

Parameters:

fieldName - The name of the field to save the Stream to.

data - a java.io.InputStream object to save to the field. May be null if you want the field to be null.

length - The size of the CLOB stream to save to the database

Throws:

IllegalArgumentException - if fieldName is null.

DataException - upon database communications error.

saveClob

public void saveClob(String fieldName,
                     Reader data,
                     int length)
              throws DataException

Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).

Parameters:

fieldName - The name of the field to save the Stream to.

data - a java.io.Reader object to save to the field. May be null if you want the field to be null.

length - The size of the data stream to save to the database

Throws:

DataException - upon database communications error.

IllegalArgumentException - if fieldName is null.

saveClob

public void saveClob(String fieldName,
                     String data)
              throws DataException

Saves a string to a CLOB field.

Parameters:

fieldName - the name of the field to save to.

data - the String value to save to the field.

Throws:

DataException - upon error

saveClob

public void saveClob(String fieldName,
                     Clob data)
              throws DataException

Saves an InputStream into the database given the criteria and the fieldname (Criteria should have been previously set).

Parameters:

fieldName - The name of the field to save the Stream to.

data - a java.io.Reader object to save to the field. May be null if you want the field to be null.

Throws:

DataException - upon database communications error.

IllegalArgumentException - if fieldName is null.

close

public void close()

Close the query resources held by the object. This should be wrapped in a try/finally block so that database connection resources are not left floating in limbo.

finalize

protected void finalize()
                 throws Throwable

Override of base object finalization to make sure that the database resources are closed if for some reason they haven't had this done to them already.

Throws:

Throwable

prepSelectResultSet

protected void prepSelectResultSet(JDBCDataObject baseObject,
                                   String fieldName,
                                   DBConnection theConnection)
                            throws DataException

Internal helper function that does the guts of the work

Parameters:

baseObject - The object that contains the metadata for this BLOB

fieldName - the name of the field that is the BLOB field

theConnection - an already allocated DBConnection object. This function modifies the state of theConnection by allocating a prepared statement

Throws:

DataException - upon error

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/11/18 02:03:27 $

prepUpdate

protected PreparedStatement prepUpdate(JDBCDataObject baseObject,
                                       String fieldName,
                                       DBConnection theConnection)
                                throws DataException

Internal helper function to prepare a LOB update

Parameters:

baseObject - The object that contains the metadata for this BLOB

fieldName - the name of the field that is the BLOB field

theConnection - an already allocated DBConnection object

Returns:

a created PreparedStatement object

Throws:

DataException - Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/11/18 02:03:27 $

finalizeUpdate

protected void finalizeUpdate(DBConnection theConnection)
                       throws DataException

Throws:

DataException

oraclePrepSelectForUpdate

protected void oraclePrepSelectForUpdate(JDBCDataObject baseObject,
                                         String fieldName,
                                         DBConnection theConnection)
                                  throws DataException

Internal helper function to prepare a BLOB update for Oracle. Updates the record, setting the BLOB to to empty_blob() because inserts without setting the BLOB will result in a LOB Locator not being present, which will prevent the BLOB from being added to the record.

Parameters:

baseObject - The object that contains the metadata for this BLOB

fieldName - the name of the field that is the BLOB field

theConnection - an already allocated DBConnection object

Throws:

DataException - Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/11/18 02:03:27 $