com.ibm.etill.framework.archive
Class ETillArchive

java.lang.Object
  |
  +--com.ibm.etill.framework.archive.ETillArchive
All Implemented Interfaces:
FrameworkReturnCodes, PaymentAPIConstants

public final class ETillArchive
extends Object
implements PaymentAPIConstants

ETillArchive manages access to the Commerce Payments database using JDBC calls. All Cassette access of the database should go through ETillArchive.


Field Summary
static Object archiveLock
          Deprecated. Use ETillArchive.getArchiveLock
static int DEFAULT_390_BINARY_LENGTH
           
static int DEFAULT_BINARY_LENGTH
          Deprecated. Use the ETillArchive.getMaxBinaryLength method.
static int ORACLE_BINARY_LENGTH
          Deprecated. Use the ETillArchive.getMaxBinaryLength method.
static short shortFalse
          Use to represent boolean false value as a small integer in the Commerce Payments database.
static short shortTrue
          Use to represent boolean true value as a small integer in the Commerce Payments database.
 
Constructor Summary
ETillArchive()
           
 
Method Summary
static void addBoolean(boolean booleanToSave, PreparedStatement pstmt, int index)
          Adds a short integer representation of a boolean value to an existing JDBC prepared statement at the specified index.
static void addBoolean(Boolean booleanToSave, PreparedStatement pstmt, int index)
          Adds a short integer representation of a boolean value to an existing JDBC prepared statement at the specified index.
static void addByteField(byte[] bytesToSave, PreparedStatement pstmt, int index)
          Adds a byte array to an existing JDBC prepared statement at the specified index.
static String addExternalField(Object externallySavedObject, PreparedStatement pstmt, int index)
          Creates a uniqueKey for an object saved in another database table (typically the ETBINARYDATA table) and adds that key to an existing JDBC prepared statement at the specified index.
static void addInteger(Integer integerToSave, PreparedStatement pstmt, int index)
          Adds an integer to an existing JDBC prepared statement at the specified index.
static void addString(String stringToSave, PreparedStatement pstmt, int index)
          Adds a string to an existing JDBC prepared statement at the specified index.
static void addTimestamp(Timestamp timestampToSave, PreparedStatement pstmt, int index)
          Adds a Timestamp to an existing JDBC prepared statement at the specified index.
static void addUTF8String(String stringToSave, PreparedStatement pstmt, int index)
          Adds a UTF8 string to an existing JDBC prepared statement at the specified index.
 ResultSet beginQuery(String sqlQuery)
          Sends an SQL QUERY command to the database manager.
 ResultSet beginQuery(String sqlQuery, Integer resultSetMaxSize)
          Sends an SQL QUERY command to the database manager, placing a limit on the size of the returned ResultSet.
 Connection beginTransaction()
          Begins a new transaction with the database.
 void commitAndCloseTransaction(Connection conn)
          Commits a transaction consisting of one or more SQL operations
static void createBinaryField(byte[] binaryData, String uniqueKey, Connection conn)
          Creates a new binary field in the ETBINARYDATA table.
static void deleteBinaryField(String uniqueKey, Connection conn)
          Deletes a binary field from the ETBINARYDATA table.
 void endQuery()
          Closes and removes objects related to the currently active SQL QUERY.
static Object getArchiveLock()
           
static String getDatabaseProductName()
          Returns the database product name for the Commerce Payments database.
static String getDBDriver()
          Returns the database JDBC driver name.
static String geteTillDatabasejdbcURL()
          Returns the Commerce Payments database's JDBC URL.
static String geteTillDatabaseOwner()
          Returns the userid of the Commerce Payments database owner.
static String geteTillDatabasePassword()
          Returns the Commerce Payments database password.
static String geteTillDatabaseUserID()
          Returns the Commerce Payments database userid.
static int getMaxBinaryLength()
          Return the size (in bytes) of the largest physical binary field that will be supported by the underlying Commerce Payments database.
static int getMaxConnections()
          Returns the maximum number of concurrent database connections that will be established.
static String getOwner()
          Deprecated. Use ETillArchive.geteTillDatabaseOwner instead
static byte[] readBinaryField(String uniqueKey)
          Reads the contents of a binary field from the ETBINARYDATA table.
static Boolean readBoolean(ResultSet rs, String field)
          returns a Boolean from a ResultSet corresponding to the specified keyword
static byte[] readByteField(ResultSet rs, String field)
          returns a byte array from a ResultSet corresponding to the specified keyword
static Integer readInteger(ResultSet rs, String field)
          returns an Integer from a ResultSet corresponding to the specified keyword
static Serializable readSerializedObject(byte[] serializedData)
          "Re-instantiates" an object that was previously serialized by the serializeObject method.
static String readString(ResultSet rs, String field)
          returns a string from a ResultSet corresponding to the specified keyword
static Timestamp readTimestamp(ResultSet rs, String field)
          returns a Timestamp from a ResultSet corresponding to the specified keyword
static String readUTF8String(ResultSet rs, String field)
          returns a UTF8 string from a ResultSet corresponding to the specified keyword
 void rollbackAndCloseTransaction(Connection conn)
          Rolls back a transaction consisting of one or more SQL operations
static byte[] serializeObject(Serializable serializableObject)
          Serializes an object so that it can be stored in Commerce Payments database.
static boolean toBoolean(short value)
          Converts a short (SMALLINT) from a database table to its corresponding boolean value.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

archiveLock

public static Object archiveLock
Deprecated. Use ETillArchive.getArchiveLock

Used to synchronize all access to JDBC from within the Commerce Payments process. This is a temporary workaround for thread-safety problems within some JDBC drivers.

shortFalse

public static final short shortFalse
Use to represent boolean false value as a small integer in the Commerce Payments database.

shortTrue

public static final short shortTrue
Use to represent boolean true value as a small integer in the Commerce Payments database.

DEFAULT_BINARY_LENGTH

public static final int DEFAULT_BINARY_LENGTH
Deprecated. Use the ETillArchive.getMaxBinaryLength method.


DEFAULT_390_BINARY_LENGTH

public static final int DEFAULT_390_BINARY_LENGTH

ORACLE_BINARY_LENGTH

public static final int ORACLE_BINARY_LENGTH
Deprecated. Use the ETillArchive.getMaxBinaryLength method.

Constructor Detail

ETillArchive

public ETillArchive()
Method Detail

getMaxBinaryLength

public static int getMaxBinaryLength()
Return the size (in bytes) of the largest physical binary field that will be supported by the underlying Commerce Payments database. This method can be used to decide whether or not a given binary data item should be stored using the ETBINARYDATA table (via the ETillArchive.createBinaryField method) or if it will fit within a column in another table.
Returns:
the maximum physical binary field size in bytes
See Also:
createBinaryField(byte[], java.lang.String, java.sql.Connection)

beginTransaction

public Connection beginTransaction()
                            throws ETillAbortOperation
Begins a new transaction with the database. Commerce Payments ensures that an SQL connection to the database is available for the transaction. Any number of SQL operations can be performed within this transaction using queries, or record creation, updates or deletions through objects that implement the Archivable interface.
Returns:
Connection - a connection to the database
Throws:
ETillAbortOperation - if any errors occur while allocating a new database connection.
See Also:
com.ibm.etill.framework.Archivable, com.ibm.etill.framework.Commitable, com.ibm.etill.framework.CommitPoint

commitAndCloseTransaction

public void commitAndCloseTransaction(Connection conn)
                               throws ETillAbortOperation
Commits a transaction consisting of one or more SQL operations
Parameters:
conn - A Connection object that was previously created through a call to the beginTransaction method.
Throws:
ETillAbortOperation - if any errors occur while committing or closing the transaction.

rollbackAndCloseTransaction

public void rollbackAndCloseTransaction(Connection conn)
                                 throws ETillAbortOperation
Rolls back a transaction consisting of one or more SQL operations
Parameters:
conn - A Connection object that was previously created through a call to the beginTransaction method.
Throws:
ETillAbortOperation - if any errors occur while rolling back or closing the transaction.

beginQuery

public ResultSet beginQuery(String sqlQuery,
                            Integer resultSetMaxSize)
                     throws SQLException
Sends an SQL QUERY command to the database manager, placing a limit on the size of the returned ResultSet. Once all work related to the query is complete, the endQuery method must be called.
Parameters:
sqlQuery - the String containing the SQL QUERY command to be issued.
resultSetMaxSize - the requested maximum number of records to be returned in the result set; if specified as null, then no limit is imposed.
Returns:
ResultSet - the resulting data as returned by JDBC
Throws:
SQLException - generated by JDBC if an error occurs
See Also:
endQuery()

beginQuery

public ResultSet beginQuery(String sqlQuery)
                     throws SQLException
Sends an SQL QUERY command to the database manager. Once all work related to the query is complete, the endQuery method must be called.
Parameters:
sqlQuery - the String containing the SQL QUERY command to be issued.
Returns:
ResultSet - the resulting data as returned by JDBC
Throws:
SQLException - generated by JDBC if an error occurs
See Also:
endQuery()

endQuery

public void endQuery()
              throws SQLException
Closes and removes objects related to the currently active SQL QUERY. This must be issued after all processing of the ResultSet returned by a previous beginQuery call is complete.
Throws:
SQLException - generated by JDBC if an error occurs
See Also:
beginQuery(java.lang.String, java.lang.Integer)

createBinaryField

public static void createBinaryField(byte[] binaryData,
                                     String uniqueKey,
                                     Connection conn)
                              throws ETillAbortOperation
Creates a new binary field in the ETBINARYDATA table.

Binary fields are particularly troublesome when multiple database engines are supported. This method inserts data into a binary field while hiding all of the idiosyncracies of different JDBC drivers and database products, including the underlying data types and length limitations.

Parameters:
binaryData - the byte array containing the binary data to be written into the new ETBINARYDATA record.
uniqueKey - a String containing a uniqueKey obtained through the Supervisor.getUniqueKey method. Each binary field must be assigned a unique uniqueKey value.
conn - the Connection object representing the database transaction under which this field will be created.
Throws:
ETillAbortOperation - if Commerce Payments catches an SQLException while creating the database records through JDBC.
See Also:
Supervisor.getUniqueKey(), deleteBinaryField(java.lang.String, java.sql.Connection), readBinaryField(java.lang.String)

deleteBinaryField

public static void deleteBinaryField(String uniqueKey,
                                     Connection conn)
                              throws ETillAbortOperation
Deletes a binary field from the ETBINARYDATA table. This field must have been previously created using the createBinaryField method.
Parameters:
uniqueKey - a String containing the uniqueKey of the binary field to be deleted.
conn - the Connection object representing the database transaction under which this field will be deleted.
Throws:
ETillAbortOperation - if Commerce Payments catches an SQLException while deleting the database records through JDBC.
See Also:
createBinaryField(byte[], java.lang.String, java.sql.Connection), readBinaryField(java.lang.String)

readBinaryField

public static byte[] readBinaryField(String uniqueKey)
                              throws ETillAbortOperation
Reads the contents of a binary field from the ETBINARYDATA table. This field must have been previously created using the createBinaryField method.
Parameters:
uniqueKey - a String containing the uniqueKey of the binary field to be read.
Returns:
byte[] - the contents of the binary field retrieved from the database.
Throws:
ETillAbortOperation - if Commerce Payments catches an SQLException while reading the data through JDBC.
See Also:
createBinaryField(byte[], java.lang.String, java.sql.Connection), deleteBinaryField(java.lang.String, java.sql.Connection)

serializeObject

public static byte[] serializeObject(Serializable serializableObject)
                              throws ETillAbortOperation
Serializes an object so that it can be stored in Commerce Payments database.
Parameters:
serializableObject - an object that implements the Serializable interface
Returns:
byte[] - the serialized version of the object
Throws:
ETillAbortOperation - if the Commerce Payments catches an IOException while serializing the object

readSerializedObject

public static Serializable readSerializedObject(byte[] serializedData)
                                         throws ETillAbortOperation
"Re-instantiates" an object that was previously serialized by the serializeObject method.
Parameters:
serializedData - the byte array containing a serialized object
Returns:
Serializable the object instance, built from the serialized version
Throws:
ETillAbortOperation - if the Commerce Payments catches an IOException while instantiating the object

addString

public static void addString(String stringToSave,
                             PreparedStatement pstmt,
                             int index)
                      throws SQLException
Adds a string to an existing JDBC prepared statement at the specified index.
Parameters:
stringToSave - the String to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the string should be added
Throws:
SQLException - if any SQL errors occur

readString

public static String readString(ResultSet rs,
                                String field)
                         throws SQLException
returns a string from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field
Returns:
String string from ResultSet that cooresponds to keyword
Throws:
SQLException - if any SQL errors occur

addUTF8String

public static void addUTF8String(String stringToSave,
                                 PreparedStatement pstmt,
                                 int index)
                          throws SQLException
Adds a UTF8 string to an existing JDBC prepared statement at the specified index.
Parameters:
stringToSave - the String to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the string should be added
Throws:
SQLException - if any SQL errors occur

readUTF8String

public static String readUTF8String(ResultSet rs,
                                    String field)
                             throws SQLException
returns a UTF8 string from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field mapping to the UTF8 string
Returns:
String string from a ResultSet corresponding to the specified keyword
Throws:
SQLException - if any SQL errors occur

addBoolean

public static void addBoolean(boolean booleanToSave,
                              PreparedStatement pstmt,
                              int index)
                       throws SQLException
Adds a short integer representation of a boolean value to an existing JDBC prepared statement at the specified index.
Parameters:
booleanToSave - the boolean value to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the value should be added
Throws:
SQLException - if any SQL errors occur

addBoolean

public static void addBoolean(Boolean booleanToSave,
                              PreparedStatement pstmt,
                              int index)
                       throws SQLException
Adds a short integer representation of a boolean value to an existing JDBC prepared statement at the specified index.
Parameters:
booleanToSave - the boolean value to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the value should be added
Throws:
SQLException - if any SQL errors occur

readBoolean

public static Boolean readBoolean(ResultSet rs,
                                  String field)
                           throws SQLException
returns a Boolean from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field
Returns:
Boolean Boolean from a ResultSet corresponding to the specified keyword
Throws:
SQLException - if any SQL errors occur

addInteger

public static void addInteger(Integer integerToSave,
                              PreparedStatement pstmt,
                              int index)
                       throws SQLException
Adds an integer to an existing JDBC prepared statement at the specified index.
Parameters:
integerToSave - the Integer value to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the value should be added
Throws:
SQLException - if any SQL errors occur

readInteger

public static Integer readInteger(ResultSet rs,
                                  String field)
                           throws SQLException
returns an Integer from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field mapping to the UTF8 string
Returns:
Integer Integer from a ResultSet corresponding to the specified keyword
Throws:
SQLException - if any SQL errors occur

addByteField

public static void addByteField(byte[] bytesToSave,
                                PreparedStatement pstmt,
                                int index)
                         throws SQLException
Adds a byte array to an existing JDBC prepared statement at the specified index.
Parameters:
bytesToSave - the byte array value to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the value should be added
Throws:
SQLException - if any SQL errors occur

readByteField

public static byte[] readByteField(ResultSet rs,
                                   String field)
                            throws SQLException
returns a byte array from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field mapping to the UTF8 string
Returns:
byte[] byte array from a ResultSet corresponding to the specified keyword
Throws:
SQLException - if any SQL errors occur

addTimestamp

public static void addTimestamp(Timestamp timestampToSave,
                                PreparedStatement pstmt,
                                int index)
                         throws SQLException
Adds a Timestamp to an existing JDBC prepared statement at the specified index.
Parameters:
timestampToSave - the Timestamp value to be added to the prepared statement
pstmt - the PreparedStatement object
index - an int containing the index at which the value should be added
Throws:
SQLException - if any SQL errors occur

readTimestamp

public static Timestamp readTimestamp(ResultSet rs,
                                      String field)
                               throws SQLException
returns a Timestamp from a ResultSet corresponding to the specified keyword
Parameters:
rs - the ResultSet containing the results of a query
field - the specified field
Returns:
Timestamp Timestamp from a ResultSet corresponding to the specified keyword
Throws:
SQLException - if any SQL errors occur

addExternalField

public static String addExternalField(Object externallySavedObject,
                                      PreparedStatement pstmt,
                                      int index)
                               throws SQLException
Creates a uniqueKey for an object saved in another database table (typically the ETBINARYDATA table) and adds that key to an existing JDBC prepared statement at the specified index.
Parameters:
externallySavedObject - the Object that has been or will be saved elsewhere; typically, the object is saved in the ETBINARYDATA table using the ETillArchive.createBinaryField method.
pstmt - the PreparedStatement object
index - an int containing the index at which the new key should be added
Returns:
String - the uniqueKey value created for the externally saved object
Throws:
SQLException - if any SQL errors occur
See Also:
createBinaryField(byte[], java.lang.String, java.sql.Connection)

getDatabaseProductName

public static String getDatabaseProductName()
Returns the database product name for the Commerce Payments database.
Returns:
String - the name of the underlying database product as returned by the database metadata.

getMaxConnections

public static int getMaxConnections()
Returns the maximum number of concurrent database connections that will be established. This value is determined at run time based on the environment.
Returns:
int - the maximum number of concurrent JDBC connections that will be maintained.

getDBDriver

public static String getDBDriver()
Returns the database JDBC driver name.
Returns:
String - the name of the underlying database product as returned by the database metadata.

geteTillDatabasejdbcURL

public static String geteTillDatabasejdbcURL()
Returns the Commerce Payments database's JDBC URL.
Returns:
String - the JDBC URL as it was specified on the command that started the Payment Engine.

geteTillDatabaseOwner

public static String geteTillDatabaseOwner()
Returns the userid of the Commerce Payments database owner.
Returns:
String - the userid of the database owner as it was specified on the command that started the Payment Engine.

getOwner

public static String getOwner()
Deprecated. Use ETillArchive.geteTillDatabaseOwner instead

Returns the userid of the Commerce Payments database owner.
Returns:
String - the userid of the database owner as it was specified on the command that started the Payment Engine.

geteTillDatabaseUserID

public static String geteTillDatabaseUserID()
Returns the Commerce Payments database userid.
Returns:
String - contains the database userid.

geteTillDatabasePassword

public static String geteTillDatabasePassword()
Returns the Commerce Payments database password.
Returns:
String - the database password as specified at Payment Engine startup.

toBoolean

public static boolean toBoolean(short value)
Converts a short (SMALLINT) from a database table to its corresponding boolean value.
Parameters:
value - the short value to convert to a boolean value.
Returns:
boolean - if value = 1, true is returned; any other value returns false

getArchiveLock

public static Object getArchiveLock()