ATM Problem Operation Description Forms

NOTE: The prototypes appearing in these operation description forms reflect the C++ implementation. With one exception, the corresponding Java methods have the same parameters, but the prototypes differ slightly due to syntactic differences between C++ and Java. In particular:

C++ accessor methods have the keyword const at the end of the prototype, to specify that the method does not alter the object to which it is applied. Java lacks a corresponding feature, and so this is omitted in the Java prototypes.
The C++ implementation uses several enumeration types (Status::Code, Bank::AccountType, and several used internally within a class). Since Java has no enumeration types, the corresponding parameters, variables, and return types are declared as ints, and the enumeration values are declared within the appropriate class as static final ints.
The type C++ calls bool is called boolean in Java.
In the C++ implementation, method parameters that are character strings are declared const char *. In Java, the built-in type String is used for this purpose. (Note: most C++ class libraries have some sort of string class, but this was not used in the C++ implementation for portability reasons. When the ANSI C++ class library standard standardizes and all compilers support it, the use of the String type would be preferable in C++ as well.)
In C++, when objects are passed as parameters to a method, they may be passed either by value or by reference ("&" between type and parameter name). In Java, objects are always passed by reference, and "&" never appears in a prototype.
In the Java implementation, some methods are declared synchronized. This is needed if they contain a wait() call to suspend the main thread until some GUI event occurs. There is nothing similar in C++, and in any case the C++ implementation does not use a GUI.

Operations of class ATM - which has the following components:
Operations of class Session
Operations of class Transaction and its subclasses
Operations of class Bank

[ Intro ] [ Requirements ] [ Domain Objects ] [ Use Cases ] [ State Diagram ] [ Interaction Diagram ]
[ CRC Cards ] [ Class Diagram ] [ Class Desc. Forms ] [ Operation Desc. Forms ] [ Code ] [ Executable ]

Copyright © 1996, 1997, 1998 - Russell C. Bjork. Permission for non-commercial reproduction for educational use is hereby granted; all other rights are reserved.

Operations of class ATM

ATM::	ATM
Prototype	ATM(int number, const char * location, Bank & bank)
Purpose	Constructor
Receives	number - the ATM's number
	location - the ATM's location
	bank - the ATM's Bank
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

ATM::	startupOperation
Prototype	Money startupOperation()
Purpose	Perform startup tasks when the ATM's switch is turned on
Receives
Returns	Initial cash in the cash dispenser
Remarks	Waits for operator to turn switch on. Sets _state to RUNNING. Asks operator how much cash is in the dispenser.

[ View C++ implementation ] [ View Java implementation ]

ATM::	serviceCustomers
Prototype	void serviceCustomers(Money initialCash)
Purpose	Run the ATM until the switch is turned off
Receives	initialCash - amount of money in cash dispenser to start
Returns
Remarks	Creates a new Session when a readable card is inserted. Polls operator switch when no session is active, sets _state to STOPPED and exits when switch is turned off.

[ View C++ implementation ] [ View Java implementation ]

ATM::	getPIN
Prototype	int getPIN() const
Purpose	Get personal identification number (PIN) from customer
Receives
Returns	PIN entered by customer
Remarks	Displays request on screen, then reads PIN from keyboard. PIN digits are echoed as asterisks to preserve secrecy.

[ View C++ implementation ] [ View Java implementation ]

ATM::

getMenuChoice

Prototype

int getMenuChoice(

const char * whatToChoose,
int numItems,
const char * items[]) const

Purpose

Get choice from a menu of options from customer

Receives

whatToChoose - explanation of what customer is choosing
numItems - number of items to choose from
items - descriptions of individual items

Returns

Customer choice (1 .. numItems) or 0 if cancelled

Remarks

Displays list of choices, then requests customer to choose
one using keyboard.

[ View C++ implementation ] [ View Java implementation ]

ATM::	getAmountEntry
Prototype	Money getAmountEntry() const
Purpose	Ask customer to enter an amount of money for a deposit, etc.
Receives
Returns	Amount of money customer entered.
Remarks	Asks user to enter amount, then reads amount typed at keyboard.

[ View C++ implementation ] [ View Java implementation ]

ATM::	checkIfCashAvailable
Prototype	bool checkIfCashAvailable(Money amount) const
Purpose	Determine if cash dispenser has enough cash left to satisfy a withdrawl request
Receives	amount - amount desired
Returns	True iff requested amount is available.
Remarks

[ View C++ implementation ] [ View Java implementation ]

ATM::	dispenseCash
Prototype	void dispenseCash(Money amount) const
Purpose	Dispense cash to customer
Receives	amount - amount of money to dispense
Returns
Remarks	Caller must check that requested amount is available before invoking this method.

[ View C++ implementation ] [ View Java implementation ]

ATM::	acceptEnvelope
Prototype	bool acceptEnvelope() const
Purpose	Accept a deposit envelope from customer.
Receives
Returns	True iff envelope is successfully accepted.
Remarks	Displays request for customer to insert envelope and waits for customer to do so. Times out if customer does not do so within a specified time.

[ View C++ implementation ] [ View Java implementation ]

ATM::

issueReceipt

Prototype

void issueReceipt(

int cardNumber,
int serialNumber,
const char * description,
Money amount,
Money balance,
Money availableBalance) const

Purpose

Print a receipt for a transaction.

Receives

cardNumber - number appearing on customer's card
serialNumber - transaction serial number - same as sent to bank
description - brief description of transaction
amount - amount of transaction - 0 if this does not apply
balance - balance in account after transaction
availableBalance - available balance after transaction

Returns

Remarks

[ View C++ implementation ] [ View Java implementation ]

ATM::	reEnterPIN
Prototype	int reEnterPIN() const
Purpose	Ask customer to re-enter PIN if PIN entered originally was not valid
Receives
Returns	PIN entered by customer
Remarks	Displays request for customer to re-enter PIN, then reads PIN from keyboard. PIN digits are echoed as asterisks to preserve secrecy.

[ View C++ implementation ] [ View Java implementation ]

ATM::	reportTransactionFailure
Prototype	bool reportTransactionFailure(const char * explanation) const
Purpose	Tell customer a transaction has failed and why; ask customer if he/she would like to do another.
Receives	explanation - reason for failure
Returns	true if customer would like to do another, false if not
Remarks

[ View C++ implementation ] [ View Java implementation ]

ATM::	ejectCard
Prototype	void ejectCard() const
Purpose	Return ATM card to customer at end of session.
Receives
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

ATM::	retainCard
Prototype	void retainCard() const
Purpose	Permanently retain card due to failure to enter correct PIN.
Receives
Returns
Remarks	Displays screen telling customer the card has been retained and instructing customer to contact the bank.

[ View C++ implementation ] [ View Java implementation ]

ATM::	number
Prototype	int number() const
Purpose	Provide the ATM's identifying number for inclusion in messages to the bank and on receipts.
Receives
Returns	ATM's identifying number
Remarks

[ View C++ implementation ] [ View Java implementation ]

Operations of class CardReader

CardReader::	CardReader
Prototype	CardReader()
Purpose	Constructor
Receives
Returns
Remarks

CardReader::	ejectCard
Prototype	void ejectCard()
Purpose	Physically eject customer's ATM card.
Receives
Returns
Remarks

CardReader::	retainCard
Prototype	void retainCard()
Purpose	Physically retain customer's ATM card.
Receives
Returns
Remarks

CardReader::	checkForCardInserted
Prototype	CardReader::ReaderStatus checkForCardInserted()
Purpose	Report whether or not a readable card has been inserted.
Receives
Returns	NO_CARD if no card has been inserted UNREADABLE_CARD if a card has been inserted incorrectly or is damaged CARD_HAS_BEEN_READ if a card has been inserted and read
Remarks

CardReader::	cardNumber
Prototype	int cardNumber() const
Purpose	Return number read from back of card.
Receives
Returns	Card number of card that is currently in the machine.
Remarks	Should only be called after a call to checkForCardInserted has returned CARD_HAS_BEEN_READ.

Operations of class Display

Display::	Display
Prototype	Display()
Purpose	Constructor
Receives
Returns
Remarks

Display::	requestCard
Prototype	void requestCard()
Purpose	Ask customer to insert card into machine.
Receives
Returns
Remarks

Display::	requestPIN
Prototype	void requestPIN()
Purpose	Ask customer to enter PIN on keyboard.
Receives
Returns
Remarks

Display::

displayMenu

Prototype

void displayMenu(

const char * whatToChoose,
int numItems,
const char * items[])

Purpose

Display a menu of options for the customer to choose from.

Receives

Returns

Remarks

Display::	requestAmountEntry
Prototype	void requestAmountEntry()
Purpose	Ask customer to enter a dollar amount on keyboard.
Receives
Returns
Remarks

Display::	requestDepositEnvelope
Prototype	void requestDepositEnvelope()
Purpose	Ask customer to insert a deposit envelope into machine.
Receives
Returns
Remarks

Display::	reportCardUnreadable
Prototype	void reportCardUnreadable()
Purpose	Inform customer that card he/she inserted could not be read.
Receives
Returns
Remarks

Display::	reportTransactionFailure
Prototype	void reportTransactionFailure(const char * explanation)
Purpose	Inform customer that a transaction failed and why.
Receives	explanation - why transaction failed
Returns
Remarks

Display::	requestReEnterPIN
Prototype	void requestReEnterPIN()
Purpose	Inform customer that PIN was incorrect, and ask him/her to re-enter it
Receives
Returns
Remarks

Display::	reportCardRetained
Prototype	void reportCardRetained()
Purpose	Inform customer that card has been retained because of too many incorrect PIN entries; customer should contact the bank.
Receives
Returns
Remarks

Display::	echoInput
Prototype	void echoInput(const char * echo)
Purpose	Echo user input typed on the keyboard onto the screen
Receives	echo - what to display
Returns
Remarks

Display::	clearDisplay
Prototype	void clearDisplay()
Purpose	Clear the display Screen
Receives
Returns
Remarks

Operations of class Keyboard

Keyboard::	Keyboard
Prototype	Keyboard()
Purpose	Constructor
Receives
Returns
Remarks

Keyboard::	readPIN
Prototype	int readPIN(Display & echoOn)
Purpose	Read a PIN typed in by the user.
Receives	echoOn - reference to display that asterisks are to be echoed onto
Returns	PIN the user typed.
Remarks	PIN is echoed as asterisks for security.

Keyboard::	readMenuChoice
Prototype	int readMenuChoice(int numItems)
Purpose	Allow customer to choose a specific item from a displayed menu
Receives	numItems - number of items displayed
Returns	Number of customer's choice (1..numItems) or 0 if customer presses Cancel.
Remarks

Keyboard::	readAmountEntry
Prototype	Money readAmountEntry(Display & echoOn)
Purpose	Allow customer to enter a dollar amount.
Receives	echoOn - reference to display that figures typed are to be echoed onto
Returns	Dollar amount entered by customer.
Remarks	Dollar amount is echoed on screen as customer types it.

Operations of class CashDispenser

CashDispenser::	CashDispenser
Prototype	CashDispenser()
Purpose	Constructor
Receives
Returns
Remarks

CashDispenser::	setCash
Prototype	void setCash(Money initialCash)
Purpose	Set amount of cash in dispenser at start of run.
Receives	initialCash - amount of money in dispenser
Returns
Remarks

CashDispenser::	dispenseCash
Prototype	void dispenseCash(Money amount)
Purpose	Physically dispense cash to customer
Receives	amount - amount of cash to dispense
Returns
Remarks

CashDispenser::	currentCash
Prototype	Money currentCash() const
Purpose	Report amount of cash currently available to be dispensed.
Receives
Returns	Amount of cash currently available to be dispensed.
Remarks

Operations of class EnvelopeAcceptor

EnvelopeAcceptor::	EnvelopeAcceptor
Prototype	EnvelopeAcceptor()
Purpose	Constructor
Receives
Returns
Remarks

EnvelopeAcceptor::	acceptEnvelope
Prototype	bool acceptEnvelope()
Purpose	Physically accept an envelope from customer.
Receives
Returns	True iff envelope is successfully accepted.
Remarks	Times out and returns false if envelope is not inserted within allowed time

Operations of class ReceiptPrinter

ReceiptPrinter::	ReceiptPrinter
Prototype	ReceiptPrinter()
Purpose	Constructor
Receives
Returns
Remarks

ReceiptPrinter::

printReceipt

Prototype

void printReceipt(

int theATMnumber,
const char * theATMlocation,
int cardNumber,
int serialNumber,
const char * description,
Money amount,
Money balance,
Money availableBalance)

Purpose

Physically print a receipt.

Receives

theATMnumber - number of the particular ATM
theATMlocation - location of the ATM
cardNumber - number appearing on customer's card
serialNumber - transaction serial number - same as sent to bank
description - brief description of transaction
amount - amount of transaction - 0 if this does not apply
balance - balance in account after transaction
availableBalance - available balance after transaction

Returns

Remarks

Operations of class OperatorPanel

OperatorPanel::	OperatorPanel
Prototype	OperatorPanel()
Purpose	Constructor
Receives
Returns
Remarks

OperatorPanel::	switchOn
Prototype	bool switchOn()
Purpose	Report physical setting of the switch.
Receives
Returns	True iff switch is in the "on" position
Remarks

OperatorPanel::	getInitialCash
Prototype	Money getInitialCash()
Purpose	Get amount of cash in cash dispenser from operator.
Receives
Returns	Amount of money in cash dispenser.
Remarks

Operations of class Session

Session::	Session
Prototype	Session(int cardNumber, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	cardNumber - card number read from customer's ATM card when it was inserted atm - ATM this session is serving bank - Bank the ATM is serving
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

Session::	doSessionUseCase
Prototype	void doSessionUseCase()
Purpose	Implement session use case
Receives
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

Session::	doInvalidPINExtension
Prototype	Status::Code doInvalidPINExtension()
Purpose	Perform invalid PIN extension
Receives
Returns	Result of sending transaction to bank with newly entered PIN value
Remarks	Asks user to re-enter PIN and then re-sends current transaction to the bank. If the bank still says the PIN is invalid, this process is repeated up to a maximum of three tries. A third failure will result in the card being retained and the session being aborted.

[ View C++ implementation ] [ View Java implementation ]

Session::	doFailedTransactionExtension
Prototype	bool doFailedTransactionExtension(Status::Code reason)
Purpose	Perform Failed Transaction extension
Receives	reason - code indicating why transaction failed.
Returns	true iff customer chooses to do another transaction
Remarks	Displays reason for transaction failure, and asks customer if he/she wants to do another. Customer is allowed to choose yes or no from menu

[ View C++ implementation ] [ View Java implementation ]

Session::	cardNumber
Prototype	int cardNumber() const
Purpose	Return customer's ATM card number.
Receives
Returns	Customer's ATM card number.
Remarks

[ View C++ implementation ] [ View Java implementation ]

Session::	PIN
Prototype	int PIN() const
Purpose	Return PIN that customer entered at start of session (or re-entered if original was invalid.)
Receives
Returns	PIN entered by customer.
Remarks

[ View C++ implementation ] [ View Java implementation ]

Operations of class Transaction and its subclasses

Transaction::	Transaction
Prototype	Transaction(Session & session, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	session - reference to session which is creating this transaction atm - ATM this transaction is serving bank - Bank to perform transaction
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

Transaction::

chooseTransaction

Prototype

static Transaction * chooseTransaction(

	Session & session,
	ATM & atm,
	Bank & bank)

Purpose

Ask user to choose a transaction type, and create a transaction object
of the appropriate subclass

Receives

session - reference to session which is creating this transaction
atm - ATM this transaction is serving
bank - Bank to perform transaction

Returns

Newly created transaction object

Remarks

Calls constructor for appropriate subclass and returns result

[ View C++ implementation ] [ View Java implementation ]

Transaction::	doTransactionUseCase
Prototype	Status::Code doTransactionUseCase()
Purpose	Carry out transaction use case
Receives
Returns	Code indicating whether transaction succeeded or failed, and reason for failure if it failed.
Remarks	This method implements features common to all transactions. The type-specific features are implemented by calling the three abstract methods defined below, in turn.

[ View C++ implementation ] [ View Java implementation ]

Transaction:: and subclasses	getTransactionSpecificsFromCustomer
Prototype	Status::Code getTransactionSpecificsFromCustomer()
Purpose	Get specific information relevant to this transaction from customer.
Receives
Returns	Success code if valid information was obtained; otherwise, code indicating nature of the problem.
Remarks	This method is abstract in class Transaction, and is implemented concretely for each of its subclasses.

[ View C++ implementation ] [ View Java implementation ]

Transaction:: and subclasses	sendToBank
Prototype	Status::Code sendToBank()
Purpose	Send transaction to bank.
Receives
Returns	Code returned by Bank indicating successful completion or reason for rejection.
Remarks	This method is abstract in class Transaction, and is implemented concretely for each of its subclasses.

[ View C++ implementation ] [ View Java implementation ]

Transaction:: and subclasses	finishApprovedTransaction
Prototype	Status::Code finishApprovedTransaction()
Purpose	Finish a transaction once the bank has approved it.
Receives
Returns	Success code if completed successfully; otherwise, code indicating nature of the problem.
Remarks	This method is abstract in class Transaction, and is implemented concretely for each of its subclasses.

[ View C++ implementation ] [ View Java implementation ]

WithdrawlTransaction::	WithdrawlTransaction
Prototype	WithdrawlTransaction(Session & session, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	session - reference to session which created this transaction atm - ATM this transaction is serving bank - Bank to perform transaction
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

DepositTransaction::	DepositTransaction
Prototype	DepositTransaction(Session & session, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	session - reference to session which created this transaction atm - ATM this transaction is serving bank - Bank to perform transaction
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

TransferTransaction::	TransferTransaction
Prototype	TransferTransaction(Session & session, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	session - reference to session which created this transaction atm - ATM this transaction is serving bank - Bank to perform transaction
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

InquiryTransaction::	InquiryTransaction
Prototype	InquiryTransaction(Session & session, ATM & atm, Bank & bank)
Purpose	Constructor
Receives	session - reference to session which created this transaction atm - ATM this transaction is serving bank - Bank to perform transaction
Returns
Remarks

[ View C++ implementation ] [ View Java implementation ]

Operations of class Bank

Bank::	Bank
Prototype	Bank()
Purpose	Constructor
Receives
Returns
Remarks

Bank::

initiateWithdrawl

Prototype

Status::Code initiateWithdrawl(

int cardNumber,
int PIN,
int ATMnumber,
int serialNumber,
AccountType from,
Money amount,
Money & newBalance,
Money & availableBalance)

Purpose

Initiate a withdrawl transaction.

Receives

cardNumber - number of the customer's ATM Card
PIN - PIN entered by the customer
ATMnumber - Identifying number of the ATM
serialNumber - Serial number of the transaction assigned by ATM
from - account from which money is to be withdrawn
amount - amount of withdrawl

Returns

return value - indicates whether transaction was approved or rejected
by the bank, and the reason for rejection if this is the case.
newBalance - if the transaction is approved, this is set to balance in
account after the transaction
availableBalance - if the transaction is approved, this is set to available
balance in account after the transaction

Remarks

If the transaction is approved, a call to finishWithdrawl must
be done to indicate whether or not the transaction was physically
completed.

Bank::

finishWithdrawl

Prototype

void finishWithdrawl(

int ATMnumber,
int serialNumber,
bool succeeded)

Purpose

Inform bank whether or not a withdrawl transaction was physically
completed by the ATM.

Receives

ATMnumber - Identifying number of the ATM
serialNumber - Serial number of the transaction assigned by ATM
succeeded - true iff transaction was physically completed by the ATM

Returns

Remarks

Bank::

initiateDeposit

Prototype

Status::Code initiateDeposit(

int cardNumber,
int PIN,
int ATMnumber,
int serialNumber,
AccountType to,
Money amount,
Money & newBalance,
Money & availableBalance)

Purpose

Initiate a deposit transaction.

Receives

cardNumber - number of the customer's ATM Card
PIN - PIN entered by the customer
ATMnumber - Identifying number of the ATM
serialNumber - Serial number of the transaction assigned by ATM
to - account to which money is to be deposited
amount - amount of deposit

Returns

Remarks

If the transaction is approved, a call to finishDeposit must be done to
indicate whether or not the transaction was physically completed.

Bank::

finishDeposit

Prototype

void finishDeposit(

int ATMnumber,
int serialNumber,
bool succeeded)

Purpose

Inform bank whether or not a deposit transaction was physically
completed by the ATM.

Receives

ATMnumber - Identifying number of the ATM
serialNumber - Serial number of the transaction assigned by ATM
succeeded - true iff transaction was physically completed by the ATM

Returns

Remarks

Bank::

doTransfer

Prototype

Status::Code doTransfer(

int cardNumber,
int PIN,
int ATMnumber,
int serialNumber,
AccountType from,
AccountType to,
Money amount,
Money & newBalance,
Money & availableBalance)

Purpose

Perform a transfer transaction.

Receives

Returns

return value - indicates whether transaction was approved or rejected
by the bank, and the reason for rejection if this is the case.
newBalance - if the transaction is approved, this is set to balance in
"to" account after the transaction
availableBalance - if the transaction is approved, this is set to
available balance in "to" account after the transaction.

Remarks

If the transaction is approved, it is completed by this operation.
No second method call is needed for this case.

Bank::

doInquiry

Prototype

Status::Code doInquiry(

int cardNumber,
int PIN,
int ATMnumber,
int serialNumber,
AccountType from,
Money &newBalance,
Money & availableBalance)

Purpose

Perform an inquiry transaction.

Receives

Returns

return value - indicates whether transaction was approved or rejected
by the bank, and the reason for rejection if this is the case.
newBalance - if the transaction is approved, this is set to
balance in account
availableBalance - if the transaction is approved, this is set to available
balance in account.

Remarks

If the transaction is approved, it is completed by this operation.
No second method call is needed for this case.

Bank::	chooseAccountType
Prototype	AccountType chooseAccountType(const char * purpose, ATM & atm) const
Purpose	Allow customer to choose an account from a menu of options
Receives	purpose - how this account will be used
	atm - ATM to use to dialog with customer
Returns	Code for type of account chosen
Remarks

Bank::	accountName
Prototype	const char * accountName(AccountType type) const
Purpose	Return a short name for an account for printing on receipt.
Receives	type - account type whose name is desired
Returns	Printable name for account
Remarks

Bank::	rejectionExplanation
Prototype	const char * rejectionExplanation(Status::Code code) const
Purpose	Return a brief textual explanation of a particular rejection code the bank returned when a transaction was initiated.
Receives	code - the rejection code the bank returned
Returns	Explanation for the code.
Remarks