class CallableLocatorProcedures
extends java.lang.Object
Connection
parameter and
all calls will be made on that connection.
The class makes sure that each procedure call is only prepared once
per instance. Hence, it will keep references to
CallableStatement
objects for procedures that have
been called through this instance. This makes it possible to
prepare each procedure call only once per Connection
.
Since LOBs can not be parameters to stored procedures, the framework should make sure that calls involving a byte[] or String that does not fit in a VARCHAR (FOR BIT DATA), are split into several calls each operating on a fragment of the LOB.
for an example of how to use
this class.
Constructor | Description |
---|---|
CallableLocatorProcedures(ClientConnection conn) |
Create an instance to be used for calling locator-based stored
procedures.
|
Modifier and Type | Method | Description |
---|---|---|
(package private) int |
blobCreateLocator() |
Allocates an empty BLOB on server and returns its locator.
|
(package private) byte[] |
blobGetBytes(int sourceLocator,
long fromPosition,
int forLength) |
Retrieves all or part of the
BLOB value that is identified
by sourceLocator , as an array of bytes. |
(package private) long |
blobGetLength(int sourceLocator) |
Returns the number of bytes in the
BLOB value
designated by this sourceLocator . |
(package private) long |
blobGetPositionFromBytes(int locator,
byte[] searchLiteral,
long fromPosition) |
Retrieves the byte position at which the specified byte array
searchLiteral begins within the BLOB value
identified by locator . |
private long |
blobGetPositionFromBytes(int locator,
long fromPosition,
byte[] searchLiteral,
int offset,
int length) |
Retrieves the byte position at which the specified part of the byte
array
searchLiteral begins within the BLOB
value identified by locator . |
(package private) long |
blobGetPositionFromLocator(int locator,
int searchLocator,
long fromPosition) |
Retrieves the byte position in the BLOB value designated by this
locator at which pattern given by
searchLocator begins. |
(package private) void |
blobReleaseLocator(int locator) |
This method frees the BLOB and releases the resources that it
holds.
|
(package private) void |
blobSetBytes(int sourceLocator,
long fromPosition,
int forLength,
byte[] bytes) |
Writes all or part of the given
byte array to the
BLOB value designated by sourceLocator . |
(package private) void |
blobTruncate(int sourceLocator,
long length) |
Truncates the
BLOB value identified by
sourceLocator to be length bytes. |
(package private) int |
clobCreateLocator() |
Allocates an empty CLOB on server and returns its locator.
|
(package private) long |
clobGetLength(int sourceLocator) |
Returns the number of character in the
CLOB value
designated by this sourceLocator . |
(package private) long |
clobGetPositionFromLocator(int locator,
int searchLocator,
long fromPosition) |
Retrieves the character position in the CLOB value designated by this
locator at which substring given by
searchLocator begins. |
private long |
clobGetPositionFromString(int locator,
long fromPosition,
java.lang.String searchLiteral,
int offset,
int length) |
Retrieves the character position at which the specified part of the
substring
searchLiteral begins within the CLOB
value identified by locator . |
(package private) long |
clobGetPositionFromString(int locator,
java.lang.String searchLiteral,
long fromPosition) |
Retrieves the character position at which the specified substring
searchLiteral begins within the CLOB value
identified by locator . |
(package private) java.lang.String |
clobGetSubString(int sourceLocator,
long fromPosition,
int forLength) |
Retrieves all or part of the
CLOB value that is identified
by sourceLocator , as a String . |
(package private) void |
clobReleaseLocator(int locator) |
This method frees the CLOB and releases the resources that it
holds.
|
(package private) void |
clobSetString(int sourceLocator,
long fromPosition,
int forLength,
java.lang.String string) |
Writes all or part of the given
String to the
CLOB value designated by sourceLocator . |
(package private) void |
clobTruncate(int sourceLocator,
long length) |
Truncates the
CLOB value identified by
sourceLocator to be length characters. |
private SqlException |
handleInvalidLocator(SqlException sqle) |
If the given exception indicates that locator was not valid, we
assume the locator has been garbage-collected due to
transaction commit, and wrap the exception in an exception with
SQL state
LOB_OBJECT_INVALID . |
private boolean isLocatorSupportAvailable
private ClientCallableStatement blobCreateLocatorCall
private ClientCallableStatement blobReleaseLocatorCall
private ClientCallableStatement blobGetPositionFromLocatorCall
private ClientCallableStatement blobGetPositionFromBytesCall
private ClientCallableStatement blobGetLengthCall
private ClientCallableStatement blobGetBytesCall
private ClientCallableStatement blobSetBytesCall
private ClientCallableStatement blobTruncateCall
private ClientCallableStatement clobCreateLocatorCall
private ClientCallableStatement clobReleaseLocatorCall
private ClientCallableStatement clobGetPositionFromStringCall
private ClientCallableStatement clobGetPositionFromLocatorCall
private ClientCallableStatement clobGetLengthCall
private ClientCallableStatement clobGetSubStringCall
private ClientCallableStatement clobSetStringCall
private ClientCallableStatement clobTruncateCall
private final ClientConnection connection
private static final int VARCHAR_MAXWIDTH
private static final int INVALID_LOCATOR
CallableLocatorProcedures(ClientConnection conn)
conn
- the connection to be used to prepare calls.int blobCreateLocator() throws SqlException
SqlException
void blobReleaseLocator(int locator) throws SqlException
locator
- locator that designates the BLOB to be released.SqlException
long blobGetPositionFromLocator(int locator, int searchLocator, long fromPosition) throws SqlException
locator
at which pattern given by
searchLocator
begins. The search begins at position
fromPosition
.locator
- locator that identifies the BLOB to be searched.searchLocator
- locator designating the BLOB value for which to
searchfromPosition
- the position in the BLOB value
at which to begin searching; the first position is 1SqlException
long blobGetPositionFromBytes(int locator, byte[] searchLiteral, long fromPosition) throws SqlException
searchLiteral
begins within the BLOB
value
identified by locator
. The search for
searchLiteral
begins at position fromPosition
.
If searchLiteral
is longer than the maximum length of a
VARCHAR FOR BIT DATA, it will be split into smaller fragments, and
repeated procedure calls will be made to perform the entire search
locator
- locator that identifies the BLOB to be searched.searchLiteral
- the byte array for which to searchfromPosition
- the position at which to begin searching; the
first position is 1SqlException
private long blobGetPositionFromBytes(int locator, long fromPosition, byte[] searchLiteral, int offset, int length) throws SqlException
searchLiteral
begins within the BLOB
value identified by locator
. The search for
searchLiteral
begins at position fromPosition
.
This is a helper function used by blobGetPositionFromBytes(int, byte[], long) for each call to the BLOBGETPOSITIONFROMBYTES procedure.
locator
- locator that identifies the BLOB to be searched.searchLiteral
- the byte array for which to searchfromPosition
- the position at which to begin searching; the
first position is 1offset
- the offset into the array searchLiteral
at
which the pattern to search for startslength
- the number of bytes from the array of bytes
searchLiteral
to use for the pattern to search
for. It is assumed that this length is smaller than the maximum
size of a VARCHAR FOR BIT DATA column. Otherwise, an exception
will be thrown.SqlException
long blobGetLength(int sourceLocator) throws SqlException
BLOB
value
designated by this sourceLocator
.sourceLocator
- locator that identifies the BLOBBLOB
in bytesSqlException
byte[] blobGetBytes(int sourceLocator, long fromPosition, int forLength) throws SqlException
BLOB
value that is identified
by sourceLocator
, as an array of bytes. This
byte
array contains up to forLength
consecutive bytes starting at position fromPosition
.
If forLength
is larger than the maximum length of a VARCHAR
FOR BIT DATA, the reading of the BLOB will be split into repeated
procedure calls.
sourceLocator
- locator that identifies the Blob to operate onfromPosition
- the ordinal position of the first byte in the
BLOB
value to be extracted; the first byte is at
position 1forLength
- the number of consecutive bytes to be copied; the value
for length must be 0 or greater. Specifying a length that goes
beyond the end of the BLOB (i.e., fromPosition + forLength
> blob.length()
), will result in an error.forLength
consecutive
bytes from the BLOB
value designated by
sourceLocator
, starting with the byte at position
fromPosition
SqlException
void blobSetBytes(int sourceLocator, long fromPosition, int forLength, byte[] bytes) throws SqlException
byte
array to the
BLOB
value designated by sourceLocator
.
Writing starts at position fromPosition
in the
BLOB
value; forLength
bytes from the given
byte array are written. If the end of the Blob
value is
reached while writing the array of bytes, then the length of the
Blob
value will be increased to accomodate the extra bytes.
If forLength
is larger than the maximum length of a VARCHAR
FOR BIT DATA, the writing to the BLOB value will be split into repeated
procedure calls.
sourceLocator
- locator that identifies the Blob to operated onfromPosition
- the position in the BLOB
value at which
to start writing; the first position is 1forLength
- the number of bytes to be written to the
BLOB
value from the array of bytes
bytes
. Specifying a length that goes beyond the end
of the BLOB (i.e., fromPosition + forLength >
blob.length()
, will result in an error.bytes
- the array of bytes to be writtenSqlException
void blobTruncate(int sourceLocator, long length) throws SqlException
BLOB
value identified by
sourceLocator
to be length
bytes.
Note: If the value specified for length
is greater
than the length+1 of the BLOB
value then an
SqlException
will be thrown.
sourceLocator
- locator identifying the Blob to be truncatedlength
- the length, in bytes, to which the BLOB
value
should be truncatedSqlException
int clobCreateLocator() throws SqlException
SqlException
void clobReleaseLocator(int locator) throws SqlException
locator
- locator that designates the CLOB to be released.SqlException
long clobGetPositionFromString(int locator, java.lang.String searchLiteral, long fromPosition) throws SqlException
searchLiteral
begins within the CLOB
value
identified by locator
. The search for
searchLiteral
begins at position fromPosition
.
If searchLiteral
is longer than the maximum length of a
VARCHAR, it will be split into smaller fragments, and
repeated procedure calls will be made to perform the entire search
locator
- locator that identifies the CLOB to be searched.searchLiteral
- the substring for which to searchfromPosition
- the position at which to begin searching; the
first position is 1SqlException
private long clobGetPositionFromString(int locator, long fromPosition, java.lang.String searchLiteral, int offset, int length) throws SqlException
searchLiteral
begins within the CLOB
value identified by locator
. The search for
searchLiteral
begins at position fromPosition
.
This is a helper function used by clobGetPositionFromString(int, String, long) for each call to the CLOBGETPOSITIONFROMSTRING procedure.
locator
- locator that identifies the CLOB to be searched.searchLiteral
- the substring for which to searchfromPosition
- the position at which to begin searching; the
first position is 1offset
- the offset into the string searchLiteral
at
which the pattern to search for startslength
- the number of characters from the string
searchLiteral
to use for the pattern to search
for. It is assumed that this length is smaller than the maximum
size of a VARCHAR column. Otherwise, an exception will be
thrown.SqlException
long clobGetPositionFromLocator(int locator, int searchLocator, long fromPosition) throws SqlException
locator
at which substring given by
searchLocator
begins. The search begins at position
fromPosition
.locator
- locator that identifies the CLOB to be searched.searchLocator
- locator designating the CLOB value for which to
searchfromPosition
- the position in the CLOB value
at which to begin searching; the first position is 1SqlException
long clobGetLength(int sourceLocator) throws SqlException
CLOB
value
designated by this sourceLocator
.sourceLocator
- locator that identifies the CLOBCLOB
in charactersSqlException
java.lang.String clobGetSubString(int sourceLocator, long fromPosition, int forLength) throws SqlException
CLOB
value that is identified
by sourceLocator
, as a String
. This
String
contains up to forLength
consecutive
characters starting at position fromPosition
.
If forLength
is larger than the maximum length of a
VARCHAR, the reading of the CLOB will be split into repeated procedure
calls.
sourceLocator
- locator that identifies the CLOB to operate onfromPosition
- the ordinal position of the first character in the
CLOB
value to be extracted; the first character is
at position 1forLength
- the number of consecutive characters to be copied; the
value for length must be 0 or greater. Specifying a length that
goes beyond the end of the CLOB (i.e., fromPosition +
forLength > clob.length()
, will result in an error.forLength
consecutive
characters from the CLOB
value designated by
sourceLocator
, starting with the character at
position fromPosition
SqlException
void clobSetString(int sourceLocator, long fromPosition, int forLength, java.lang.String string) throws SqlException
String
to the
CLOB
value designated by sourceLocator
.
Writing starts at position fromPosition
in the
CLOB
value; forLength
characters from the
given string are written. If the end of the CLOB
value is
reached while writing the string, then the length of the
CLOB
value will be increased to accomodate the extra
characters.
If forLength
is larger than the maximum length of a
VARCHAR, the writing to the CLOB value will be split into repeated
procedure calls.
sourceLocator
- locator that identifies the CLOB to operated onfromPosition
- the position in the CLOB
value at which
to start writing; the first position is 1forLength
- the number of characters to be written to the
CLOB
value from the string string
.
Specifying a length that goes beyond the end of the CLOB (i.e.,
fromPosition + forLength > clob.length()
, will
result in an error.string
- the string to be writtenSqlException
void clobTruncate(int sourceLocator, long length) throws SqlException
CLOB
value identified by
sourceLocator
to be length
characters.
Note: If the value specified for length
is greater
than the length+1 of the CLOB
value then an
SqlException
will be thrown.
sourceLocator
- locator identifying the CLOB to be truncatedlength
- the length, in characters, to which the CLOB
value should be truncatedSqlException
private SqlException handleInvalidLocator(SqlException sqle)
LOB_OBJECT_INVALID
.sqle
- Exception to be checkedsqle
indicates that locator was
invalid, an SqlException
with SQL state
LOB_OBJECT_INVALID
. Otherwise, the
incoming exception is returned.Apache Derby V10.14 Internals - Copyright © 2004,2018 The Apache Software Foundation. All Rights Reserved.