Movatterモバイル変換

Interface Clob

All Known Subinterfaces:

NClob

All Known Implementing Classes:

SerialClob

public interfaceClob

The mapping in the Java programming language for the SQLCLOB type. An SQLCLOB is a built-in type that stores a Character Large Object as a column value in a row of a database table. By default drivers implement aClob object using an SQLlocator(CLOB), which means that aClob object contains a logical pointer to the SQLCLOB data rather than the data itself. AClob object is valid for the duration of the transaction in which it was created.

TheClob interface provides methods for getting the length of an SQLCLOB (Character Large Object) value, for materializing aCLOB value on the client, and for searching for a substring orCLOB object within aCLOB value. Methods in the interfacesResultSet,CallableStatement, andPreparedStatement, such asgetClob andsetClob allow a programmer to access an SQLCLOB value. In addition, this interface has methods for updating aCLOB value.

All methods on theClob interface must be fully implemented if the JDBC driver supports the data type.

Since:

1.2

length

longlength()            throwsSQLException

Retrieves the number of characters in theCLOB value designated by thisClob object.

Returns:

length of theCLOB in characters

Throws:

SQLException - if there is an error accessing the length of theCLOB value

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

getSubString

StringgetSubString(long pos,                    int length)                    throwsSQLException

Retrieves a copy of the specified substring in theCLOB value designated by thisClob object. The substring begins at positionpos and has up tolength consecutive characters.

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; the value for length must be 0 or greater

Returns:

aString that is the specified substring in theCLOB value designated by thisClob object

Throws:

SQLException - if there is an error accessing theCLOB value; if pos is less than 1 or length is less than 0

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

getCharacterStream

ReadergetCharacterStream()                          throwsSQLException

Retrieves theCLOB value designated by thisClob object as ajava.io.Reader object (or as a stream of characters).

Returns:

ajava.io.Reader object containing theCLOB data

Throws:

SQLException - if there is an error accessing theCLOB value

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

See Also:

setCharacterStream(long)

getAsciiStream

InputStreamgetAsciiStream()                           throwsSQLException

Retrieves theCLOB value designated by thisClob object as an ascii stream.

Returns:

ajava.io.InputStream object containing theCLOB data

Throws:

SQLException - if there is an error accessing theCLOB value

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

See Also:

setAsciiStream(long)

position

longposition(String searchstr,              long start)              throwsSQLException

Retrieves the character position at which the specified substringsearchstr appears in the SQLCLOB value represented by thisClob object. The search begins at positionstart.

Parameters:

searchstr - the substring for which to search

start - the position at which to begin searching; the first position is 1

Returns:

the position at which the substring appears or -1 if it is not present; the first position is 1

Throws:

SQLException - if there is an error accessing theCLOB value or if pos is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

position

longposition(Clob searchstr,              long start)              throwsSQLException

Retrieves the character position at which the specifiedClob objectsearchstr appears in thisClob object. The search begins at positionstart.

Parameters:

searchstr - theClob object for which to search

start - the position at which to begin searching; the first position is 1

Returns:

the position at which theClob object appears or -1 if it is not present; the first position is 1

Throws:

SQLException - if there is an error accessing theCLOB value or if start is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.2

setString

intsetString(long pos,String str)              throwsSQLException

Writes the given JavaString to theCLOB value that thisClob object designates at the positionpos. The string will overwrite the existing characters in theClob object starting at the positionpos. If the end of theClob value is reached while writing the given string, then the length of theClob value will be increased to accomodate the extra characters.

Note: If the value specified forpos is greater then the length+1 of theCLOB value then the behavior is undefined. Some JDBC drivers may throw aSQLException while other drivers may support this operation.

Parameters:

pos - the position at which to start writing to theCLOB value that thisClob object represents; The first position is 1

str - the string to be written to theCLOB value that thisClob designates

Returns:

the number of characters written

Throws:

SQLException - if there is an error accessing theCLOB value or if pos is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

setString

intsetString(long pos,String str,              int offset,              int len)              throwsSQLException

Writeslen characters ofstr, starting at characteroffset, to theCLOB value that thisClob represents. The string will overwrite the existing characters in theClob object starting at the positionpos. If the end of theClob value is reached while writing the given string, then the length of theClob value will be increased to accomodate the extra characters.

Note: If the value specified forpos is greater then the length+1 of theCLOB value then the behavior is undefined. Some JDBC drivers may throw aSQLException while other drivers may support this operation.

Parameters:

pos - the position at which to start writing to thisCLOB object; The first position is 1

str - the string to be written to theCLOB value that thisClob object represents

offset - the offset intostr to start reading the characters to be written

len - the number of characters to be written

Returns:

the number of characters written

Throws:

SQLException - if there is an error accessing theCLOB value or if pos is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

setAsciiStream

OutputStreamsetAsciiStream(long pos)                            throwsSQLException

Retrieves a stream to be used to write Ascii characters to theCLOB value that thisClob object represents, starting at positionpos. Characters written to the stream will overwrite the existing characters in theClob object starting at the positionpos. If the end of theClob value is reached while writing characters to the stream, then the length of theClob value will be increased to accomodate the extra characters.

Note: If the value specified forpos is greater then the length+1 of theCLOB value then the behavior is undefined. Some JDBC drivers may throw aSQLException while other drivers may support this operation.

Parameters:

pos - the position at which to start writing to thisCLOB object; The first position is 1

Returns:

the stream to which ASCII encoded characters can be written

Throws:

SQLException - if there is an error accessing theCLOB value or if pos is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

See Also:

getAsciiStream()

setCharacterStream

WritersetCharacterStream(long pos)                          throwsSQLException

Retrieves a stream to be used to write a stream of Unicode characters to theCLOB value that thisClob object represents, at positionpos. Characters written to the stream will overwrite the existing characters in theClob object starting at the positionpos. If the end of theClob value is reached while writing characters to the stream, then the length of theClob value will be increased to accomodate the extra characters.

Note: If the value specified forpos is greater then the length+1 of theCLOB value then the behavior is undefined. Some JDBC drivers may throw aSQLException while other drivers may support this operation.

Parameters:

pos - the position at which to start writing to theCLOB value; The first position is 1

Returns:

a stream to which Unicode encoded characters can be written

Throws:

SQLException - if there is an error accessing theCLOB value or if pos is less than 1

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

See Also:

getCharacterStream()

truncate

voidtruncate(long len)              throwsSQLException

Truncates theCLOB value that thisClob designates to have a length oflen characters.

Note: If the value specified forpos is greater then the length+1 of theCLOB value then the behavior is undefined. Some JDBC drivers may throw aSQLException while other drivers may support this operation.

Parameters:

len - the length, in characters, to which theCLOB value should be truncated

Throws:

SQLException - if there is an error accessing theCLOB value or if len is less than 0

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

free

voidfree()          throwsSQLException

This method frees theClob object and releases the resources the resources that it holds. The object is invalid once thefree method is called.

Afterfree has been called, any attempt to invoke a method other thanfree will result in aSQLException being thrown. Iffree is called multiple times, the subsequent calls tofree are treated as a no-op.

Throws:

SQLException - if an error occurs releasing the Clob's resources

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.6

getCharacterStream

ReadergetCharacterStream(long pos,                          long length)                          throwsSQLException

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

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 if pos + length is greater than the number of characters in theClob

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.6