com.ibm.etill.framework.cassette
Class Cassette

java.lang.Object
  |
  +--com.ibm.etill.framework.cassette.Cassette

public abstract class Cassette
extends Object

Cassette is the main class that defines the framework's interface to each cassette.

When Commerce Payments is asked to start a cassette, the Framework running in the Payment Engine JVM creates a single instance of the cassette's Cassette subclass. This Cassette subclass object is instantiated in the Payment Engine only. Once the object is intstantiated, the Framework calls several of the object's methods to initialize the cassette. After the cassette has successfully started, the Framework calls the methods on the Cassette object to process requests, provide information about the cassette and the objects it manages, and to perform other functions in support of the Framework.

Every cassette must extend this class and implement all of its abstract methods. To implement these methods, it is important to understand the purpose and responsibilities of each function as defined in this javadoc, as well as the sequence of events which cause the Framework to call each method. These sequences are documented in the Cassette Kit Programmer's Guide.

Note 1: The names of the derived classes are built from cassette name and company name in the cassette configuration table, ETCASSETTECFG. Complete rules for cassette and cassette package names can be found in the Cassette Kit Programmer's Guide.

Note 2: Cassette objects are not instantiated in the Payment Servlet JVM, where all of the query API commands are processed. In that JVM, the com.ibm.etill.framework.cassette.query.CassetteQuery class serves as the Framework's interface to the cassette.

See Also:
CassetteOrder, CassetteQuery, CassetteRequest, CassetteResponse

Constructor Summary
Cassette()
          Sole constructor should never be called by the cassette.
 
Method Summary
abstract  Vector createComPoints()
          Creates the cassette's ComPoint objects during the cassette startup phase.
abstract  ProtocolRequest createProtocolRequest(ETillConnection connection)
          Receives and parses a payment protocol request that's arrived at one of the cassette's ComPoints.
abstract  void destroyComPoints()
          Closes and deactivates the cassette's ComPoint objects during the cassette shutdown phase.
 CassetteAdmin getCassetteAdminObject()
          Returns the Cassette Administration object for the cassette.
 String getName()
          Returns the debug name of this cassette.
 Hashtable getParameterValidationTable()
          Obtain a parameter mapping table for checking syntax of an incoming request.
 String getPaymentSystemName()
          Returns the name of the payment system (the name of the cassette) as specified in the ETCASSETTECFG table.
 ReaderWriterMonitor getReaderWriterMonitor()
          Cassettes should not override or call this method.
 void initialize(String name, String paymentSystem)
          Sets the payment system name and the debug name for the cassette, then calls the initializeCassette method which must be implemented in the derived class.
abstract  void initializeCassette()
          Performs start-up initialization for the payment cassette.
 boolean isAcceptPaymentSupported()
          Returns whether the acceptPayment command is supported by this cassette.
 boolean isApprovalExpirationSupported()
          Cassettes that support this function should return true.
 boolean isReceivePaymentSupported()
          Returns whether the receivePayment command is supported by this cassette.
abstract  CassetteBatch newCassetteBatch(Batch aBatch, ParameterTable protocolData)
          Instantiates and initializes a new CassetteBatch object according to the requirements of the cassette.
abstract  CassetteTransaction newCassetteCredit(Credit aCredit, ParameterTable protocolData)
          Instantiates and initializes a new CassetteTransaction object representing the cassette's version of the specified credit.
abstract  CassetteOrder newCassetteOrder(Order anOrder, ParameterTable protocolData)
          Instantiates and initializes a new CassetteOrder object according to the requirements of the cassette.
abstract  CassetteTransaction newCassettePayment(Payment aPayment, ParameterTable protocolData)
          Instantiates and initializes a new CassetteTransaction object representing the cassette's version of the specified payment.
abstract  void readCassetteConfig()
          Reads the cassette-specific configuration from the Commerce Payments database.
abstract  CassetteBatch resurrectCassetteBatch(Batch aBatch)
          Instantiates an in-memory CassetteBatch object using the information stored in the cassette's database tables.
abstract  CassetteTransaction resurrectCassetteCredit(Credit aCredit)
          Instantiates an in-memory CassetteTransaction object representing the cassette's version of the specified credit using the information stored in the cassette's database tables.
abstract  CassetteOrder resurrectCassetteOrder(Order anOrder)
          Instantiates an in-memory CassetteOrder object using the information stored in the cassette's database tables.
abstract  CassetteTransaction resurrectCassettePayment(Payment aPayment)
          Instantiates an in-memory CassetteTransaction object representing the cassette's version of the specified payment using the information stored in the cassette's database tables.
abstract  void service(CassetteRequest request, CassetteResponse response)
          Processes an inbound API or protocol request and generates an appropriate response.
abstract  void setMessageID(String id)
          Sets the cassette's message resource bundle identifier.
abstract  void shutdown()
          Quiesces and deactivates the cassette such that is will no longer process API commands or (if appropriate) protocol requests.
abstract  void start()
          Activates the cassette so that it is ready to accept API commands and (if appropriate) protocol requests.
abstract  void verifyConfig()
          Verifies the cassette-specific configuration which was read by the previous invocation of readCassetteConfig.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Cassette

public Cassette()
Sole constructor should never be called by the cassette. The Framework instantiates a single instance of each configured cassette's implementation of this class. All initialization and startup function is done explicitly after construction.
Method Detail

initialize

public void initialize(String name,
                       String paymentSystem)
Sets the payment system name and the debug name for the cassette, then calls the initializeCassette method which must be implemented in the derived class. This method is called by the Framework when the cassette is started.
Parameters:
name - a String that contains the name of the class for use in trace entries and error log messages.
paymentSystem - a String that contains the payment system as it appears in the Cassette Configuration table (ETCASSETTECFG).

initializeCassette

public abstract void initializeCassette()
                                 throws ETillAbortOperation
Performs start-up initialization for the payment cassette. The Framework calls this method during Framework initialization or when a cassette is started. (The sequence of Framework calls into the payment cassette at cassette startup time is described in the Cassette Kit Programmer's Guide.)

This is where cassettes should load native libraries, start background and timed work items, and perform other initialization items.

Throws:
ETillAbortOperation - Thrown if initialization fails; puts the cassette in an invalid (unusable) state.

readCassetteConfig

public abstract void readCassetteConfig()
                                 throws ETillAbortOperation
Reads the cassette-specific configuration from the Commerce Payments database. The Framework calls this method during start processing after the message identifier has been set. (The sequence of Framework calls into the payment cassette at cassette startup time is described in the Cassette Kit Programmer's Guide.)

Each cassette is expected to define its own configuration tables to be included in the Commerce Payments database. All configuration should be read into memory for later use when this method is called. Validity checking of the format of individual fields can be performed here.

Note that the cassette's configuration data is verified in the verifyConfig method, which is called after this method.

Throws:
ETillAbortOperation - Thrown if reading configuration data fails; puts the cassette in an invalid (unusable) state.
See Also:
verifyConfig()

verifyConfig

public abstract void verifyConfig()
                           throws ETillAbortOperation
Verifies the cassette-specific configuration which was read by the previous invocation of readCassetteConfig. (The sequence of Framework calls into the payment cassette at cassette startup time is described in the Cassette Kit Programmer's Guide.)

This is where cassettes should check for consistency across fields and tables.

Throws:
ETillAbortOperation - Thrown if verification fails; puts the cassette in an invalid (unusable) state.
See Also:
readCassetteConfig()

createComPoints

public abstract Vector createComPoints()
                                throws ETillAbortOperation
Creates the cassette's ComPoint objects during the cassette startup phase. The Framework calls this method after any open batches have been resurrected. (The sequence of Framework calls into the payment cassette at cassette startup time is described in the Cassette Kit Programmer's Guide.)

Cassettes should create one ComPoint object for each server-side communication point (that is, each communication point that listens for inbound connections or messages) with the outside world. The number and implementation of these ComPoints is based completely on the requirements of the payment protocol being implemented by the cassette. The cassette's ComPoints understands:

Typically, the messages sent to cassette ComPoint objects are sent directly from consumers or financial institutions.
Returns:
Vector - each element contains one of the cassette's ComPoint objects
Throws:
ETillAbortOperation - if any of the required ComPoint objects cannot be instantiated
See Also:
destroyComPoints()

destroyComPoints

public abstract void destroyComPoints()
                               throws ETillAbortOperation
Closes and deactivates the cassette's ComPoint objects during the cassette shutdown phase. The Framework calls this method when a "stop cassette" command is received or when Commerce Payments is shut down. (The sequence of Framework calls into the payment cassette at cassette shutdown time is described in the Cassette Kit Programmer's Guide.)

Cassettes should only destroy the ComPoint objects that it created in the createComPoint method. Cassettes must close all ComPoints and do other clean-up work in this method.

Throws:
ETillAbortOperation - if any of the ComPoints cannot be closed or deactivated.
See Also:
createComPoints()

newCassetteOrder

public abstract CassetteOrder newCassetteOrder(Order anOrder,
                                               ParameterTable protocolData)
                                        throws ETillAbortOperation
Instantiates and initializes a new CassetteOrder object according to the requirements of the cassette. The Framework calls this method just after creating a new Framework Order object in response to an ACCEPTPAYMENT or RECEIVEPAYMENT command. The framework's order caching facility ensures that only only one copy of the Framework Order and CassetteOrder object exists in memory at any given time.

If the cassette does not manage such an object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
anOrder - the Framework Order object with which the new CassetteOrder object will be associated.
protocolData - a ParameterTable containing any protocol data (cassette-specific) parameters received on the associated API call; null if no protocol data parameters were present.
Returns:
CassetteOrder - the new cassette-specific object associated with the input Order object.
Throws:
ETillAbortOperation - thrown if cassette object cannot be built because of some error condition

resurrectCassetteOrder

public abstract CassetteOrder resurrectCassetteOrder(Order anOrder)
                                              throws ETillAbortOperation
Instantiates an in-memory CassetteOrder object using the information stored in the cassette's database tables.

When the Framework receives an API command associated with an existing Order, it looks in the cache for an in-memory representation of that Order. If the Order is found in the cache, all the associated objects are already available - Payments, Credits and the cassette-specific order, payments and credits. If the order is not present in the cache, the Framework recreates the Order object from data in the database and then calls this method to ask the cassette to recreate the associated CassetteOrder from data in the database.

If the cassette does not manage such an object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
anOrder - the Framework Order object with which the CassetteOrder is associated.
Returns:
CassetteOrder the retrieved CassetteOrder that was successfully found in the database.
Throws:
ETillAbortOperation - thrown if required data cannot be found or retrieved from the database or if the object cannot be instantiated for any other reason.

newCassettePayment

public abstract CassetteTransaction newCassettePayment(Payment aPayment,
                                                       ParameterTable protocolData)
                                                throws ETillAbortOperation
Instantiates and initializes a new CassetteTransaction object representing the cassette's version of the specified payment. This object is built based on the requirements of the cassette. The Framework calls this method just after creating a new Framework Payment object, usually in response to an APPROVE command or an ACCEPTPAYMENT or RECEIVEPAYMENT with automatic approval specified. The framework's order caching facility ensures that only one copy of the Framework Payment and CassetteTransaction object exists in memory at any given time.

If the cassette does not manage such an object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aPayment - the Framework Payment object with which the new CassetteTransaction object will be associated.
protocolData - a ParameterTable containing any protocol data (cassette-specific) parameters received on the associated API call; null if no protocol data parameters were present.
Returns:
CassetteTransaction - the new cassette-specific object associated with the input Payment object
Throws:
ETillAbortOperation - thrown if cassette object cannot be built of some error condition

resurrectCassettePayment

public abstract CassetteTransaction resurrectCassettePayment(Payment aPayment)
                                                      throws ETillAbortOperation
Instantiates an in-memory CassetteTransaction object representing the cassette's version of the specified payment using the information stored in the cassette's database tables.

When the Framework receives an API command associated with an existing Payment, it looks in the cache for an in-memory representation of that Payment. If the Payment is found in the cache, all the associated objects are already available - the Order and the cassette-specific order and payment. If the Payment is not present in the cache, the Framework recreates the necessary Framework objects (Order and Payment) from data in the database and then calls this method to ask the cassette to recreate the associated CassetteTransaction object from data in the database.

If the cassette does not manage such an object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aPayment - the Framework Payment object with which the CassetteTransaction is associated.
Returns:
CassetteTransaction the retrieved CassetteTransaction that was successfully found in the database.
Throws:
ETillAbortOperation - thrown if required data cannot be found or retrieved from the database or if the object cannot be instantiated for any other reason.

newCassetteCredit

public abstract CassetteTransaction newCassetteCredit(Credit aCredit,
                                                      ParameterTable protocolData)
                                               throws ETillAbortOperation
Instantiates and initializes a new CassetteTransaction object representing the cassette's version of the specified credit. This object is built based on the requirements of the cassette. The Framework calls this method just after creating a new Framework Credit object, usually in response to a REFUND command. The framework's order caching facility ensures that only one copy of the Framework Credit and CassetteTransaction object exists in memory at any given time.

If the cassette does not support refunds (credits), then this method should throw the following exception:

throw new ETillAbortOperation(PRC_COMMAND_NOT_SUPPORTED, RC_NONE);

If the cassette does support refunds but does not manage an explicit cassette credit object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aCredit - the Framework Credit object with which the new CassetteTransaction object will be associated.
protocolData - a ParameterTable containing any protocol data (cassette-specific) parameters received on the associated API call; null if no protocol data parameters were present.
Returns:
CassetteTransaction - the new cassette-specific object associated with the input Credit object
Throws:
ETillAbortOperation - thrown if cassette object cannot be built of some error condition

resurrectCassetteCredit

public abstract CassetteTransaction resurrectCassetteCredit(Credit aCredit)
                                                     throws ETillAbortOperation
Instantiates an in-memory CassetteTransaction object representing the cassette's version of the specified credit using the information stored in the cassette's database tables.

When the Framework receives an API command associated with an existing Credit, it looks in the cache for an in-memory representation of that Credit. If the Credit is found in the cache, all the associated objects are already available - the Order and the cassette-specific order and credit. If the Credit is not present in the cache, the Framework recreates the necessary Framework objects (Order and Credit) from data in the database and then calls this method to ask the cassette to recreate the associated CassetteTransaction object from data in the database.

If the cassette does not support refunds (credits), then this method should throw the following exception:

throw new ETillAbortOperation(PRC_COMMAND_NOT_SUPPORTED, RC_NONE);

If the cassette does support refunds but does not manage an explicit cassette credit object (this would occur if the Framework object already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aCredit - the Framework Credit object with which the CassetteTransaction is associated.
Returns:
CassetteTransaction the retrieved CassetteTransaction that was successfully found in the database.
Throws:
ETillAbortOperation - thrown if required data cannot be found or retrieved from the database or if the object cannot be instantiated for any other reason.

newCassetteBatch

public abstract CassetteBatch newCassetteBatch(Batch aBatch,
                                               ParameterTable protocolData)
                                        throws ETillAbortOperation
Instantiates and initializes a new CassetteBatch object according to the requirements of the cassette. The Framework calls this method just after creating a new Framework Batch object. The framework's batch caching facility ensures that only only one copy of the Framework Batch and CassetteBatch object exists in memory at any given time.

If the cassette does not support batches at all, then this method should throw the following exception:

throw new ETillAbortOperation(PRC_COMMAND_NOT_SUPPORTED, RC_NONE);

If the cassette only supports batches in specific situations, then the cases where batches are not supported, this method should throw the following exception:

throw new ETillAbortOperation(PRC_CASSETTE_ERROR, an_appropriate_secondary_return_code);

If the cassette supports batches under the given scenario but does not manage a cassette-specific batch object (this would occur if the Framework batch already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aBatch - the Framework Batch object with which the new CassetteBatch object will be associated.
protocolData - a ParameterTable containing any protocol data (cassette-specific) parameters received on the associated API call; null if no protocol data parameters were present.
Returns:
CassetteBatch - the new cassette-specific object associated with the input Batch object.
Throws:
ETillAbortOperation - thrown if cassette object cannot be built of some error condition

resurrectCassetteBatch

public abstract CassetteBatch resurrectCassetteBatch(Batch aBatch)
                                              throws ETillAbortOperation
Instantiates an in-memory CassetteBatch object using the information stored in the cassette's database tables.

When the Framework starts the cassette, it creates in-memory objects representing each of the batches associated with the cassette. For each of those batches, the Framework first instantiates the Framework Batch object and its associated objects and then calls this method to create the in-memory cassette object for the batch from the data stored in the cassette's data in the database.

If the cassette does not support batches in the given scenario or at all, then the cassette should reject it with the following call:

throw new ETillAbortOperation(PRC_UNDEFINED_OBJECT, RC_BATCH);

If the cassette supports batches under the given scenario but does not manage a cassette-specific batch object (this would occur if the Framework batch already contains all of the data needed by the cassette), then this method should just return a null value.

Parameters:
aBatch - the Framework Batch object with which the CassetteBatch is associated.
Returns:
CassetteBatch the in-memory cassette specific object for framework batches.
Throws:
ETillAbortOperation - thrown if required data cannot be found or retrieved from the database or if the object cannot be instantiated for any other reason.

createProtocolRequest

public abstract ProtocolRequest createProtocolRequest(ETillConnection connection)
                                               throws ETillAbortOperation
Receives and parses a payment protocol request that's arrived at one of the cassette's ComPoints. This method should:

There are two ways to handle invalid protocol messages. The needs of the cassette and its respective payment protocol should determine which approach to use:

  1. Throw an ETillAbortOperation exception. If this exception is thrown, the Framework will close the inbound connection without sending any response message to the client.
  2. In order to send a response message to the client to indicate an error, then this method should build a valid ProtocolRequest object that contains an appropriate error indication. By doing this, the cassette's service method, which will be invoked soon after this method returns to the framework, will be able to build and send an appropriate error response.
Parameters:
connection - the ETillConnection object from which the inbound protocol message can be read.
Returns:
ProtocolRequest the appropriate cassette-specific request object to contain all of the pertinent data from the inbound protocol message.
Throws:
ETillAbortOperation - can be thrown to flag an error reading from the ETillConnection or building the ProtocolRequest object. If this exception is thrown, the Framework will close the inbound connection without sending any response message to the client.
See Also:
ProtocolRequest, service(com.ibm.etill.framework.cassette.CassetteRequest, com.ibm.etill.framework.cassette.CassetteResponse), ETillConnection.read()

setMessageID

public abstract void setMessageID(String id)
Sets the cassette's message resource bundle identifier. Every cassette is given a string handle which identifies the cassette's ResourceBundle, which is created from its properties file (this handle is actually the cassette name as specified in the ETCASSETTECFG table). This method should store this string in a convenient location for access by all of the cassette code. A static data member in the derived Cassette class is one good choice.

Note that in previous releases, the messageId was implemented as an integer value. This was changed to accomodate the new servlet-based Commerce Payments 2.1 architecture.

Parameters:
id - the String containing the cassette's ResourceBundle identifier.

start

public abstract void start()
Activates the cassette so that it is ready to accept API commands and (if appropriate) protocol requests. The Framework calls this method as the last step of the cassette startup phase. By the time this method is called, the cassette has sucessfully: (The sequence of Framework calls into the payment cassette at cassette startup time is described in the Cassette Kit Programmer's Guide.)

This method should perform any payment processing that may be necessary to complete remaining recovery or initialization functions. Once control is returned from this method to the framework, the cassette is eligible to receive new user requests.


shutdown

public abstract void shutdown()
Quiesces and deactivates the cassette such that is will no longer process API commands or (if appropriate) protocol requests. The Framework calls this method as the last step of the cassette shutdown phase. By the time this method is called, the cassette has sucessfully: In addition, the Framework has destroyed all of the cassette's protocol threads by the time this method is called. (The sequence of Framework calls into the payment cassette at cassette shutdown time is described in the Cassette Kit Programmer's Guide.)

This method should perform any final processing that may be necessary to completely close down the cassette and prepare for an eventual restart.


service

public abstract void service(CassetteRequest request,
                             CassetteResponse response)
                      throws ETillAbortOperation
Processes an inbound API or protocol request and generates an appropriate response. service performs or directs the majority of the work for which the cassette is responsible.

The relationship between the Framework and the cassette is similar to the relationship between a Java Servlet and a Server. Both of these interfaces revolve around a service method called by the Server/Framework and implemented by the Servlet/Cassette.

Parameters:
request - a CassetteRequest object which fully describes the request to be processed by the cassette.
response - a CassetteResponse object used by the cassette to respond to the original sender of the request and/or to the Framework.
Throws:
ETillAbortOperation - thrown if request processing fails. The primary and secondary return codes contained in the exception object will be returned to the original requestor in a response message by the Framework. The Framework will then continue processing of the next incoming request.

isAcceptPaymentSupported

public boolean isAcceptPaymentSupported()
Returns whether the acceptPayment command is supported by this cassette.
Returns:
boolean - true is the command is supported

isReceivePaymentSupported

public boolean isReceivePaymentSupported()
Returns whether the receivePayment command is supported by this cassette.
Returns:
boolean - true is the command is supported

getParameterValidationTable

public Hashtable getParameterValidationTable()
Obtain a parameter mapping table for checking syntax of an incoming request. The framework will use this mapping table in constructing the ParameterTable object to be passed to the cassette on other calls (e.g., in the Request object of the service method, on newCassetteOrder, etc.). The default behavior is to not perform any checking, resulting in a ParameterTable that includes all (uninterpreted) byte arrays that were passed. Cassette writers may override this method, returning a mapping table that is to be used for all syntax checking in construction of the ParameterTable.

getPaymentSystemName

public final String getPaymentSystemName()
Returns the name of the payment system (the name of the cassette) as specified in the ETCASSETTECFG table.
Returns:
String - the name of the cassette

getCassetteAdminObject

public final CassetteAdmin getCassetteAdminObject()
Returns the Cassette Administration object for the cassette.
Returns:
CassetteAdmin - the Cassette Administration object

getName

public final String getName()
Returns the debug name of this cassette.
Returns:
String - the debug name of the cassette

getReaderWriterMonitor

public final ReaderWriterMonitor getReaderWriterMonitor()
Cassettes should not override or call this method. The Framework calls this method to access this cassette's ReaderWriterMonitor, which is used to synchronize access to the cassette and its resources.
Returns:
ReaderWriterMonitor - this cassette's monitor.

isApprovalExpirationSupported

public boolean isApprovalExpirationSupported()
Cassettes that support this function should return true. The @38247 default is false
Returns:
true implies that the function us supported