oracle.sql
Class BLOB

java.lang.Object
  |
  +--oracle.sql.Datum
        |
        +--oracle.sql.DatumWithConnection
              |
              +--oracle.sql.BLOB

public class BLOB

extends DatumWithConnection

implements java.sql.Blob

Field Summary

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

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() Return a empty lob.
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() Oracle extension.
java.io.OutputStream	getBinaryOutputStream(long pos) Write to the BLOB from a stream at the requested position.
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.
OracleConnection	getConnection()
java.sql.Connection	getJavaSqlConnection()
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	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.
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) Oracle extension.
int	putBytes(long pos, byte[] bytes, int length) Oracle extension.
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) Trim the value of the BLOB to the length you specify in the newlen parameter.
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, getOracleConnection

Methods inherited from class oracle.sql.Datum

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

Methods inherited from class java.lang.Object

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

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.

DURATION_SESSION

public static final int DURATION_SESSION

DURATION_CALL

public static final int DURATION_CALL

MODE_READONLY

public static final int MODE_READONLY

MODE_READWRITE

public static final int MODE_READWRITE

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

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

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

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.

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:

searchstr - 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.

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.

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

putBytes

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

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.

putBytes

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

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.

getBinaryOutputStream

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

Oracle extension. Write to the BLOB from a stream.

Returns:

a output stream to write data to the BLOB

getChunkSize

public int getChunkSize()
                 throws java.sql.SQLException

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

Returns:

size in bytes

getBufferSize

public int getBufferSize()
                  throws java.sql.SQLException

Oracle extension. Get ideal LOB db access buffer size.

Returns:

size in bytes

empty_lob

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

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

Since:

8.1.7

isEmptyLob

public boolean isEmptyLob()
                   throws java.sql.SQLException

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

Returns:

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

Since:

8.1.7

getBinaryOutputStream

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

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

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.

Parameters:

pos - is the position data to be read.

Returns:

a input stream to read data from the BLOB

Since:

8.2.0

trim

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

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

Parameters:

newlen - the new length of the BLOB.

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.

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.

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.

Returns:

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

Since:

8.2.0

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.

Since:

8.2.0

close

public void close()
           throws java.sql.SQLException

Close a previously opened BLOB.

Since:

8.2.0

isOpen

public boolean isOpen()
               throws java.sql.SQLException

Check whether the BLOB is opened.

Returns:

true if the LOB is opened.

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.

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

See Also:

getBytes(long, int)

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.

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

See Also:

getBytes(long, int)

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.

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.

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.

Returns:

this object.

Throws:

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

Overrides:

toJdbc in class Datum

isConvertibleTo

public boolean isConvertibleTo(java.lang.Class jClass)

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

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.

Overrides:

isConvertibleTo in class Datum

getJavaSqlConnection

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

Overrides:

getJavaSqlConnection in class DatumWithConnection

getConnection

public OracleConnection getConnection()
                               throws java.sql.SQLException

Overrides:

getConnection in class DatumWithConnection