Class 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.
    • 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.