oracle.sql
Class CLOB

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

All Implemented Interfaces:

java.io.Serializable, java.sql.Clob, oracle.jdbc.internal.OracleDatumWithConnection, OracleClob

Direct Known Subclasses:

NCLOB

public class CLOB
extends DatumWithConnection
implements oracle.jdbc.internal.OracleClob

This class implements java.sql.Clob 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
static int	MODE_READONLY
static int	MODE_READWRITE
static boolean	TRACE

Constructor Summary

CLOB(OracleConnection conn, byte[] lob_descriptor, short csform)

Method Summary

void	close() Close a previously opened CLOB.
static CLOB	createTemporary(java.sql.Connection conn, boolean cache, int _duration) Create a temporary clob.
static CLOB	createTemporary(java.sql.Connection conn, boolean cache, int _duration, short form_of_use) Create a temporary clob or nclob.
static CLOB	empty_lob() Deprecated. use getEmptyCLOB instead
void	freeTemporary() Free the contents and the locator of the temporary clob.
static void	freeTemporary(CLOB temp_lob) Free the contents and the locator of the temporary clob.
java.io.OutputStream	getAsciiOutputStream() Deprecated. This method is deprecated. Use setAsciiStream( 1L );
java.io.OutputStream	getAsciiOutputStream(long pos) Deprecated. This method is deprecated. Use setAsciiStream.
java.io.InputStream	getAsciiStream() Implements the Clob interface method.
java.io.InputStream	getAsciiStream(long pos) Read from the CLOB as a stream at the requested position.
int	getBufferSize() Oracle extension.
java.io.Writer	getCharacterOutputStream() Deprecated. This method is deprecated. Use setCharacterStream( 1L ).
java.io.Writer	getCharacterOutputStream(long pos) Deprecated. This method is deprecated. Use setCharacterStream.
java.io.Reader	getCharacterStream() Implements the Clob interface method.
java.io.Reader	getCharacterStream(long pos) Read from the CLOB as a stream at the requested position.
int	getChars(long pos, int length, char[] buffer) Oracle extension.
int	getChunkSize() Oracle extension.
static CLOB	getEmptyCLOB() Return a empty lob.
java.sql.Connection	getJavaSqlConnection() Oracle extension Return the java.sql.Connection associated with the receiver.
int	getPrefetchedDataSize()
java.lang.String	getSubString(long pos, int length) Implements the Clob interface method.
boolean	isConvertibleTo(java.lang.Class jClass) Test whether this data object can be converted to the specified Java data type.
boolean	isEmptyLob() Return true if this is a empty lob.
boolean	isNCLOB()
boolean	isOpen() Check whether the CLOB 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 clob.
static boolean	isTemporary(CLOB lob) Return true if the lob locator points to a temporary clob.
long	length() Implements the Clob interface method.
void	open(int mode) Open a CLOB in the indicated mode.
void	open(LargeObjectAccessMode mode) Public method using enum instead of int
long	position(java.sql.Clob searchstr, long start) Implements the Clob interface method.
long	position(java.lang.String searchstr, long start) Implements the Clob interface method.
int	putChars(long pos, char[] chars) Oracle extension.
int	putChars(long pos, char[] chars, int length) Oracle extension.
int	putChars(long pos, char[] chars, int offset, int length) Oracle extension.
int	putString(long pos, java.lang.String str) Deprecated. This method is deprecated -- use setString.
java.io.OutputStream	setAsciiStream(long pos) JDBC 3.0 Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos.
java.io.Writer	setCharacterStream(long pos) JDBC 3.0 Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos.
int	setString(long pos, java.lang.String str) JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos.
int	setString(long pos, java.lang.String str, int offset, int len) JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
java.lang.String	stringValue() Convert to a String representation of the datum object
java.lang.Object	toJdbc() Convert this data object into its default Java object type.
void	trim(long newlen) Deprecated. This method is deprecated. Use truncate().
void	truncate(long len) JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters.

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, 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, timestampValue, timestampValue, timeValue, timeValue

Field Detail

MAX_CHUNK_SIZE

public static final int MAX_CHUNK_SIZE

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

Constructor Detail

CLOB

public CLOB(OracleConnection conn,
            byte[] lob_descriptor,
            short csform)
     throws java.sql.SQLException

Throws:

java.sql.SQLException

Method Detail

isNCLOB

public boolean isNCLOB()

Returns:

true if the data is bound for a SQL NCHAR datatype false otherwise

length

public long length()
            throws java.sql.SQLException

Implements the Clob interface method. Returns the number of characters in the CLOB value designated by this Clob object.

Specified by:

length in interface java.sql.Clob

Returns:

length of the CLOB in characters

Throws:

java.sql.SQLException - if there is an error accessing the length of the CLOB

getSubString

public java.lang.String getSubString(long pos,
                                     int length)
                              throws java.sql.SQLException

Implements the Clob interface method. Returns a copy of the specified substring in the CLOB value designated by this Clob object. The substring begins at position pos and has up to length consecutive characters.

Specified by:

getSubString in interface java.sql.Clob

Parameters:

pos - the first character of the substring to be extracted. The first character is at position 1.

length - the number of consecutive characters to be copied

Returns:

a String that is the specified substring in the CLOB value designated by this Clob object. If the pos argument is larger than the length of the data the result is an empty String. 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.

Throws:

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

getCharacterStream

public java.io.Reader getCharacterStream()
                                  throws java.sql.SQLException

Implements the Clob interface method. Gets the Clob contents as a Unicode stream.

Specified by:

getCharacterStream in interface java.sql.Clob

Returns:

a Unicode stream containing the CLOB data

Throws:

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

getAsciiStream

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

Implements the Clob interface method. Gets the CLOB value designated by this Clob object as a stream of Ascii bytes.

Specified by:

getAsciiStream in interface java.sql.Clob

Returns:

an ascii stream containing the CLOB data

Throws:

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

position

public long position(java.lang.String searchstr,
                     long start)
              throws java.sql.SQLException

Implements the Clob interface method. Determine the character position at which the given substring

Specified by:

position in interface java.sql.Clob

Parameters:

searchstr - is the substring to search for.

start - is the position at which to begin searching.

Returns:

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

Throws:

java.sql.SQLException

position

public long position(java.sql.Clob searchstr,
                     long start)
              throws java.sql.SQLException

Implements the Clob interface method. Determine the character position at which the given substring

Specified by:

position in interface java.sql.Clob

Parameters:

searchstr - is the substring to search for.

start - is the position at which to begin searching.

Returns:

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

Throws:

java.sql.SQLException

getChars

public int getChars(long pos,
                    int length,
                    char[] buffer)
             throws java.sql.SQLException

Oracle extension. Return copy of the substring of the CLOB at the requested position.

Parameters:

buffer - is the buffer into whcih the characters are read.

pos - is the first character of the substring to be extracted.

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

Returns:

the actual number of characters read.

Throws:

java.sql.SQLException

getCharacterOutputStream

public java.io.Writer getCharacterOutputStream()
                                        throws java.sql.SQLException

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

Oracle extension. Write Unicode stream to the CLOB.

Returns:

a Unicode character output stream.

Throws:

java.sql.SQLException

getAsciiOutputStream

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

Deprecated. This method is deprecated. Use setAsciiStream( 1L );

Oracle extension. Write ascii stream to the CLOB.

Returns:

a ascii output stream.

Throws:

java.sql.SQLException

putChars

public int putChars(long pos,
                    char[] chars)
             throws java.sql.SQLException

Oracle extension. Write characters at the requested position.

Parameters:

pos - is the position to write characters.

chars - is the buffer of characters to be written.

Returns:

the actual number of characters written.

Throws:

java.sql.SQLException

putChars

public int putChars(long pos,
                    char[] chars,
                    int length)
             throws java.sql.SQLException

Oracle extension. Write characters at the requested position.

Parameters:

pos - is the position to write characters.

chars - is the buffer of characters to be written.

length - is the length to write

Returns:

the actual number of characters written.

Throws:

java.sql.SQLException

putChars

public int putChars(long pos,
                    char[] chars,
                    int offset,
                    int length)
             throws java.sql.SQLException

Oracle extension. Write characters at the requested position.

Parameters:

pos - is the position to write characters.

chars - is the buffer of characters to be written.

offset - is the position in the buffer from which to begin

length - is the length to write

Returns:

the actual number of characters written.

Throws:

java.sql.SQLException

putString

public int putString(long pos,
                     java.lang.String str)
              throws java.sql.SQLException

Deprecated. This method is deprecated -- use setString.

Oracle extension. Write String to a CLOB This method provides support to return a 32-bit specification of the number of characters written to the CLOB.

Throws:

java.sql.SQLException

getChunkSize

public int getChunkSize()
                 throws java.sql.SQLException

Oracle extension. Get database LOB storage chunk size.

Returns:

the size in terms of characters.

Throws:

java.sql.SQLException

getBufferSize

public int getBufferSize()
                  throws java.sql.SQLException

Oracle extension. Get ideal LOB db access buffer size.

Returns:

the size in terms of characters.

Throws:

java.sql.SQLException

empty_lob

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

Deprecated. use getEmptyCLOB 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

getEmptyCLOB

public static CLOB getEmptyCLOB()
                         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

Throws:

java.sql.SQLException

Since:

10.2

isEmptyLob

public boolean isEmptyLob()
                   throws java.sql.SQLException

Return true if this is a empty lob.

Specified by:

isEmptyLob in interface OracleClob

Returns:

true if this is a empty lob. This method supports only Clobs that are not returned from the database. For Clobs returned from the database, use length(), i.e. check for zero length

Throws:

java.sql.SQLException

Since:

8.1.7

See Also:

empty_lob

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 OracleClob

Returns:

true if this is a SecureFile and false otherwise.

Throws:

java.sql.SQLException

getAsciiOutputStream

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

Deprecated. This method is deprecated. Use setAsciiStream.

Write to the CLOB 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 CLOB

Throws:

java.sql.SQLException

Since:

8.2.0

getCharacterOutputStream

public java.io.Writer getCharacterOutputStream(long pos)
                                        throws java.sql.SQLException

Deprecated. This method is deprecated. Use setCharacterStream.

Write to the CLOB 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 CLOB

Throws:

java.sql.SQLException

Since:

8.2.0

getAsciiStream

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

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

Parameters:

pos - is the position data to be put.

Returns:

a input stream to read data from the CLOB

Throws:

java.sql.SQLException

Since:

8.2.0

getCharacterStream

public java.io.Reader getCharacterStream(long pos)
                                  throws java.sql.SQLException

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

Parameters:

pos - is the position data to be put.

Returns:

a input stream to read data from the CLOB

Throws:

java.sql.SQLException

Since:

8.2.0

trim

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

Deprecated. This method is deprecated. Use truncate().

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

Parameters:

newlen - the new length of the CLOB.

Throws:

java.sql.SQLException

Since:

8.2.0

createTemporary

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

Create a temporary clob.

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

Throws:

java.sql.SQLException

Since:

8.2.0

createTemporary

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

Create a temporary clob or nclob.

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.

form_of_use - Valid values are FORM_CHAR and FORM_NCHAR

Returns:

A temporary clob.

Throws:

java.sql.SQLException

Since:

10g

freeTemporary

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

Free the contents and the locator of the temporary clob.

Parameters:

temp_lob - A temporary clob 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(CLOB lob)
                           throws java.sql.SQLException

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

Parameters:

lob - the clob to test.

Returns:

true if the lob locator points to a temporary clob. 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 clob.

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 clob. False if it does not.

Specified by:

isTemporary in interface OracleClob

Returns:

true if the lob locator points to a temporary clob. 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 OracleClob

Throws:

java.sql.SQLException

open

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

Open a CLOB 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 CLOB.

Specified by:

close in interface OracleClob

Throws:

java.sql.SQLException

Since:

8.2.0

isOpen

public boolean isOpen()
               throws java.sql.SQLException

Check whether the CLOB is opened.

Specified by:

isOpen in interface OracleClob

Returns:

true if the LOB is opened.

Throws:

java.sql.SQLException

Since:

8.2.0

setString

public int setString(long pos,
                     java.lang.String str)
              throws java.sql.SQLException

JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos.

Specified by:

setString in interface java.sql.Clob

Parameters:

pos - the position at which to start writing to the CLOB value that this Clob object represents

str - the string to be written to the CLOB value that this Clob designates

Returns:

the number of characters written

Throws:

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

Since:

9.0.2

setString

public int setString(long pos,
                     java.lang.String str,
                     int offset,
                     int len)
              throws java.sql.SQLException

JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.

Specified by:

setString in interface java.sql.Clob

Parameters:

pos - the position at which to start writing to this CLOB object

str - the string to be written to the CLOB value that this Clob object represents

offset - the offset into str to start reading the characters to be written

len - the number of characters to be written

Returns:

the number of characters written

Throws:

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

Since:

9.0.2 This method is currently not supported. Use setString( long pos, String str )

setAsciiStream

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

JDBC 3.0 Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos.

Specified by:

setAsciiStream in interface java.sql.Clob

Parameters:

pos - the position at which to start writing to this CLOB object

Returns:

the stream to which ASCII encoded characters can be written

Throws:

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

Since:

9.0.2

setCharacterStream

public java.io.Writer setCharacterStream(long pos)
                                  throws java.sql.SQLException

JDBC 3.0 Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos.

Specified by:

setCharacterStream in interface java.sql.Clob

Parameters:

pos - the position at which to start writing to the CLOB value

Returns:

a stream to which Unicode encoded characters can be written

Throws:

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

Since:

9.0.2

truncate

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

JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters.

Specified by:

truncate in interface java.sql.Clob

Parameters:

len - the length, in bytes, to which the CLOB value should be truncated

Throws:

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

Since:

9.0.2

toJdbc

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

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)

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.

stringValue

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

Convert to a String representation of the datum object

Specified by:

stringValue in interface oracle.jdbc.internal.OracleDatumWithConnection

Overrides:

stringValue in class Datum

Returns:

String representation of the datum object

Throws:

SQLException, - if no String representation exists

java.sql.SQLException

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()