|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.etill.framework.cassette.Cassette
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.
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 |
public Cassette()
Method Detail |
public void initialize(String name, String paymentSystem)
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).public abstract void initializeCassette() throws ETillAbortOperation
This is where cassettes should load native libraries, start background and timed work items, and perform other initialization items.
ETillAbortOperation
- Thrown if initialization fails; puts the
cassette in an invalid (unusable) state.public abstract void readCassetteConfig() throws ETillAbortOperation
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.
ETillAbortOperation
- Thrown if reading configuration data fails;
puts the cassette in an invalid (unusable) state.verifyConfig()
public abstract void verifyConfig() throws ETillAbortOperation
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.
ETillAbortOperation
- Thrown if verification fails;
puts the cassette in an invalid (unusable) state.readCassetteConfig()
public abstract Vector createComPoints() throws ETillAbortOperation
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:
ETillAbortOperation
- if any of the required ComPoint objects
cannot be instantiateddestroyComPoints()
public abstract void destroyComPoints() throws ETillAbortOperation
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.
ETillAbortOperation
- if any of the ComPoints cannot be closed
or deactivated.createComPoints()
public abstract CassetteOrder newCassetteOrder(Order anOrder, ParameterTable protocolData) throws ETillAbortOperation
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.
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.ETillAbortOperation
- thrown if cassette object cannot be built because
of some error conditionpublic abstract CassetteOrder resurrectCassetteOrder(Order anOrder) throws ETillAbortOperation
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.
anOrder
- the Framework Order object with which the
CassetteOrder is associated.ETillAbortOperation
- thrown if required data cannot be found or
retrieved from the database or if the object
cannot be instantiated for any other reason.public abstract CassetteTransaction newCassettePayment(Payment aPayment, ParameterTable protocolData) throws ETillAbortOperation
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.
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.ETillAbortOperation
- thrown if cassette object cannot be built
of some error conditionpublic abstract CassetteTransaction resurrectCassettePayment(Payment aPayment) throws ETillAbortOperation
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.
aPayment
- the Framework Payment object with which the
CassetteTransaction is associated.ETillAbortOperation
- thrown if required data cannot be found or
retrieved from the database or if the object
cannot be instantiated for any other reason.public abstract CassetteTransaction newCassetteCredit(Credit aCredit, ParameterTable protocolData) throws ETillAbortOperation
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.
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.ETillAbortOperation
- thrown if cassette object cannot be built
of some error conditionpublic abstract CassetteTransaction resurrectCassetteCredit(Credit aCredit) throws ETillAbortOperation
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.
aCredit
- the Framework Credit object with which the
CassetteTransaction is associated.ETillAbortOperation
- thrown if required data cannot be found or
retrieved from the database or if the object
cannot be instantiated for any other reason.public abstract CassetteBatch newCassetteBatch(Batch aBatch, ParameterTable protocolData) throws ETillAbortOperation
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.
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.ETillAbortOperation
- thrown if cassette object cannot be built
of some error conditionpublic abstract CassetteBatch resurrectCassetteBatch(Batch aBatch) throws ETillAbortOperation
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.
aBatch
- the Framework Batch object with which the
CassetteBatch is associated.ETillAbortOperation
- thrown if required data cannot be found or
retrieved from the database or if the object
cannot be instantiated for any other reason.public abstract ProtocolRequest createProtocolRequest(ETillConnection connection) throws ETillAbortOperation
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:
ETillAbortOperation
exception. If this exception
is thrown, the Framework will close the inbound connection without sending
any response message to the client.
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.
connection
- the ETillConnection object from which the
inbound protocol message can be read.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.ProtocolRequest
,
service(com.ibm.etill.framework.cassette.CassetteRequest, com.ibm.etill.framework.cassette.CassetteResponse)
,
ETillConnection.read()
public abstract void setMessageID(String id)
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.
id
- the String containing the cassette's ResourceBundle identifier.public abstract void start()
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.
public abstract void shutdown()
This method should perform any final processing that may be necessary to completely close down the cassette and prepare for an eventual restart.
public abstract void service(CassetteRequest request, CassetteResponse response) throws ETillAbortOperation
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.
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.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.public boolean isAcceptPaymentSupported()
public boolean isReceivePaymentSupported()
public Hashtable getParameterValidationTable()
public final String getPaymentSystemName()
public final CassetteAdmin getCassetteAdminObject()
public final String getName()
public final ReaderWriterMonitor getReaderWriterMonitor()
public boolean isApprovalExpirationSupported()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |