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

Modifier and Type	Field and 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

Access	Constructor and Description
pack-priv	EmbedClob(EmbedConnection The Connection object associated with this EmbedClob object. con) Creates an empty Clob object.
protected	EmbedClob(EmbedConnection associated connection for the Clob con, StringDataValue string data value descriptor providing the Clob source dvd) Creates a Clob on top of a data value descriptor.

Method Summary

Modifier and Type	Method and Description
private void	checkValidity()
public void	free() Implements java.sql.Clob.free, org.apache.derby.iapi.jdbc.EngineLOB.free. Frees the `Clob` and releases the resources that it holds.
public InputStream	Returns: An Ascii stream containing the `CLOB` data. Valid values in the stream are 0 - 255. getAsciiStream() Implements java.sql.Clob.getAsciiStream. Gets the `CLOB` value designated by this `Clob` object as a stream of Ascii bytes.
public Reader	Returns: A character stream containing the `CLOB` data. getCharacterStream() Implements java.sql.Clob.getCharacterStream. Gets the `Clob` contents as a stream of characters.
public Reader	Returns: `Reader` through which the partial `Clob` value can be read. getCharacterStream(long the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1. pos, long the length in characters of the partial value to be retrieved. length) Implements java.sql.Clob.getCharacterStream. Returns a `Reader` object that contains a partial `Clob` value, starting with the character specified by pos, which is length characters in length.
pack-priv InternalClob	Returns: The current internal Clob representation. getInternalClob() Returns the current internal Clob representation.
public int	Returns: locator value for this Clob. getLocator() Implements org.apache.derby.iapi.jdbc.EngineLOB.getLocator. Returns LOB locator key.
public String	Returns: A `String` that is the specified substring in the `CLOB` value designated by this `Clob` object getSubString(long the first character of the substring to be extracted. The first character is at position 1. pos, int the number of consecutive characters to be copied length) Implements java.sql.Clob.getSubString. Returns a copy of the specified substring in the `CLOB` value designated by this `Clob` object.
public long	Returns: The length of the `CLOB` in number of characters. length() Implements java.sql.Clob.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 number of characters to be cloned (should be smaller than clob length) len) Makes a writable clone of the current Clob.
public long	Returns: The position at which the substring appears, `-1` if it does not appear in the `CLOB` value. The first position is `1`. position(String the substring for which to search searchStr, long the position at which to begin searching; the first position is `1` start) Implements java.sql.Clob.position. Determines the character position at which the specified substring `searchStr` appears in the `CLOB` value.
public long	Returns: the position at which the `Clob` object appears, else -1; the first position is 1 position(Clob the `Clob` object for which to search searchClob, long the position at which to begin searching; the first position is 1 start) Implements java.sql.Clob.position. Determines the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object.
public OutputStream	Returns: the stream to which ASCII encoded characters can be written setAsciiStream(long the position at which to start writing to this Clob object pos) Implements java.sql.Clob.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.
public Writer	Returns: the stream to which Unicode encoded characters can be written setCharacterStream(long the position at which to start writing to this Clob object pos) Implements java.sql.Clob.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.
public int	Returns: the number of characters written setString(long the position at which to start writing to the CLOB value that this Clob object represents pos, String the string to be written to the `CLOB` value that this `Clob` designates str) Implements java.sql.Clob.setString. JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos.
public int	Returns: the number of characters written setString(long the position at which to start writing to this Clob object pos, String the string to be written to the CLOB value that this Clob designates str, int the offset into str to start reading the characters to be written offset, int the number of characters to be written len) Implements java.sql.Clob.setString. JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
public void	truncate(long the length, in characters, to which the CLOB value should be truncated, 0 is accepted len) Implements java.sql.Clob.truncate. JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters

Inherited from org.apache.derby.impl.jdbc.ConnectionChild:: commitIfAutoCommit commitIfNeeded getCal getConnectionSynchronization getEmbedConnection getLanguageConnectionContext getLCC handleException needCommit newSQLException restoreContextStack restoreIntrFlagIfSeen setupContextStack

clob	back to summary
private InternalClob clob The underlying Clob object, which may change depending on what the user does with the Clob.

isValid	back to summary
private boolean isValid Tells whether the Clob has been freed or not.

locator	back to summary
private int locator

EmbedClob	back to summary
pack-priv EmbedClob(EmbedConnection con) throws SQLException Creates an empty Clob object. Parameters con:EmbedConnection The Connection object associated with this EmbedClob object.

EmbedClob	back to summary
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`. The data value descriptor may provide a `String` or a stream as the source of the Clob. Parameters con:EmbedConnection associated connection for the Clob dvd:StringDataValue string data value descriptor providing the Clob source

Method Detail

checkValidity	back to summary
private void checkValidity() throws SQLException

free back to summary

free	back to summary
public void free() throws SQLException Implements java.sql.Clob.free, org.apache.derby.iapi.jdbc.EngineLOB.free. Frees the `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. Exceptions SQLException: if an error occurs releasing the Clobs resources

public void free() throws SQLException

Implements java.sql.Clob.free, org.apache.derby.iapi.jdbc.EngineLOB.free.

Frees the 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.

Exceptions

SQLException:: if an error occurs releasing the Clobs resources

getAsciiStream back to summary

getAsciiStream	back to summary
public InputStream getAsciiStream() throws SQLException Implements java.sql.Clob.getAsciiStream. Gets the `CLOB` value designated by this `Clob` object as a stream of Ascii bytes. Returns:InputStream An Ascii stream containing the `CLOB` data. Valid values in the stream are 0 - 255. Exceptions SQLException: if there is an error accessing the `CLOB` value

public InputStream getAsciiStream() throws SQLException

Implements java.sql.Clob.getAsciiStream.

Gets the CLOB value designated by this Clob object as a stream of Ascii bytes.

Returns:InputStream

An Ascii stream containing the CLOB data. Valid values in the stream are 0 - 255.

Exceptions

SQLException:: if there is an error accessing the CLOB value

getCharacterStream back to summary

getCharacterStream	back to summary
public Reader getCharacterStream() throws SQLException Implements java.sql.Clob.getCharacterStream. Gets the `Clob` contents as a stream of characters. Returns:Reader A character stream containing the `CLOB` data. Exceptions SQLException: if there is an error accessing the `CLOB`

public Reader getCharacterStream() throws SQLException

Implements java.sql.Clob.getCharacterStream.

Gets the Clob contents as a stream of characters.

Returns:Reader

A character stream containing the CLOB data.

Exceptions

SQLException:: if there is an error accessing the CLOB

getCharacterStream back to summary

getCharacterStream	back to summary
public Reader getCharacterStream(long pos, long length) throws SQLException Implements java.sql.Clob.getCharacterStream. Returns a `Reader` object that contains a partial `Clob` value, starting with the character specified by pos, which is length characters in length. Parameters pos:long the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1. length:long the length in characters of the partial value to be retrieved. Returns:Reader `Reader` through which the partial `Clob` value can be read. Exceptions 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`

public Reader getCharacterStream(long pos, long length) throws SQLException

Implements java.sql.Clob.getCharacterStream.

Returns a Reader object that contains a partial Clob value, starting with the character specified by pos, which is length characters in length.

Parameters

pos:long: the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1.
length:long: the length in characters of the partial value to be retrieved.

Returns:Reader

Reader through which the partial Clob value can be read.

Exceptions

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

getInternalClob	back to summary
pack-priv 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:InternalClob The current internal Clob representation.

getInternalClob

back to summary

pack-priv 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:InternalClob: The current internal Clob representation.

getLocator back to summary

getLocator	back to summary
public int getLocator() Implements org.apache.derby.iapi.jdbc.EngineLOB.getLocator. Doc from org.apache.derby.iapi.jdbc.EngineLOB.getLocator. Returns LOB locator key. The key can be used with `org.apache.derby.impl.jdbc.EmbedConnection#getLOBMapping` to retrieve this LOB at a later time. Returns:int locator value for this Clob.

public int getLocator()

Implements org.apache.derby.iapi.jdbc.EngineLOB.getLocator.

Doc from org.apache.derby.iapi.jdbc.EngineLOB.getLocator.

Returns LOB locator key.

The key can be used with org.apache.derby.impl.jdbc.EmbedConnection#getLOBMapping to retrieve this LOB at a later time.

Returns:int: locator value for this Clob.

getSubString back to summary

getSubString	back to summary
public String getSubString(long pos, int length) throws SQLException Implements java.sql.Clob.getSubString. Returns a copy of the specified substring in the `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. Parameters pos:long the first character of the substring to be extracted. The first character is at position 1. length:int the number of consecutive characters to be copied Returns:String A `String` that is the specified substring in the `CLOB` value designated by this `Clob` object Exceptions SQLException: if there is an error accessing the `CLOB`

public String getSubString(long pos, int length) throws SQLException

Implements java.sql.Clob.getSubString.

Returns a copy of the specified substring in the 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.

Parameters

pos:long: the first character of the substring to be extracted. The first character is at position 1.
length:int: the number of consecutive characters to be copied

Returns:String

A String that is the specified substring in the CLOB value designated by this Clob object

Exceptions

SQLException:: if there is an error accessing the CLOB

length back to summary

length	back to summary
public long length() throws SQLException Implements java.sql.Clob.length. Returns the number of characters in the `CLOB` value designated by this `Clob` object. Returns:long The length of the `CLOB` in number of characters. Exceptions SQLException: if obtaining the length fails

public long length() throws SQLException

Implements java.sql.Clob.length.

Returns the number of characters in the CLOB value designated by this Clob object.

Returns:long

The length of the CLOB in number of characters.

Exceptions

SQLException:: if obtaining the length fails

makeWritableClobClone back to summary

makeWritableClobClone	back to summary
private void makeWritableClobClone() throws IOException, 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. Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail

private void makeWritableClobClone() throws IOException, 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.

Exceptions

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

makeWritableClobClone back to summary

makeWritableClobClone	back to summary
private void makeWritableClobClone(long len) throws IOException, 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:long number of characters to be cloned (should be smaller than clob length) Exceptions IOException: if accessing underlying I/O resources fail SQLException: if accessing underlying resources fail

private void makeWritableClobClone(long len) throws IOException, 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:long: number of characters to be cloned (should be smaller than clob length)

Exceptions

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

position back to summary

position	back to summary
public long position(String searchStr, long start) throws SQLException Implements java.sql.Clob.position. Determines the character position at which the specified substring `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: If a matching char is found, increment `matchCount`. If `matchCount` is equal to the length of `searchStr`, 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`. Parameters searchStr:String the substring for which to search start:long the position at which to begin searching; the first position is `1` Returns:long The position at which the substring appears, `-1` if it does not appear in the `CLOB` value. The first position is `1`. Exceptions SQLException: if there is an error accessing the `CLOB` value

public long position(String searchStr, long start) throws SQLException

Implements java.sql.Clob.position.

Determines the character position at which the specified substring 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:

If a matching char is found, increment matchCount.
If matchCount is equal to the length of searchStr, 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.

Parameters

searchStr:String: the substring for which to search
start:long: the position at which to begin searching; the first position is 1

Returns:long

The position at which the substring appears, -1 if it does not appear in the CLOB value. The first position is 1.

Exceptions

SQLException:: if there is an error accessing the CLOB value

position back to summary

position	back to summary
public long position(Clob searchClob, long start) throws SQLException Implements java.sql.Clob.position. Determines the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object. The search begins at position `start`. Parameters searchClob:Clob the `Clob` object for which to search start:long the position at which to begin searching; the first position is 1 Returns:long the position at which the `Clob` object appears, else -1; the first position is 1 Exceptions SQLException: if there is an error accessing the `CLOB` value

public long position(Clob searchClob, long start) throws SQLException

Implements java.sql.Clob.position.

Determines the character position at which the specified Clob object searchstr appears in this Clob object. The search begins at position start.

Parameters

searchClob:Clob: the Clob object for which to search
start:long: the position at which to begin searching; the first position is 1

Returns:long

the position at which the Clob object appears, else -1; the first position is 1

Exceptions

SQLException:: if there is an error accessing the CLOB value

setAsciiStream	back to summary
public OutputStream setAsciiStream(long pos) throws SQLException Implements java.sql.Clob.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. Parameters pos:long the position at which to start writing to this Clob object Returns:OutputStream the stream to which ASCII encoded characters can be written Exceptions SQLException: if obtaining the stream fails

setAsciiStream

back to summary

public OutputStream setAsciiStream(long pos) throws SQLException

Implements java.sql.Clob.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.

Parameters

pos:long: the position at which to start writing to this Clob object

Returns:OutputStream

the stream to which ASCII encoded characters can be written

Exceptions

SQLException:: if obtaining the stream fails

setCharacterStream	back to summary
public Writer setCharacterStream(long pos) throws SQLException Implements java.sql.Clob.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. Parameters pos:long the position at which to start writing to this Clob object Returns:Writer the stream to which Unicode encoded characters can be written Exceptions SQLException: if obtaining the stream fails

setCharacterStream

back to summary

public Writer setCharacterStream(long pos) throws SQLException

Implements java.sql.Clob.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.

Parameters

pos:long: the position at which to start writing to this Clob object

Returns:Writer

the stream to which Unicode encoded characters can be written

Exceptions

SQLException:: if obtaining the stream fails

setString back to summary

setString	back to summary
public int setString(long pos, String str) throws SQLException Implements java.sql.Clob.setString. JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos. Parameters pos:long the position at which to start writing to the CLOB value that this Clob object represents str:String Doc from java.sql.Clob.setString. the string to be written to the `CLOB` value that this `Clob` designates Returns:int the number of characters written Exceptions SQLException: if writing the string fails

public int setString(long pos, String str) throws SQLException

Implements java.sql.Clob.setString.

JDBC 3.0 Writes the given Java String to the CLOB value that this Clob object designates at the position pos.

Parameters

pos:long

the position at which to start writing to the CLOB value that this Clob object represents

str:String

Doc from java.sql.Clob.setString.

the string to be written to the CLOB value that this Clob designates

Returns:int

the number of characters written

Exceptions

SQLException:: if writing the string fails

setString	back to summary
public int setString(long pos, String str, int offset, int len) throws SQLException Implements java.sql.Clob.setString. JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents. Parameters pos:long the position at which to start writing to this Clob object str:String the string to be written to the CLOB value that this Clob designates offset:int the offset into str to start reading the characters to be written len:int the number of characters to be written Returns:int the number of characters written Exceptions SQLException: if writing the string fails

setString

back to summary

public int setString(long pos, String str, int offset, int len) throws SQLException

Implements java.sql.Clob.setString.

JDBC 3.0 Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.

Parameters

pos:long: the position at which to start writing to this Clob object
str:String: the string to be written to the CLOB value that this Clob designates
offset:int: the offset into str to start reading the characters to be written
len:int: the number of characters to be written

Returns:int

the number of characters written

Exceptions

SQLException:: if writing the string fails

truncate	back to summary
public void truncate(long len) throws SQLException Implements java.sql.Clob.truncate. JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters Parameters len:long the length, in characters, to which the CLOB value should be truncated, 0 is accepted Exceptions SQLException: if truncating the CLOB value fails

truncate

back to summary

public void truncate(long len) throws SQLException

Implements java.sql.Clob.truncate.

JDBC 3.0 Truncates the CLOB value that this Clob designates to have a length of len characters

Parameters

len:long: the length, in characters, to which the CLOB value should be truncated, 0 is accepted

Exceptions

SQLException:: if truncating the CLOB value fails

pack-priv final Class EmbedClob

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail