sale
Class Shop

java.lang.Object
  |
  +--sale.Shop

public class Shop

extends Object

implements SerializableListener

The central class in a SalesPoint application, responsible for central management tasks and for persistence.

There is only one instance of the Shop class per application, and you can obtain, or change this central, singleton instance through calls to getTheShop() or setTheShop(sale.Shop), resp.

The Shop will manage the application's display, creating and removing additional SalesPoints' displays as necessary. Also, the Shop will offer a central MenuSheet, from which the user can select certain central, administrative actions, like shutdown, loadup, creating and removing SalesPoints, etc. This MenuSheet can, of course, be adapted. See createShopMenuSheet(), if you're interested in this.

The Shop can make persistent the entire current state of the application by calling just one method: makePersistent().

The Shop serves as a ProcessContext for remote and background processes, which will be equipped with a NullDisplay. To find out about running processes at the Shop, see runProcess(sale.SaleProcess, sale.Display, users.User, data.DataBasket) and runBackgroundProcess(sale.SaleProcess, users.User, data.DataBasket).

Hooks:

Change Shutdown Conditions , Change Shop Quit Behavior , Change global Logging Behavior , Define Persistance Streams , Define Shop MenuSheet , Incorporate new Shop , React to Adding or Removing Of SalesPoint

Since:

v2.0

Version:

2.0 28/05/1999

Author:

Steffen Zschaler

See Also:

Serialized Form

Inner Class Summary

protected static class

Shop.ProcessHandle A ProcessContext for one remote or background process.

Field Summary

static int	DEAD Constant marking the Shop's state.
static String	LOAD_TAG MenuSheetObject tag marking the "Load..." item.
protected JFrame	m_jfShopFrame The Shop's frame.
protected List	m_lphProcesses All remote or background processes currently running on this Shop, represented by their process handles.
protected List	m_lspSalesPoints The SalesPoints that belong to the system.
protected Map	m_mpToPersistify Objects that where registered to be made persistent.
protected Rectangle	m_rShopFrameBounds The ShopFrames bounds.
protected String	m_sShopFrameTitle The title of the Shop's frame.
protected Timer	m_trTimer The Timer used by this Shop for managing the simulation time.
static String	QUIT_SHOP_TAG MenuSheetObject tag marking the "Quit" item.
static int	RUNNING Constant marking the Shop's state.
static String	SAVE_TAG MenuSheetObject tag marking the "Save..." item.
static String	SEPARATOR_ONE_TAG MenuSheetObject tag marking the first separator.
static String	SEPARATOR_TWO_TAG MenuSheetObject tag marking the second separator.
static String	SET_CURRENT_SP_TAG MenuSheetObject tag marking the "Set Current SalesPoint" item.
static String	SHOP_MENU_TAG MenuSheetObject tag marking the entire Shop MenuSheet.
static int	SUSPENDED Constant marking the Shop's state.

Constructor Summary

protected

Shop() Sole constructor to enforce singleton pattern.

Method Summary

void	addCatalog(Catalog c) Add a Catalog to the global table of Catalogs.
void	addSalesPoint(SalesPoint sp) Add a SalesPoint to the Shop.
void	addStock(Stock st) Add a Stock to the global list of Stocks.
protected boolean	canShutdown(boolean fPersistify) Check whether shutdown can be permitted in the current state of the system.
protected void	clearInternalStructures() Clear the internal structures maintained by the Shop, thus finishing off shutdown.
protected MenuSheet	createShopMenuSheet() Create and return the Shop's main MenuSheet.
protected Display	createStatusDisplay(SalesPoint sp) Create a status display for a SalesPoint.
Catalog	getCatalog(String sName) Get a Catalog from the global list of Catalogs.
SalesPoint	getCurrentSalesPoint() Return the current SalesPoint of the Shop.
Object	getPersistentObject(Object oKey) Get a persistent object.
Iterator	getPersistentObjects() Get an iterator of all persistent objects.
protected Object	getProcessesLock() Return the monitor synchronizing access to the list of processes.
List	getSalesPoints() Get a list of all SalesPoints in the Shop.
protected Object	getSalesPointsLock() Return the monitor synchronizing access to the list of SalesPoints.
protected JFrame	getShopFrame() Get the Shop's main frame.
Rectangle	getShopFrameBounds() Returns the Framebounds of the Shops assoziated JFrame.
int	getShopState() Return the Shop's state, being one of DEAD, RUNNING or SUSPENDED.
Stock	getStock(String sName) Look up a Stock in the global Stock list.
static Shop	getTheShop() Get the global, singleton Shop instance.
Timer	getTimer() Get the Shop's timer.
boolean	isCurrentSalesPointAdjusting() Return whether or not calls to setCurrentSalesPoint(sale.SalesPoint) have any effect.
void	log(Loggable la) Log a piece of information to the global log file.
void	makePersistent() Make the current state of the Shop persistent.
protected void	onLoadFrames(ObjectInputStream ois) Load the Shop's main frame's and the status frame's state from the given stream.
protected void	onSalesPointAdded(SalesPoint sp) Hook method performing additional work when a SalesPoint was added.
protected void	onSalesPointRemoved(SalesPoint sp) Hook method called when a SalesPoint was removed from the Shop.
protected void	onSaveFrames(ObjectOutputStream oos) Save the Shop's main frame's and the status frame's state to the given stream.
void	quit() Close the Shop and quit the application.
Catalog	removeCatalog(String sName) Remove a catalog from the global table of Catalogs.
void	removeSalesPoint(SalesPoint sp) Remove a SalesPoint from the Shop.
protected void	removeStatusDisplay(Display d) Close a status display.
Stock	removeStock(String sName) Remove a Stock from the global list of Stocks.
void	resetCurrentSalesPointIsAdjusting() Reset a flag that can be used to optimize setCurrentSalesPoint calls.
void	restore() Restore the Shop's state from a Stream.
void	resume() Resume a suspended Shop.
protected InputStream	retrievePersistanceInStream() Retrieve the stream from which to read the Shop's state.
protected OutputStream	retrievePersistanceOutStream() Retrieve the stream to which the Shop's state is to be written.
void	runBackgroundProcess(SaleProcess p, User usr, DataBasket db) Run a background process on the Shop.
void	runProcess(SaleProcess p, Display d, User usr, DataBasket db) Run a process on the Shop.
void	setCurrentSalesPoint(SalesPoint sp) Make a SalesPoint the current SalesPoint.
void	setCurrentSalesPointIsAdjusting() Set a flag that can be used to optimize setCurrentSalesPoint calls.
Object	setObjectPersistent(Object oKey, Object oToPersistify) Set an object to be persistent.
Object	setObjectTransient(Object oKey) Set an object to be no longer persistent.
void	setShopFrameBounds(Rectangle r) Sets the Framebounds of the Shops assoziated JFrame.
void	setShopFrameTitle(String sTitle) Set the Shop frame's title.
static void	setTheShop(Shop shTheShop) Set the global, singleton Shop instance.
void	setTimer(Timer trTimer) Set the Shop's Timer.
boolean	shutdown(boolean fPersistify) Close the Shop.
void	start() Start the Shop.
void	suspend() Suspend a running Shop.

Methods inherited from class java.lang.Object

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

Field Detail

m_lspSalesPoints

protected List m_lspSalesPoints

The SalesPoints that belong to the system.

m_rShopFrameBounds

protected Rectangle m_rShopFrameBounds

The ShopFrames bounds.

m_lphProcesses

protected List m_lphProcesses

All remote or background processes currently running on this Shop, represented by their process handles.

m_jfShopFrame

protected transient JFrame m_jfShopFrame

The Shop's frame.

m_sShopFrameTitle

protected String m_sShopFrameTitle

The title of the Shop's frame.

m_trTimer

protected Timer m_trTimer

The Timer used by this Shop for managing the simulation time.

m_mpToPersistify

protected Map m_mpToPersistify

Objects that where registered to be made persistent.

DEAD

public static final int DEAD

Constant marking the Shop's state. DEAD means the Shop was either shut down or not started yet.

RUNNING

public static final int RUNNING

Constant marking the Shop's state. RUNNING means the Shop was started and neither suspended nor shutdown.

SUSPENDED

public static final int SUSPENDED

Constant marking the Shop's state. SUSPENDED means the Shop was suspended.

SHOP_MENU_TAG

public static final String SHOP_MENU_TAG

MenuSheetObject tag marking the entire Shop MenuSheet.

SET_CURRENT_SP_TAG

public static final String SET_CURRENT_SP_TAG

MenuSheetObject tag marking the "Set Current SalesPoint" item.

SEPARATOR_ONE_TAG

public static final String SEPARATOR_ONE_TAG

MenuSheetObject tag marking the first separator.

LOAD_TAG

public static final String LOAD_TAG

MenuSheetObject tag marking the "Load..." item.

SAVE_TAG

public static final String SAVE_TAG

MenuSheetObject tag marking the "Save..." item.

SEPARATOR_TWO_TAG

public static final String SEPARATOR_TWO_TAG

MenuSheetObject tag marking the second separator.

QUIT_SHOP_TAG

public static final String QUIT_SHOP_TAG

MenuSheetObject tag marking the "Quit" item.

Constructor Detail

Shop

protected Shop()

Sole constructor to enforce singleton pattern.

Method Detail

getSalesPointsLock

protected final Object getSalesPointsLock()

Return the monitor synchronizing access to the list of SalesPoints.

Override:

Never.

getProcessesLock

protected final Object getProcessesLock()

Return the monitor synchronizing access to the list of processes.

Override:

Never.

addSalesPoint

public void addSalesPoint(SalesPoint sp)

Add a SalesPoint to the Shop.

Override:

Never.

Instead, override onSalesPointAdded(sale.SalesPoint).

Parameters:

sp - the SalesPoint to be added.

onSalesPointAdded

protected void onSalesPointAdded(SalesPoint sp)

Hook method performing additional work when a SalesPoint was added.

Override:

Sometimes.

Make sure to call the super class's method if overriding this method.

Parameters:

sp - the SalesPoint that was removed from the Shop.

Hooks:

React to Adding or Removing Of SalesPoint

removeSalesPoint

public void removeSalesPoint(SalesPoint sp)

Remove a SalesPoint from the Shop.

Prior to being removed from the Shop, the SalesPoint will be suspended.

Override:

Never.

Instead, override onSalesPointRemoved(sale.SalesPoint).

Parameters:

sp - the SalesPoint to be removed

onSalesPointRemoved

protected void onSalesPointRemoved(SalesPoint sp)

Hook method called when a SalesPoint was removed from the Shop.

Override:

Sometimes.

Make sure to call the super class's method if you override this method.

Parameters:

sp - the SalesPoint that was removed from the Shop.

Hooks:

React to Adding or Removing Of SalesPoint

createStatusDisplay

protected Display createStatusDisplay(SalesPoint sp)

Create a status display for a SalesPoint.

Override:

Never.

Parameters:

sp - the SalesPoint for which to create the status display.

removeStatusDisplay

protected void removeStatusDisplay(Display d)

Close a status display.

Override:

Never.

Parameters:

d - the status display to be closed.

getSalesPoints

public List getSalesPoints()

Get a list of all SalesPoints in the Shop.

The list is backed by the SalesPoint's queue, but is immutable.

Override:

Never.

setCurrentSalesPoint

public void setCurrentSalesPoint(SalesPoint sp)

Make a SalesPoint the current SalesPoint.

This will bring the specified SalesPoint's window to the front.

Override:

Never.

Parameters:

sp - the SalesPoint to be the current SalesPoint from now on.

setCurrentSalesPointIsAdjusting

public void setCurrentSalesPointIsAdjusting()

Set a flag that can be used to optimize setCurrentSalesPoint calls. As long as this flag is set, i.e. isCurrentSalesPointAdjusting() returns true, calls to setCurrentSalesPoint(sale.SalesPoint) will have no effect. You can reset the flag by calling resetCurrentSalesPointIsAdjusting().

Override:

Never.

resetCurrentSalesPointIsAdjusting

public void resetCurrentSalesPointIsAdjusting()

Reset a flag that can be used to optimize setCurrentSalesPoint calls. There must be one call to resetCurrentSalesPointIsAdjusting for each call to setCurrentSalesPointIsAdjusting(). Calls to this function must be followed by an explicit call to setCurrentSalesPoint(sale.SalesPoint).

Override:

Never.

isCurrentSalesPointAdjusting

public boolean isCurrentSalesPointAdjusting()

Return whether or not calls to setCurrentSalesPoint(sale.SalesPoint) have any effect.

Override:

Never.

getCurrentSalesPoint

public SalesPoint getCurrentSalesPoint()

Return the current SalesPoint of the Shop.

Override:

Never.

runProcess

public void runProcess(SaleProcess p,
                       Display d,
                       User usr,
                       DataBasket db)

Run a process on the Shop.

Override:

Never.

Parameters:

p - the process to be run.

d - the display to be used by the Shop. This can be null, then, a NullDisplay will be used.

usr - the user to be the current user for the process.

db - the DataBasket to be used by the process.

runBackgroundProcess

public void runBackgroundProcess(SaleProcess p,
                                 User usr,
                                 DataBasket db)

Run a background process on the Shop. A background process does not have a display. You can use background processes to perform tasks that do not need user communication.

Override:

Never.

Parameters:

p - the process to be run.

usr - the user to be the current user for the process.

db - the DataBasket to be used by the process.

Hooks:

Incorporate a process that does not need user interaction

start

public void start()

Start the Shop.

This method must not be called after load up.

Override:

Never.

setShopFrameBounds

public void setShopFrameBounds(Rectangle r)

Sets the Framebounds of the Shops assoziated JFrame.

Example:

Shop.getTheShop().setShopFrameBounds (new Rectangle (10,10,200,200)); This moves the JFrame to Position (10,10) with a size of (200,200).

Override:

Sometimes.

getShopFrameBounds

public Rectangle getShopFrameBounds()

Returns the Framebounds of the Shops assoziated JFrame.

Override:

Sometimes.

suspend

public void suspend()

Suspend a running Shop. Suspending the Shop includes suspending all SalesPoints currently in the Shop.

Override:

Never.

resume

public void resume()

Resume a suspended Shop. Resuming includes resuming all SalesPoints currently in the Shop.

Override:

Never.

Hooks:

Change Shutdown Conditions

quit

public void quit()

Close the Shop and quit the application.

This method is linked to the "Quit" item in the Shop's MenuSheet as well as to the close window gesture for the Shop frame.

Override:

Sometimes.

By default implemented as:

 if (Shop.getTheShop().shutdown (true)) {
   System.exit (0);
 };
 

Hooks:

Change Shop Quit Behavior

shutdown

public boolean shutdown(boolean fPersistify)

Close the Shop.

Calling this method will stop any processes currently running on any SalesPoints in the Shop after calling canShutdown(boolean) to check whether shutdown is permitted at the moment. The method must therefore not be called from within a process !

Override:

Never.

Parameters:

fPersistify - if true, the current state of the Shop will be made persistent prior to actually closing the Shop.

Returns:

true if the shutdown was successful.

Hooks:

Change Shop Quit Behavior

canShutdown

protected boolean canShutdown(boolean fPersistify)

Check whether shutdown can be permitted in the current state of the system.

In this method you can assume that you are the owner of getSalesPointsLock() and getProcessesLock(), so that you can access the list of SalesPoints and the list of processes without extra synchronization.

The default implementation will first suspend() the Shop, should its state be RUNNING. It will then check all processes running on the Shop. If no such processes exist or if all of them confirm that shut down is possible, it will call the SalesPoint.canQuit(boolean) method of any SalesPoint in the system, passing !fPersistify as the parameter. If all SalesPoints return true, the Shop stays suspended and canShutdown returns true. In any other case, the Shop will be resumed again, and false will be returned.

This method is usually not called directly, but if you do, make sure to call it with synchronization on getSalesPointsLock() and getProcessesLock().

Override:

Sometimes.

Parameters:

fPersistify - if true, the Shop's state will be made persistent before shutdown.

Returns:

true to indicate shutdown is OK; false otherwise.

getShopState

public int getShopState()

Return the Shop's state, being one of DEAD, RUNNING or SUSPENDED.

Override:

Never.

Hooks:

Change Shutdown Conditions

makePersistent

public void makePersistent()
                    throws IOException,
                           CancelledException

Make the current state of the Shop persistent.

Override:

Never.

Throws:

IOException - if an error occurred.

CancelledException - if the retrieval of the persistance stream was cancelled by the user.

onSaveFrames

protected void onSaveFrames(ObjectOutputStream oos)
                     throws IOException

Save the Shop's main frame's and the status frame's state to the given stream.

Override:

Never.

Parameters:

oos - the Stream to save to

Throws:

IOException - if an error occurred while saving the frames' states.

restore

public void restore()
             throws IOException,
                    ClassNotFoundException,
                    CancelledException

Restore the Shop's state from a Stream.

Attention: Any old reference to the Shop is invalid afterwards. The new Shop can be acquired through Shop.getTheShop().

Override:

Never.

Throws:

IOException - if an exception occurred while loading

ClassNotFoundException - if an exception occurred while loading

CancelledException - if the user cancels loading.

onLoadFrames

protected void onLoadFrames(ObjectInputStream ois)
                     throws IOException,
                            ClassNotFoundException

Load the Shop's main frame's and the status frame's state from the given stream.

Override:

Never.

Parameters:

ois - the Stream to load from

Throws:

IOException - if an error occurred while loading the frames' states.

ClassNotFoundException - if an error occurred while loading the frames' states.

retrievePersistanceOutStream

protected OutputStream retrievePersistanceOutStream()
                                             throws IOException,
                                                    CancelledException

Retrieve the stream to which the Shop's state is to be written.

Override:

Sometimes.

The default implementation allows the user to select a file name and creates a stream for the specified file.

Throws:

IOException - if an exception occurred while creating the stream

CancelledException - if the user cancelled the save process.

Hooks:

Define Persistance Streams

retrievePersistanceInStream

protected InputStream retrievePersistanceInStream()
                                           throws IOException,
                                                  CancelledException

Retrieve the stream from which to read the Shop's state.

Override:

Sometimes.

The default implementation allows the user to select a file name and creates a stream for the specified file.

Throws:

IOException - if an exception occurred while creating the stream

CancelledException - if the user cancelled the save process.

Hooks:

Define Persistance Streams

setObjectPersistent

public Object setObjectPersistent(Object oKey,
                                  Object oToPersistify)

Set an object to be persistent. The object can be accessed at the given key.

Override:

Never.

Parameters:

oKey - the key at which the object can be accessed.

oToPersistify - the object that is to be made persistent.

Returns:

the object previously stored at that key.

Hooks:

Make Object Persistent

setObjectTransient

public Object setObjectTransient(Object oKey)

Set an object to be no longer persistent.

Override:

Never.

Parameters:

oKey - the key at which the object can be accessed.

Returns:

the object that was made transient.

getPersistentObject

public Object getPersistentObject(Object oKey)

Get a persistent object.

Override:

Never.

Parameters:

oKey - the key that describes the object.

Returns:

the persistent object.

getPersistentObjects

public Iterator getPersistentObjects()

Get an iterator of all persistent objects. You can use the iterator's remove() method to make objects transient.

Override:

Never.

clearInternalStructures

protected void clearInternalStructures()

Clear the internal structures maintained by the Shop, thus finishing off shutdown.

Override:

Never.

setShopFrameTitle

public void setShopFrameTitle(String sTitle)

Set the Shop frame's title. Initially, this is "Shop".

Override:

Never.

Parameters:

sTitle - the new title.

getShopFrame

protected JFrame getShopFrame()

Get the Shop's main frame.

The main Shop frame will be the frame in which the Shop's menu gets displayed.

By default this creates a MultiWindow with the title that you specified in a call to setShopFrameTitle(java.lang.String).

Override:

Never.

createShopMenuSheet

protected MenuSheet createShopMenuSheet()

Create and return the Shop's main MenuSheet.

The default implementation will provide two MenuSheets in the Shop's MenuSheet:

MenuSheet (name/tag)	Item text	Item tag	Item action	Comments
Shop SHOP_MENU_TAG	Set current SalesPoint	SET_CURRENT_SP_TAG	setCurrentSalesPoint().	This is a Sub-MenuSheet that shows all the SalesPoints in the Shop. The user can click the one he or she wants to select. As long as this MenuSheet is found in the Shop's MenuSheet, it will be updated by calls to addSalesPoint(sale.SalesPoint) and removeSalesPoint(sale.SalesPoint).
	Separator	SEPARATOR_ONE_TAG
	Load...	LOAD_TAG	Load a persistent Shop image.
	Save...	SAVE_TAG	Save current Shop state to create a persistant Shop image.
	Separator	SEPARATOR_TWO_TAG
	Quit	QUIT_SHOP_TAG	quit().
	MultiWindow MultiWindow.MULTIWINDOW_MENU_TAG	see MultiWindow.getMultiWindowMenuSheet()

Override:

Sometimes.

Hooks:

Define Shop MenuSheet

getTimer

public Timer getTimer()

Get the Shop's timer. If no timer has been set using setTimer(sale.Timer), the default timer will be a StepTimer with a Step time.

Override:

Never.

Returns:

the Shop's Timer

setTimer

public void setTimer(Timer trTimer)

Set the Shop's Timer.

Override:

Never.

Parameters:

trTimer - the Timer to be used from now on

Hooks:

Incorporate Timer

log

public void log(Loggable la)
         throws IOException

Log a piece of information to the global log file.

Override:

Never.

Parameters:

la - the information to be logged.

Throws:

IOException - on any error while logging.

Hooks:

Change global Logging Behavior

addStock

public void addStock(Stock st)
              throws DuplicateKeyException

Add a Stock to the global list of Stocks. The Stock can later be identified by its name.

Override:

Never.

Parameters:

st - the Stock to be added to the global list of Stocks.

Throws:

DuplicateKeyException - if a Stock of the same name already exists in the global list of Stocks.

removeStock

public Stock removeStock(String sName)

Remove a Stock from the global list of Stocks.

Override:

Never.

Parameters:

sName - the name of the Stock to be removed.

Returns:

the removed Stock, if any.

getStock

public Stock getStock(String sName)

Look up a Stock in the global Stock list.

Override:

Never.

Parameters:

sName - the name of the Stock to be looked up.

Returns:

the Stock, if any.

addCatalog

public void addCatalog(Catalog c)
                throws DuplicateKeyException

Add a Catalog to the global table of Catalogs. The Catalog will be identifiable by its name.

Override:

Never.

Parameters:

c - the Catalog to be added to the global list of Catalogs

Throws:

DuplicateKeyException - if a Catalog of the same name already existed in the global list of Catalogs.

removeCatalog

public Catalog removeCatalog(String sName)

Remove a catalog from the global table of Catalogs.

Override:

Never.

Parameters:

sName - the name of the Catalog to be removed.

Returns:

the Catalog that was removed, if any.

getCatalog

public Catalog getCatalog(String sName)

Get a Catalog from the global list of Catalogs.

Override:

Never.

Parameters:

sName - the name of the Catalog to be returned.

Returns:

the associated Catalog, if any.

getTheShop

public static Shop getTheShop()

Get the global, singleton Shop instance.

Hooks:

Add a new point of sale , Make Object Persistent , Incorporate a process that does not need user interaction , Incorporate Timer

setTheShop

public static void setTheShop(Shop shTheShop)

Set the global, singleton Shop instance.

This method will only have an effect the next time, getTheShop() gets called. So to avoid inconsistency, use this method only in the beginning of your program, to install an instance of a subclass of Shop as the global, singleton Shop instance.

Parameters:

shTheShop - the new global, singleton Shop instance

Hooks:

Incorporate new Shop