Class semper.payment.Purse
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class semper.payment.Purse

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

public class Purse
extends Object
implements Streamable
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.44 $ $Date: 1997/04/04 13:28:00 $
Author:
N. Asokan (aso@zurich.ibm.com)
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 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 getAmount()
Get the current amount 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 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 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 myStreamSize()
Implementing the Streamable interface
 o offeredSecurityServices()
Get the list of security services offered.
 o readObject(StreamInputInterface)
Implementing the Streamable interface
 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(TinguinDisplay)
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
 o writeObject(StreamOutputInterface)
Implementing the Streamable interface

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 DEF_PROT
  protected final static String DEF_PROT
Default parameters for purse configuration: communication protocol
 o DEF_PORT
  protected final static String DEF_PORT
Default parameters for purse configuration: local communication port for value transfer transactions
 o DEF_BANK_PORT
  protected final static String DEF_BANK_PORT
Default parameters for purse configuration: communication port of the bank
 o DEF_BANK_HOST
  protected final static String DEF_BANK_HOST
Default parameters for purse configuration: host name of the bank

Constructors

 o Purse
  public Purse()

Methods

 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.
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)
See Also:
getAmountFromBank
 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 synchronized abstract void setUnlockedAmount(Amount amount)
Set the unlocked amount (to be depracated once the policy framework is in place)
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 final static 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 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 void setup(TinguinDisplay 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.

The implementation here is mostly intended as an example. Each adapter should really re-implement it. The default implementation provides for the following:
- setting bank information (host, port number, protocol)
- setting user information (user name, port number and protocol
the latter two are relevant only for purses that receive payments)
- setting purse name
- registration (registration will simply invoke the registerWithBank() method of the purse.

Parameters:
dis - an active Tinguin session
Returns:
nothing
Throws: PaymentServiceException
on misc. errors
See Also:
createPurses
 o toString
  public String toString()
Now redefine toString for pretty printing
Returns:
string describing this purse
Overrides:
toString in class Object
 o writeObject
  public void writeObject(StreamOutputInterface s) throws StreamIOException
Implementing the Streamable interface
Throws: StreamIOException
as usual
 o readObject
  public void readObject(StreamInputInterface s) throws StreamIOException
Implementing the Streamable interface
Throws: StreamIOException
as usual
 o myStreamSize
  public int myStreamSize() throws StreamIOException
Implementing the Streamable interface

All Packages  Class Hierarchy  This Package  Previous  Next  Index