com.ibm.etill.framework.payapi
Class Batch

java.lang.Object
  |
  +--com.ibm.etill.framework.payapi.Batch
All Implemented Interfaces:
Archivable, PSServerBatchConstants
Direct Known Subclasses:
FrameworkBatch

public abstract class Batch
extends Object
implements Archivable, PSServerBatchConstants

Batch objects contain all of the generic information that the Framework needs to represent a batch through which a group of transactions are processed. The combination of this object and the CassetteBatch object for the same batch constitutes the complete representation of a given batch.

A batch is uniquely identified by the combination of the merchant number and batch number. Therefore, all batch numbers for a given merchant must be unique.

Among the data maintained in Batch objects are:

The creation of Batch objects is ultimately the responsibility of cassettes since batch policies are a fundamental part of each payment protocol. To create a new Batch, cassettes should call call the Supervisor.createBatch method. For more information on Batch creation, please see Cassette Kit Programmer's Guide Chapter 2 -Framework Object Model -Financial Objects and their states -Batches

This class implements methods to log the generic information about a batch into the ETBATCH database table and to retrieve that same information later on.

See Also:
BatchTotalsItem, Supervisor.createBatch(java.lang.String, java.lang.String, java.lang.String)

Fields inherited from interface com.ibm.etill.framework.xdm.PSServerBatchConstants
APPROXIMATE_XDM_OBJECT_SIZE, BATCH, BATCHCREDITVIEW, BATCHPAYMENTVIEW, BATCHVIEW, COL_ACCOUNTNUMBER, COL_BATCHID, COL_BATCHNUMBER, COL_CLOSEALLOWED, COL_CURRENTSTATE, COL_GROWTH1, COL_MERCHANTNAME, COL_PAYMENTTYPE, COL_PURGEALLOWED, COL_STATUS, COL_TIMECLOSED, COL_TIMECREATED, COL_TIMEMODIFIED, COL_TOTALSFD, COL_TOTALSKEY, COL_UNIQUEKEY, MAXBATCHVIEW, VIEW_ACCOUNTNUMBER, VIEW_BATCHNUMBER, VIEW_CLOSEALLOWED, VIEW_GROWTH1, VIEW_MAXBATCHNUMBER, VIEW_MERCHANTNAME, VIEW_PAYMENTTYPE, VIEW_PURGEALLOWED, VIEW_STATE, VIEW_STATUS, VIEW_TIMECLOSED, VIEW_TIMECREATED, VIEW_TIMEMODIFIED, VIEW_TOTALS
 
Constructor Summary
Batch()
          Cassettes should never call this constructor.
 
Method Summary
 void addCredit(Credit credit)
          Adds the specified credit to this batch.
 void addPayment(Payment payment)
          Adds the specified payment to this batch.
 Cassette cassette()
          Returns the Cassette object for the cassette through which this Batch is processed.
 void createRecord(Connection conn)
          This method should never be called directly from cassettes.
 void deleteRecord(Connection conn)
          This method should never be called directly from cassettes.
 AccountAdmin getAccount()
          Returns the generic account object with which this Batch is associated.
 String getAccountNumber()
          Returns the account number with which this Batch is associated.
 BatchKey getBatchKey()
          Returns an object suitable for use as a Hashtable key to represent this Batch object.
 String getBatchNumber()
          Returns this Batch's order number.
 short getBatchStatus()
          Returns the current balance status of this Batch object.
 CassetteBatch getCassetteBatch()
          Returns the CassetteBatch object associated with this generic Batch object.
 boolean getCloseAllowed()
          Indicates whether or not the merchant software may issue a BATCHCLOSE for this Batch.
 Enumeration getCreditList()
          Returns an Enumeration of keys that identify each Credit object associated with this Batch object.
 int getCurrentState()
          Returns the current state of this Batch object.
 boolean getForceAllowed()
          Indicates whether or not the merchant software may issue a BATCHCLOSE command with FORCE set to true for this Batch.
 String getMerchantName()
          Returns the merchant number of the merchant to which this Batch belongs.
 String getMerchantNumber()
          Returns the merchant number of the merchant to which this Batch belongs.
 Enumeration getPaymentList()
          Returns an Enumeration of keys that identify each Payment object associated with this Batch object.
 String getPaymentSystemName()
          Returns the name of the cassette that is associated with this Batch.
 boolean getPurgeAllowed()
          Indicates whether or not the merchant software may issue a BATCHPURGE for this Batch.
 ReaderWriterMonitor getReaderWriterMonitor()
          Cassettes should not call this method.
 Enumeration getRelatedOrders()
          Returns an Enumeration of keys that identify each Order object that owns a Payment or Credit in this Batch.
 Timestamp getTimeClosed()
          Returns the time and date when this Batch object was closed.
 Timestamp getTimeCreated()
          Returns the time and date when this Batch object was created.
 Timestamp getTimeModified()
          Returns the time and date when this Batch object was last modified.
 Enumeration getTotals()
          Returns an Enumeration of each BatchTotalsItem belonging to this Batch object.
 BatchTotalsItem getTotals(short currency, int amountExp10)
          Returns this batch's totals for the specified currency and amountExp10.
 void markCreditDeleted(Credit credit)
           
 void markPaymentDeleted(Payment payment)
           
 void removeCredit(Credit credit)
          Removes the specified credit from this batch.
 void removePayment(Payment payment)
          Removes the specified payment from this batch.
 void resurrectCassetteBatch()
          Cassettes should not call this method.
 void setBatchID(int batchID)
          Deprecated.  
 void setBatchStatus(short batchStatus)
          Updates this Batch object's batch balancing status.
 void setCloseAllowed(boolean closeAllowed)
          Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHCLOSE command for this Batch object.
 void setCurrentState(int state)
          Updates the current state of this Batch object and generates a StateEvent.
 void setForceAllowed(boolean forceAllowed)
          Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHCLOSE command for this Batch object with the FORCE flag set to true.
 void setPurgeAllowed(boolean purgeAllowed)
          Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHPURGE command for this Batch object.
 void setTimeClosed(Timestamp timeClosed)
          Marks the time that this Batch was closed.
 void setUniqueKey(String uniqueKey)
          Deprecated.  
 void updateRecord(Connection conn)
          This method should never be called directly from cassettes.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Batch

public Batch()
Cassettes should never call this constructor. The Framework instantiates new Batch objects as they are needed. To create a new Batch, cassettes should call call the Supervisor.createBatch method.
See Also:
Supervisor.createBatch(java.lang.String, java.lang.String, java.lang.String)
Method Detail

createRecord

public void createRecord(Connection conn)
                  throws ETillAbortOperation
This method should never be called directly from cassettes.

Creates a new record representing this Batch object in the ETBATCH database table. This method is part of Batch's implementation of the Archivable interface. The CommitPoint object calls this method calls during commit processing when this Batch object is a member of the CommitPoint create list.

Specified by:
createRecord in interface Archivable
Parameters:
Connection - The JDBC Connection object used to access the database.
Throws:
ETillAbortOperation - Thrown if an SQLException is caught.
See Also:
CommitPoint

updateRecord

public void updateRecord(Connection conn)
                  throws ETillAbortOperation
This method should never be called directly from cassettes.

Udates the database record that represents this Batch object in the ETBATCH table. This method is part of Batch's implementation of the Archivable interface. The CommitPoint object calls this method calls during commit processing when this Batch object is a member of the CommitPoint update list.

Specified by:
updateRecord in interface Archivable
Parameters:
Connection - The JDBC Connection object used to access the database.
Throws:
ETillAbortOperation - Thrown if an SQLException is caught.
See Also:
CommitPoint

deleteRecord

public void deleteRecord(Connection conn)
                  throws ETillAbortOperation
This method should never be called directly from cassettes.

Deletes the database record that represents this Batch object from the ETBATCH table. This method is part of Batch's implementation of the Archivable interface. The CommitPoint object calls this method calls during commit processing when this Batch object is a member of the CommitPoint delete list.

Specified by:
deleteRecord in interface Archivable
Parameters:
Connection - The JDBC Connection object used to access the database.
Throws:
ETillAbortOperation - Thrown if an SQLException is caught.
See Also:
CommitPoint

resurrectCassetteBatch

public void resurrectCassetteBatch()
                            throws ETillAbortOperation
Cassettes should not call this method. The Framework calls this method to retrieve and reinstantiate the associated CassetteBatch object from the database. This method calls the Cassette object's resurrectCassetteBatch method which is responsible for recreating the cassette's batch object.
Throws:
ETillAbortOperation - thrown by the cassette to report errors.

addPayment

public void addPayment(Payment payment)
Adds the specified payment to this batch. Cassettes should call this method when a DEPOSIT command received for an order that is associated with an account that requires batches to be maintained. When a payment is added to a batch,
Parameters:
payment - the Payment object representing the payment to add to the batch.

removePayment

public void removePayment(Payment payment)
Removes the specified payment from this batch. Cassettes should call this method when a DEPOSITREVERSAL is received for the payment (remember that DEPOSITREVERSAL are only supported for the full deposit amount). When a payment is removed from a batch,

Parameters:
payment - the Payment object representing the payment to remove from the batch.

markPaymentDeleted

public void markPaymentDeleted(Payment payment)

addCredit

public void addCredit(Credit credit)
Adds the specified credit to this batch. Cassettes should call this method when a REFUND command received for an order that is associated with an account that requires batches to be maintained. When a credit is added to a batch,
Parameters:
credit - the Credit object representing the payment to add to the batch.
Throws:
ETillCassetteException - thrown if the same Credit is added to this batch twice. If this exception is thrown, the Framework will stop the cassette.

removeCredit

public void removeCredit(Credit credit)
Removes the specified credit from this batch. Cassettes should call this method when a REFUNDREVERSAL command received for an order that is associated with an account that requires batches to be maintained (remember that REFUNDREVERSAL are only supported for the full credit amount). When a credit is removed from a batch,
Parameters:
credit - the Credit object representing the credit to remove from the batch.
Throws:
ETillCassetteException - thrown if an attempt is made to remove a credit that is not currently a member of this batch. If this exception is thrown, the Framework will stop the cassette.

markCreditDeleted

public void markCreditDeleted(Credit credit)

getPaymentList

public Enumeration getPaymentList()
Returns an Enumeration of keys that identify each Payment object associated with this Batch object.
Returns:
Enumeration - the list of TransactionKey objects. One such key will exist for each Payment object associated with this Batch.
See Also:
Payment

getCreditList

public Enumeration getCreditList()
Returns an Enumeration of keys that identify each Credit object associated with this Batch object.
Returns:
Enumeration - the list of TransactionKey objects. One such key will exist for each Credit object associated with this Batch.
See Also:
Credit

getRelatedOrders

public Enumeration getRelatedOrders()
Returns an Enumeration of keys that identify each Order object that owns a Payment or Credit in this Batch.
Returns:
Enumeration - the list of Order objects.
See Also:
Order

getTotals

public Enumeration getTotals()
Returns an Enumeration of each BatchTotalsItem belonging to this Batch object. Each BatchTotalsItem object contains the deposit and credit total for a unique currency/amountExp10 combination.
Returns:
Enumeration - the list of BatchTotalsItem objects.
See Also:
BatchTotalsItem

getTotals

public BatchTotalsItem getTotals(short currency,
                                 int amountExp10)
Returns this batch's totals for the specified currency and amountExp10.
Parameters:
currency - a short containing the requested ISO 4217 currency code.
amountExp10 - an int containing the requested base10 exponent value.
Returns:
BatchTotalsItem - the corresponding totals object. If no transactions exist in the batch for the specified currency/amountExp10, null is returned.

setCloseAllowed

public void setCloseAllowed(boolean closeAllowed)
Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHCLOSE command for this Batch object. Since this decision depends on the payment protocol and possibly the cassette's configuration, the Cassette object must call this method with the appropriate value from its newCassetteBatch method (during batch creation).

If this method is never called, BATCHCLOSE commands will not be allowed for this batch.

Parameters:
closeAllowed - a boolean set to true if merchants are allowed to issue BATCHCLOSE commands for this Batch or false if not.
See Also:
getCloseAllowed()

setPurgeAllowed

public void setPurgeAllowed(boolean purgeAllowed)
Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHPURGE command for this Batch object. Since this decision depends on the payment protocol and possibly the cassette's configuration, the Cassette object must call this method with the appropriate value.

If this method is never called, BATCHPURGE commands will not be allowed for this batch.

Parameters:
purgeAllowed - a boolean set to true if merchants are allowed to issue BATCHPURGE commands for this Batch or false if not.
See Also:
getPurgeAllowed()

setForceAllowed

public void setForceAllowed(boolean forceAllowed)
Sets an internal flag that indicates whether or not the merchant software is allowed to issue a BATCHCLOSE command for this Batch object with the FORCE flag set to true. Since this decision depends on the payment protocol and possibly the cassette's configuration, the Cassette object must call this method with the appropriate value.

If this method is never called, BATCHCLOSE commands with FORCE set to true will not be allowed for this batch.

Parameters:
forceAllowed - a boolean set to true if merchants are allowed to issue BATCHCLOSE commands with FORCE set to true for this Batch or false if not.
See Also:
getForceAllowed()

setTimeClosed

public void setTimeClosed(Timestamp timeClosed)
Marks the time that this Batch was closed. The cassette should call this method once this Batch has been successfully closed.
Parameters:
timeClosed - a java.sql.Timestamp object containing the time that the batch close operation completed.

setBatchStatus

public void setBatchStatus(short batchStatus)
Updates this Batch object's batch balancing status. Cassettes should call this method after attempting to balance the batch totals (if the cassette supports batch balancing). Valid values (defined in com.ibm.etill.framework.payapi.PaymentAPIConstants) are:

Parameters:
batchStatus - a short containing a valid batch status value.

setUniqueKey

public void setUniqueKey(String uniqueKey)
Deprecated.  


setBatchID

public void setBatchID(int batchID)
Deprecated.  


setCurrentState

public void setCurrentState(int state)
Updates the current state of this Batch object and generates a StateEvent.

Cassettes should call this method as necessary to keep this object's state synchronized with the cassette's corresponding CassetteBatch object. The cassette writer is responsible for defining how the CassetteBatch's states map to those of the generic Batch objects.

The Framework generates a StateEvent if the input state value is different from the current state value. This event will be sent out to registered event listeners the next time the commit method of this thread's CommitPoint is called.

Parameters:
state - an int containing the new state value. This must be one of the following order state values as defined in com.ibm.etill.framework.payapi.PaymentAPIConstants:
  • BATCH_OPENING
  • BATCH_OPEN
  • BATCH_PENDING_DEPRECATED
  • BATCH_CLOSING
  • BATCH_CLOSED
See Also:
CommitPoint.addToEventList(com.ibm.etill.framework.eventmgr.PSEvent)

getMerchantNumber

public String getMerchantNumber()
Returns the merchant number of the merchant to which this Batch belongs.
Returns:
String - the merchant number

getAccountNumber

public String getAccountNumber()
Returns the account number with which this Batch is associated.
Returns:
String - the account number

getBatchNumber

public String getBatchNumber()
Returns this Batch's order number.
Returns:
String - the batch number

getPaymentSystemName

public String getPaymentSystemName()
Returns the name of the cassette that is associated with this Batch. ("Payment system" is a term used to refer the relationship between a merchant and a cassette.)
Returns:
String - the configured cassette name

getCloseAllowed

public boolean getCloseAllowed()
Indicates whether or not the merchant software may issue a BATCHCLOSE for this Batch.
Returns:
boolean - true if the merchant is allowed to issue BATCHCLOSE commands for this Batch or false if not.
See Also:
setCloseAllowed(boolean)

getPurgeAllowed

public boolean getPurgeAllowed()
Indicates whether or not the merchant software may issue a BATCHPURGE for this Batch.
Returns:
boolean - true if the merchant is allowed to issue BATCHPURGE commands for this Batch or false if not.
See Also:
setPurgeAllowed(boolean)

getForceAllowed

public boolean getForceAllowed()
Indicates whether or not the merchant software may issue a BATCHCLOSE command with FORCE set to true for this Batch.
Returns:
boolean - true if the merchant is allowed to issue BATCHCLOSE commands with FORCE set to true for this Batch. Returns false otherwise.
See Also:
setForceAllowed(boolean)

getTimeCreated

public Timestamp getTimeCreated()
Returns the time and date when this Batch object was created.
Returns:
Timestamp - the creation time of this object, expressed as the number of milliseconds since January 1, 1970, 00:00:00 UTC.

getTimeClosed

public Timestamp getTimeClosed()
Returns the time and date when this Batch object was closed.
Returns:
Timestamp - the closing time of this object, expressed as the number of milliseconds since January 1, 1970, 00:00:00 UTC.

getTimeModified

public Timestamp getTimeModified()
Returns the time and date when this Batch object was last modified.
Returns:
Timestamp - the modification time of this object, expressed as the number of milliseconds since January 1, 1970, 00:00:00 UTC.

getCurrentState

public int getCurrentState()
Returns the current state of this Batch object. Valid batch state values (defined in com.ibm.etill.framework.payapi.PaymentAPIConstants) are:
Returns:
int - the current state value of this Batch

getBatchStatus

public short getBatchStatus()
Returns the current balance status of this Batch object. Valid batch status values (defined in com.ibm.etill.framework.payapi.PaymentAPIConstants) are:
Returns:
int - the current balance status of this Batch

getCassetteBatch

public CassetteBatch getCassetteBatch()
Returns the CassetteBatch object associated with this generic Batch object.
Returns:
CassetteBatch - the corresponding CassetteBatch.

getAccount

public AccountAdmin getAccount()
Returns the generic account object with which this Batch is associated.
Returns:
AccountAdmin - the generic account object

getBatchKey

public BatchKey getBatchKey()
Returns an object suitable for use as a Hashtable key to represent this Batch object.
Returns:
BatchKey - a Hashtable key based on this Batch's merchant number and batch number.

getMerchantName

public String getMerchantName()
Returns the merchant number of the merchant to which this Batch belongs.
Returns:
String - the merchant number

cassette

public Cassette cassette()
Returns the Cassette object for the cassette through which this Batch is processed.
Returns:
Cassette - the Cassette object. If a CassetteBatch object has not been associated with this Batch object yet, then null is returned.

getReaderWriterMonitor

public ReaderWriterMonitor getReaderWriterMonitor()
Cassettes should not call this method.

The Framework calls this method to access the Batch object's ReaderWriterMonitor, which is used to obtain the object lock.