|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.derby.client.am.CallableLocatorProcedures
class CallableLocatorProcedures
Contains the necessary methods to call the stored procedure that
operate on LOBs identified by locators. An instance of this class
will be initialized with a 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 Summary | |
---|---|
CallableLocatorProcedures(Connection conn)
Create an instance to be used for calling locator-based stored procedures. |
Method Summary | |
---|---|
(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 . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
boolean isLocatorSupportAvailable
private CallableStatement blobCreateLocatorCall
private CallableStatement blobReleaseLocatorCall
private CallableStatement blobGetPositionFromLocatorCall
private CallableStatement blobGetPositionFromBytesCall
private CallableStatement blobGetLengthCall
private CallableStatement blobGetBytesCall
private CallableStatement blobSetBytesCall
private CallableStatement blobTruncateCall
private CallableStatement clobCreateLocatorCall
private CallableStatement clobReleaseLocatorCall
private CallableStatement clobGetPositionFromStringCall
private CallableStatement clobGetPositionFromLocatorCall
private CallableStatement clobGetLengthCall
private CallableStatement clobGetSubStringCall
private CallableStatement clobSetStringCall
private CallableStatement clobTruncateCall
private final Connection connection
private static final int VARCHAR_MAXWIDTH
private static final int INVALID_LOCATOR
Constructor Detail |
---|
CallableLocatorProcedures(Connection conn)
conn
- the connection to be used to prepare calls.Method Detail |
---|
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 1
SqlException
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 1
SqlException
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 BLOB
BLOB
in bytes
SqlException
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 written
SqlException
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 truncated
SqlException
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 1
SqlException
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 1
SqlException
long clobGetLength(int sourceLocator) throws SqlException
CLOB
value
designated by this sourceLocator
.
sourceLocator
- locator that identifies the CLOB
CLOB
in characters
SqlException
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 written
SqlException
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 truncated
SqlException
private SqlException handleInvalidLocator(SqlException sqle)
LOB_OBJECT_INVALID
.
sqle
- Exception to be checked
sqle
indicates that locator was
invalid, an SqlException
with SQL state
LOB_OBJECT_INVALID
. Otherwise, the
incoming exception is returned.
|
Built on Thu 2011-03-10 11:54:14+0000, from revision ??? | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |