Class EmbedClob
- java.lang.Object
-
- org.apache.derby.impl.jdbc.ConnectionChild
-
- org.apache.derby.impl.jdbc.EmbedClob
-
- All Implemented Interfaces:
java.sql.Clob
,EngineLOB
final class EmbedClob extends ConnectionChild implements java.sql.Clob, EngineLOB
Implements java.sql.Clob (see the JDBC 2.0 spec). A clob sits on top of a CHAR, VARCHAR or LONG VARCHAR column. If its data is small (less than 1 page) it is a byte array taken from the SQLChar class. If it is large (more than 1 page) it is a long column in the database. The long column is accessed as a stream, and is implemented in store as an OverflowInputStream. The Resetable interface allows sending messages to that stream to initialize itself (reopen its container and lock the corresponding row) and to reset itself to the beginning.NOTE: In the case that the data is large, it is represented as a stream. This stream can be returned to the user in the getAsciiStream() method. This means that we have limited control over the state of the stream, since the user can read bytes from it at any time. Thus all methods here reset the stream to the beginning before doing any work. CAVEAT: The methods may not behave correctly if a user sets up multiple threads and sucks data from the stream (returned from getAsciiStream()) at the same time as calling the Clob methods.
Supports
- JSR169 - no subsetting for java.sql.Clob
- JDBC 2.0
- JDBC 3.0 - no new dependencies on new JDBC 3.0 or JDK 1.4 classes, new update methods can safely be added into implementation.
-
-
Field Summary
Fields Modifier and Type Field Description private InternalClob
clob
The underlying Clob object, which may change depending on what the user does with the Clob.private boolean
isValid
Tells whether the Clob has been freed or not.private int
locator
-
Fields inherited from class org.apache.derby.impl.jdbc.ConnectionChild
factory, localConn
-
-
Constructor Summary
Constructors Modifier Constructor Description (package private)
EmbedClob(EmbedConnection con)
Creates an empty Clob object.protected
EmbedClob(EmbedConnection con, StringDataValue dvd)
Creates a Clob on top of a data value descriptor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
checkValidity()
void
free()
Frees theClob
and releases the resources that it holds.java.io.InputStream
getAsciiStream()
Gets theCLOB
value designated by thisClob
object as a stream of Ascii bytes.java.io.Reader
getCharacterStream()
Gets theClob
contents as a stream of characters.java.io.Reader
getCharacterStream(long pos, long length)
Returns aReader
object that contains a partialClob
value, starting with the character specified by pos, which is length characters in length.(package private) InternalClob
getInternalClob()
Returns the current internal Clob representation.int
getLocator()
Returns LOB locator key.java.lang.String
getSubString(long pos, int length)
Returns a copy of the specified substring in theCLOB
value designated by thisClob
object.long
length()
Returns the number of characters in theCLOB
value designated by thisClob
object.private void
makeWritableClobClone()
Makes a writable clone of the current Clob.private void
makeWritableClobClone(long len)
Makes a writable clone of the current Clob.long
position(java.lang.String searchStr, long start)
Determines the character position at which the specified substringsearchStr
appears in theCLOB
value.long
position(java.sql.Clob searchClob, long start)
Determines the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object.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 characters to the CLOB value that this Clob object represents, starting 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.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 org.apache.derby.impl.jdbc.ConnectionChild
commitIfAutoCommit, commitIfNeeded, getCal, getConnectionSynchronization, getEmbedConnection, getLanguageConnectionContext, getLCC, handleException, needCommit, newSQLException, restoreContextStack, restoreIntrFlagIfSeen, setupContextStack
-
-
-
-
Field Detail
-
clob
private InternalClob clob
The underlying Clob object, which may change depending on what the user does with the Clob.
-
isValid
private boolean isValid
Tells whether the Clob has been freed or not.
-
locator
private int locator
-
-
Constructor Detail
-
EmbedClob
EmbedClob(EmbedConnection con) throws java.sql.SQLException
Creates an empty Clob object.- Parameters:
con
- The Connection object associated with this EmbedClob object.- Throws:
java.sql.SQLException
-
EmbedClob
protected EmbedClob(EmbedConnection con, StringDataValue dvd) throws StandardException, java.sql.SQLException
Creates a Clob on top of a data value descriptor.This constructor should only be called by
EmbedResultSet.getClob(int)
. The data value descriptor may provide aString
or a stream as the source of the Clob.- Parameters:
dvd
- string data value descriptor providing the Clob sourcecon
- associated connection for the Clob- Throws:
StandardException
java.sql.SQLException
-
-
Method Detail
-
length
public long length() throws java.sql.SQLException
Returns the number of characters in theCLOB
value designated by thisClob
object.- Specified by:
length
in interfacejava.sql.Clob
- Returns:
- The length of the
CLOB
in number of characters. - Throws:
java.sql.SQLException
- if obtaining the length fails
-
getSubString
public java.lang.String getSubString(long pos, int length) throws java.sql.SQLException
Returns a copy of the specified substring in theCLOB
value designated by thisClob
object.The substring begins at position
pos
and has up to *length
consecutive characters. The starting position must be between 1 and the length of the CLOB plus 1. This allows for zero-length CLOB values, from which only zero-length substrings can be returned.If a larger length is requested than there are characters available, characters from the start position to the end of the CLOB are returned.
NOTE: If the starting position is the length of the CLOB plus 1, zero characters are returned regardless of the length requested.
- Specified by:
getSubString
in interfacejava.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 theCLOB
value designated by thisClob
object - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
-
getCharacterStream
public java.io.Reader getCharacterStream() throws java.sql.SQLException
Gets theClob
contents as a stream of characters.- Specified by:
getCharacterStream
in interfacejava.sql.Clob
- Returns:
- A character stream containing the
CLOB
data. - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
-
getAsciiStream
public java.io.InputStream getAsciiStream() throws java.sql.SQLException
Gets theCLOB
value designated by thisClob
object as a stream of Ascii bytes.- Specified by:
getAsciiStream
in interfacejava.sql.Clob
- Returns:
- An Ascii stream containing the
CLOB
data. Valid values in the stream are 0 - 255. - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value
-
position
public long position(java.lang.String searchStr, long start) throws java.sql.SQLException
Determines the character position at which the specified substringsearchStr
appears in theCLOB
value.The search begins at position
start
. The method uses the following algorithm for the search:If the
CLOB
value is materialized as a string, useString.indexOf
.If the
CLOB
value is represented as a stream, read a block of chars from the start position and compare the chars withsearchStr
. Then:- If a matching char is found, increment
matchCount
. - If
matchCount
is equal to the length ofsearchStr
, return with the current start position. - If no match is found, and there is more data, restart search (see below).
- If no match is found, return
-1
.
The position where the stream has a char equal to the first char of
searchStr
will be remembered and used as the starting position for the next search-iteration if the current match fails. If a non-matching char is found, start a fresh search from the position remembered. If there is no such position, next search will start at the current position+1
.- Specified by:
position
in interfacejava.sql.Clob
- Parameters:
searchStr
- the substring for which to searchstart
- the position at which to begin searching; the first position is1
- Returns:
- The position at which the substring appears,
-1
if it does not appear in theCLOB
value. The first position is1
. - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value
- If a matching char is found, increment
-
position
public long position(java.sql.Clob searchClob, long start) throws java.sql.SQLException
Determines the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object. The search begins at positionstart
.- Specified by:
position
in interfacejava.sql.Clob
- Parameters:
searchClob
- theClob
object for which to searchstart
- the position at which to begin searching; the first position is 1- Returns:
- the position at which the
Clob
object appears, else -1; the first position is 1 - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value
-
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 interfacejava.sql.Clob
- Parameters:
pos
- the position at which to start writing to the CLOB value that this Clob object represents- Returns:
- the number of characters written
- Throws:
java.sql.SQLException
- if writing the string fails
-
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 interfacejava.sql.Clob
- Parameters:
pos
- the position at which to start writing to this Clob objectstr
- the string to be written to the CLOB value that this Clob designatesoffset
- the offset into str to start reading the characters to be writtenlen
- the number of characters to be written- Returns:
- the number of characters written
- Throws:
java.sql.SQLException
- if writing the string fails
-
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 interfacejava.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 obtaining the stream fails
-
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 characters to the CLOB value that this Clob object represents, starting at position pos.- Specified by:
setCharacterStream
in interfacejava.sql.Clob
- Parameters:
pos
- the position at which to start writing to this Clob object- Returns:
- the stream to which Unicode encoded characters can be written
- Throws:
java.sql.SQLException
- if obtaining the stream fails
-
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 interfacejava.sql.Clob
- Parameters:
len
- the length, in characters, to which the CLOB value should be truncated, 0 is accepted- Throws:
java.sql.SQLException
- if truncating the CLOB value fails
-
free
public void free() throws java.sql.SQLException
Frees theClob
and releases the resources that it holds.The object is invalid once the
free
method is called. Iffree
is called multiple times, the subsequent calls tofree
are treated as a no-op.
-
getCharacterStream
public java.io.Reader getCharacterStream(long pos, long length) throws java.sql.SQLException
Returns aReader
object that contains a partialClob
value, starting with the character specified by pos, which is length characters in length.- Specified by:
getCharacterStream
in interfacejava.sql.Clob
- Parameters:
pos
- the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1.length
- the length in characters of the partial value to be retrieved.- Returns:
Reader
through which the partialClob
value can be read.- Throws:
java.sql.SQLException
- if pos is less than 1 or if pos is greater than the number of characters in theClob
or ifpos + length
is greater thanClob.length() +1
-
checkValidity
private void checkValidity() throws java.sql.SQLException
- Throws:
java.sql.SQLException
-
makeWritableClobClone
private void makeWritableClobClone() throws java.io.IOException, java.sql.SQLException
Makes a writable clone of the current Clob.This is called when we have a
StoreStreamClob
and the user calls a method updating the content of the Clob. A temporary Clob will then be created to hold the updated content.- Throws:
java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources fail
-
makeWritableClobClone
private void makeWritableClobClone(long len) throws java.io.IOException, java.sql.SQLException
Makes a writable clone of the current Clob.This is called when we have a
StoreStreamClob
and the user calls a method updating the content of the Clob. A temporary Clob will then be created to hold the updated content.- Parameters:
len
- number of characters to be cloned (should be smaller than clob length)- Throws:
java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources fail
-
getInternalClob
InternalClob getInternalClob()
Returns the current internal Clob representation.Care should be taken, as the representation can change when the user performs operations on the Clob. An example is if the Clob content is served from a store stream and the user updates the content. The internal representation will then be changed to a temporary Clob copy that allows updates.
- Returns:
- The current internal Clob representation.
-
getLocator
public int getLocator()
Description copied from interface:EngineLOB
Returns LOB locator key.The key can be used with
EmbedConnection.getLOBMapping(int)
to retrieve this LOB at a later time.- Specified by:
getLocator
in interfaceEngineLOB
- Returns:
- locator value for this Clob.
-
-