org.apache.derby.impl.jdbc
Class LOBStoredProcedure

java.lang.Object
  extended by org.apache.derby.impl.jdbc.LOBStoredProcedure

public class LOBStoredProcedure
extends java.lang.Object

Contains the stored procedures that will be used in the LOB client side methods.


Field Summary
static int MAX_BLOB_RETURN_LEN
          The maximum length of the data returned from the BLOB stored procedures.
static int MAX_CLOB_RETURN_LEN
          The maximum length of the data returned from the CLOB stored procedures.
 
Constructor Summary
LOBStoredProcedure()
           
 
Method Summary
static int BLOBCREATELOCATOR()
          Creates a new empty Blob and registers it in the HashMap in the Connection and returns the locator value corresponding to this Blob.
static byte[] BLOBGETBYTES(int LOCATOR, long pos, int len)
          Reads up to len bytes from the associated Blob and returns a byte array containing the bytes read.
static long BLOBGETLENGTH(int LOCATOR)
          Returns the length in bytes of the Blob.
static long BLOBGETPOSITIONFROMBYTES(int LOCATOR, byte[] searchBytes, long pos)
          Returns the first occurrence of the byte array in the Blob.
static long BLOBGETPOSITIONFROMLOCATOR(int LOCATOR, int searchLocator, long pos)
          Returns the first occurrence of locator in the Blob.
static void BLOBRELEASELOCATOR(int LOCATOR)
          Removes the supplied LOCATOR entry from the hash map.
static void BLOBSETBYTES(int LOCATOR, long pos, int len, byte[] replaceBytes)
          Replaces the bytes at pos with len bytes
static void BLOBTRUNCATE(int LOCATOR, long length)
          truncates the Blob value represented by LOCATOR to have a length of length.
static int CLOBCREATELOCATOR()
          Creates a new empty Clob and registers it in the HashMap in the Connection and returns the locator value corresponding to this Clob.
static long CLOBGETLENGTH(int LOCATOR)
          returns the length of the Clob corresponding to the LOCATOR value.
static long CLOBGETPOSITIONFROMLOCATOR(int LOCATOR, int searchLocator, long fromPosition)
          returns the first occurrence of the given search string from the given start search position inside the Clob.
static long CLOBGETPOSITIONFROMSTRING(int LOCATOR, java.lang.String searchLiteral, long fromPosition)
          returns the first occurrence of the given search string from the given start search position inside the Clob.
static java.lang.String CLOBGETSUBSTRING(int LOCATOR, long pos, int len)
          Returns the String starting from pos and consisting of up to len consecutive characters from the Clob corresponding to LOCATOR.
static void CLOBRELEASELOCATOR(int LOCATOR)
          Removes the supplied LOCATOR entry from the hash map.
static void CLOBSETSTRING(int LOCATOR, long pos, int length, java.lang.String str)
          replaces the characters starting at fromPosition and with length ForLength
static void CLOBTRUNCATE(int LOCATOR, long length)
          truncates the Clob value represented by LOCATOR to have a length of length.
private static java.sql.Blob getBlobObjectCorrespondingtoLOCATOR(int LOCATOR)
          returns the Blob object corresponding to the locator.
private static java.sql.Clob getClobObjectCorrespondingtoLOCATOR(int LOCATOR)
          returns the Clob object corresponding to the locator.
private static EmbedConnection getEmbedConnection()
          Returns the EmbedConnection object.
private static java.sql.SQLException newSQLException(java.lang.String messageId)
          Generate the SQLException with the appropriate SQLState.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_BLOB_RETURN_LEN

public static final int MAX_BLOB_RETURN_LEN
The maximum length of the data returned from the BLOB stored procedures.

This value is currently dictated by the maximum length of VARCHAR/VARBINARY, because these are the return types of the stored procedures.

See Also:
Constant Field Values

MAX_CLOB_RETURN_LEN

public static final int MAX_CLOB_RETURN_LEN
The maximum length of the data returned from the CLOB stored procedures.

This value is currently dictated by the maximum length of VARCHAR/VARBINARY, because these are the return types of the stored procedures, and the modified UTF8 encoding used for CLOB data. This threshold value could be higher (equal to MAX_BLOB_RETURN_LEN), but then the procedure fetching data from the CLOB must be rewritten to have more logic.

For now we use the defensive assumption that all characters are represented by three bytes.

See Also:
Constant Field Values
Constructor Detail

LOBStoredProcedure

public LOBStoredProcedure()
Method Detail

CLOBCREATELOCATOR

public static int CLOBCREATELOCATOR()
                             throws java.sql.SQLException
Creates a new empty Clob and registers it in the HashMap in the Connection and returns the locator value corresponding to this Clob.

Returns:
an integer that maps to the Clob value created.
Throws:
java.sql.SQLException

CLOBRELEASELOCATOR

public static void CLOBRELEASELOCATOR(int LOCATOR)
                               throws java.sql.SQLException
Removes the supplied LOCATOR entry from the hash map.

Parameters:
LOCATOR - an integer that represents the locator that needs to be removed from the hash map.
Throws:
java.sql.SQLException

CLOBGETPOSITIONFROMSTRING

public static long CLOBGETPOSITIONFROMSTRING(int LOCATOR,
                                             java.lang.String searchLiteral,
                                             long fromPosition)
                                      throws java.sql.SQLException
returns the first occurrence of the given search string from the given start search position inside the Clob.

Parameters:
LOCATOR - an integer that represents the locator of the Clob in which the given position of the given sub-string needs to be found.
searchLiteral - a String whose occurence inside the Clob needs to be found starting from pos.
fromPosition - an integer that represents the position inside the Clob from which the search needs to begin.
Returns:
an integer that represents the position inside the Clob of the first occurrence of the sub-string from the given starting position.
Throws:
java.sql.SQLException

CLOBGETPOSITIONFROMLOCATOR

public static long CLOBGETPOSITIONFROMLOCATOR(int LOCATOR,
                                              int searchLocator,
                                              long fromPosition)
                                       throws java.sql.SQLException
returns the first occurrence of the given search string from the given start search position inside the Clob.

Parameters:
LOCATOR - an integer that represents the locator of the Clob in which the given position of the given sub-string needs to be found.
searchLocator - a Locator representing a Clob whose occurence inside the Clob needs to be found starting from pos.
fromPosition - an integer that represents the position inside the Clob from which the search needs to begin.
Returns:
an integer that represents the position inside the Clob of the first occurrence of the sub-string from the given starting position.
Throws:
java.sql.SQLException

CLOBGETLENGTH

public static long CLOBGETLENGTH(int LOCATOR)
                          throws java.sql.SQLException
returns the length of the Clob corresponding to the LOCATOR value.

Parameters:
LOCATOR - an integer that represents the locator of the Clob whose length needs to be obtained.
Returns:
an integer that represents the length of the Clob.
Throws:
java.sql.SQLException

CLOBGETSUBSTRING

public static java.lang.String CLOBGETSUBSTRING(int LOCATOR,
                                                long pos,
                                                int len)
                                         throws java.sql.SQLException
Returns the String starting from pos and consisting of up to len consecutive characters from the Clob corresponding to LOCATOR.

Parameters:
LOCATOR - an integer that represents the LOCATOR used to retrieve an instance of the LOB.
pos - a long that represents the position from which the substring begins.
len - an integer representing the maximum length of the substring. The value will be reduced to the maximum allowed return length if required (see MAX_CLOB_RETURN_LEN).
Returns:
A substring from the Clob starting at the given position, not longer than len characters.
Throws:
java.sql.SQLException

CLOBSETSTRING

public static void CLOBSETSTRING(int LOCATOR,
                                 long pos,
                                 int length,
                                 java.lang.String str)
                          throws java.sql.SQLException
replaces the characters starting at fromPosition and with length ForLength

Parameters:
LOCATOR - an integer that represents the locator of the Clob in which the characters need to be replaced.
pos - an integer that represents the position inside the Clob from which the string needs to be replaced.
length - the number of characters from the string that need to be used for replacement.
str - the string from which the repalcement characters are built.
Throws:
java.sql.SQLException

CLOBTRUNCATE

public static void CLOBTRUNCATE(int LOCATOR,
                                long length)
                         throws java.sql.SQLException
truncates the Clob value represented by LOCATOR to have a length of length.

Parameters:
LOCATOR - an integer that represents the LOCATOR used to retrieve an instance of the LOB.
length - an integer that represents the length to which the Clob must be truncated to.
Throws:
java.sql.SQLException

getClobObjectCorrespondingtoLOCATOR

private static java.sql.Clob getClobObjectCorrespondingtoLOCATOR(int LOCATOR)
                                                          throws java.sql.SQLException
returns the Clob object corresponding to the locator.

Parameters:
LOCATOR - an integer that represents the locator corresponding to the Clob object requested.
Returns:
a Clob object that is mapped to the LOCATOR object passed in.
Throws:
a - SQLException.
java.sql.SQLException

BLOBCREATELOCATOR

public static int BLOBCREATELOCATOR()
                             throws java.sql.SQLException
Creates a new empty Blob and registers it in the HashMap in the Connection and returns the locator value corresponding to this Blob.

Returns:
an integer that maps to the Blob value created.
Throws:
java.sql.SQLException

BLOBRELEASELOCATOR

public static void BLOBRELEASELOCATOR(int LOCATOR)
                               throws java.sql.SQLException
Removes the supplied LOCATOR entry from the hash map.

Parameters:
LOCATOR - an integer that represents the locator that needs to be removed from the hash map.
Throws:
java.sql.SQLException

BLOBGETPOSITIONFROMLOCATOR

public static long BLOBGETPOSITIONFROMLOCATOR(int LOCATOR,
                                              int searchLocator,
                                              long pos)
                                       throws java.sql.SQLException
Returns the first occurrence of locator in the Blob.

Parameters:
LOCATOR - the locator value of the Blob in which the seaching needs to be done.
searchLocator - the locator value of the Blob whose position needs needs to be found.
pos - the position from which the seaching needs to be done.
Returns:
the position at which the first occurrence of the Blob is found.
Throws:
java.sql.SQLException

BLOBGETPOSITIONFROMBYTES

public static long BLOBGETPOSITIONFROMBYTES(int LOCATOR,
                                            byte[] searchBytes,
                                            long pos)
                                     throws java.sql.SQLException
Returns the first occurrence of the byte array in the Blob.

Parameters:
LOCATOR - the locator value of the Blob in which the seaching needs to be done.
searchBytes - the byte array whose position needs needs to be found.
pos - the position from which the seaching needs to be done.
Returns:
the position at which the first occurrence of the Byte array is found.
Throws:
java.sql.SQLException

BLOBGETLENGTH

public static long BLOBGETLENGTH(int LOCATOR)
                          throws java.sql.SQLException
Returns the length in bytes of the Blob.

Parameters:
LOCATOR - the locator value of the Blob whose length needs to be found.
Returns:
the length of the Blob object mapped to the locator .
Throws:
java.sql.SQLException

BLOBGETBYTES

public static byte[] BLOBGETBYTES(int LOCATOR,
                                  long pos,
                                  int len)
                           throws java.sql.SQLException
Reads up to len bytes from the associated Blob and returns a byte array containing the bytes read.

Note that a smaller number of bytes than requested might be returned. The number of bytes returned can be found by checking the length of the returned byte array.

Parameters:
LOCATOR - the locator value of the Blob from which the byte array needs to be retrieved.
len - the maximum number of bytes to read. The value will be reduced to the maximum allowed return length if required (see MAX_BLOB_RETURN_LEN).
pos - the position from which the bytes from the Blob need to be retrieved.
Returns:
A byte array containing the bytes read, starting from position pos in the Blob.
Throws:
java.sql.SQLException

BLOBSETBYTES

public static void BLOBSETBYTES(int LOCATOR,
                                long pos,
                                int len,
                                byte[] replaceBytes)
                         throws java.sql.SQLException
Replaces the bytes at pos with len bytes

Parameters:
LOCATOR - the integer that represents the Blob in which the bytes need to be replaced.
pos - the position stating from which the byte replacement needs to happen.
len - the number of bytes that need to be used in replacement.
replaceBytes - the byte array that contains the bytes that needs to be used for replacement.
Throws:
java.sql.SQLException

BLOBTRUNCATE

public static void BLOBTRUNCATE(int LOCATOR,
                                long length)
                         throws java.sql.SQLException
truncates the Blob value represented by LOCATOR to have a length of length.

Parameters:
LOCATOR - an integer that represents the LOCATOR used to retrieve an instance of the LOB.
length - an integer that represents the length to which the Blob must be truncated to.
Throws:
java.sql.SQLException

getBlobObjectCorrespondingtoLOCATOR

private static java.sql.Blob getBlobObjectCorrespondingtoLOCATOR(int LOCATOR)
                                                          throws java.sql.SQLException
returns the Blob object corresponding to the locator.

Parameters:
LOCATOR - an integer that represents the locator corresponding to the Blob object requested.
Returns:
a Blob object that is mapped to the LOCATOR object passed in.
Throws:
java.sql.SQLException

getEmbedConnection

private static EmbedConnection getEmbedConnection()
                                           throws java.sql.SQLException
Returns the EmbedConnection object.

Throws:
SQLException.
java.sql.SQLException

newSQLException

private static java.sql.SQLException newSQLException(java.lang.String messageId)
Generate the SQLException with the appropriate SQLState.

Parameters:
messageId - The messageId of the message associated with this message.
Returns:
a SQLEXception.

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

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