com.ibm.etill.framework.cassette
Class CassetteRequest

java.lang.Object
  |
  +--com.ibm.etill.framework.cassette.CassetteRequest
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
APIRequest, CassetteWorkItem, ProtocolRequest

public class CassetteRequest
extends Object
implements Serializable

CassetteRequest is the base class for all API and protocol request classes that can be passed to a cassette's service method for processing. Objects derived from CassetteRequests hold all the incoming information associated with the request.

The Commerce Payments Framework communicates with cassettes by asking them to service requests representing outside-world events requiring action. Outside-world events include API commands received from a merchant's shopping system and payment protocol messages received on behalf of a particular cassette. Every one of these requests is represented by an object whose type is derived from CassetteRequest. Study the CassetteRequest hierarchy to get the full picture of the types of requests serviced by cassettes.

The Commerce Payments Framework creates every API request object and asks the cassette to build protocol request objects by calling the Cassette object's createProtocolRequest method. Cassettes later service these request objects through the Cassette object's service method.

All CassetteRequests have a token representing the external event associated with the request, and an ETillConnection through which the event arrived. The data items specific to each request type is defined by the classes that extend CassetteRequest.

This class implemnts Serializable so that the request can be serialized and saved to the database if needed to accomplish restart.

See Also:
Cassette, CassetteResponse, Serialized Form

Field Summary
protected  Vector monitors
          monitors variable is not to be accessed by Cassettes
protected static int NoLock
          NoLock variable should not be accessed by Cassettes
protected static int ReadLock
          ReadLock variable should not be accessed by Cassettes
protected static int WriteLock
          WriteLock variable should not be accessed by Cassettes
 
Constructor Summary
protected CassetteRequest(int token, com.ibm.etill.framework.io.ETillConnection connection)
          This constructor should not be called directly by cassettes.
 
Method Summary
protected  void addMonitor(ReaderWriterMonitor monitor, int lock)
          Protected method that should never be called by cassettes.
protected  void clearMonitors()
          Protected method that should never be called by cassettes.
 com.ibm.etill.framework.io.ETillConnection getConnection()
          Returns the connection object through which this request object arrived at Commerce Payments.
 int getToken()
          Returns the event token associated with this request object.
 void obtainLocks()
          Acquires all locks necessary to protect the processing of this request from other concurrent activity within Commerce Payments.
 void releaseLocks()
          Releases the locks acquired through the obtainLocks method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

monitors

protected Vector monitors
monitors variable is not to be accessed by Cassettes

NoLock

protected static final int NoLock
NoLock variable should not be accessed by Cassettes

ReadLock

protected static final int ReadLock
ReadLock variable should not be accessed by Cassettes

WriteLock

protected static final int WriteLock
WriteLock variable should not be accessed by Cassettes
Constructor Detail

CassetteRequest

protected CassetteRequest(int token,
                          com.ibm.etill.framework.io.ETillConnection connection)
This constructor should not be called directly by cassettes. The Framework calls this constructor as the last in a chain of constructors to build a request containing the specified event token and ETillConnection object.
Parameters:
token - an int representing the external event. API event tokens are defined by the Framework in PaymentAPIConstants. Protocol event tokens are defined by a cassette, and known only to that cassette.
connection - an ETillConnection object through which the event arrived at the PaymentServer.
See Also:
PaymentAPIConstants
Method Detail

getToken

public final int getToken()
Returns the event token associated with this request object.

This token can be used as input to the cassette's finite state machine. It represents the outside world event that is being processed. Outside world events are primarily API commands and protocol messages.

Note: The event is also identified by the type of the request. The token is redundant information provided in a format that can be easily used as input to the cassette's FSM object.

Returns:
int - the event token

getConnection

public final com.ibm.etill.framework.io.ETillConnection getConnection()
Returns the connection object through which this request object arrived at Commerce Payments. Cassettes should call this method from their Cassette.createProtocolRequest method in order to read inbound protocol request messages.

Note: Since the Framework reads API command messages completely, cassettes should never use this method for API requests.

Note: The same ETillConnection object is referenced from both the CassetteRequest and CassetteResponse objects for each given request event. This means the ETillConnection object represents both the incoming data stream and the outgoing data stream.

Note: The method is useful for determining if the Request object was created as part of an API command, or if it was created so that it could be used in a CassetteWorkItem and scheduled at a later time. The method will return null, if it is the later.

Returns:
ETillConnection - the connection over which this request object arrived at Commerce Payments.

clearMonitors

protected void clearMonitors()
Protected method that should never be called by cassettes.

addMonitor

protected void addMonitor(ReaderWriterMonitor monitor,
                          int lock)
Protected method that should never be called by cassettes.

obtainLocks

public void obtainLocks()
Acquires all locks necessary to protect the processing of this request from other concurrent activity within Commerce Payments. Cassettes should not have to call this method since the Framework calls it before invoking the Cassette object's service method.

Commerce Payments locks a specific set of objects for each request type to ensure that all involved objects are synchronized properly to guarantee thread safety, data integrity and the best possible performance.

See Also:
releaseLocks()

releaseLocks

public void releaseLocks()
Releases the locks acquired through the obtainLocks method. As with that method, cassettes should not have to call this method directly since the Framework calls it after the cassette object's service method returns control.
See Also:
obtainLocks()