Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.jdbc.InternalClob

Method Summary

Modifier and Type	Method and Description
public long	Returns: Number of characters in the Clob. getCharLength() Gets the number of characters in the Clob.
public long	Returns: Number of characters in the Clob, or `-1` if the length is currently unknown (not cached). getCharLengthIfKnown() Gets the number of characters in the Clob if it is already known.
public Reader	Returns: A `Reader` serving the content of the Clob. getInternalReader(long character position. The first character is at position `1`. characterPosition) Returns an internal reader for the Clob content, initialized at the specified character position.
public InputStream	Returns: A stream of bytes representing the content of the Clob, initialized at byte position 0. getRawByteStream() Returns a stream serving the raw bytes of the Clob.
public Reader	Returns: A `Reader` serving the content of the Clob. getReader(long character position. The first character is at position `1`. characterPosition) Returns a reader for the Clob content, initialized at the specified character position.
public long	Returns: Update count, starting at zero. getUpdateCount() Returns the update count of the Clob.
public Writer	Returns: A writer initialized at the specified character position. getWriter(long the starting character position. The first character is at position `1`. charPos) Returns a writer to write data into the Clob.
public long	Returns: The number of characters inserted. insertString(String the string to insert str, long the character position the string will be inserted at. Must be between `1` and `clob.length() +1`, inclusive. pos) Inserts the given string at the specified character position.
public boolean	Returns: `true` if released, `false` if not. isReleased() Tells if the the Clob has been released.
public boolean	Returns: `true` if the Clob is intended to be writable, `false` if modifying the Clob is definitely not possible. isWritable() Tells if the Clob representation is intended to be writable.
public void	release() Frees the resources held by the internal Clob representation.
public void	truncate(long the length in characters to truncate to newLength)

Method Detail

getCharLength	back to summary
public long getCharLength() throws IOException, SQLException Gets the number of characters in the Clob. Returns:long Number of characters in the Clob. Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail

getCharLength

back to summary

public long getCharLength() throws IOException, SQLException

Gets the number of characters in the Clob.

Returns:long

Number of characters in the Clob.

Exceptions

IOException:: if accessing underlying I/O resources fail
SQLException:: if accessing underlying resources fail

getCharLengthIfKnown back to summary

getCharLengthIfKnown	back to summary
public long getCharLengthIfKnown() Gets the number of characters in the Clob if it is already known. 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). Returns:long Number of characters in the Clob, or `-1` if the length is currently unknown (not cached).

public long getCharLengthIfKnown()

Gets the number of characters in the Clob if it is already known.

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

Returns:long: Number of characters in the Clob, or -1 if the length is currently unknown (not cached).

getInternalReader back to summary

getInternalReader	back to summary
public Reader getInternalReader(long characterPosition) throws IOException, SQLException Returns an internal reader for the Clob content, initialized at the specified character position. 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`. Parameters characterPosition:long character position. The first character is at position `1`. Returns:Reader A `Reader` serving the content of the Clob. Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail EOFException: if the position is larger then the Clob

public Reader getInternalReader(long characterPosition) throws IOException, SQLException

Returns an internal reader for the Clob content, initialized at the specified character position.

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.

Parameters

characterPosition:long: character position. The first character is at position 1.

Returns:Reader

A Reader serving the content of the Clob.

Exceptions

IOException:: if accessing underlying I/O resources fail
SQLException:: if accessing underlying resources fail
EOFException:: if the position is larger then the Clob

getRawByteStream	back to summary
public InputStream getRawByteStream() throws IOException, SQLException Returns a stream serving the raw bytes of the Clob. 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 stream may be closed by the end user when it is not supposed to operations on the stream might throw exceptions we don't want to present to the end user unwrapped the stream may contain a Derby specific end-of-stream marker 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. Returns:InputStream A stream of bytes representing the content of the Clob, initialized at byte position 0. Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail

getRawByteStream

back to summary

public InputStream getRawByteStream() throws IOException, SQLException

Returns a stream serving the raw bytes of the Clob.

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 stream may be closed by the end user when it is not supposed to
operations on the stream might throw exceptions we don't want to present to the end user unwrapped
the stream may contain a Derby specific end-of-stream marker

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.

Returns:InputStream

A stream of bytes representing the content of the Clob, initialized at byte position 0.

Exceptions

IOException:: if accessing underlying I/O resources fail
SQLException:: if accessing underlying resources fail

getReader back to summary

getReader	back to summary
public Reader getReader(long characterPosition) throws IOException, SQLException Returns a reader for the Clob content, initialized at the specified character position. Parameters characterPosition:long character position. The first character is at position `1`. Returns:Reader A `Reader` serving the content of the Clob. Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail EOFException: if the position is larger then the Clob

public Reader getReader(long characterPosition) throws IOException, SQLException

Returns a reader for the Clob content, initialized at the specified character position.

Parameters

characterPosition:long: character position. The first character is at position 1.

Returns:Reader

A Reader serving the content of the Clob.

Exceptions

IOException:: if accessing underlying I/O resources fail
SQLException:: if accessing underlying resources fail
EOFException:: if the position is larger then the Clob

getUpdateCount	back to summary
public long getUpdateCount() Returns the update count of the Clob. The update count is increased each time a modification of the Clob content is made. Returns:long Update count, starting at zero.

getUpdateCount

back to summary

public long getUpdateCount()

Returns the update count of the Clob.

The update count is increased each time a modification of the Clob content is made.

Returns:long: Update count, starting at zero.

getWriter back to summary

getWriter	back to summary
public Writer getWriter(long charPos) throws IOException, SQLException Returns a writer to write data into the Clob. The semantics of the writer is the same as for `insertString`. Parameters charPos:long the starting character position. The first character is at position `1`. Returns:Writer A writer initialized at the specified character position. Exceptions IOException: if writing to the Clob fails SQLException: if accessing underlying resources fail UnsupportedOperationException: if the Clob representation is read-only

public Writer getWriter(long charPos) throws IOException, SQLException

Returns a writer to write data into the Clob.

The semantics of the writer is the same as for insertString.

Parameters

charPos:long: the starting character position. The first character is at position 1.

Returns:Writer

A writer initialized at the specified character position.

Exceptions

IOException:: if writing to the Clob fails
SQLException:: if accessing underlying resources fail
UnsupportedOperationException:: if the Clob representation is read-only

insertString back to summary

insertString	back to summary
public long insertString(String str, long pos) throws IOException, SQLException Inserts the given string at the specified character position. 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 Parameters str:String the string to insert pos:long the character position the string will be inserted at. Must be between `1` and `clob.length() +1`, inclusive. Returns:long The number of characters inserted. Exceptions IOException: if writing to the I/O resources fail SQLException: it the position is invalid IllegalArgumentException: if the string is `null` UnsupportedOperationException: if the Clob representation is read-only

public long insertString(String str, long pos) throws IOException, SQLException

Inserts the given string at the specified character position.

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

Parameters

str:String: the string to insert
pos:long: the character position the string will be inserted at. Must be between 1 and clob.length() +1, inclusive.

Returns:long

The number of characters inserted.

Exceptions

IOException:: if writing to the I/O resources fail
SQLException:: it the position is invalid
IllegalArgumentException:: if the string is null
UnsupportedOperationException:: if the Clob representation is read-only

isReleased back to summary

isReleased	back to summary
public boolean isReleased() Tells if the the Clob has been released. 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. Returns:boolean `true` if released, `false` if not.

public boolean isReleased()

Tells if the the Clob has been released.

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.

Returns:boolean: true if released, false if not.

isWritable back to summary

isWritable	back to summary
public boolean isWritable() Tells if the Clob representation is intended to be writable. 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). Returns:boolean `true` if the Clob is intended to be writable, `false` if modifying the Clob is definitely not possible.

public boolean isWritable()

Tells if the Clob representation is intended to be writable.

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

Returns:boolean: true if the Clob is intended to be writable, false if modifying the Clob is definitely not possible.

release	back to summary
public void release() throws IOException, SQLException Frees the resources held by the internal Clob representation. After calling this method, all other operations on the Clob will be invalid and throw an exception. Exceptions IOException: if freeing associated I/O resources fails SQLException: if freeing associated resources fails

release

back to summary

public void release() throws IOException, SQLException

Frees the resources held by the internal Clob representation.

After calling this method, all other operations on the Clob will be invalid and throw an exception.

Exceptions

IOException:: if freeing associated I/O resources fails
SQLException:: if freeing associated resources fails

truncate	back to summary
public void truncate(long newLength) throws IOException, SQLException Parameters newLength:long the length in characters to truncate to Exceptions IOException: if accessing the underlying I/O resources fails SQLException: if accessing underlying resources fail UnsupportedOperationException: if the Clob representation is read-only

pack-priv Interface InternalClob

Method Summary

Method Detail