uk.ac.liv.auction.core
Class RoundRobinAuction

java.lang.Object
  java.util.Observable
      uk.ac.liv.auction.core.AuctionImpl
          uk.ac.liv.auction.core.RoundRobinAuction

All Implemented Interfaces:

Auction, Parameterizable, QuoteProvider, Resetable, java.lang.Runnable, java.io.Serializable

Direct Known Subclasses:

RandomRobinAuction

public class RoundRobinAuction

extends AuctionImpl

implements java.lang.Runnable, java.io.Serializable, Parameterizable

A class representing an auction in which RoundRobinTraders can trade by placing shouts in a synchronous round-robin shedule.

TraderAgents are notified that it is their turn to bid by invokation of the requestShout() method on each agent.

This class implements Runnable so auctions can be run as threads, e.g.:

Thread t = new Thread(auction); t.start();

However, this class is not necessarily itself thread-safe.

This class is designed for high-performance lightweight simulation of auctions. Developers wishing to provide asynchronous auction functionality through, e.g. a web servlet, should either extend AuctionImpl or implement the Auction directly directly using the existing Auctioneer classes to provide the "bidding logic".

Parameters

base.maximumrounds int >= 0	(the number of auction rounds)
base.maximumdays int >= 0	(the number of days in the auction)
base.lengthofday int >= 0	(the maximum number of rounds in a trading day)
base.auctioneer class, inherits uk.ac.liv.auction.core.Auctioneer	(the auction protocol to use)
base.logger class, inherits uk.ac.liv.auction.stats.MarketDataLogger	(the MarketDataLogger to use)
base.stats class, inherits uk.ac.liv.auction.stats.MarketStats	(the MarketStats to use)
base.name string	(the name of this auction)
base.agenttype.n int	(the number of different agent types)
base.agenttype.i classname, inherits uk.ac.liv.auction.agent.RoundRobinTrader	(the class for agent type #i)

Version:

$Revision: 1.91 $

Author:

Steve Phelps

See Also:

TradingAgent, Serialized Form

Field Summary

protected java.util.HashSet	acceptedShouts The set of shouts that have been matched in the current round.
protected java.util.LinkedList	activeTraders The collection of TraderAgents currently taking part in this auction.
protected int	age
protected int	day The current trading day (period)
protected java.util.LinkedList	defunctTraders The collection of idle TraderAgents
static java.lang.String	ERROR_SHOUTSVISIBLE
protected AuctionConsoleFrame	guiConsole Optional graphical console
protected int	lengthOfDay The maximum length in rounds of a trading day
protected int	maximumDays The maximum number of trading days before the auction closes
protected int	maximumRounds The maximum number of rounds in the auction.
static java.lang.String	P_AGENT_TYPE
static java.lang.String	P_AUCTIONEER
static java.lang.String	P_CONSOLE
static java.lang.String	P_EVENTHANDLER
static java.lang.String	P_LENGTH_OF_DAY
static java.lang.String	P_MAXIMUM_DAYS
static java.lang.String	P_MAXIMUM_ROUNDS
static java.lang.String	P_NAME
static java.lang.String	P_NUM_AGENT_TYPES
static java.lang.String	P_NUM_AGENTS
static java.lang.String	P_REPORT
static java.lang.String	P_STATS
protected java.util.LinkedList	registeredTraders The collection of all TraderAgents registered in the auction.
protected int	round The current round.
protected boolean	shoutsProcessed Were any shouts processed (received & accepted) in the last round of trading?

Fields inherited from class uk.ac.liv.auction.core.AuctionImpl

auctioneer, closed, eventListeners, id, lastAsk, lastBid, lastShout, name, report

Constructor Summary

RoundRobinAuction()

RoundRobinAuction(java.lang.String name)
Construct a new auction in the stopped state, with no traders, no shouts, and no auctioneer.

Method Summary

protected void	activate(TradingAgent agent)
void	activateGUIConsole() Activate a graphical console for monitoring and controlling the progress of the auction.
void	begin()
void	changeShout(Shout shout)
protected void	checkEndOfDay() Terminate the current trading day (period) if the auction is quiescent or the maximum time allowed for a period has expired.
void	clear(Shout ask, Shout bid, double trPrice) Handle a single clearing operation between two traders
void	deactivateGUIConsole() Deactivate the graphical console.
void	end()
protected void	endDay() Terminate the current trading period (day)
void	generateReport() Generate a report.
java.util.Iterator	getActiveTraderIterator()
int	getAge()
AuctionConsoleFrame	getConsole()
int	getDay()
Shout	getLastAsk() Get the last ask placed in the auction.
Shout	getLastBid() Get the last bid placed in the auction.
int	getLengthOfDay()
int	getMaximumDays()
int	getMaximumRounds() Return the maximum number of rounds for this auction.
int	getNumberOfRegisteredTraders() Return the total number of traders registered in the auction.
int	getNumberOfTraders() Return the number of traders currently active in the auction.
int	getRemainingTime() Get the remaining time in the current trading day (period).
int	getRound() Get the current round number
java.util.Iterator	getTraderIterator() Return an iterator iterating over all traders registered (as opposed to actively trading) in the auction.
void	informRoundClosed()
protected void	initialise()
boolean	isQuiescent() Returns true if no bidding activity occured in the latest auction round.
void	newShout(Shout shout) Handle a new shout in the auction.
void	register(TradingAgent trader) Register a new trader in the auction.
void	remove(TradingAgent trader) Remove a trader from the auction.
void	requestShout(TradingAgent trader)
void	requestShouts() Invokes the requestShout() method on each trader in the auction, giving each trader the opportunity to bid in the auction.
void	reset() Restore the auction to its original state, ready for another run.
void	run() Runs the auction.
void	runSingleRound()
void	setConsole(AuctionConsoleFrame console)
void	setLengthOfDay(int lengthOfDay)
void	setMaximumDays(int maximumDays)
void	setMaximumRounds(int maximumRounds) Set the maximum number of rounds for this auction.
void	setup(ec.util.ParameterDatabase parameters, ec.util.Parameter base) Initialise this object from a parameter database.
boolean	shoutAccepted(Shout shout) Determines whether or not the given shout was matched in the current round of trading.
void	step()
protected void	sweepDefunctTraders() Remove defunct traders.
boolean	transactionsOccured() Determines whether or not any transactions have occured in the current round of trading.

Methods inherited from class uk.ac.liv.auction.core.AuctionImpl

addAuctionEventListener, addAuctionEventListener, addListener, addReport, close, closed, fireEvent, getAuctioneer, getLastShout, getName, getQuote, getReport, getReport, getResults, informAuctionClosed, informAuctionOpen, informEndOfDay, printState, recordShout, removeAuctionEventListener, removeAuctionEventListener, removeShout, setAuctioneer, setName, setReport, toString

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

activeTraders

protected java.util.LinkedList activeTraders

The collection of TraderAgents currently taking part in this auction.

defunctTraders

protected java.util.LinkedList defunctTraders

The collection of idle TraderAgents

registeredTraders

protected java.util.LinkedList registeredTraders

The collection of all TraderAgents registered in the auction.

round

protected int round

The current round.

age

protected int age

maximumRounds

protected int maximumRounds

The maximum number of rounds in the auction. Ignored if negative.

shoutsProcessed

protected boolean shoutsProcessed

Were any shouts processed (received & accepted) in the last round of trading?

guiConsole

protected AuctionConsoleFrame guiConsole

Optional graphical console

lengthOfDay

protected int lengthOfDay

The maximum length in rounds of a trading day

day

protected int day

The current trading day (period)

maximumDays

protected int maximumDays

The maximum number of trading days before the auction closes

acceptedShouts

protected java.util.HashSet acceptedShouts

The set of shouts that have been matched in the current round.

P_MAXIMUM_ROUNDS

public static final java.lang.String P_MAXIMUM_ROUNDS

See Also:

Constant Field Values

P_MAXIMUM_DAYS

public static final java.lang.String P_MAXIMUM_DAYS

See Also:

Constant Field Values

P_REPORT

public static final java.lang.String P_REPORT

See Also:

Constant Field Values

P_AUCTIONEER

public static final java.lang.String P_AUCTIONEER

See Also:

Constant Field Values

P_NAME

public static final java.lang.String P_NAME

See Also:

Constant Field Values

P_STATS

public static final java.lang.String P_STATS

See Also:

Constant Field Values

P_LENGTH_OF_DAY

public static final java.lang.String P_LENGTH_OF_DAY

See Also:

Constant Field Values

P_NUM_AGENT_TYPES

public static final java.lang.String P_NUM_AGENT_TYPES

See Also:

Constant Field Values

P_NUM_AGENTS

public static final java.lang.String P_NUM_AGENTS

See Also:

Constant Field Values

P_AGENT_TYPE

public static final java.lang.String P_AGENT_TYPE

See Also:

Constant Field Values

P_CONSOLE

public static final java.lang.String P_CONSOLE

See Also:

Constant Field Values

P_EVENTHANDLER

public static final java.lang.String P_EVENTHANDLER

See Also:

Constant Field Values

ERROR_SHOUTSVISIBLE

public static final java.lang.String ERROR_SHOUTSVISIBLE

See Also:

Constant Field Values

Constructor Detail

RoundRobinAuction

public RoundRobinAuction(java.lang.String name)

Construct a new auction in the stopped state, with no traders, no shouts, and no auctioneer.

Parameters:

name - The name of this auction.

RoundRobinAuction

public RoundRobinAuction()

Method Detail

setup

public void setup(ec.util.ParameterDatabase parameters,
                  ec.util.Parameter base)

Description copied from interface: Parameterizable

Initialise this object from a parameter database.

Specified by:

setup in interface Parameterizable

clear

public void clear(Shout ask,
                  Shout bid,
                  double trPrice)

Description copied from interface: Auction

Handle a single clearing operation between two traders

Specified by:

clear in interface Auction

shoutAccepted

public boolean shoutAccepted(Shout shout)
                      throws ShoutsNotVisibleException

Determines whether or not the given shout was matched in the current round of trading.

Specified by:

shoutAccepted in interface Auction

Throws:

ShoutsNotVisibleException

transactionsOccured

public boolean transactionsOccured()
                            throws ShoutsNotVisibleException

Determines whether or not any transactions have occured in the current round of trading.

Specified by:

transactionsOccured in interface Auction

Throws:

ShoutsNotVisibleException

register

public void register(TradingAgent trader)

Register a new trader in the auction.

remove

public void remove(TradingAgent trader)

Remove a trader from the auction.

requestShouts

public void requestShouts()

Invokes the requestShout() method on each trader in the auction, giving each trader the opportunity to bid in the auction.

requestShout

public void requestShout(TradingAgent trader)

setMaximumRounds

public void setMaximumRounds(int maximumRounds)

Set the maximum number of rounds for this auction. The auction will automatically close after this number of rounds has been dealt.

Parameters:

maximumRounds - The maximum number of roudns for this auction.

getMaximumRounds

public int getMaximumRounds()

Return the maximum number of rounds for this auction.

getLengthOfDay

public int getLengthOfDay()

getMaximumDays

public int getMaximumDays()

getNumberOfTraders

public int getNumberOfTraders()

Return the number of traders currently active in the auction.

Specified by:

getNumberOfTraders in interface Auction

getNumberOfRegisteredTraders

public int getNumberOfRegisteredTraders()

Return the total number of traders registered in the auction.

getRound

public int getRound()

Get the current round number

Specified by:

getRound in interface Auction

getAge

public int getAge()

getDay

public int getDay()

Specified by:

getDay in interface Auction

getRemainingTime

public int getRemainingTime()

Description copied from interface: Auction

Get the remaining time in the current trading day (period).

Specified by:

getRemainingTime in interface Auction

getLastBid

public Shout getLastBid()
                 throws ShoutsNotVisibleException

Get the last bid placed in the auction.

Throws:

ShoutsNotVisibleException

getLastAsk

public Shout getLastAsk()
                 throws ShoutsNotVisibleException

Get the last ask placed in the auction.

Throws:

ShoutsNotVisibleException

run

public void run()

Runs the auction.

Specified by:

run in interface java.lang.Runnable

begin

public void begin()

end

public void end()

step

public void step()
          throws AuctionClosedException

Throws:

AuctionClosedException

runSingleRound

public void runSingleRound()
                    throws AuctionClosedException

Throws:

AuctionClosedException

informRoundClosed

public void informRoundClosed()

newShout

public void newShout(Shout shout)
              throws AuctionException

Description copied from class: AuctionImpl

Handle a new shout in the auction.

Specified by:

newShout in interface Auction

Overrides:

newShout in class AuctionImpl

Parameters:

shout - The new shout in the auction.

Throws:

AuctionException

changeShout

public void changeShout(Shout shout)
                 throws AuctionException

Throws:

AuctionException

getTraderIterator

public java.util.Iterator getTraderIterator()

Return an iterator iterating over all traders registered (as opposed to actively trading) in the auction.

getActiveTraderIterator

public java.util.Iterator getActiveTraderIterator()

isQuiescent

public boolean isQuiescent()

Returns true if no bidding activity occured in the latest auction round.

reset

public void reset()

Restore the auction to its original state, ready for another run. This method can be used to rerun simulations efficienctly without the overhead of (re)constructing new auction objects.

Specified by:

reset in interface Resetable

Overrides:

reset in class AuctionImpl

generateReport

public void generateReport()

Generate a report.

activateGUIConsole

public void activateGUIConsole()

Activate a graphical console for monitoring and controlling the progress of the auction. Activation of the console may significantly impact the time performance of the auction.

deactivateGUIConsole

public void deactivateGUIConsole()

Deactivate the graphical console.

setConsole

public void setConsole(AuctionConsoleFrame console)

getConsole

public AuctionConsoleFrame getConsole()

setLengthOfDay

public void setLengthOfDay(int lengthOfDay)

setMaximumDays

public void setMaximumDays(int maximumDays)

sweepDefunctTraders

protected void sweepDefunctTraders()

Remove defunct traders.

initialise

protected void initialise()

Overrides:

initialise in class AuctionImpl

activate

protected void activate(TradingAgent agent)

checkEndOfDay

protected void checkEndOfDay()

Terminate the current trading day (period) if the auction is quiescent or the maximum time allowed for a period has expired.

endDay

protected void endDay()

Terminate the current trading period (day)