StoreStreamClob
, TemporaryClob
interface InternalClob
The methods defined by Clob
must be implemented on top of
this interface. In addition, there are some methods to aid internal tasks and
organization, like transferring one internal Clob representation to another
one.
Modifier and Type | Method | Description |
---|---|---|
long |
getCharLength() |
Gets the number of characters in the Clob.
|
long |
getCharLengthIfKnown() |
Gets the number of characters in the Clob if it is already known.
|
java.io.Reader |
getInternalReader(long characterPosition) |
Returns an internal reader for the Clob content, initialized at the
specified character position.
|
java.io.InputStream |
getRawByteStream() |
Returns a stream serving the raw bytes of the Clob.
|
java.io.Reader |
getReader(long characterPosition) |
Returns a reader for the Clob content, initialized at the specified
character position.
|
long |
getUpdateCount() |
Returns the update count of the Clob.
|
java.io.Writer |
getWriter(long charPos) |
Returns a writer to write data into the Clob.
|
long |
insertString(java.lang.String str,
long pos) |
Inserts the given string at the specified character position.
|
boolean |
isReleased() |
Tells if the the Clob has been released.
|
boolean |
isWritable() |
Tells if the Clob representation is intended to be writable.
|
void |
release() |
Frees the resources held by the internal Clob representation.
|
void |
truncate(long newLength) |
long getCharLength() throws java.io.IOException, java.sql.SQLException
java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources faillong getCharLengthIfKnown()
This method will not do any work to obtain the length if it isn't
already known. Due to special handling of zero in the code, this method
will return -1
if a length of zero is cached internally.
If a positive value is returned, it is expected to be equal to the actual length of the Clob (i.e., no stale values must be returned).
-1
if the length is
currently unknown (not cached).java.io.InputStream getRawByteStream() throws java.io.IOException, java.sql.SQLException
Note that it is up to the caller of this method to handle the issue of encoding. There is no predetermined encoding associated with this byte stream, it is up to the Clob representation which one it uses.
This stream may be an internal store stream, and should not be directly published to the end user (returned through the JDBC API). There are three reasons for this:
The primary use of this method is to clone the Clob contents without going via char (or String). Make sure the clone uses the same encoding as the original Clob representation.
java.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources failjava.io.Reader getReader(long characterPosition) throws java.io.IOException, java.sql.SQLException
characterPosition
- character position. The first character is at
position 1
.Reader
serving the content of the Clob.EOFException
- if the position is larger then the Clobjava.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources failjava.io.Reader getInternalReader(long characterPosition) throws java.io.IOException, java.sql.SQLException
This method can return a shared reader object, avoiding instantiation and
repositioning costs for internal operations where the stream itself is
not published to the end-user. One such example is
Clob.getSubString
.
characterPosition
- character position. The first character is at
position 1
.Reader
serving the content of the Clob.EOFException
- if the position is larger then the Clobjava.io.IOException
- if accessing underlying I/O resources failjava.sql.SQLException
- if accessing underlying resources faillong getUpdateCount()
The update count is increased each time a modification of the Clob content is made.
java.io.Writer getWriter(long charPos) throws java.io.IOException, java.sql.SQLException
The semantics of the writer is the same as for insertString(java.lang.String, long)
.
charPos
- the starting character position. The first character is
at position 1
.java.io.IOException
- if writing to the Clob failsjava.sql.SQLException
- if accessing underlying resources failjava.lang.UnsupportedOperationException
- if the Clob representation is
read-onlylong insertString(java.lang.String str, long pos) throws java.io.IOException, java.sql.SQLException
The behavior of this method can be defined by the following examples on
the Clob clob
with value "ABCDEFG"
;
clob.setString(2, "XX")
- "AXXDEFG"
clob.setString(1, "XX")
- "XXCDEFG"
clob.setString(8, "XX")
- "ABCDEFGXX"
clob.setString(7, "XX")
- "ABCDEFXX"
clob.setString(9, "XX")
- throws exception
str
- the string to insertpos
- the character position the string will be inserted at. Must be
between 1
and clob.length() +1
, inclusive.java.io.IOException
- if writing to the I/O resources failjava.sql.SQLException
- it the position is invalidjava.lang.IllegalArgumentException
- if the string is null
java.lang.UnsupportedOperationException
- if the Clob representation is
read-onlyboolean isReleased()
Depending on the context, a Clob is released either because the internal
representation has been changed, or because the Clob itself has been
closed. The former can happen when a user modifies a stream that is
currently represented as a store stream. The latter can happen if
Clob.free
has been called, or if Derby implicitly closes the
Clob.
true
if released, false
if not.boolean isWritable()
Note that even if this method returns true
, it might not be
possible to write to the Clob. If this happens, it is because the
assoicated database is read-only, and the internal Clob representation is
unable to obtain the resources it require (could be an area on disk to
write temporary data).
true
if the Clob is intended to be writable,
false
if modifying the Clob is definitely not possible.void release() throws java.io.IOException, java.sql.SQLException
After calling this method, all other operations on the Clob will be invalid and throw an exception.
java.io.IOException
- if freeing associated I/O resources failsjava.sql.SQLException
- if freeing associated resources failsvoid truncate(long newLength) throws java.io.IOException, java.sql.SQLException
newLength
- the length in characters to truncate tojava.io.IOException
- if accessing the underlying I/O resources failsjava.sql.SQLException
- if accessing underlying resources failjava.lang.UnsupportedOperationException
- if the Clob representation is
read-onlyApache Derby V10.14 Internals - Copyright © 2004,2018 The Apache Software Foundation. All Rights Reserved.