oracle.sql
Class CLOB

java.lang.Object
  |
  +--oracle.sql.Datum
        |
        +--oracle.sql.DatumWithConnection
              |
              +--oracle.sql.CLOB
public class CLOB
extends DatumWithConnection
implements java.sql.Clob

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
           
 
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 empty_lob()
          Return a empty lob.
 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()
          Oracle extension.
 java.io.OutputStream getAsciiOutputStream(long pos)
          Write to the CLOB from a stream at the requested position.
 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()
          Oracle extension.
 java.io.Writer getCharacterOutputStream(long pos)
          Write to the CLOB from a stream at the requested position.
 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.
 OracleConnection getConnection()
           
 java.sql.Connection getJavaSqlConnection()
           
 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 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.
 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 putString(long pos, java.lang.String str)
          Oracle extension.
 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.Object toJdbc()
          Convert this data object into its default Java object type.
 void trim(long newlen)
          Trim the value of the CLOB to the length you specify in the newlen parameter.
 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, 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
Constructor Detail

CLOB

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

isNCLOB

public boolean isNCLOB()

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

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.

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.

getCharacterOutputStream

public java.io.Writer getCharacterOutputStream()
                                        throws java.sql.SQLException
Oracle extension. Write Unicode stream to the CLOB.
Returns:
a Unicode character output stream.

getAsciiOutputStream

public java.io.OutputStream getAsciiOutputStream()
                                          throws java.sql.SQLException
Oracle extension. Write ascii stream to the CLOB.
Returns:
a ascii output stream.

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.

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.
Returns:
the actual number of characters written.

putString

public int putString(long pos,
                     java.lang.String str)
              throws java.sql.SQLException
Oracle extension. Write Java string at the requested position.
Parameters:
pos - is the position to write characters.
str - is the Java string to be written.
Returns:
the actual number of characters written.

getChunkSize

public int getChunkSize()
                 throws java.sql.SQLException
Oracle extension. Get database LOB storage chunk size.
Returns:
the size in terms of characters.

getBufferSize

public int getBufferSize()
                  throws java.sql.SQLException
Oracle extension. Get ideal LOB db access buffer size.
Returns:
the size in terms of characters.

empty_lob

public static CLOB 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 this is a empty lob.
Returns:
true if this is a empty lob.
Since:
8.1.7
See Also:
empty_lob

getAsciiOutputStream

public java.io.OutputStream getAsciiOutputStream(long pos)
                                          throws java.sql.SQLException
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
Since:
8.2.0

getCharacterOutputStream

public java.io.Writer getCharacterOutputStream(long pos)
                                        throws java.sql.SQLException
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
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
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
Since:
8.2.0

trim

public void trim(long newlen)
          throws java.sql.SQLException
Trim the value of the CLOB to the length you specify in the newlen parameter.
Parameters:
newlen - the new length of the CLOB.
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.
Since:
8.2.0

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.
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.
Returns:
true if the lob locator points to a temporary clob. False if it does not.
Since:
8.2.0

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.
Since:
8.2.0

close

public void close()
           throws java.sql.SQLException
Close a previously opened CLOB.
Since:
8.2.0

isOpen

public boolean isOpen()
               throws java.sql.SQLException
Check whether the CLOB is opened.
Returns:
true if the LOB is opened.
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.
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.
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

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.
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
See Also:
getAsciiStream()

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.
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
See Also:
getCharacterStream()

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