All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class semper.payment.Purse

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

public abstract class Purse
extends Object
implements Serializable
Generic abstraction of a payment system instance. A purse is a repository of information related an installed payment system. As with the PurseServices hierarchy, the Purse class hierarchy has a root class and model-specific subclasses of it. The root class defines a set of services. Some are in the form of abstract method definitions which need to be implemented by the Purse subclasses. For the rest, default implementations are provided; the subclasses may override them if needed.

Version:
$Revision: 1.64 $ $Date: 1998/08/04 11:51:52 $
Author:
N. Asokan ([email protected])
See Also:
createPurse, deletePurse, registerPurseClassName, PurseManagement, PurseManagementApp, PurseServices

Variable Index

 o _acl
Access control structure used by this purse
 o _address
Address of this purse.
 o _bank
The "bank" with which this purse is associated.
 o _brandName
Name of the brand.
 o _purseName
The name of this purse.
 o _purseRef
A handle to the purse reference object
 o _type
Purse type: one of pay-only, receive-only, pay-and-receive
 o DEF_BANK_HOST
Default parameters for purse configuration: host name of the bank
 o DEF_BANK_PORT
Default parameters for purse configuration: communication port of the bank
 o DEF_PORT
Default parameters for purse configuration: local communication port for value transfer transactions
 o DEF_PROT
Default parameters for purse configuration: communication protocol
 o LOGO_SIZE_NORMAL
Font size: normal
 o LOGO_SIZE_SMALL
Font size: reserved
 o LOGO_SIZE_TINY
Font size small: 50x12 pixels
 o TYPE_PAY_AND_RECEIVE
purse type flag indicating the purse can be used to pay and receive
 o TYPE_PAY_ONLY
purse type flag indicating the purse can be used to pay only
 o TYPE_RECEIVE_ONLY
purse type flag indicating the purse can be used to receive only (aka till)

Constructor Index

 o Purse()

Method Index

 o disable()
Disable an active purse.
 o doPurseOp(TinguinSession, String)
Perform a special purse operation.
 o getACHandle()
Return the access control structure object of this purse.
 o getAmount()
Get the current amount according to the local state maintained in the purse.
 o getAmounts()
Get the current amounts according to the local state maintained in the purse.
 o getBank()
Get the identity of the bank.
 o getBrandName()
Get the brand name
 o getListOfAllTXRHandles()
Return the list of archive handles for all the transaction records stored in the archive.
 o getListOfTXRHandles()
Return a copy of the list of transaction record handles.
 o getLogo()
Default get logo method (returns a normal size logo)
 o getLogo(int)
Get a logo of the specified size.
 o getNewTXRHandle()
Return a unique archive handle to be used for a new transaction record.
 o getPaymentSystemName()
Get the name of the payment system.
 o getPrintableStatusInfo()
Return a hash table containing "attribute-value" pairs describing the status of the purse.
 o getPurseAddress()
Get the address to which payment protocol messages should be sent in order to interact with this purse.
 o getPurseName()
Gets the name of the purse Access to the attribute _purseName.
 o getPurseOpsList()
Returns a vector containing names of supported special purse operations.
 o getPurseType()
Get the purse type
 o getUnlockedAmount()
Get the unlocked amount (to be depracated once the policy framework is in place)
 o getUserName()
Return the user name associated with this purse (This information is part of the purse address).
 o init()
Initialise the purse.
 o isCurrencySupported(Currency)
Check if a given currency is supported.
 o isEnabled()
Is the adapter of this Purse enabled for use? Each subclass of this class should override this method if the adapter is to be usable.
 o isRegistered()
Has this purse been registered with its "bank"?
 o isSecurityServiceOffered(SecurityOption)
Check if a specific security service is offered.
 o offeredSecurityServices()
Get the list of security services offered.
 o registerWithBank()
Register or re-register a purse _with_ _the_ _bank_.
 o removeTXRHandle(AccessName)
Remove an archive handle from this purses list of handles.
 o setBank(PaymentEntity)
Set the identity of the bank.
 o setBrandName(String)
Set the brand name
 o setPurseAddress(PaymentEntity)
Set the address of this purse
 o setPurseName(String)
Set the name of a purse Access to the attribute _purseName.
 o setPurseType(int)
Set the purse type
 o setUnlockedAmount(Amount)
Set the unlocked amount (to be depracated once the policy framework is in place).
 o setup(TinguinSession)
Setup the purse.
 o startTransaction()
Start a transaction on this purse.
 o startTransaction(PaymentTransactionRecord)
Start a transaction on this purse, using the specified transaction record.
 o store()
Commit this purse to the archive (by calling the externaliser methods defined by the Purse subclass).
 o supportedCurrency()
Return the list of supported currencies.
 o toString()
Now redefine toString for pretty printing

Variables

 o _brandName
 protected String _brandName
Name of the brand. The same payment system may support different brands of purses (e.g. SET/EuroCard)

 o _address
 protected PaymentEntity _address
Address of this purse. From this object, it must be possible to extract the address to which subsequent messages in the payment system protocol should be sent.

 o _purseName
 protected String _purseName
The name of this purse. Each purse must have a unique name.

 o _purseRef
 protected transient PurseReference _purseRef
A handle to the purse reference object

 o _bank
 protected PaymentEntity _bank
The "bank" with which this purse is associated. The bank is the entity that the user of this purse has to contact in order to map between electronic representation of money as seen by this purse and "real value".

 o _acl
 protected PaymentAccessControlStructure _acl
Access control structure used by this purse

 o TYPE_PAY_AND_RECEIVE
 public final int TYPE_PAY_AND_RECEIVE
purse type flag indicating the purse can be used to pay and receive

 o TYPE_PAY_ONLY
 public final int TYPE_PAY_ONLY
purse type flag indicating the purse can be used to pay only

 o TYPE_RECEIVE_ONLY
 public final int TYPE_RECEIVE_ONLY
purse type flag indicating the purse can be used to receive only (aka till)

 o _type
 protected int _type
Purse type: one of pay-only, receive-only, pay-and-receive

 o LOGO_SIZE_NORMAL
 public static final int LOGO_SIZE_NORMAL
Font size: normal

 o LOGO_SIZE_SMALL
 public static final int LOGO_SIZE_SMALL
Font size: reserved

 o LOGO_SIZE_TINY
 public static final int LOGO_SIZE_TINY
Font size small: 50x12 pixels

 o DEF_PROT
 protected static final String DEF_PROT
Default parameters for purse configuration: communication protocol

 o DEF_PORT
 protected static final String DEF_PORT
Default parameters for purse configuration: local communication port for value transfer transactions

 o DEF_BANK_PORT
 protected static final String DEF_BANK_PORT
Default parameters for purse configuration: communication port of the bank

 o DEF_BANK_HOST
 protected static final String DEF_BANK_HOST
Default parameters for purse configuration: host name of the bank

Constructors

 o Purse
 public Purse()

Methods

 o getACHandle
 public PaymentAccessControlStructure getACHandle()
Return the access control structure object of this purse. The access control structure object is expected to be initialised in the constructor of the purse. So the return value may be null, if the purse subclass did not initialise.

Returns:
PaymentAccessControlStructure
 o getLogo
 public URL getLogo()
Default get logo method (returns a normal size logo)

Returns:
a URL to the logo
 o getLogo
 public URL getLogo(int size_index)
Get a logo of the specified size. Returns null by default. Adapters can override this method.

Returns:
a URL to the logo
 o registerWithBank
 public abstract void registerWithBank() throws PaymentServiceException
Register or re-register a purse _with_ _the_ _bank_. Purse subclasses must provide an implementation of this method. "Registration" is defined as whatever one-time action it takes to make a new (or expired) purse usable. This is different from "initialisation" which is defined the action that needs to be performed to make a purse usable after it has been freshly read in from the archive. Typically initialisation is done every time SEMPER is started up whereas registration is done when a new purse is created.

Throws: PaymentServiceException
if registration failed
See Also:
getBank, init, setup
 o supportedCurrency
 public abstract Vector supportedCurrency()
Return the list of supported currencies.

Returns:
list of supported currencies (Vector of Currency objects)
See Also:
Currency, Vector
 o isCurrencySupported
 public abstract boolean isCurrencySupported(Currency currency)
Check if a given currency is supported.

Parameters:
currency - currency
Returns:
true if the indicated currency is supported by the purse in value transfer transactions; false otherwise.
See Also:
Currency
 o offeredSecurityServices
 public abstract Vector offeredSecurityServices()
Get the list of security services offered.

Returns:
list of supported security services (a Vector containing SecurityOption objects)
See Also:
SecurityOption
 o isSecurityServiceOffered
 public abstract boolean isSecurityServiceOffered(SecurityOption service)
Check if a specific security service is offered.

Parameters:
service - security service
Returns:
true of the indicated security service is supported by the purse in value transfer transactions; false otherwise.
See Also:
SecurityOption
 o getAmount
 public abstract Amount getAmount() throws AmountNotApplicable
Get the current amount according to the local state maintained in the purse. The value of the amount can be positive or negative. In account-based purses, this local view may not be the same as the view at the bank where the account is maintained. A separate method (getAmountFromBank) is available to get the amount from the bank, and in the process, update the local view.

If the purse supports multiple currencies, this amount will be the amount in the "primary" currency. If there is no single primary currency, the AmountNotApplicable will be thrown

Returns:
amount being held in the purse
Throws: AmountNotApplicable
on a purse where the current amount does not make sense (e.g. in certain credit card systems) or where there are multiple current amounts (in different currencies) associated with purse.
See Also:
getAmountFromBank
 o getAmounts
 public Vector getAmounts() throws AmountNotApplicable
Get the current amounts according to the local state maintained in the purse. The value of an amount can be positive or negative.

Returns:
Vector of amounts being held in the purse
Throws: AmountNotApplicable
on a purse where the current amount does not make sense (e.g. in certain credit card systems)
See Also:
getAmount
 o getUnlockedAmount
 public abstract Amount getUnlockedAmount()
Get the unlocked amount (to be depracated once the policy framework is in place)

Returns:
currently unlocked amount
See Also:
Amount
 o setUnlockedAmount
 public abstract void setUnlockedAmount(Amount amount)
Set the unlocked amount (to be depracated once the policy framework is in place). Any implementation must be therad-safe.

Parameters:
amount - new unlocked amount
Returns:
none
See Also:
Amount
 o startTransaction
 public abstract PaymentTransaction startTransaction() throws PaymentServiceException
Start a transaction on this purse.

Returns:
a PaymentTransaction object
Throws: PaymentServiceException
when a transaction cannot be started.
See Also:
PaymentTransaction, getNewTXRHandle
 o startTransaction
 public abstract PaymentTransaction startTransaction(PaymentTransactionRecord tr_rec) throws PaymentServiceException
Start a transaction on this purse, using the specified transaction record. This version can be used for resuming a transaction.

Parameters:
tr_rec - Transaction Record
Returns:
a PaymentTransaction object
Throws: PaymentServiceException
when a transaction cannot be started with the specified record
See Also:
resumeTransaction
 o getPaymentSystemName
 public abstract String getPaymentSystemName()
Get the name of the payment system. It must be possible to conduct a transaction between purses having the same payment system name. In some cases (e.g. credit cards), this name may contain the basic payment system name (e.g. iKP/SET) and the brand name (e.g. EuroCard). It is up to the adapter designer to decide what string is to be returned by this method. There isn't a corresponding setPaymentSystemName(); It is assumed that purses will initialise the payment system name attribute when they are created.

Returns:
unique name for the payment system
 o isEnabled
 public abstract boolean isEnabled()
Is the adapter of this Purse enabled for use? Each subclass of this class should override this method if the adapter is to be usable. For example, if this method returns false, the purse management application will not present this adapter as a possible choice during purse creation.

Before returning true, this method must ensure that all necessary libraries to use the adapter are available and loaded.

Returns:
boolean status
 o isRegistered
 public boolean isRegistered() throws NotApplicable
Has this purse been registered with its "bank"?

Returns:
s true if registered, false otherwise
Throws: NotApplicable
for purses of payment systems where registration does not make sense.
 o getPrintableStatusInfo
 public Hashtable getPrintableStatusInfo()
Return a hash table containing "attribute-value" pairs describing the status of the purse. Entries of the hashtable must be such that each key and value must be printable. A default implementation is provided here. Each subclass is free to override it.

Returns:
Hashtable containing printable attr-value pairs
 o getNewTXRHandle
 protected final AccessName getNewTXRHandle() throws ArchiveManException
Return a unique archive handle to be used for a new transaction record. The handle is added to the listofTXRHandles.

Returns:
a new AccessName object guaranteed to be unique
Throws: ArchiveManException
on failure
 o removeTXRHandle
 public final void removeTXRHandle(AccessName handle) throws PaymentServiceException, ArchiveManException
Remove an archive handle from this purses list of handles. TODO: This shouldn't be a public method; once we have a proper transaction record browser; we should make this friendly or protected.

Parameters:
handle - AccessName object of archive handle to be remvoed
Returns:
nothing
Throws: PaymentServiceException
if the purse knows nothing
Throws: ArchiveManException
if the updated list cannot be written to stable storage about this handle
 o getListOfTXRHandles
 public Vector getListOfTXRHandles()
Return a copy of the list of transaction record handles. Use removeTXRHandle() and getNewTXRHandle to actually manipulate the list.

Returns:
a Vector containing AccessName objects
See Also:
Vector, AccessName, getNewTXRHandle, removeTXRHandle
 o getListOfAllTXRHandles
 public static final Vector getListOfAllTXRHandles() throws ArchiveManException
Return the list of archive handles for all the transaction records stored in the archive.

Returns:
a Vector containing AccessName objects
Throws: ArchiveManException
if the list cannot be retrieved
 o getPurseAddress
 public PaymentEntity getPurseAddress()
Get the address to which payment protocol messages should be sent in order to interact with this purse. Since the return value is a PaymentEntity object, it also contains the "name" of the user to be associated with this purse.

Returns:
PaymentEntity object indicating the address
 o setPurseAddress
 public synchronized void setPurseAddress(PaymentEntity address)
Set the address of this purse

Parameters:
address - PaymentEntity
Returns:
nothing
 o getUserName
 public String getUserName() throws PaymentServiceException
Return the user name associated with this purse (This information is part of the purse address).

Returns:
string representing the user name associated with this purse, if it had been set using the setPurseAddress method.
Throws: PaymentServiceException
if user name is not set
See Also:
setPurseAddress
 o setBrandName
 public synchronized void setBrandName(String brand_name)
Set the brand name

Parameters:
String - brand name
Returns:
nothing
 o getBrandName
 public String getBrandName()
Get the brand name

Returns:
string representing the brand name
 o setPurseType
 public synchronized void setPurseType(int type) throws IllegalArgumentException
Set the purse type

Parameters:
type - integer flag indicating type
 o getPurseType
 public int getPurseType()
Get the purse type

Returns:
flag representing purse type
 o getPurseName
 public String getPurseName()
Gets the name of the purse Access to the attribute _purseName. method defined in Purse.java

See Also:
setPurseName
 o setPurseName
 public synchronized void setPurseName(String purse_name) throws PaymentServiceException
Set the name of a purse Access to the attribute _purseName. method defined in Purse.java

Throws: PaymentServiceException
if the new status cannot be sync'd
See Also:
getPurseName
 o getBank
 public PaymentEntity getBank()
Get the identity of the bank.

Returns:
unique name for the bank
 o setBank
 public synchronized void setBank(PaymentEntity address)
Set the identity of the bank.

Parameters:
address - PaymentEntity object with contact information for the bank
 o store
 public final synchronized void store() throws ArchiveManException
Commit this purse to the archive (by calling the externaliser methods defined by the Purse subclass). It should almost never required to override this method.

Throws: ArchiveManException
if commit fails
See Also:
createPurse
 o disable
 protected void disable() throws PaymentServiceException
Disable an active purse. This method should do whatever is necessary to disable a purse, typically prior to deletion. The default implementation does nothing. Sub-classes of this class can override the method to carry out any action specific to the payment system (e.g. killing dedicated threads running on behalf of this purse)

Throws: PaymentServiceException
if purse cannot be disabled
 o init
 public void init() throws PaymentServiceException
Initialise the purse. Purse subclasses that require any sort of initialisation should override this method to do whatever is necessary to initialise this purse on startup. These may include the reading of preferences, starting of any daemons etc. Dummy implementation here just so that adapter writers don't have to re-implement it if their purse needs no special initialisation.

Throws: PaymentServiceException
on failure
 o setup
 public abstract void setup(TinguinSession dis) throws PaymentServiceException
Setup the purse. Purse subclasses that require any sort of user-driven setup (e.g. port numbers, addresses of banks etc.) should do whatever is necessary by overriding this method. Any user interaction must be via the Tinguin session passed as parameter. This will be used by the PurseMangement class.

Each adapter should really re-implement it. See genericPurse::setup() for an example.

Parameters:
dis - an active Tinguin session
Returns:
nothing
Throws: PaymentServiceException
on misc. errors
 o toString
 public String toString()
Now redefine toString for pretty printing

Returns:
string describing this purse
Overrides:
toString in class Object
 o getPurseOpsList
 public Vector getPurseOpsList()
Returns a vector containing names of supported special purse operations. These names will be used by the purse management application to present a menu to the user. It is important that doPurseOp knows about all the commands defined by this method. If a subclass wants to add more methods, they should make sure to include the methods defined by this class.
  • Used-by: PurseManagement

    Returns:
    Vector containing names of operations
    See Also:
    doPurseOp
  •  o doPurseOp
     public boolean doPurseOp(TinguinSession dis,
                              String cmd) throws PaymentServiceException
    
    Perform a special purse operation.

    Parameters:
    cmd - name of the operation; this must be one of the strings returned by getPurseOpsList method. It is important that this method knows about all the operations defined by the getPurseOpsList method. If a subclass override this method in order to support more operations, it must pass unknown operations up, by calling the method on the superclass.
  • Used-by: PurseManagement
    a - tinguin session
    Returns:
    true/false: if we return true, the user will be presented again with the list of operations from getPurseOpsList; if we return false, the user will be returned to the main purse management menu. This implementation returns true.
    Throws: PaymentServiceException
    if the operation cannot be performed
    See Also:
    getPurseOpsList

  • All Packages  Class Hierarchy  This Package  Previous  Next  Index