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

Version:

$Revision: 1.44 $ $Date: 1997/04/04 13:28:00 $

Author:

N. Asokan ([email protected])

See Also:

createPurse, deletePurse, registerPurseClassName, PurseManagement, PurseManagementApp, PurseServices

_acl

Access control structure used by this purse

_address

Address of this purse.

_bank

The "bank" with which this purse is associated.

_brandName

Name of the brand.

_purseName

The name of this purse.

_purseRef

A handle to the purse reference object

_type

Purse type: one of pay-only, receive-only, pay-and-receive

DEF_BANK_HOST

Default parameters for purse configuration: host name of the bank

DEF_BANK_PORT

Default parameters for purse configuration: communication port of the bank

DEF_PORT

Default parameters for purse configuration: local communication port for value transfer transactions

DEF_PROT

Default parameters for purse configuration: communication protocol

TYPE_PAY_AND_RECEIVE

purse type flag indicating the purse can be used to pay and receive

TYPE_PAY_ONLY

purse type flag indicating the purse can be used to pay only

TYPE_RECEIVE_ONLY

purse type flag indicating the purse can be used to receive only (aka till)

Purse()

getAmount()

Get the current amount according to the local state maintained in the purse.

getBank()

Get the identity of the bank.

getBrandName()

Get the brand name

getListOfAllTXRHandles()

Return the list of archive handles for all the transaction records stored in the archive.

getListOfTXRHandles()

Return a copy of the list of transaction record handles.

getNewTXRHandle()

Return a unique archive handle to be used for a new transaction record.

getPaymentSystemName()

Get the name of the payment system.

getPrintableStatusInfo()

Return a hash table containing "attribute-value" pairs describing the status of the purse.

getPurseAddress()

Get the address to which payment protocol messages should be sent in order to interact with this purse.

getPurseName()

Gets the name of the purse Access to the attribute _purseName.

getPurseType()

Get the purse type

getUnlockedAmount()

Get the unlocked amount (to be depracated once the policy framework is in place)

getUserName()

Return the user name associated with this purse (This information is part of the purse address).

init()

Initialise the purse.

isCurrencySupported(Currency)

Check if a given currency is supported.

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.

isRegistered()

Has this purse been registered with its "bank"?

isSecurityServiceOffered(SecurityOption)

Check if a specific security service is offered.

myStreamSize()

Implementing the Streamable interface

offeredSecurityServices()

Get the list of security services offered.

readObject(StreamInputInterface)

Implementing the Streamable interface

registerWithBank()

Register or re-register a purse _with_ _the_ _bank_.

removeTXRHandle(AccessName)

Remove an archive handle from this purses list of handles.

setBank(PaymentEntity)

Set the identity of the bank.

setBrandName(String)

Set the brand name

setPurseAddress(PaymentEntity)

Set the address of this purse

• Used-by: setup() method

setPurseName(String)

Set the name of a purse Access to the attribute _purseName.

setPurseType(int)

Set the purse type

setUnlockedAmount(Amount)

Set the unlocked amount (to be depracated once the policy framework is in place)

setup(TinguinDisplay)

Setup the purse.

startTransaction()

Start a transaction on this purse.

startTransaction(PaymentTransactionRecord)

Start a transaction on this purse, using the specified transaction record.

store()

Commit this purse to the archive (by calling the externaliser methods defined by the Purse subclass).

supportedCurrency()

Return the list of supported currencies.

toString()

Now redefine toString for pretty printing

writeObject(StreamOutputInterface)

Implementing the Streamable interface

  protected String _brandName

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

  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.

  protected String _purseName

The name of this purse. Each purse must have a unique name.

  protected transient PurseReference _purseRef

A handle to the purse reference object

  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".

  protected PaymentAccessControlStructure _acl

Access control structure used by this purse

  public final int TYPE_PAY_AND_RECEIVE

purse type flag indicating the purse can be used to pay and receive

  public final int TYPE_PAY_ONLY

purse type flag indicating the purse can be used to pay only

  public final int TYPE_RECEIVE_ONLY

purse type flag indicating the purse can be used to receive only (aka till)

  protected int _type

Purse type: one of pay-only, receive-only, pay-and-receive

  protected final static String DEF_PROT

Default parameters for purse configuration: communication protocol

  protected final static String DEF_PORT

Default parameters for purse configuration: local communication port for value transfer transactions

  protected final static String DEF_BANK_PORT

Default parameters for purse configuration: communication port of the bank

  protected final static String DEF_BANK_HOST

Default parameters for purse configuration: host name of the bank

  public Purse()

  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.

• Pre-conditions: the purse has been created and configured properly (the setup() method should ensure all necessary configuration has been done before calling this method)
• Post-conditions: the purse can be initialised and used in a transaction.
• Used-by: the setup() method

Throws: PaymentServiceException

if registration failed

See Also:

getBank, init, setup

  public abstract Vector supportedCurrency()

Return the list of supported currencies.

Returns:

list of supported currencies (Vector of Currency objects)

See Also:

Currency, Vector

  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

  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

  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

  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

  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

  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

  public abstract PaymentTransaction startTransaction() throws PaymentServiceException

Start a transaction on this purse.

• Pre-conditions: purse has been initialised.
• Post-conditions: a new transaction associated with this purse has been created, along with a new transaction record; the archive handle for the new transaction record must be created using the getNewTXRHandle() method in PaymentTransactionRecord class.
• Used-by: users of payment block (e.g. transfer manager)

Returns:

a PaymentTransaction object

Throws: PaymentServiceException

when a transaction cannot be started.

See Also:

PaymentTransaction, getNewTXRHandle

  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.

• Pre-conditions: purse has been initialised,tr_rec exists and must be from the same adapter as this purse (i.e. if the adapter subclasses PaymentTransactionRecord, then tr_rec must be an object of the subclass)
• Used-by: PaymentTransactionRecord.resumeTransaction()

Parameters:

tr_rec - Transaction Record

Returns:

a PaymentTransaction object

Throws: PaymentServiceException

when a transaction cannot be started with the specified record

See Also:

resumeTransaction

  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.

• Used-by: users of payment block(e.g. transfer manager), payment manager.

Returns:

unique name for the payment system

  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

  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.

  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.

• Used-by: PurseManagementApp during purse configuration

Returns:

Hashtable containing printable attr-value pairs

  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

  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

  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

  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

  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.

• Used-by: various entities

Returns:

PaymentEntity object indicating the address

  public synchronized void setPurseAddress(PaymentEntity address)

Set the address of this purse

• Used-by: setup() method

Parameters:

address - PaymentEntity

Returns:

nothing

  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

  public synchronized void setBrandName(String brand_name)

Set the brand name

Parameters:

String - brand name

Returns:

nothing

  public String getBrandName()

Get the brand name

Returns:

string representing the brand name

  public synchronized void setPurseType(int type) throws IllegalArgumentException

Set the purse type

Parameters:

type - integer flag indicating type

  public int getPurseType()

Get the purse type

Returns:

flag representing purse type

  public String getPurseName()

Gets the name of the purse Access to the attribute _purseName. method defined in Purse.java

See Also:

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

  public PaymentEntity getBank()

Get the identity of the bank.

Returns:

unique name for the bank

  public synchronized void setBank(PaymentEntity address)

Set the identity of the bank.

Parameters:

address - PaymentEntity object with contact information for the bank

  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.

• Pre-condition: the archive handle of the purse is already initialised (this happens when the purse is created using the PaymentManager#createPurse)

Throws: ArchiveManException

if commit fails

See Also:

createPurse

  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.

• Pre-conditions: The payment block has already been initialised
• Other conditions: initialisation must be idempotent: it must be possible to repeatedly initialise the same purse without any problem. What exactly happens when a purse is intialised for a subsequent time is up to the adapter. It can simply return doing nothing or it can do something more (e.g. re-start any purse-specific threads).

Throws: PaymentServiceException

on failure

  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

  public String toString()

Now redefine toString for pretty printing

Returns:

string describing this purse

Overrides:

toString in class Object

  public void writeObject(StreamOutputInterface s) throws StreamIOException

Implementing the Streamable interface

Throws: StreamIOException

as usual

  public void readObject(StreamInputInterface s) throws StreamIOException

Implementing the Streamable interface

Throws: StreamIOException

as usual

  public int myStreamSize() throws StreamIOException

Implementing the Streamable interface

All Packages  Class Hierarchy  This Package  Previous  Next  Index