All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface semper.payment.TPurseServices

public interface TPurseServices
This interface defines all the generic services that a payment system should typically provide. It is (for the time being, optionally) implemented by leaf subclasses of the PaymentTransaction class. The interface is defined for a token-based model in the style of GSS-API: the adapter/payment system perform no communication between peers of a transaction (e.g. payer and payee in a payment transaction) internally. Instead, they construct tokens and hand them to the calling application. Peer calling applications have a communication channel between them established a priori. The tokens passed up to the calling applications from the payment system are exchanged between the peer applications using this channel. The payment system is still responsible keeping protocol state. The application is responsible for inter-peer communication and fault-tolerance. The payment system may however perform any communication with third parties (e.g. communication between the payee and the acquirer during a credit-card payment transaction) within the payment system.

Each service described in the PurseServices interface has a corresponding 'start' method in this interface (e.g. "startPay()). Each such start method should:

  • initialise the transaction and construct the first token to be sent to the peer,
  • include the token in the TokenCapsule object returned to the caller. Subsequent steps in the protocol are carried out by calling the "processToken" method. Example Usage:
    Assuming that a purse "p" has been chosen and a ComPoint "c" has been opened for communication with the peer, a payment proceeds as follows: 
     	TokenCapsule mesg=null;
	TokenCapsule reply=null;
	tr = p.startTransaction();
	mesg = tr.startPay(<other params>,R_ANY,<other params>);
	for (;;) {
		Object token = mesg.getToken();
		if (token != null) {
			// We have an output token;  so send it to peer.
			c.write(token);
		}
		// Check if we should wait for a token from the peer
		if (!mesg.getTokenStatus() == TokenCapsule.S_CONTINUE_NEEDED)
                 break;
		Object r_token = c.read();
              reply = new TokenCapsule (r_token, .....);
		mesg = tr.processToken(reply);
 	}
     // Now check the status and deal with it
     PaymentTransactionState state = tr.getState();
     //...

    Version:
    $Revision: 1.4 $ $Date: 1998/03/12 10:53:11 $
    Author:
    N. Asokan ([email protected])
    See Also:
    PurseServices, ComPoint

    Variable Index

    o R_ANY
    Role: any (in this case, the adapter will assign a default role -- if the default assigned role is "responder", the TokenCapsule object returned should contain a null token indicating that the application has nothing to send in the current protocol step.
    o R_INITIATOR
    Role: initiator
    o R_RESPONDER
    Role: responder; the TokenCapsule object returned should contain a null token.

    Method Index

    o processToken(TokenCapsule)
    Process an intermediate token in a protocol.
    o startPay(PaymentEntity, Amount, Vector, int, String)
    Start the protocol for moving a specified amount from payer to payee.
    o startReceivePayment(PaymentEntity, Amount, Vector, int, String)
    Start the protocol for accepting an incoming payment from a payer.
    o startReversePayment(int, PaymentTransactionRecord)
    Start the protocol for reversal of a previously made payment.
    o startReverseReceivedPayment(int, PaymentTransactionRecord)
    Process request for reversing a previously received payment.

    Variables

    o R_ANY 
     public static final int R_ANY
    Role: any (in this case, the adapter will assign a default role -- if the default assigned role is "responder", the TokenCapsule object returned should contain a null token indicating that the application has nothing to send in the current protocol step.

    o R_INITIATOR 
     public static final int R_INITIATOR
    Role: initiator

    o R_RESPONDER 
     public static final int R_RESPONDER
    Role: responder; the TokenCapsule object returned should contain a null token.

    Methods

    o startPay 
     public abstract TokenCapsule startPay(PaymentEntity payee,
                                       Amount amount,
                                       Vector options,
                                       int role,
                                       String ext_ref) throws PaymentServiceException
    Start the protocol for moving a specified amount from payer to payee.

    Parameters:
    payee - Object containing necessary information to identify the recipient
    amount - Amount to be moved
    options - List of options for the transaction (Vector of SecurityOption objects)
    role - integer flag indicating the role of this player
    ext_ref - External reference string
    Returns:
    TokenCapsule object containing the first token to be sent to peer.
    Throws: PaymentServiceException
    for misc errors
    See Also:
    receivePayment, startReceivePayment, SecurityOption
    o startReceivePayment 
     public abstract TokenCapsule startReceivePayment(PaymentEntity payer,
                                                  Amount amount,
                                                  Vector options,
                                                  int role,
                                                  String ext_ref) throws PaymentServiceException
    Start the protocol for accepting an incoming payment from a payer.

    Parameters:
    payer - Object containing necessary information to identify the payer
    options - List of options for the transaction (Vector of SecurityOption objects)
    amount - Amount to be moved
    role - integer flag indicating the role of this player
    ext_ref - External reference string
    Returns:
    TokenCapsule object containing the first token to be sent to peer.
    Throws: PaymentServiceException
    for misc errors
    See Also:
    pay, startPay, SecurityOption
    o startReversePayment 
     public abstract TokenCapsule startReversePayment(int role,
                                                  PaymentTransactionRecord ref) throws PaymentServiceException
    Start the protocol for reversal of a previously made payment.

    Parameters:
    ref - PaymentTransaction object corresponding to the payment to be reversed.
    role - integer flag indicating the role of this player
    Returns:
    TokenCapsule object containing the first token to be sent to peer.
    Throws: PaymentServiceException
    for misc errors
    See Also:
    pay
    o startReverseReceivedPayment 
     public abstract TokenCapsule startReverseReceivedPayment(int role,
                                                          PaymentTransactionRecord ref) throws PaymentServiceException
    Process request for reversing a previously received payment.

    Parameters:
    ref - PaymentTransaction object corresponding to the payment to be reversed.
    role - integer flag indicating the role of this player
    Returns:
    TokenCapsule object containing the first token to be sent to peer.
    Throws: PaymentServiceException
    for misc errors
    See Also:
    receivePayment
    o processToken 
     public abstract TokenCapsule processToken(TokenCapsule mesg) throws PaymentServiceException
    Process an intermediate token in a protocol. TODO: More explanation.

    Parameters:
    mesg - TokenCapsule containing the token sent by the peer
    Returns:
    TokenCapsule object containing the next token to be sent to the peer.
    Throws: PaymentServiceException
    on misc. errors 
    All Packages  Class Hierarchy  This Package  Previous  Next  Index