com.ibm.etill.framework.cassette
Class ProtocolRequest

java.lang.Object
  |
  +--com.ibm.etill.framework.cassette.CassetteRequest
        |
        +--com.ibm.etill.framework.cassette.ProtocolRequest
All Implemented Interfaces:
Serializable

public class ProtocolRequest
extends CassetteRequest

ProtocolRequest is the base class for all classes that represent incoming payment protocol messages. Each cassette is responsible for extending this class as needed to represent the protocol-specific request messages that its payment protocol expects from the outside world. As with any abstract class, the cassette's derived classes must implement all of the abstract methods in this class.

When the Commerce Payments Framework receives an incoming message on behalf of a cassette, it asks the cassette to create a ProtocolRequest object from the incoming message by calling the Cassette object's createProtocolRequest method. That method creates a new instance of a ProtocolRequest derivative class. During construction of that object, the Framework retrieves the associated Order (if any) from the cache and stores it in the new ProtocolRequest object. Once the new ProtocolRequest object is returned to the Framework, the Framework calls the Cassette object's service method to handle the request.

When ProtocolRequest objects are sent to a cassette for processing, the Framework will obtain the following locks while the request is being processed. This ensures thread safety and data integrity acrosss this request and all other operations being simultaneously performed within Commerce Payments:
ObjectLock TypeEffect
Cassette Read Prevents any significant configuration changes to the cassette
PayServer Read Prevents any significant configuration changes to Commerce Payments

Additionally, if an Order object is associated with this ProtocolRequest, these locks are also held:
ObjectLock TypeEffect
Order Write Prevents any other activity for the order
MerchantAdmin Read Prevents any significant configuration changes to the merchant
AccountAdmin Read Prevents a BATCHCLOSE operation from beginning. This lock is only obtained if the batchLock indicator is set (or defaulted) to true.

See Also:
com.ibm.etill.framework.cassette.ProtocolResponse, Cassette.createProtocolRequest(com.ibm.etill.framework.io.ETillConnection), Cassette.service(com.ibm.etill.framework.cassette.CassetteRequest, com.ibm.etill.framework.cassette.CassetteResponse), Serialized Form

Field Summary
protected  FrameworkAccountAdmin account
           
protected  FrameworkMerchantAdmin merchant
           
 
Fields inherited from class com.ibm.etill.framework.cassette.CassetteRequest
monitors, NoLock, ReadLock, WriteLock
 
Constructor Summary
protected ProtocolRequest(int token, com.ibm.etill.framework.io.ETillConnection connection, Cassette cassette)
          Constructs a ProtocolRequest object for the specified protocol-specific event and associates the object with the specified connection and cassette objects.
protected ProtocolRequest(int token, com.ibm.etill.framework.io.ETillConnection connection, String merchantNumber, String orderNumber)
          Constructs a ProtocolRequest object that is associated with a particular merchant and (optionally) order using the specified input values.
 
Method Summary
 AccountAdmin getAccount()
          Returns the AccountAdmin object associated with this request.
 com.ibm.etill.framework.payapi.Order getOrder()
          Returns the Order object associated with this request.
 void obtainLocks()
          Overrides the superclass's obtainLocks method to add extra conditional logic.
protected  void setBatchLock(boolean batchLock)
          Sets an internal flag to indicate whether or not this request object requires a lock on the associated Batch object to ensure thread safety and data integrity when the request is processed.
 
Methods inherited from class com.ibm.etill.framework.cassette.CassetteRequest
addMonitor, clearMonitors, getConnection, getToken, releaseLocks
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

merchant

protected FrameworkMerchantAdmin merchant

account

protected FrameworkAccountAdmin account
Constructor Detail

ProtocolRequest

protected ProtocolRequest(int token,
                          com.ibm.etill.framework.io.ETillConnection connection,
                          String merchantNumber,
                          String orderNumber)
                   throws com.ibm.etill.framework.payapi.ETillAbortOperation
Constructs a ProtocolRequest object that is associated with a particular merchant and (optionally) order using the specified input values. When a class derived from ProtocolRequest is constructed by the cassette, this constructor should be invoked by the subclass's constructor before any other work is done.
Parameters:
token - an int that represents the protocol-specific request type. This value must be determined by the subclass's constructor after reading all or part of the input message from the associated ETillConnection object.
connection - is the ETillConnection object over which the protocol message arrived at Commerce Payments. (The Framework passes this connection to the cassette object's createProtocolRequest method which is where ProtocolRequests objects are instantiated).
merchantNumber - is a String containing the number of the merchant to which this request is directed.
orderNumber - is a String that contains the number of the order with which this request is associated. If this value is null, then the request is assumed to not be associated with any particular order. If the value is not null, then the framework will ensure that the associated Order object exists in the cache before this constructor completes. If the order cannot be found, then an ETillAbortOperation exception will be thrown.
Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown if the associated Order object cannot be found.
See Also:
Cassette.createProtocolRequest(com.ibm.etill.framework.io.ETillConnection), ETillConnection

ProtocolRequest

protected ProtocolRequest(int token,
                          com.ibm.etill.framework.io.ETillConnection connection,
                          Cassette cassette)
Constructs a ProtocolRequest object for the specified protocol-specific event and associates the object with the specified connection and cassette objects. When a class derived from ProtocolRequest is constructed by the cassette, this constructor should be invoked by the subclass's constructor before any other work is done.
Parameters:
token - an int that represents the protocol-specific request type. This value must be determined by the subclass's constructor after reading all or part of the input message from the associated ETillConnection object.
connection - is the ETillConnection object over which the protocol message arrived at Commerce Payments. (The Framework passes this connection to the cassette object's createProtocolRequest method which is where ProtocolRequests objects are instantiated).
cassette - the Cassette object under which this request object is being built.
See Also:
Cassette.createProtocolRequest(com.ibm.etill.framework.io.ETillConnection), ETillConnection
Method Detail

setBatchLock

protected void setBatchLock(boolean batchLock)
Sets an internal flag to indicate whether or not this request object requires a lock on the associated Batch object to ensure thread safety and data integrity when the request is processed. The internal flag set by this method will be used later when the Framework calls this object's obtainLocks method.

If this method is not called, the default is to obtain the Batch lock while the request is being processed by the Cassette object's service method.

The batch lock should be held for any request that may cause a batch to be closed during the processing of that request. If this does not apply to a given protocol request, then this method should be called with a false value from within the subclass's constructor in order to improve performance of all current requests related to the associated batch.

Parameters:
batchLock - a boolean that indicates whether or not to obtain the batch lock. If this value is true, then the lock will be obtained. If the value is false, the batch lock will not be obtained. The default value for the request object is true.
Throws:
ETillCassetteException - thrown if batchLock is specified as true, but there is no Account object associated with this request. This indicates a logic error in the cassette.
See Also:
obtainLocks()

obtainLocks

public void obtainLocks()
Overrides the superclass's obtainLocks method to add extra conditional logic. See the class description above for details on the locks that are obtained for ProtocolRequest objects.

Cassettes should not have to call this method since the Framework calls it before invoking the Cassette object's service method.

Overrides:
obtainLocks in class CassetteRequest
See Also:
CassetteRequest.obtainLocks(), CassetteRequest.releaseLocks()

getOrder

public final com.ibm.etill.framework.payapi.Order getOrder()
Returns the Order object associated with this request.
Returns:
Order - a reference to the generic Order object with which this ProtocolRequest is associated. This value may be null.

getAccount

public final AccountAdmin getAccount()
Returns the AccountAdmin object associated with this request.
Returns:
AccountAdmin - a reference to the generic AccountAdmin object with which this ProtocolRequest is associated. This value may be null.