All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class semper.payment.PurseSelection

java.lang.Object
   |
   +----semper.payment.PurseSelection

public class PurseSelection
extends Object
Purse selection provides services for selecting a purse for value transfer transactions. The selection is based on Usage>: TBD

Version:
$Revision: 1.12 $ $Date: 1998/08/25 13:31:05 $
Author:
N. Asokan (aso@zurich.ibm.com)

Variable Index

 o FREE_CHOICE
Choice type flag to use during payment system selection negotiation: this value makes no restrictions on what the peer can choose.
 o INT_ASK_USER
Cardinality of 'interact' preference for PrefGroup PurseSelection#PREFS_PURSESEL_ASKUSER
 o INT_PICK_ANY
Cardinality of 'do not interact' preference for PrefGroup PurseSelection#PREFS_PURSESEL_ASKUSER
 o PF_PURSESEL_ASKUSER
Name of preference group for deciding whether to interact with the user during purse selection
 o PG_PURSESEL
Name of the purse selection preference group
 o PREFS_PURSESEL_NEG
Unused
 o SELECT_PS_AND_SET_AMOUNT
Choice type flag to use during payment system selection negotiation: this value makes no restrictions on what the peer can do: he can select a subset of the proposed list of payment systems and reset the amount associated with each selected payment system.
 o SELECT_PS_ONLY
Choice type flag to use during payment system selection negotiation: this value allows the peer to select only the payment system name.

Constructor Index

 o PurseSelection(PaymentEntity, String, Amount, ServiceType, Vector, Vector, Vector)
Constructor

Method Index

 o choosePS(ComPoint)
Receive a proposed list of payment systems and corresponding amounts from the peer along with a choice_type flag.
 o confirmPurse(ComPoint)
Receive a confirmation request from the peer containing a single payment system and a corresponding amount.
 o getAmount()
 o getCandidatePurseNames()
 o getCandidatePurses()
Return the list of selected purses at the current state
 o getChoiceType()
 o getLocalAlias()
 o getOptions()
 o getPeerAddress()
 o getPeerValTransAddress()
Return the address of the peer for value transfer
 o getPIMList()
 o getPSList()
 o getSelectedPurse()
 o getServiceType()
 o init()
Initialise the PurseSelection class
  • if we are a server, register an address with the comm.
     o isInitialised()
    Check the initialisation status
     o requestChoiceOfPS(ComPoint)
    Propose a list of payment systems and corresponding amounts to the peer and request them to choose a subset of the payment systems.
     o requestPurseConfirmation(ComPoint)
    Having selected a purse, request confirmation from the peer.
     o selectCandidatePurses()
    Select a set of candidate purses locally for a transaction specified by the current state.
     o selectPayingPurse(PaymentEntity, String, Amount, Vector, Vector, Vector, String)
    A specific way of selecting a purse for payment.
     o selectPurse()
    Select a single from the input list restricted by the results of negotiations which is also given as input.
     o selectPurse(PaymentEntity, ServiceType, Vector)
    Select a single purse from the input list.
     o selectReceivingPurse(PaymentEntity, String, Amount, Vector, Vector, Vector, String)
    A specific way of selecting a purse for receiving payment.
     o setCandidatePurses(Vector)
    Set the list of candidate purses to the input list purse_refs.
     o setChoiceType(int)
     o setPIMList(Vector)
     o startSelectPayingPurse(ComPoint)
     o startSelectReceivingPurse(ComPoint)

Variables

 o PG_PURSESEL
 public static final String PG_PURSESEL
Name of the purse selection preference group

 o PF_PURSESEL_ASKUSER
 public static final String PF_PURSESEL_ASKUSER
Name of preference group for deciding whether to interact with the user during purse selection

 o PREFS_PURSESEL_NEG
 public static final String PREFS_PURSESEL_NEG
Unused

 o INT_ASK_USER
 public static final int INT_ASK_USER
Cardinality of 'interact' preference for PrefGroup PurseSelection#PREFS_PURSESEL_ASKUSER

 o INT_PICK_ANY
 public static final int INT_PICK_ANY
Cardinality of 'do not interact' preference for PrefGroup PurseSelection#PREFS_PURSESEL_ASKUSER

 o FREE_CHOICE
 public static final int FREE_CHOICE
Choice type flag to use during payment system selection negotiation: this value makes no restrictions on what the peer can choose.

See Also:
requestChoiceOfPS, choosePS
 o SELECT_PS_AND_SET_AMOUNT
 public static final int SELECT_PS_AND_SET_AMOUNT
Choice type flag to use during payment system selection negotiation: this value makes no restrictions on what the peer can do: he can select a subset of the proposed list of payment systems and reset the amount associated with each selected payment system. Note that resetting of amount is useful in situations where the amount is dependent on the payment system used for the value transfer.

See Also:
requestChoiceOfPS, choosePS
 o SELECT_PS_ONLY
 public static final int SELECT_PS_ONLY
Choice type flag to use during payment system selection negotiation: this value allows the peer to select only the payment system name.

See Also:
requestChoiceOfPS, choosePS

Constructors

 o PurseSelection
 public PurseSelection(PaymentEntity peer,
                       String my_alias,
                       Amount amount,
                       ServiceType service_type,
                       Vector PS_list,
                       Vector purse_name_list,
                       Vector options)
Constructor

Parameters:
peer - the entity with whom we plan to engage in a transaction using one of the selected purses
my_alias - the name by which I am known to the peer; only those purses that have this string as the "username" will be chosen (some purses can have wildcard usernames?)
amount - the amount we tentatively plan to transfer
service_type - flag indicating the type of service for which the purse is being selected. Use the enumerations defined in the ServiceType class hierarchy.
PS_list - list of acceptable payment systems (Vector of Strings)
purse_name_list - list of names of acceptable purses (Vector of Strings); if this is null, all available purses are treated as candidates.
options - list of security attributes required for the proposed transaction (Vector of SecurityOption objects)
See Also:
PurseReference, SecurityOption, PaymentEntity

Methods

 o getOptions
 public Vector getOptions()
 o getLocalAlias
 public String getLocalAlias()
 o getCandidatePurseNames
 public Vector getCandidatePurseNames()
 o getPeerValTransAddress
 public PaymentEntity getPeerValTransAddress()
Return the address of the peer for value transfer

Returns:
PaymentEntity address of the peer for value transfer
 o getCandidatePurses
 public Vector getCandidatePurses()
Return the list of selected purses at the current state

Returns:
a Vector of Purse reference objects
See Also:
PurseReferences
 o getSelectedPurse
 public PurseReference getSelectedPurse()
 o getPIMList
 public Vector getPIMList()
 o getChoiceType
 public int getChoiceType()
 o getPSList
 public Vector getPSList()
 o getAmount
 public Amount getAmount()
 o getPeerAddress
 public PaymentEntity getPeerAddress()
 o getServiceType
 public ServiceType getServiceType()
 o setPIMList
 public void setPIMList(Vector pim_list) throws IllegalArgumentException
 o setChoiceType
 public void setChoiceType(int choice_type) throws IllegalArgumentException
 o setCandidatePurses
 public void setCandidatePurses(Vector purse_refs) throws IllegalArgumentException
Set the list of candidate purses to the input list purse_refs. The input list is a Vector of PurseReference objects.

Throws: IllegalArgumentException
if the input list contains anything other than PurseReference objects.
 o init
 public static void init() throws PaymentServiceException
Initialise the PurseSelection class
  • if we are a server, register an address with the comm. manager to listen for incoming negotiation requests.
  • do other initialisation
  • Pre-conditions
    • SEMPER blocks log, configuration, archive, preferences, tinguin, and payment must be already initialised
  • Post-conditions:
    • Payment block is ready for use
  • Used-by: typically only the SEMPER bootstrap process needs to use this.

    Returns:
    nothing
    Throws: PaymentServiceException
    if initialisation failed
  •  o isInitialised
     public boolean isInitialised()
    
    Check the initialisation status

    Returns:
    false if completely uninitialised; true otherwise
     o selectCandidatePurses
     public void selectCandidatePurses() throws PaymentServiceException
    
    Select a set of candidate purses locally for a transaction specified by the current state. There is no negotiation with peer or user involved in this method. User interaction _may_ be involved. For now, all parameters in the current state, except PSList are ignored. The candidate list can be retrieved at any time using the getCandidatePurses method.

    Returns:
    nothing
    Throws: PaymentServiceException
    for miscellaneous errors
    See Also:
    getCandidatePurses
     o selectPurse
     public static PurseReference selectPurse(PaymentEntity peer,
                                              ServiceType service_type,
                                              Vector candidate_purserefs) throws NoSuitablePurse
    
    Select a single purse from the input list. This selection will be eventually based on:
    • preferences,
    • interaction with the user,
    • etc.
    There is no negotiation with the peer involved in this method. For now, it is simple and stupid: select the first element of the list.

    Parameters:
    peer - the entity with whom we plan to engage in a transaction using one of the selected purses
    service_type - flag indicating the type of service for which the purse is being selected. Use the enumerations defined in the ServiceType class hierarchy.
    candidate_purserefs - list of candidate purses (Vector of PurseReference objects)
    Returns:
    the PurseReference object corresponding to the selected purse.
    Throws: NoSuitablePurse
    if no suitable purse is found
     o selectPurse
     public void selectPurse() throws NoSuitablePurse, PaymentServiceException
    
    Select a single from the input list restricted by the results of negotiations which is also given as input. There is no direct negotiation with the peer involved in this method. This selection will be eventually based on:
    • preferences,
    • interaction with the user,
    • etc.
    For now, it is simple and stupid: depending on how the user has set her preferences, either it asks the user or it makes an arbitrary choice.

    Parameters:
    peer - the entity with whom we plan to engage in a transaction using one of the selected purses
    service_type - flag indicating the type of service for which the purse is being selected. Use the enumerations defined in the ServiceType class hierarchy.
    amount - the amount to be transferred in the proposed transaction. If the selected item from the PIM_shortlist has an different amount, then the value of this parameter will be reset accordingly. The caller should therefore examine the value of this parameter on return.
    PIM_shortlist - Vector of PaymentInformationMessage representing the negotiated shortlist
    candidate_purses - a Vector of PurseReference objects representing the candidate purses
    Returns:
    the PurseReference object corresponding to the selected purse.
    Throws: PaymentServiceException
    for misc. errors
    Throws: NoSuitablePurse
    if no suitable purse is found
    See Also:
    PaymentInformationMessage
     o requestChoiceOfPS
     public void requestChoiceOfPS(ComPoint c) throws ComPointException, PaymentServiceException
    
    Propose a list of payment systems and corresponding amounts to the peer and request them to choose a subset of the payment systems. The choice_type flag indicates how the peer should carry out his choice. In particular, if the peer is also allowed to set a different amount than the one proposed, the value of the amount parameter will be updated on return.

    Parameters:
    c - an already open communication channel PIM_list proposal list in the form of a Vector of PaymentInformationMessage objects sets a Vector of PaymentInformationMessage objects representing the payment systems and corresponding amounts chosen by the peer
    Throws: ComPointException
    on communication errors
    Throws: PaymentServiceException
    on miscellaneous errors
    See Also:
    choosePS, MessageListHead, PaymentInformationMessage
     o choosePS
     public void choosePS(ComPoint c) throws PaymentServiceException, ComPointException
    
    Receive a proposed list of payment systems and corresponding amounts from the peer along with a choice_type flag. Choose a subset of the payment systems based on the input list of payment systems and the peer's proposals.

    Parameters:
    c - an already open communication channel
    choice_type - flag indicating restrictions that the peer can impose on us for the choice. It can be one of:
    • FREE_CHOICE
    • SELECT_PS_AND_SET_AMOUNT
    • SELECT_PS_ONLY
    if it is anything other than FREE_CHOICE, the peer's choice_type should agree with our choice_type
    PIM_list - our proposals list in the form of a Vector of PaymentInformationMessage objects
    Returns:
    a Vector of PaymentInformationMessage objects representing the payment systems and corresponding amounts chosen by the peer
    Throws: ComPointException
    on communication errors
    Throws: PaymentServiceException
    on miscellaneous errors
    See Also:
    requestChoiceOfPS, PaymentInformationMessage
     o requestPurseConfirmation
     public boolean requestPurseConfirmation(ComPoint c) throws ComPointException, PaymentServiceException
    
    Having selected a purse, request confirmation from the peer. Exchange all parameters required for subsequent payment: e.g. the address to which payment protocol messages should be sent.

    Parameters:
    c - an already open channel
    my_purse - reference to the selected purse
    short_list - the short list (a Vector of PaymentInformationMessage objects) used earlier during the purse selection process. The amount will be taken from the first element in this short_list that corresponds to the chosen purse
    peer - address of the peer entity to which subsequent payment system protocol messages should be sent. This negotiation is currently not supported.
    Returns:
    true/false indicating whether the confirmation succeeded
    Throws: ComPointException
    for communication errors
    Throws: PaymentServiceException
    for misc errors
    See Also:
    PaymentInformationMessage, confirmPurse
     o confirmPurse
     public void confirmPurse(ComPoint c) throws ComPointException, PaymentServiceException
    
    Receive a confirmation request from the peer containing a single payment system and a corresponding amount. Decide if it is an acceptable choice based on our own input parameters. Choose a single purse from the list available to us. Set any other parameters necessary for subsequent protocol flows inside the chosen payment system.

    Parameters:
    c - an already open channel
    service_type - flag indicating the type of service for which the purse is being selected. Use the enumerations defined in the ServiceType class hierarchy.
    amount - location to return the value of the agreed upon amount
    PIM_list - list of acceptable combinations in the form of a Vector of PaymentInformationMessage objects.
    candidate_purses - list of candidate purses
    peer - location to return the address to which subsequent payment system protocol messages should be sent.
    Throws: ComPointException
    for communication errors
    Throws: PaymentServiceException
    for misc errors
    See Also:
    requestPurseConfirmation, PaymentInformationMessage
     o selectPayingPurse
     public static PurseSelection selectPayingPurse(PaymentEntity peer,
                                                    String my_alias,
                                                    Amount amount,
                                                    Vector PS_list,
                                                    Vector purse_name_list,
                                                    Vector options,
                                                    String ext_ref) throws NoSuitablePurse, PaymentServiceException, ComPointException
    
    A specific way of selecting a purse for payment. There are many ways in which the various purse selection methods (both local and negotiated) can be combined. This method implements one such combination with certain policy assumptions for selecting a purse for payment. These assumptions are:
    • the payee is allowed to choose a subset of the payment systems that we propose _and_ to reset the amount we propose to pay.

    Parameters:
    peer - entity to which we propose to make a payment
    my_alias - the alias by which I am known to the peer
    amount - the amount we propose to pay
    PS_list - the payment systems we are prepared to use. This parameter is a Vector of Strings. If it is null, all payment systems are considered to be candidates.
    purse_name_list - the list of purses that we are prepared to use (this parameter is not used yet). This parameter os a Vector of Strings. If it is null, all purses are considered to be candidates.
    options - list of security options required. This parameter is a Vector SecurityOption objects.
    ext_ref - external reference string
    Returns:
    reference to the purse selection transaction from which the selected purse can be extracted
    Throws: NoSuitablePurse
    if a suitable purse cannot be found
    Throws: ComPointException
    on communication errors.
    Throws: PaymentServiceException
    on misc. errors.
    See Also:
    selectReceivingPurse, SecurityOption
     o startSelectPayingPurse
     public TokenCapsule startSelectPayingPurse(ComPoint c) throws PaymentServiceException, ComPointException
    
     o selectReceivingPurse
     public static PurseSelection selectReceivingPurse(PaymentEntity peer,
                                                       String my_alias,
                                                       Amount amount,
                                                       Vector PS_list,
                                                       Vector purse_name_list,
                                                       Vector options,
                                                       String ext_ref) throws NoSuitablePurse, PaymentServiceException, ComPointException
    
    A specific way of selecting a purse for receiving payment. There are many ways in which the various purse selection methods (both local and negotiated) can be combined. This method implments one such combination with certain policy assumptions for selecting a purse for receiving payment. These assumptions are:
    • the payee is allowed to choose a subset of the payment systems that we propose _and_ to reset the amount we propose to pay.

    Parameters:
    peer - entity from whom we propose to receive a payment
    my_alias - String indicating the name by which we want to be known to the peer.
    amount - the amount we propose to receive
    PS_list - the payment systems we are prepared to use. This parameter is a Vector of Strings. If it is null, all payment systems are considered to be candidates.
    purse_name_list - the list of purses that we are prepared to use (this parameter is not used yet). This parameter os a Vector of Strings. If it is null all purses are considered to be candidates.
    options - list of security options required. This parameter is a Vector SecurityOption objects.
    ext_ref - external reference string sent by the peer
    Returns:
    reference to the purse selection transaction, from the selected purse can be extracted.
    Throws: ComPointException
    on communication errors.
    Throws: NoSuitablePurse
    if a suitable purse cannot be found
    Throws: PaymentServiceException
    on misc. errors.
    See Also:
    selectPayingPurse, SecurityOption
     o startSelectReceivingPurse
     public TokenCapsule startSelectReceivingPurse(ComPoint c) throws PaymentServiceException, ComPointException
    

    All Packages  Class Hierarchy  This Package  Previous  Next  Index