java.sql.Clob
, EngineLOB
final class EmbedClob extends ConnectionChild implements java.sql.Clob, EngineLOB
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
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 |
factory, localConn
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.
|
Modifier and Type | Method | Description |
---|---|---|
private void |
checkValidity() |
|
void |
free() |
Frees the
Clob and releases the resources that it holds. |
java.io.InputStream |
getAsciiStream() |
Gets the
CLOB value designated by this Clob
object as a stream of Ascii bytes. |
java.io.Reader |
getCharacterStream() |
Gets the
Clob contents as a stream of characters. |
java.io.Reader |
getCharacterStream(long pos,
long length) |
Returns a
Reader object that contains a partial
Clob 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 the
CLOB value
designated by this Clob object. |
long |
length() |
Returns the number of characters in the
CLOB value
designated by this Clob 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 substring
searchStr appears in the CLOB value. |
long |
position(java.sql.Clob searchClob,
long start) |
Determines the character position at which the specified
Clob object searchstr appears in this
Clob 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
|
commitIfAutoCommit, commitIfNeeded, getCal, getConnectionSynchronization, getEmbedConnection, getLanguageConnectionContext, getLCC, handleException, needCommit, newSQLException, restoreContextStack, restoreIntrFlagIfSeen, setupContextStack
private InternalClob clob
private boolean isValid
private int locator
EmbedClob(EmbedConnection con) throws java.sql.SQLException
con
- The Connection object associated with this EmbedClob object.java.sql.SQLException
protected EmbedClob(EmbedConnection con, StringDataValue dvd) throws StandardException, java.sql.SQLException
This constructor should only be called by EmbedResultSet.getClob(int)
.
The data value descriptor may provide a String
or a stream
as the source of the Clob.
dvd
- string data value descriptor providing the Clob sourcecon
- associated connection for the ClobStandardException
java.sql.SQLException
public long length() throws java.sql.SQLException
CLOB
value
designated by this Clob
object.length
in interface java.sql.Clob
CLOB
in number of characters.java.sql.SQLException
- if obtaining the length failspublic java.lang.String getSubString(long pos, int length) throws java.sql.SQLException
CLOB
value
designated by this Clob
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.
getSubString
in interface java.sql.Clob
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 copiedString
that is the specified substring in the
CLOB
value designated by this Clob
objectjava.sql.SQLException
- if there is an error accessing the
CLOB
public java.io.Reader getCharacterStream() throws java.sql.SQLException
Clob
contents as a stream of characters.getCharacterStream
in interface java.sql.Clob
CLOB
data.java.sql.SQLException
- if there is an error accessing the
CLOB
public java.io.InputStream getAsciiStream() throws java.sql.SQLException
CLOB
value designated by this Clob
object as a stream of Ascii bytes.getAsciiStream
in interface java.sql.Clob
CLOB
data. Valid
values in the stream are 0 - 255.java.sql.SQLException
- if there is an error accessing the
CLOB
valuepublic long position(java.lang.String searchStr, long start) throws java.sql.SQLException
searchStr
appears in the CLOB
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, use
String.indexOf
.
If the CLOB
value is represented as a stream, read a block
of chars from the start position and compare the chars with
searchStr
. Then:
matchCount
.
matchCount
is equal to the length of
searchStr
, return with the current start position.
-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
.
position
in interface java.sql.Clob
searchStr
- the substring for which to searchstart
- the position at which to begin searching; the first position
is 1
-1
if
it does not appear in the CLOB
value. The first position
is 1
.java.sql.SQLException
- if there is an error accessing the
CLOB
valuepublic long position(java.sql.Clob searchClob, long start) throws java.sql.SQLException
Clob
object searchstr
appears in this
Clob
object. The search begins at position
start
.position
in interface java.sql.Clob
searchClob
- the Clob
object for which to searchstart
- the position at which to begin searching; the first
position is 1Clob
object appears,
else -1; the first position is 1java.sql.SQLException
- if there is an error accessing the
CLOB
valuepublic int setString(long pos, java.lang.String str) throws java.sql.SQLException
setString
in interface java.sql.Clob
pos
- the position at which to start writing to the CLOB value that
this Clob object representsjava.sql.SQLException
- if writing the string failspublic int setString(long pos, java.lang.String str, int offset, int len) throws java.sql.SQLException
setString
in interface java.sql.Clob
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 writtenjava.sql.SQLException
- if writing the string failspublic java.io.OutputStream setAsciiStream(long pos) throws java.sql.SQLException
setAsciiStream
in interface java.sql.Clob
pos
- the position at which to start writing to this Clob objectjava.sql.SQLException
- if obtaining the stream failspublic java.io.Writer setCharacterStream(long pos) throws java.sql.SQLException
setCharacterStream
in interface java.sql.Clob
pos
- the position at which to start writing to this Clob objectjava.sql.SQLException
- if obtaining the stream failspublic void truncate(long len) throws java.sql.SQLException
truncate
in interface java.sql.Clob
len
- the length, in characters, to which the CLOB value should be
truncated, 0 is acceptedjava.sql.SQLException
- if truncating the CLOB value failspublic void free() throws java.sql.SQLException
Clob
and releases the resources that it holds.
The object is invalid once the free
method
is called. If free
is called multiple times, the
subsequent calls to free
are treated as a no-op.
public java.io.Reader getCharacterStream(long pos, long length) throws java.sql.SQLException
Reader
object that contains a partial
Clob
value, starting with the character specified by pos,
which is length characters in length.getCharacterStream
in interface java.sql.Clob
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.Reader
through which the partial Clob
value can be read.java.sql.SQLException
- if pos is less than 1 or if pos is greater than the
number of
characters in the Clob
or if pos + length
is greater than
Clob.length() +1
private void checkValidity() throws java.sql.SQLException
java.sql.SQLException
private void makeWritableClobClone() throws java.io.IOException, java.sql.SQLException
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.
java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources failprivate void makeWritableClobClone(long len) throws java.io.IOException, java.sql.SQLException
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.
len
- number of characters to be cloned (should be smaller
than clob length)java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources failInternalClob getInternalClob()
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.
public int getLocator()
EngineLOB
The key can be used with
EmbedConnection.getLOBMapping(int)
to
retrieve this LOB at a later time.
getLocator
in interface EngineLOB
Apache Derby V10.14 Internals - Copyright © 2004,2018 The Apache Software Foundation. All Rights Reserved.