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

Version:

$Revision: 1.64 $ $Date: 1998/08/04 11:51:52 $

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

LOGO_SIZE_NORMAL

Font size: normal

LOGO_SIZE_SMALL

Font size: reserved

LOGO_SIZE_TINY

Font size small: 50x12 pixels

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()

disable()

Disable an active purse.

doPurseOp(TinguinSession, String)

Perform a special purse operation.

getACHandle()

Return the access control structure object of this purse.

getAmount()

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

getAmounts()

Get the current amounts 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.

getLogo()

Default get logo method (returns a normal size logo)

getLogo(int)

Get a logo of the specified size.

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.

getPurseOpsList()

Returns a vector containing names of supported special purse operations.

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.

offeredSecurityServices()

Get the list of security services offered.

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(TinguinSession)

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

 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

 public static final int LOGO_SIZE_NORMAL

Font size: normal

 public static final int LOGO_SIZE_SMALL

Font size: reserved

 public static final int LOGO_SIZE_TINY

Font size small: 50x12 pixels

 protected static final String DEF_PROT

Default parameters for purse configuration: communication protocol

 protected static final String DEF_PORT

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

 protected static final String DEF_BANK_PORT

Default parameters for purse configuration: communication port of the bank

 protected static final String DEF_BANK_HOST

Default parameters for purse configuration: host name of the bank

 public Purse()

 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

 public URL getLogo()

Default get logo method (returns a normal size logo)

Returns:

a URL to the logo

 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

 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.

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

 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

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

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

 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

 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)

• Pre-conditions: The purse must have been already initiated during PaymentManager.init
• Post-condition: The purse is disabled and can be safely deleted if necessary
• Used-by: PurseReference#deactivate

Throws: PaymentServiceException

if purse cannot be disabled

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

 public String toString()

Now redefine toString for pretty printing

Returns:

string describing this purse

Overrides:

toString in class Object

 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

 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