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:
Object | Lock Type | Effect |
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:
Object | Lock Type | Effect |
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
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 java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
merchant
protected FrameworkMerchantAdmin merchant
account
protected FrameworkAccountAdmin account
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
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.