oracle.sql
Class BLOB

java.lang.Object
  oracle.sql.Datum
      oracle.sql.DatumWithConnection
          oracle.sql.BLOB

All Implemented Interfaces:

java.io.Serializable, java.sql.Blob, oracle.jdbc.internal.OracleDatumWithConnection, OracleBlob

public class BLOB
extends DatumWithConnection
implements oracle.jdbc.internal.OracleBlob

This class implements the java.sql.Blob interface in JDBC 2.0

See Also:

Serialized Form

Field Summary

static java.lang.String	BUILD_DATE
static int	DURATION_CALL
static int	DURATION_SESSION
static int	MAX_CHUNK_SIZE 1907584: Changed MAX_CHUNK_SIZE from 32512 to 32768.
static int	MODE_READONLY
static int	MODE_READWRITE
static boolean	TRACE

Method Summary

void	close() Close a previously opened BLOB.
static BLOB	createTemporary(java.sql.Connection conn, boolean cache, int _duration) Create a temporary blob.
static BLOB	empty_lob() Deprecated. use getEmptyBLOB instead
void	freeTemporary() Free the contents and the locator of the temporary blob.
static void	freeTemporary(BLOB temp_lob) Free the contents and the locator of the temporary blob.
java.io.OutputStream	getBinaryOutputStream() Deprecated. This method is deprecated. Use setBinaryStream(1L).
java.io.OutputStream	getBinaryOutputStream(long pos) Deprecated. This method is deprecated -- use setBinaryStream
java.io.InputStream	getBinaryStream() Implements the Blob interface function.
java.io.InputStream	getBinaryStream(long pos) Read from the BLOB as a stream at the requested position.
int	getBufferSize() Oracle extension.
byte[]	getBytes(long pos, int length) Implements the Blob interface function.
int	getBytes(long pos, int length, byte[] buf) Oracle extension.
int	getChunkSize() Oracle extension.
static BLOB	getEmptyBLOB() Return a empty lob.
java.sql.Connection	getJavaSqlConnection() Oracle extension Return the java.sql.Connection associated with the receiver.
int	getPrefetchedDataSize()
boolean	isConvertibleTo(java.lang.Class jClass) Oracle extension.
boolean	isEmptyLob() Return true if the lob locator points to a empty blob.
boolean	isOpen() Check whether the BLOB is opened.
boolean	isSecureFile() Returns true if this is a SecureFile (LOBs with the STORE AS SECUREFILE option, which were introduced in Oracle Database 11g Release 1).
boolean	isTemporary() Return true if the lob locator points to a temporary blob.
static boolean	isTemporary(BLOB lob) Return true if the lob locator points to a temporary blob.
long	length() Implements the Blob interface function.
void	open(int mode) Open a BLOB in the indicated mode.
void	open(LargeObjectAccessMode mode) Public method using enum instead of int
long	position(java.sql.Blob pattern, long start) Implements the Blob interface function.
long	position(byte[] pattern, long start) Implements the Blob interface function.
int	putBytes(long pos, byte[] bytes) Deprecated. This method is deprecated -- use setBytes
int	putBytes(long pos, byte[] bytes, int length) Deprecated. This method is deprecated -- use setBytes
java.io.OutputStream	setBinaryStream(long pos) JDBC 3.0 Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.
int	setBytes(long pos, byte[] bytes) JDBC 3.0 Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.
int	setBytes(long pos, byte[] bytes, int offset, int len) JDBC 3.0 Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written.
java.lang.Object	toJdbc() Oracle extension.
void	trim(long newlen) Deprecated. This method id deprecated -- use truncate
void	truncate(long len) JDBC 3.0 Truncates the BLOB value that this Blob object represents to be len bytes in length.

Methods inherited from class oracle.sql.DatumWithConnection

assertNotNull, assertNotNull, getConnection, getOracleConnection

Methods inherited from class oracle.sql.Datum

bigDecimalValue, booleanValue, byteValue, dateValue, doubleValue, equals, floatValue, getBytes, getLength, getStream, intValue, longValue, setBytes, setShareBytes, shareBytes, stringValue, stringValue, timestampValue, timestampValue, timeValue, timeValue

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.jdbc.internal.OracleDatumWithConnection

bigDecimalValue, booleanValue, byteValue, dateValue, doubleValue, floatValue, getBytes, getConnection, getInternalConnection, getLength, getOracleConnection, getStream, intValue, longValue, setBytes, setPhysicalConnectionOf, setShareBytes, shareBytes, stringValue, stringValue, timestampValue, timestampValue, timeValue, timeValue

Field Detail

MAX_CHUNK_SIZE

public static final int MAX_CHUNK_SIZE

1907584: Changed MAX_CHUNK_SIZE from 32512 to 32768. This was done to accommodate larger DB_BLOCK_SIZEs. Using 32512 would cause getBufferSize() to return 32512 for DB_BLOCK_SIZEs from 8192-32768. For these block sizes getBufferSize() should return getChunkSize(); not 32512. By using 32768 as the MAX_CHUNK_SIZE, getBufferSize() returns the correct chunk size. Please see bug for details.

See Also:

Constant Field Values

DURATION_SESSION

public static final int DURATION_SESSION

See Also:

Constant Field Values

DURATION_CALL

public static final int DURATION_CALL

See Also:

Constant Field Values

MODE_READONLY

public static final int MODE_READONLY

See Also:

Constant Field Values

MODE_READWRITE

public static final int MODE_READWRITE

See Also:

Constant Field Values

BUILD_DATE

public static final java.lang.String BUILD_DATE

See Also:

Constant Field Values

TRACE

public static final boolean TRACE

See Also:

Constant Field Values

Method Detail

length

public long length()
            throws java.sql.SQLException

Implements the Blob interface function. Return the length of the Binary Large OBject in bytes.

Specified by:

length in interface java.sql.Blob

Returns:

length of the BLOB in bytes

Throws:

java.sql.SQLException

getBytes

public byte[] getBytes(long pos,
                       int length)
                throws java.sql.SQLException

Implements the Blob interface function. Return a copy of the contents of the BLOB at the requested position.

Specified by:

getBytes in interface java.sql.Blob

Parameters:

pos - is the first byte of the blob to be extracted.

length - is the number of consecutive bytes to be copied.

Returns:

a byte array containing a portion of the BLOB If the pos argument is larger than the length of the data the result is null. If the pos argument is less than the length of the data, but the sum of pos argument and the length is greater than the length of the data, the result will be smaller than the length requested. If the length is zero return and empty array

Throws:

java.sql.SQLException

getBinaryStream

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

Implements the Blob interface function. Retrieve the entire BLOB as a stream.

Specified by:

getBinaryStream in interface java.sql.Blob

Returns:

a stream containing the BLOB data

Throws:

java.sql.SQLException

position

public long position(byte[] pattern,
                     long start)
              throws java.sql.SQLException

Implements the Blob interface function. Determine the byte position at which the given byte pattern

Specified by:

position in interface java.sql.Blob

Parameters:

pattern - is the pattern to search for.

start - is the position at which to begin searching.

Returns:

the position at which the pattern appears, else -1.

Throws:

java.sql.SQLException

position

public long position(java.sql.Blob pattern,
                     long start)
              throws java.sql.SQLException

Implements the Blob interface function. Determine the byte position at which the given pattern

Specified by:

position in interface java.sql.Blob

Parameters:

pattern - is the pattern to search for.

start - is the position at which to begin searching.

Returns:

the position at which the pattern appears, else -1.

Throws:

java.sql.SQLException

getBytes

public int getBytes(long pos,
                    int length,
                    byte[] buf)
             throws java.sql.SQLException

Oracle extension. Copy the contents of the BLOB at the requested position to suppied buffer.

Specified by:

getBytes in interface OracleBlob

Parameters:

pos - is the first byte of the blob to be extracted.

length - is the number of consecutive bytes to be copied.

buf - is the buffer to had the extracted bytes.

Returns:

a byte array containing a portion of the BLOB

Throws:

java.sql.SQLException

putBytes

public int putBytes(long pos,
                    byte[] bytes)
             throws java.sql.SQLException

Deprecated. This method is deprecated -- use setBytes

Oracle extension. Put data to the BLOB at the requested position.

Parameters:

pos - is the position data to be put.

bytes - is the data to be written into BLOB.

Returns:

the number of bytes actually written.

Throws:

java.sql.SQLException

putBytes

public int putBytes(long pos,
                    byte[] bytes,
                    int length)
             throws java.sql.SQLException

Deprecated. This method is deprecated -- use setBytes

Oracle extension. Put data to the BLOB at the requested position.

Parameters:

pos - is the position data to be put.

bytes - is the data to be written into BLOB.

length - is the length of the data to be written into BLOB.

Returns:

the number of bytes actually written.

Throws:

java.sql.SQLException

getBinaryOutputStream

public java.io.OutputStream getBinaryOutputStream()
                                           throws java.sql.SQLException

Deprecated. This method is deprecated. Use setBinaryStream(1L).

Oracle extension. Write to the BLOB from a stream.

Returns:

a output stream to write data to the BLOB

Throws:

java.sql.SQLException

getChunkSize

public int getChunkSize()
                 throws java.sql.SQLException

Oracle extension. Get database LOB storage chunk size in database.

Returns:

size in bytes

Throws:

java.sql.SQLException

getBufferSize

public int getBufferSize()
                  throws java.sql.SQLException

Oracle extension. Get ideal LOB db access buffer size.

Returns:

size in bytes

Throws:

java.sql.SQLException

empty_lob

public static BLOB empty_lob()
                      throws java.sql.SQLException

Deprecated. use getEmptyBLOB instead

Return a empty lob. An empty lob is used initialize a LOB column/attribute. Note: an empty lob can not be read or written

Returns:

a empty lob

Throws:

java.sql.SQLException

Since:

8.1.7

getEmptyBLOB

public static BLOB getEmptyBLOB()
                         throws java.sql.SQLException

Return a empty lob. An empty lob is used initialize a BLOB column/attribute. Note: an empty lob can not be read or written

Returns:

a empty lob

Throws:

java.sql.SQLException

Since:

10.2

isEmptyLob

public boolean isEmptyLob()
                   throws java.sql.SQLException

Return true if the lob locator points to a empty blob. False if it does not. This method supports only Blobs that are not returned from the database. For Blobs returned from the database, use length(), i.e. check for zero length.

Specified by:

isEmptyLob in interface OracleBlob

Returns:

true if the lob locator points to a empty blob. False if it does not.

Throws:

java.sql.SQLException

Since:

8.1.7

isSecureFile

public boolean isSecureFile()
                     throws java.sql.SQLException

Returns true if this is a SecureFile (LOBs with the STORE AS SECUREFILE option, which were introduced in Oracle Database 11g Release 1).

Specified by:

isSecureFile in interface OracleBlob

Returns:

true if this is a SecureFile and false otherwise.

Throws:

java.sql.SQLException

getBinaryOutputStream

public java.io.OutputStream getBinaryOutputStream(long pos)
                                           throws java.sql.SQLException

Deprecated. This method is deprecated -- use setBinaryStream

Write to the BLOB from a stream at the requested position.

Parameters:

pos - is the position data to be put.

Returns:

a output stream to write data to the BLOB

Throws:

java.sql.SQLException

Since:

8.2.0

getBinaryStream

public java.io.InputStream getBinaryStream(long pos)
                                    throws java.sql.SQLException

Read from the BLOB as a stream at the requested position.

Specified by:

getBinaryStream in interface OracleBlob

Parameters:

pos - is the position data to be read.

Returns:

a input stream to read data from the BLOB

Throws:

java.sql.SQLException

Since:

8.2.0

trim

public void trim(long newlen)
          throws java.sql.SQLException

Deprecated. This method id deprecated -- use truncate

Trim the value of the BLOB to the length you specify in the newlen parameter.

Parameters:

newlen - the new length of the BLOB.

Throws:

java.sql.SQLException

Since:

8.2.0

createTemporary

public static BLOB createTemporary(java.sql.Connection conn,
                                   boolean cache,
                                   int _duration)
                            throws java.sql.SQLException

Create a temporary blob.

Parameters:

cache - Specifies if LOB should be read into buffer cache or not.

_duration - The duration of the temporary LOB. The following are valid values: DURATION_SESSION, DURATION_CALL.

Returns:

A temporary blob.

Throws:

java.sql.SQLException

Since:

8.2.0

freeTemporary

public static void freeTemporary(BLOB temp_lob)
                          throws java.sql.SQLException

Free the contents and the locator of the temporary blob.

Parameters:

temp_lob - A temporary blob to be freeed.

Throws:

java.sql.SQLException - if temp_lob is a permanent lob or temp_lob has already been freed.

Since:

8.2.0

isTemporary

public static boolean isTemporary(BLOB lob)
                           throws java.sql.SQLException

Return true if the lob locator points to a temporary blob. False if it does not.

Parameters:

lob - the blob to test.

Returns:

true if the lob locator points to a temporary blob. False if it does not.

Throws:

java.sql.SQLException

Since:

8.2.0

freeTemporary

public void freeTemporary()
                   throws java.sql.SQLException

Free the contents and the locator of the temporary blob.

Throws:

java.sql.SQLException - if self is a permanent lob or self has already been freed.

Since:

8.2.0

isTemporary

public boolean isTemporary()
                    throws java.sql.SQLException

Return true if the lob locator points to a temporary blob. False if it does not.

Specified by:

isTemporary in interface OracleBlob

Returns:

true if the lob locator points to a temporary blob. False if it does not.

Throws:

java.sql.SQLException

Since:

8.2.0

open

public void open(LargeObjectAccessMode mode)
          throws java.sql.SQLException

Public method using enum instead of int

Specified by:

open in interface OracleBlob

Throws:

java.sql.SQLException

open

public void open(int mode)
          throws java.sql.SQLException

Open a BLOB in the indicated mode. Valid modes include MODE_READONLY, and MODE_READWRITE. It is an error to open the same LOB twice.

Throws:

java.sql.SQLException

Since:

8.2.0

close

public void close()
           throws java.sql.SQLException

Close a previously opened BLOB.

Specified by:

close in interface OracleBlob

Throws:

java.sql.SQLException

Since:

8.2.0

isOpen

public boolean isOpen()
               throws java.sql.SQLException

Check whether the BLOB is opened.

Specified by:

isOpen in interface OracleBlob

Returns:

true if the LOB is opened.

Throws:

java.sql.SQLException

Since:

8.2.0

setBytes

public int setBytes(long pos,
                    byte[] bytes)
             throws java.sql.SQLException

JDBC 3.0 Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.

Specified by:

setBytes in interface java.sql.Blob

Parameters:

pos - the position in the BLOB object at which to start writing

bytes - the array of bytes to be written to the BLOB value that this Blob object represents

Returns:

the number of bytes written

Throws:

java.sql.SQLException - if there is an error accessing the BLOB value

Since:

9.0.2

setBytes

public int setBytes(long pos,
                    byte[] bytes,
                    int offset,
                    int len)
             throws java.sql.SQLException

JDBC 3.0 Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written.

Specified by:

setBytes in interface java.sql.Blob

Parameters:

pos - the position in the BLOB object at which to start writing

bytes - the array of bytes to be written to this BLOB object

offset - the offset into the array bytes at which to start reading the bytes to be set

len - the number of bytes to be written to the BLOB value from the array of bytes bytes

Returns:

the number of bytes written

Throws:

java.sql.SQLException - if there is an error accessing the BLOB value

Since:

9.0.2

setBinaryStream

public java.io.OutputStream setBinaryStream(long pos)
                                     throws java.sql.SQLException

JDBC 3.0 Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos.

Specified by:

setBinaryStream in interface java.sql.Blob

Parameters:

pos - the position in the BLOB value at which to start writing

Returns:

a java.io.OutputStream object to which data can be written

Throws:

java.sql.SQLException - if there is an error accessing the BLOB value

Since:

9.0.2

See Also:

getBinaryStream()

truncate

public void truncate(long len)
              throws java.sql.SQLException

JDBC 3.0 Truncates the BLOB value that this Blob object represents to be len bytes in length.

Specified by:

truncate in interface java.sql.Blob

Parameters:

len - the length, in bytes, to which the BLOB value that this Blob object represents should be truncated

Throws:

java.sql.SQLException - if there is an error accessing the BLOB value

Since:

9.0.2

toJdbc

public java.lang.Object toJdbc()
                        throws java.sql.SQLException

Oracle extension. Convert this data object into its default Java object type.

Specified by:

toJdbc in interface oracle.jdbc.internal.OracleDatumWithConnection

Specified by:

toJdbc in class Datum

Returns:

this object.

Throws:

java.sql.SQLException - if any of the lower layer code throws an exception.

isConvertibleTo

public boolean isConvertibleTo(java.lang.Class jClass)

Oracle extension. Test whether this data object can be converted to the specified Java data type.

Specified by:

isConvertibleTo in interface oracle.jdbc.internal.OracleDatumWithConnection

Specified by:

isConvertibleTo in class Datum

Parameters:

jClass - specifies the Java data type to test against.

Returns:

true if this data object is convertible to the specified Java class, and a corresponding xxxValue() method is available; otherwise, a false is returned.

getJavaSqlConnection

public java.sql.Connection getJavaSqlConnection()
                                         throws java.sql.SQLException

Description copied from class: DatumWithConnection

Oracle extension Return the java.sql.Connection associated with the receiver. Since 9.0.0 not all Oracle JDBC connection objects are assignment compatible with oracle.jdbc.driver.OracleConnection. If the connection is wrapped, return the outermost wrapper.

Specified by:

getJavaSqlConnection in interface oracle.jdbc.internal.OracleDatumWithConnection

Overrides:

getJavaSqlConnection in class DatumWithConnection

Returns:

the connection

Throws:

java.sql.SQLException - if an error occurs

getPrefetchedDataSize

public final int getPrefetchedDataSize()