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

Fields
Modifier and Type	Field	Description
`private ClientCallableStatement`	`blobCreateLocatorCall`
`private ClientCallableStatement`	`blobGetBytesCall`
`private ClientCallableStatement`	`blobGetLengthCall`
`private ClientCallableStatement`	`blobGetPositionFromBytesCall`
`private ClientCallableStatement`	`blobGetPositionFromLocatorCall`
`private ClientCallableStatement`	`blobReleaseLocatorCall`
`private ClientCallableStatement`	`blobSetBytesCall`
`private ClientCallableStatement`	`blobTruncateCall`
`private ClientCallableStatement`	`clobCreateLocatorCall`
`private ClientCallableStatement`	`clobGetLengthCall`
`private ClientCallableStatement`	`clobGetPositionFromLocatorCall`
`private ClientCallableStatement`	`clobGetPositionFromStringCall`
`private ClientCallableStatement`	`clobGetSubStringCall`
`private ClientCallableStatement`	`clobReleaseLocatorCall`
`private ClientCallableStatement`	`clobSetStringCall`
`private ClientCallableStatement`	`clobTruncateCall`
`private ClientConnection`	`connection`	The connection to be used when calling the stored procedures.
`private static int`	`INVALID_LOCATOR`
`private boolean`	`isLocatorSupportAvailable`
`private static int`	`VARCHAR_MAXWIDTH`	Max size of byte[] and String parameters to procedures

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

Class CallableLocatorProcedures

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

isLocatorSupportAvailable

blobCreateLocatorCall

blobReleaseLocatorCall

blobGetPositionFromLocatorCall

blobGetPositionFromBytesCall

blobGetLengthCall

blobGetBytesCall

blobSetBytesCall

blobTruncateCall

clobCreateLocatorCall

clobReleaseLocatorCall

clobGetPositionFromStringCall

clobGetPositionFromLocatorCall

clobGetLengthCall

clobGetSubStringCall

clobSetStringCall

clobTruncateCall

connection

VARCHAR_MAXWIDTH

INVALID_LOCATOR

Constructor Detail

CallableLocatorProcedures

Method Detail

blobCreateLocator

blobReleaseLocator

blobGetPositionFromLocator

blobGetPositionFromBytes

blobGetPositionFromBytes

blobGetLength

blobGetBytes

blobSetBytes

blobTruncate

clobCreateLocator

clobReleaseLocator

clobGetPositionFromString

clobGetPositionFromString

clobGetPositionFromLocator

clobGetLength

clobGetSubString

clobSetString

clobTruncate

handleInvalidLocator