sale
Class Shop

java.lang.Object
  sale.Shop

All Implemented Interfaces:

EventListener, Serializable, SerializableListener

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

Since:

v2.0

Author:

Steffen Zschaler

See Also:

Serialized Form

Nested 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...
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 Map	m_pContext ProcessContext data.
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...
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 MultiWindow	createShopFrame() Creates and returns a new MultiWindow with window view mode set.
protected MenuSheet	createShopMenuSheet() Create and return the Shop's main MenuSheet.
Catalog	getCatalog(String sName) Get a Catalog from the global list of Catalogs.
SalesPoint	getCurrentSalesPoint() Returns the currently active SalesPoint of the Shop.
Object	getPersistentObject(Object oKey) Get a persistent object.
Iterator	getPersistentObjects() Get an iterator of all persistent objects.
protected Object	getProcessData(String sKey) Get an object from the ProcessContext.
protected Object	getProcessesLock() Return the monitor synchronizing access to the list of processes.
SalesPoint	getSalesPoint(int id)
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() Gets the Shop's main frame.
Rectangle	getShopFrameBounds() Returns the Framebounds of the Shops assoziated JFrame.
String	getShopFrameTitle()
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) Loads the Shop's main frame and the SalesPoints' frames' states 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	retrievePersistenceInStream() Retrieves the stream from which to read the Shop's state.
protected OutputStream	retrievePersistenceOutStream() Retrieves 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) Makes a SalesPoint the current SalesPoint.
void	setCurrentSalesPointIsAdjusting() Sets a flag that can be used to optimize setCurrentSalesPoint calls.
Object	setObjectPersistent(Object oKey, Object oToPersistify) Sets an object to be persistent.
Object	setObjectTransient(Object oKey) Set an object to be no longer persistent.
protected void	setProcessData(String sKey, Object oData) Put an object into the ProcessContext.
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.
void	setViewMode(int viewMode) Sets the view mode for the Shop.
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_pContext

protected Map m_pContext

ProcessContext data.

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.

See Also:

Constant Field Values

RUNNING

public static final int RUNNING

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

See Also:

Constant Field Values

SUSPENDED

public static final int SUSPENDED

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

See Also:

Constant Field Values

SHOP_MENU_TAG

public static final String SHOP_MENU_TAG

MenuSheetObject tag marking the entire Shop MenuSheet.

See Also:

Constant Field Values

SET_CURRENT_SP_TAG

public static final String SET_CURRENT_SP_TAG

MenuSheetObject tag marking the "Set Current SalesPoint" item.

See Also:

Constant Field Values

SEPARATOR_ONE_TAG

public static final String SEPARATOR_ONE_TAG

MenuSheetObject tag marking the first separator.

See Also:

Constant Field Values

LOAD_TAG

public static final String LOAD_TAG

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

See Also:

Constant Field Values

SAVE_TAG

public static final String SAVE_TAG

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

See Also:

Constant Field Values

SEPARATOR_TWO_TAG

public static final String SEPARATOR_TWO_TAG

MenuSheetObject tag marking the second separator.

See Also:

Constant Field Values

QUIT_SHOP_TAG

public static final String QUIT_SHOP_TAG

MenuSheetObject tag marking the "Quit" item.

See Also:

Constant Field Values

Constructor Detail

Shop

protected Shop()

Sole constructor to enforce singleton pattern.

Method Detail

setProcessData

protected void setProcessData(String sKey,
                              Object oData)

Put an object into the ProcessContext.

Parameters:

sKey - object's identifier

oData - the data object

Override:

Never

getProcessData

protected Object getProcessData(String sKey)

Get an object from the ProcessContext.

Parameters:

sKey - object's key

Returns:

the object from ProcessContext

Override:

Never

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.

Parameters:

sp - the SalesPoint to be added.

Override:

Never Instead, override onSalesPointAdded(sale.SalesPoint).

setViewMode

public void setViewMode(int viewMode)

Sets the view mode for the Shop.

Parameters:

viewMode - can be MultiWindow.WINDOW_VIEW, MultiWindow.TABBED_VIEW, MultiWindow.DESKTOP_VIEW

onSalesPointAdded

protected void onSalesPointAdded(SalesPoint sp)

Hook method performing additional work when a SalesPoint was added.

Parameters:

sp - the SalesPoint that was removed from the Shop.

Override:

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

removeSalesPoint

public void removeSalesPoint(SalesPoint sp)

Remove a SalesPoint from the Shop.

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

Parameters:

sp - the SalesPoint to be removed

Override:

Never Instead, override onSalesPointRemoved(sale.SalesPoint).

onSalesPointRemoved

protected void onSalesPointRemoved(SalesPoint sp)

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

Parameters:

sp - the SalesPoint that was removed from the Shop.

Override:

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

removeStatusDisplay

protected void removeStatusDisplay(Display d)

Close a status display.

Parameters:

d - the status display to be closed.

Override:

Never

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

getSalesPoint

public SalesPoint getSalesPoint(int id)

setCurrentSalesPoint

public void setCurrentSalesPoint(SalesPoint sp)

Makes a SalesPoint the current SalesPoint.

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

Parameters:

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

Override:

Never

setCurrentSalesPointIsAdjusting

public void setCurrentSalesPointIsAdjusting()

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

Returns the currently active SalesPoint of the Shop.

Override:

Never

runProcess

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

Run a process on the Shop.

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.

Override:

Never

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.

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.

Override:

Never

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

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);
 };
 

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 !

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.

Override:

Never

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

Parameters:

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

Returns:

true to indicate shutdown is OK; false otherwise.

Override:

Sometimes

getShopState

public int getShopState()

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

Override:

Never

makePersistent

public void makePersistent()
                    throws IOException,
                           CancelledException

Make the current state of the Shop persistent.

Throws:

IOException - if an error occurred.

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

Override:

Never

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.

Parameters:

oos - the Stream to save to

Throws:

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

Override:

Never

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

Throws:

IOException - if an exception occurred while loading

ClassNotFoundException - if an exception occurred while loading

CancelledException - if the user cancels loading.

Override:

Never

onLoadFrames

protected void onLoadFrames(ObjectInputStream ois)
                     throws IOException,
                            ClassNotFoundException

Loads the Shop's main frame and the SalesPoints' frames' states from the given stream.

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.

Override:

Never

retrievePersistenceOutStream

protected OutputStream retrievePersistenceOutStream()
                                             throws IOException,
                                                    CancelledException

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

Throws:

IOException - if an exception occurred while creating the stream

CancelledException - if the user cancelled the save process.

Override:

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

retrievePersistenceInStream

protected InputStream retrievePersistenceInStream()
                                           throws IOException,
                                                  CancelledException

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

Throws:

IOException - if an exception occurred while creating the stream

CancelledException - if the user cancelled the save process.

Override:

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

setObjectPersistent

public Object setObjectPersistent(Object oKey,
                                  Object oToPersistify)

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

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.

Override:

Never

setObjectTransient

public Object setObjectTransient(Object oKey)

Set an object to be no longer persistent.

Parameters:

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

Returns:

the object that was made transient.

Override:

Never

getPersistentObject

public Object getPersistentObject(Object oKey)

Get a persistent object.

Parameters:

oKey - the key that describes the object.

Returns:

the persistent object.

Override:

Never

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

Parameters:

sTitle - the new title.

Override:

Never

getShopFrameTitle

public String getShopFrameTitle()

getShopFrame

protected JFrame getShopFrame()

Gets 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, use createShopFrame() instead

createShopFrame

protected MultiWindow createShopFrame()

Creates and returns a new MultiWindow with window view mode set.

Override:

Sometimes If you want to customize the Shop frame create and return yours here. The customized Shop frame must be a MultiWindow or a subclass of it.

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

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.

Returns:

the Shop's Timer

Override:

Never

setTimer

public void setTimer(Timer trTimer)

Set the Shop's Timer.

Parameters:

trTimer - the Timer to be used from now on

Override:

Never

log

public void log(Loggable la)
         throws IOException

Log a piece of information to the global log file.

Parameters:

la - the information to be logged.

Throws:

IOException - on any error while logging.

Override:

Never

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.

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.

Override:

Never

removeStock

public Stock removeStock(String sName)

Remove a Stock from the global list of Stocks.

Parameters:

sName - the name of the Stock to be removed.

Returns:

the removed Stock, if any.

Override:

Never

getStock

public Stock getStock(String sName)

Look up a Stock in the global Stock list.

Parameters:

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

Returns:

the Stock, if any.

Override:

Never

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.

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.

Override:

Never

removeCatalog

public Catalog removeCatalog(String sName)

Remove a catalog from the global table of Catalogs.

Parameters:

sName - the name of the Catalog to be removed.

Returns:

the Catalog that was removed, if any.

Override:

Never

getCatalog

public Catalog getCatalog(String sName)

Get a Catalog from the global list of Catalogs.

Parameters:

sName - the name of the Catalog to be returned.

Returns:

the associated Catalog, if any.

Override:

Never

getTheShop

public static Shop getTheShop()

Get the global, singleton Shop instance.

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