Class CallableLocatorProcedures
- java.lang.Object
-
- org.apache.derby.client.am.CallableLocatorProcedures
-
class CallableLocatorProcedures extends java.lang.Object
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 aConnection
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 perConnection
.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.
- See Also:
for an example of how to use this class.
-
-
Field Summary
-
Constructor Summary
Constructors Constructor Description CallableLocatorProcedures(ClientConnection conn)
Create an instance to be used for calling locator-based stored procedures.
-
Method Summary
All Methods Instance Methods Concrete Methods 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 theBLOB
value that is identified bysourceLocator
, as an array of bytes.(package private) long
blobGetLength(int sourceLocator)
Returns the number of bytes in theBLOB
value designated by thissourceLocator
.(package private) long
blobGetPositionFromBytes(int locator, byte[] searchLiteral, long fromPosition)
Retrieves the byte position at which the specified byte arraysearchLiteral
begins within theBLOB
value identified bylocator
.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 arraysearchLiteral
begins within theBLOB
value identified bylocator
.(package private) long
blobGetPositionFromLocator(int locator, int searchLocator, long fromPosition)
Retrieves the byte position in the BLOB value designated by thislocator
at which pattern given bysearchLocator
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 givenbyte
array to theBLOB
value designated bysourceLocator
.(package private) void
blobTruncate(int sourceLocator, long length)
Truncates theBLOB
value identified bysourceLocator
to belength
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 theCLOB
value designated by thissourceLocator
.(package private) long
clobGetPositionFromLocator(int locator, int searchLocator, long fromPosition)
Retrieves the character position in the CLOB value designated by thislocator
at which substring given bysearchLocator
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 substringsearchLiteral
begins within theCLOB
value identified bylocator
.(package private) long
clobGetPositionFromString(int locator, java.lang.String searchLiteral, long fromPosition)
Retrieves the character position at which the specified substringsearchLiteral
begins within theCLOB
value identified bylocator
.(package private) java.lang.String
clobGetSubString(int sourceLocator, long fromPosition, int forLength)
Retrieves all or part of theCLOB
value that is identified bysourceLocator
, as aString
.(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 givenString
to theCLOB
value designated bysourceLocator
.(package private) void
clobTruncate(int sourceLocator, long length)
Truncates theCLOB
value identified bysourceLocator
to belength
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 stateLOB_OBJECT_INVALID
.
-
-
-
Field Detail
-
isLocatorSupportAvailable
private boolean isLocatorSupportAvailable
-
blobCreateLocatorCall
private ClientCallableStatement blobCreateLocatorCall
-
blobReleaseLocatorCall
private ClientCallableStatement blobReleaseLocatorCall
-
blobGetPositionFromLocatorCall
private ClientCallableStatement blobGetPositionFromLocatorCall
-
blobGetPositionFromBytesCall
private ClientCallableStatement blobGetPositionFromBytesCall
-
blobGetLengthCall
private ClientCallableStatement blobGetLengthCall
-
blobGetBytesCall
private ClientCallableStatement blobGetBytesCall
-
blobSetBytesCall
private ClientCallableStatement blobSetBytesCall
-
blobTruncateCall
private ClientCallableStatement blobTruncateCall
-
clobCreateLocatorCall
private ClientCallableStatement clobCreateLocatorCall
-
clobReleaseLocatorCall
private ClientCallableStatement clobReleaseLocatorCall
-
clobGetPositionFromStringCall
private ClientCallableStatement clobGetPositionFromStringCall
-
clobGetPositionFromLocatorCall
private ClientCallableStatement clobGetPositionFromLocatorCall
-
clobGetLengthCall
private ClientCallableStatement clobGetLengthCall
-
clobGetSubStringCall
private ClientCallableStatement clobGetSubStringCall
-
clobSetStringCall
private ClientCallableStatement clobSetStringCall
-
clobTruncateCall
private ClientCallableStatement clobTruncateCall
-
connection
private final ClientConnection connection
The connection to be used when calling the stored procedures.
-
VARCHAR_MAXWIDTH
private static final int VARCHAR_MAXWIDTH
Max size of byte[] and String parameters to procedures- See Also:
- Constant Field Values
-
INVALID_LOCATOR
private static final int INVALID_LOCATOR
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
CallableLocatorProcedures
CallableLocatorProcedures(ClientConnection conn)
Create an instance to be used for calling locator-based stored procedures.- Parameters:
conn
- the connection to be used to prepare calls.
-
-
Method Detail
-
blobCreateLocator
int blobCreateLocator() throws SqlException
Allocates an empty BLOB on server and returns its locator. Any subsequent operations on this BLOB value will be stored in temporary space on the server.- Returns:
- locator that identifies the created BLOB.
- Throws:
SqlException
-
blobReleaseLocator
void blobReleaseLocator(int locator) throws SqlException
This method frees the BLOB and releases the resources that it holds. (E.g., temporary space used to store this BLOB on the server.)- Parameters:
locator
- locator that designates the BLOB to be released.- Throws:
SqlException
-
blobGetPositionFromLocator
long blobGetPositionFromLocator(int locator, int searchLocator, long fromPosition) throws SqlException
Retrieves the byte position in the BLOB value designated by thislocator
at which pattern given bysearchLocator
begins. The search begins at positionfromPosition
.- Parameters:
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- Returns:
- the position at which the pattern begins, else -1
- Throws:
SqlException
-
blobGetPositionFromBytes
long blobGetPositionFromBytes(int locator, byte[] searchLiteral, long fromPosition) throws SqlException
Retrieves the byte position at which the specified byte arraysearchLiteral
begins within theBLOB
value identified bylocator
. The search forsearchLiteral
begins at positionfromPosition
.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- Parameters:
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- Returns:
- the position at which the pattern appears, else -1
- Throws:
SqlException
-
blobGetPositionFromBytes
private long blobGetPositionFromBytes(int locator, long fromPosition, byte[] searchLiteral, int offset, int length) throws SqlException
Retrieves the byte position at which the specified part of the byte arraysearchLiteral
begins within theBLOB
value identified bylocator
. The search forsearchLiteral
begins at positionfromPosition
.This is a helper function used by blobGetPositionFromBytes(int, byte[], long) for each call to the BLOBGETPOSITIONFROMBYTES procedure.
- Parameters:
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 arraysearchLiteral
at which the pattern to search for startslength
- the number of bytes from the array of bytessearchLiteral
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.- Returns:
- the position at which the pattern appears, else -1
- Throws:
SqlException
-
blobGetLength
long blobGetLength(int sourceLocator) throws SqlException
Returns the number of bytes in theBLOB
value designated by thissourceLocator
.- Parameters:
sourceLocator
- locator that identifies the BLOB- Returns:
- length of the
BLOB
in bytes - Throws:
SqlException
-
blobGetBytes
byte[] blobGetBytes(int sourceLocator, long fromPosition, int forLength) throws SqlException
Retrieves all or part of theBLOB
value that is identified bysourceLocator
, as an array of bytes. Thisbyte
array contains up toforLength
consecutive bytes starting at positionfromPosition
.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.- Parameters:
sourceLocator
- locator that identifies the Blob to operate onfromPosition
- the ordinal position of the first byte in theBLOB
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.- Returns:
- a byte array containing up to
forLength
consecutive bytes from theBLOB
value designated bysourceLocator
, starting with the byte at positionfromPosition
- Throws:
SqlException
-
blobSetBytes
void blobSetBytes(int sourceLocator, long fromPosition, int forLength, byte[] bytes) throws SqlException
Writes all or part of the givenbyte
array to theBLOB
value designated bysourceLocator
. Writing starts at positionfromPosition
in theBLOB
value;forLength
bytes from the given byte array are written. If the end of theBlob
value is reached while writing the array of bytes, then the length of theBlob
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.- Parameters:
sourceLocator
- locator that identifies the Blob to operated onfromPosition
- the position in theBLOB
value at which to start writing; the first position is 1forLength
- the number of bytes to be written to theBLOB
value from the array of bytesbytes
. 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- Throws:
SqlException
-
blobTruncate
void blobTruncate(int sourceLocator, long length) throws SqlException
Truncates theBLOB
value identified bysourceLocator
to belength
bytes.Note: If the value specified for
length
is greater than the length+1 of theBLOB
value then anSqlException
will be thrown.- Parameters:
sourceLocator
- locator identifying the Blob to be truncatedlength
- the length, in bytes, to which theBLOB
value should be truncated- Throws:
SqlException
-
clobCreateLocator
int clobCreateLocator() throws SqlException
Allocates an empty CLOB on server and returns its locator. Any subsequent operations on this CLOB value will be stored in temporary space on the server.- Returns:
- locator that identifies the created CLOB.
- Throws:
SqlException
-
clobReleaseLocator
void clobReleaseLocator(int locator) throws SqlException
This method frees the CLOB and releases the resources that it holds. (E.g., temporary space used to store this CLOB on the server.)- Parameters:
locator
- locator that designates the CLOB to be released.- Throws:
SqlException
-
clobGetPositionFromString
long clobGetPositionFromString(int locator, java.lang.String searchLiteral, long fromPosition) throws SqlException
Retrieves the character position at which the specified substringsearchLiteral
begins within theCLOB
value identified bylocator
. The search forsearchLiteral
begins at positionfromPosition
.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- Parameters:
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- Returns:
- the position at which the pattern appears, else -1
- Throws:
SqlException
-
clobGetPositionFromString
private long clobGetPositionFromString(int locator, long fromPosition, java.lang.String searchLiteral, int offset, int length) throws SqlException
Retrieves the character position at which the specified part of the substringsearchLiteral
begins within theCLOB
value identified bylocator
. The search forsearchLiteral
begins at positionfromPosition
.This is a helper function used by clobGetPositionFromString(int, String, long) for each call to the CLOBGETPOSITIONFROMSTRING procedure.
- Parameters:
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 stringsearchLiteral
at which the pattern to search for startslength
- the number of characters from the stringsearchLiteral
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.- Returns:
- the position at which the pattern appears, else -1
- Throws:
SqlException
-
clobGetPositionFromLocator
long clobGetPositionFromLocator(int locator, int searchLocator, long fromPosition) throws SqlException
Retrieves the character position in the CLOB value designated by thislocator
at which substring given bysearchLocator
begins. The search begins at positionfromPosition
.- Parameters:
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- Returns:
- the position at which the pattern begins, else -1
- Throws:
SqlException
-
clobGetLength
long clobGetLength(int sourceLocator) throws SqlException
Returns the number of character in theCLOB
value designated by thissourceLocator
.- Parameters:
sourceLocator
- locator that identifies the CLOB- Returns:
- length of the
CLOB
in characters - Throws:
SqlException
-
clobGetSubString
java.lang.String clobGetSubString(int sourceLocator, long fromPosition, int forLength) throws SqlException
Retrieves all or part of theCLOB
value that is identified bysourceLocator
, as aString
. ThisString
contains up toforLength
consecutive characters starting at positionfromPosition
.If
forLength
is larger than the maximum length of a VARCHAR, the reading of the CLOB will be split into repeated procedure calls.- Parameters:
sourceLocator
- locator that identifies the CLOB to operate onfromPosition
- the ordinal position of the first character in theCLOB
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.- Returns:
- a string containing up to
forLength
consecutive characters from theCLOB
value designated bysourceLocator
, starting with the character at positionfromPosition
- Throws:
SqlException
-
clobSetString
void clobSetString(int sourceLocator, long fromPosition, int forLength, java.lang.String string) throws SqlException
Writes all or part of the givenString
to theCLOB
value designated bysourceLocator
. Writing starts at positionfromPosition
in theCLOB
value;forLength
characters from the given string are written. If the end of theCLOB
value is reached while writing the string, then the length of theCLOB
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.- Parameters:
sourceLocator
- locator that identifies the CLOB to operated onfromPosition
- the position in theCLOB
value at which to start writing; the first position is 1forLength
- the number of characters to be written to theCLOB
value from the stringstring
. 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- Throws:
SqlException
-
clobTruncate
void clobTruncate(int sourceLocator, long length) throws SqlException
Truncates theCLOB
value identified bysourceLocator
to belength
characters.Note: If the value specified for
length
is greater than the length+1 of theCLOB
value then anSqlException
will be thrown.- Parameters:
sourceLocator
- locator identifying the CLOB to be truncatedlength
- the length, in characters, to which theCLOB
value should be truncated- Throws:
SqlException
-
handleInvalidLocator
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 stateLOB_OBJECT_INVALID
.- Parameters:
sqle
- Exception to be checked- Returns:
- If
sqle
indicates that locator was invalid, anSqlException
with SQL stateLOB_OBJECT_INVALID
. Otherwise, the incoming exception is returned.
-
-