Class CallableLocatorProcedures

java.lang.Object
org.apache.derby.client.am.CallableLocatorProcedures

class CallableLocatorProcedures extends 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:
  • Field Details

  • Constructor Details

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

    • 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.
      fromPosition - the position at which to begin searching; the first position is 1
      searchLiteral - the byte array for which to search
      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, 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, 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.
      fromPosition - the position at which to begin searching; the first position is 1
      searchLiteral - the substring for which to search
      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

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