Class EmbedClob
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
FieldsModifier and TypeFieldDescriptionprivate InternalClob
The underlying Clob object, which may change depending on what the user does with the Clob.private boolean
Tells whether the Clob has been freed or not.private int
Fields inherited from class org.apache.derby.impl.jdbc.ConnectionChild
factory, localConn
-
Constructor Summary
ConstructorsModifierConstructorDescription(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
Modifier and TypeMethodDescriptionprivate void
void
free()
Frees theClob
and releases the resources that it holds.Gets theCLOB
value designated by thisClob
object as a stream of Ascii bytes.Gets theClob
contents as a stream of characters.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
Returns the current internal Clob representation.int
Returns LOB locator key.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
Makes a writable clone of the current Clob.private void
makeWritableClobClone
(long len) Makes a writable clone of the current Clob.long
Determines the character position at which the specified substringsearchStr
appears in theCLOB
value.long
Determines the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object.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.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
JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos.int
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 charactersMethods inherited from class org.apache.derby.impl.jdbc.ConnectionChild
commitIfAutoCommit, commitIfNeeded, getCal, getConnectionSynchronization, getEmbedConnection, getLanguageConnectionContext, getLCC, handleException, needCommit, newSQLException, restoreContextStack, restoreIntrFlagIfSeen, setupContextStack
-
Field Details
-
clob
The underlying Clob object, which may change depending on what the user does with the Clob. -
isValid
private boolean isValidTells whether the Clob has been freed or not. -
locator
private int locator
-
-
Constructor Details
-
EmbedClob
EmbedClob(EmbedConnection con) throws SQLException Creates an empty Clob object.- Parameters:
con
- The Connection object associated with this EmbedClob object.- Throws:
SQLException
-
EmbedClob
protected EmbedClob(EmbedConnection con, StringDataValue dvd) throws StandardException, 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:
con
- associated connection for the Clobdvd
- string data value descriptor providing the Clob source- Throws:
StandardException
SQLException
-
-
Method Details
-
length
Returns the number of characters in theCLOB
value designated by thisClob
object.- Specified by:
length
in interfaceClob
- Returns:
- The length of the
CLOB
in number of characters. - Throws:
SQLException
- if obtaining the length fails
-
getSubString
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 interfaceClob
- 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:
SQLException
- if there is an error accessing theCLOB
-
getCharacterStream
Gets theClob
contents as a stream of characters.- Specified by:
getCharacterStream
in interfaceClob
- Returns:
- A character stream containing the
CLOB
data. - Throws:
SQLException
- if there is an error accessing theCLOB
-
getAsciiStream
Gets theCLOB
value designated by thisClob
object as a stream of Ascii bytes.- Specified by:
getAsciiStream
in interfaceClob
- Returns:
- An Ascii stream containing the
CLOB
data. Valid values in the stream are 0 - 255. - Throws:
SQLException
- if there is an error accessing theCLOB
value
-
position
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 interfaceClob
- 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:
SQLException
- if there is an error accessing theCLOB
value
- If a matching char is found, increment
-
position
Determines the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object. The search begins at positionstart
.- Specified by:
position
in interfaceClob
- 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:
SQLException
- if there is an error accessing theCLOB
value
-
setString
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 interfaceClob
- 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:
SQLException
- if writing the string fails
-
setString
JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.- Specified by:
setString
in interfaceClob
- 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:
SQLException
- if writing the string fails
-
setAsciiStream
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 interfaceClob
- 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:
SQLException
- if obtaining the stream fails
-
setCharacterStream
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 interfaceClob
- 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:
SQLException
- if obtaining the stream fails
-
truncate
JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters- Specified by:
truncate
in interfaceClob
- Parameters:
len
- the length, in characters, to which the CLOB value should be truncated, 0 is accepted- Throws:
SQLException
- if truncating the CLOB value fails
-
free
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.- Specified by:
free
in interfaceClob
- Specified by:
free
in interfaceEngineLOB
- Throws:
SQLException
- if an error occurs releasing the Clobs resources
-
getCharacterStream
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 interfaceClob
- 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:
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
- Throws:
SQLException
-
makeWritableClobClone
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:
IOException
- if accessing underlying I/O resources failSQLException
- if accessing underlying resources fail
-
makeWritableClobClone
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:
IOException
- if accessing underlying I/O resources failSQLException
- 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.
-