org.apache.derby.client.am
Class CallableLocatorProcedures

java.lang.Object
  extended by 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 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.

See Also:
for an example of how to use this class.

Field Summary
private  CallableStatement blobCreateLocatorCall
           
private  CallableStatement blobGetBytesCall
           
private  CallableStatement blobGetLengthCall
           
private  CallableStatement blobGetPositionFromBytesCall
           
private  CallableStatement blobGetPositionFromLocatorCall
           
private  CallableStatement blobReleaseLocatorCall
           
private  CallableStatement blobSetBytesCall
           
private  CallableStatement blobTruncateCall
           
private  CallableStatement clobCreateLocatorCall
           
private  CallableStatement clobGetLengthCall
           
private  CallableStatement clobGetPositionFromLocatorCall
           
private  CallableStatement clobGetPositionFromStringCall
           
private  CallableStatement clobGetSubStringCall
           
private  CallableStatement clobReleaseLocatorCall
           
private  CallableStatement clobSetStringCall
           
private  CallableStatement clobTruncateCall
           
private  Connection connection
          The connection to be used when calling the stored procedures.
private static int INVALID_LOCATOR
           
(package private)  boolean isLocatorSupportAvailable
           
private static int VARCHAR_MAXWIDTH
          Max size of byte[] and String parameters to procedures
 
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

isLocatorSupportAvailable

boolean isLocatorSupportAvailable

blobCreateLocatorCall

private CallableStatement blobCreateLocatorCall

blobReleaseLocatorCall

private CallableStatement blobReleaseLocatorCall

blobGetPositionFromLocatorCall

private CallableStatement blobGetPositionFromLocatorCall

blobGetPositionFromBytesCall

private CallableStatement blobGetPositionFromBytesCall

blobGetLengthCall

private CallableStatement blobGetLengthCall

blobGetBytesCall

private CallableStatement blobGetBytesCall

blobSetBytesCall

private CallableStatement blobSetBytesCall

blobTruncateCall

private CallableStatement blobTruncateCall

clobCreateLocatorCall

private CallableStatement clobCreateLocatorCall

clobReleaseLocatorCall

private CallableStatement clobReleaseLocatorCall

clobGetPositionFromStringCall

private CallableStatement clobGetPositionFromStringCall

clobGetPositionFromLocatorCall

private CallableStatement clobGetPositionFromLocatorCall

clobGetLengthCall

private CallableStatement clobGetLengthCall

clobGetSubStringCall

private CallableStatement clobGetSubStringCall

clobSetStringCall

private CallableStatement clobSetStringCall

clobTruncateCall

private CallableStatement clobTruncateCall

connection

private final Connection 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(Connection 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 this locator at which pattern given by searchLocator begins. The search begins at position fromPosition.

Parameters:
locator - locator that identifies the BLOB to be searched.
searchLocator - locator designating the BLOB value for which to search
fromPosition - 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 array 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

Parameters:
locator - locator that identifies the BLOB to be searched.
searchLiteral - the byte array for which to search
fromPosition - 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 array 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.

Parameters:
locator - locator that identifies the BLOB to be searched.
searchLiteral - the byte array for which to search
fromPosition - the position at which to begin searching; the first position is 1
offset - the offset into the array searchLiteral at which the pattern to search for starts
length - 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.
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 the BLOB value designated by this sourceLocator.

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

Parameters:
sourceLocator - locator that identifies the Blob to operate on
fromPosition - the ordinal position of the first byte in the BLOB value to be extracted; the first byte is at position 1
forLength - 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 the BLOB value designated by sourceLocator, starting with the byte at position fromPosition
Throws:
SqlException

blobSetBytes

void blobSetBytes(int sourceLocator,
                  long fromPosition,
                  int forLength,
                  byte[] bytes)
            throws SqlException
Writes all or part of the given 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.

Parameters:
sourceLocator - locator that identifies the Blob to operated on
fromPosition - the position in the BLOB value at which to start writing; the first position is 1
forLength - 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
Throws:
SqlException

blobTruncate

void blobTruncate(int sourceLocator,
                  long length)
            throws SqlException
Truncates the 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.

Parameters:
sourceLocator - locator identifying the Blob to be truncated
length - the length, in bytes, to which the BLOB 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 substring 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

Parameters:
locator - locator that identifies the CLOB to be searched.
searchLiteral - the substring for which to search
fromPosition - 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 substring 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.

Parameters:
locator - locator that identifies the CLOB to be searched.
searchLiteral - the substring for which to search
fromPosition - the position at which to begin searching; the first position is 1
offset - the offset into the string searchLiteral at which the pattern to search for starts
length - 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.
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 this locator at which substring given by searchLocator begins. The search begins at position fromPosition.

Parameters:
locator - locator that identifies the CLOB to be searched.
searchLocator - locator designating the CLOB value for which to search
fromPosition - 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 the CLOB value designated by this sourceLocator.

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

Parameters:
sourceLocator - locator that identifies the CLOB to operate on
fromPosition - the ordinal position of the first character in the CLOB value to be extracted; the first character is at position 1
forLength - 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 the CLOB value designated by sourceLocator, starting with the character at position fromPosition
Throws:
SqlException

clobSetString

void clobSetString(int sourceLocator,
                   long fromPosition,
                   int forLength,
                   java.lang.String string)
             throws SqlException
Writes all or part of the given 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.

Parameters:
sourceLocator - locator that identifies the Clob to operated on
fromPosition - the position in the CLOB value at which to start writing; the first position is 1
forLength - 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
Throws:
SqlException

clobTruncate

void clobTruncate(int sourceLocator,
                  long length)
            throws SqlException
Truncates the 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.

Parameters:
sourceLocator - locator identifying the Clob to be truncated
length - the length, in characters, to which the CLOB 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 state LOB_OBJECT_INVALID.

Parameters:
sqle - Exception to be checked
Returns:
If sqle indicates that locator was invalid, an SqlException with SQL state LOB_OBJECT_INVALID. Otherwise, the incoming exception is returned.

Built on Thu 2012-03-29 21:53:33+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.