org.salespointframework.core
Class SaleProcess

java.lang.Object
  org.salespointframework.core.SaleProcess

All Implemented Interfaces:

ProcessErrorCodes, LogContext, Loggable

public abstract class SaleProcess
extends java.lang.Object
implements LogContext, Loggable, ProcessErrorCodes

A process. Processes are used to manipulate data in DataBaskets, Stocks, Catalogs, and any other data structures you might want to use.

Processes are viewed as finite deterministic automata, internally represented by a directed graph. The nodes of this graph are called Gates, the edges are Transitions.

Processes are persistent, i.e. they are automatically restored when the system comes up again after having been down for some time.

A process can be suspended whenever it is at a gate. When a process is asked to suspend() while it is in a transition, it will get suspended only at the next gate. For this to be feasible, transitions must be rather short, and, in particular, must not comprise any user interaction.

Since:

v2.0

Version:

2.0 17/08/1999

Author:

Steffen Zschaler

Nested Class Summary

private class	SaleProcess.PrintErrorGate The gate that is responsible for printing error messages.
private class	SaleProcess.ProcessErrorError Internal error helper, used to cancel a transition or gate when it calls error().
static class	SaleProcess.ProcessLogEntry A log entry describing a process that was executed.
private class	SaleProcess.SubProcess A thread providing an exception firewall for all subprocesses of a process.

Field Summary

static LogEntryFilter	LOGENTRYFILTER_PROCESSES_ONLY A LogEntryFilter that will accept only such LogEntries that stem from a process.
private DataBasket	m_dbWorkBasket The DataBasket used to implement transactional behavior.
private boolean	m_fResumed Flag indicating whether the process has been resumed.
private boolean	m_fSuspended Flag indicating whether the process is currently suspended.
protected Gate	m_gCurGate The current gate, if any.
private LogContext	m_lcOldBasketContext The previous log context of the current DataBasket.
private int	m_nErrorCode Last error condition.
private int	m_nErrorNesting Count error nesting, so that we do not run into infinite loops.
private java.lang.Object	m_oBasketLock The monitor synchronizing access to the DataBasket.
private java.lang.Object	m_oContextLock The monitor synchronizing access to the process context.
private java.lang.Object	m_oErrorExtraInfo Additional information concerning the cause of the last error.
private ProcessContext	m_pcContext The context in which this process runs.
private java.lang.String	m_sName The name of this process.
protected Transition	m_tCurTransition The current transition, if any.
private java.lang.Thread	m_trdMain The process' main thread.
protected Transition	prevTransition The previous Transition, if any.

Fields inherited from interface org.salespointframework.core.exceptions.ProcessErrorCodes

DATABASKET_CONFLICT_ERROR, DUPLICATE_KEY_EXCEPTION, ERR_FORCED_SHUTDOWN, ERR_INTERNAL, ERR_LOWERBOUND, ERR_NOERROR, ERR_UPPERBOUND, NOT_ENOUGH_ELEMENTS_ERROR, REMOVE_VETO_EXCEPTION

Constructor Summary

SaleProcess(java.lang.String sName)
Create a new SaleProcess with a given name.

Method Summary

DataBasket	attach(DataBasket dbNew) Attach the DataBaskte that is going to be used to implement transactional behavior for this Process.
ProcessContext	attach(ProcessContext pcNew) Attach a ProcessContext to this process.
boolean	canQuit(boolean fContextDestroy) Return true if this Process can be stopped with a subsequent quit() command.
DataBasket	detachBasket() Detach and return the current DataBasket.
ProcessContext	detachContext() Detach and return the current process context.
void	error(int nErrorCode) Raise an error in this process.
void	error(int nErrorCode, java.lang.Object oExtraInfo) Raise an error in this process.
void	error(int nErrorCode, java.lang.Throwable tExtraInfo) Raise an error in this process.
DataBasket	getBasket() Get the currently attached DataBasket.
private java.lang.Object	getBasketLock() Return the monitor synchronizing access to the DataBasket.
Gate	getCommitGate() Return the gate to jump to when performing a commit.
ProcessContext	getContext() Return the process context attached to this process.
private java.lang.Object	getContextLock() Return the monitor synchronizing access to the process context.
Gate	getCurrentGate() Return the gate at which the process currently stands or which it just left.
protected Gate	getErrorGate(int nErrorNesting) Return the gate to jump to when an error occurs.
java.lang.String	getErrorMsg(int nErrorCode) Return a readable version of the error message.
protected abstract Gate	getInitialGate() Return the initial gate for this process.
LogEntry	getLogData() Return information that describes the process for logging purposes.
Gate	getLogGate() Return the gate that the process must jump to if it wishes to be logged before finishing.
java.lang.String	getName() Return the name of this process.
Gate	getQuitGate() Return the gate to jump to when quitting the process.
Gate	getRollbackGate() Return the gate to jump to when performing a rollback.
Gate	getStopGate() Return the last gate that this process should be at.
boolean	isAlive() Return true if this process has been started, but has not yet died.
boolean	isResumed() Return true if this process has been resumed from a previous suspended state.
boolean	isRunning() Return true if this process is currently running.
boolean	isSuspended() Return true if this process is currently suspended.
void	log(Loggable la) Logs the given data to a log file.
private void	main() The central control loop of the process.
protected void	onFinished() Hook method called whenever the process was finished, independently of whether the process was really finished or just suspended.
protected void	onResumeOrStart(boolean fIsResume) Hook method called on every start or resume of the process.
protected void	onSuspended() Hook method called whenever the process was suspended.
protected void	printErrorInfo(int nErrorCode, java.lang.Object oExtraInfo) Print error information to inform the user of an error condition.
void	quit(boolean fWaitQuit) Quit the process at the nearest gate.
void	resume() Resume a previously suspended process.
void	start() Start the process.
void	suspend() Suspend the process.

Methods inherited from class java.lang.Object

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

Field Detail

m_sName

private java.lang.String m_sName

The name of this process. Used to identify the process, esp. for debug purposes.

m_pcContext

private ProcessContext m_pcContext

The context in which this process runs. Used for all user communication, log and data access.

m_oContextLock

private transient java.lang.Object m_oContextLock

The monitor synchronizing access to the process context.

m_dbWorkBasket

private DataBasket m_dbWorkBasket

The DataBasket used to implement transactional behavior.

m_lcOldBasketContext

private LogContext m_lcOldBasketContext

The previous log context of the current DataBasket.

m_oBasketLock

private transient java.lang.Object m_oBasketLock

The monitor synchronizing access to the DataBasket.

m_gCurGate

protected Gate m_gCurGate

The current gate, if any.

m_tCurTransition

protected Transition m_tCurTransition

The current transition, if any.

prevTransition

protected Transition prevTransition

The previous Transition, if any.

m_trdMain

private transient java.lang.Thread m_trdMain

The process' main thread.

m_fSuspended

private boolean m_fSuspended

Flag indicating whether the process is currently suspended.

m_fResumed

private boolean m_fResumed

Flag indicating whether the process has been resumed.

m_nErrorCode

private int m_nErrorCode

Last error condition.

m_oErrorExtraInfo

private java.lang.Object m_oErrorExtraInfo

Additional information concerning the cause of the last error.

m_nErrorNesting

private int m_nErrorNesting

Count error nesting, so that we do not run into infinite loops.

LOGENTRYFILTER_PROCESSES_ONLY

public static final LogEntryFilter LOGENTRYFILTER_PROCESSES_ONLY

A LogEntryFilter that will accept only such LogEntries that stem from a process.

Constructor Detail

SaleProcess

public SaleProcess(java.lang.String sName)

Create a new SaleProcess with a given name.

Parameters:

sName - the name of this process.

Method Detail

getContextLock

private java.lang.Object getContextLock()

Return the monitor synchronizing access to the process context.

getBasketLock

private java.lang.Object getBasketLock()

Return the monitor synchronizing access to the DataBasket.

getName

public java.lang.String getName()

Return the name of this process.

Returns:

the name of the process.

attach

public ProcessContext attach(ProcessContext pcNew)

Attach a ProcessContext to this process.

Parameters:

pcNew - the process context to be attached.

Returns:

the previously attached process context, if any.

detachContext

public ProcessContext detachContext()

Detach and return the current process context.

getContext

public ProcessContext getContext()

Return the process context attached to this process.

attach

public DataBasket attach(DataBasket dbNew)

Attach the DataBaskte that is going to be used to implement transactional behavior for this Process.

Parameters:

dbNew - the DataBasket to be attached.

Returns:

the previously attached DataBasket, if any.

detachBasket

public DataBasket detachBasket()

Detach and return the current DataBasket.

getBasket

public DataBasket getBasket()

Get the currently attached DataBasket.

canQuit

public boolean canQuit(boolean fContextDestroy)

Return true if this Process can be stopped with a subsequent quit() command.

Parameters:

fContextDestroy - true, if the quit request was issued due to a destroyal of the process' context. If false you can assume that it will be possible to restore and resume the Process after it had been quitted.

Returns:

Currently returns !fContextDestroy, so that the process can only be quitted, if it will be possible to resume it afterwards.

error

public void error(int nErrorCode)

Raise an error in this process.

First calls printErrorInfo(int, java.lang.Object) to inform the user of the error condition, then cancels the process by jumping to the "error" gate.

Attention:This method must only be called from within a gate or a transition of this process. If called from any other environment, unpredictable behavior will result.

Parameters:

nErrorCode - the error code.

error

public void error(int nErrorCode,
                  java.lang.Object oExtraInfo)

Raise an error in this process.

First calls printErrorInfo(int, java.lang.Object) to inform the user of the error condition, then cancels the process by jumping to the "error" gate.

Attention:This method must only be called from within a gate or a transition of this process. If called from any other environment, unpredictable behavior will result.

Parameters:

nErrorCode - the error code.

oExtraInfo - additional information that explains the cause of the error.

error

public void error(int nErrorCode,
                  java.lang.Throwable tExtraInfo)

Raise an error in this process.

First calls printErrorInfo(int, java.lang.Object) to inform the user of the error condition, then cancels the process by jumping to the "error" gate.

Attention:This method must only be called from within a gate or a transition of this process. If called from any other environment, unpredictable behavior will result.

Parameters:

nErrorCode - the error code.

tExtraInfo - the exception that caused the error.

printErrorInfo

protected void printErrorInfo(int nErrorCode,
                              java.lang.Object oExtraInfo)

Print error information to inform the user of an error condition.

Calls getErrorMsg(int) to resolve the error code into an error message. All occurences of "%o" in the error message are then replaced by the extra information's string representation.

If the context has a useable display a MsgForm is displayed containing the error message. Otherwise, the error message is printed to the standard error stream.

This method is never called directly, but rather called by the Framework as appropriate. Thus, it is assured, that user communication takes place at a gate only, even in the case of an error.

Parameters:

nErrorCode - the error code.

oExtraInfo - additional information concerning the cause of the error.

getErrorMsg

public java.lang.String getErrorMsg(int nErrorCode)

Return a readable version of the error message.

Parameters:

nErrorCode - the error code.

Returns:

a readable version of the error message.

suspend

public void suspend()
             throws java.lang.InterruptedException

Suspend the process.

This method will suspend the process at the nearest gate. The method will block until the process was suspended.

Throws:

java.lang.InterruptedException - if an interrupt occurs in the calling thread while waiting for the process to suspend.

isSuspended

public final boolean isSuspended()

Return true if this process is currently suspended.

Attention:This method is not synchronized. This allows you to call it from within a gate or transition without fear for deadlocks, but there might be certain rare circumstances where the several isXXX() methods' return values give an seemingly inconsistent picture.

resume

public void resume()

Resume a previously suspended process.

This method will resume the process at the gate at which it was suspended.

isResumed

public final boolean isResumed()

Return true if this process has been resumed from a previous suspended state.

Attention:This method is not synchronized. This allows you to call it from within a gate or transition without fear for deadlocks, but there might be certain rare circumstances where the several isXXX() methods' return values give an seemingly inconsistent picture.

start

public void start()

Start the process.

isAlive

public final boolean isAlive()

Return true if this process has been started, but has not yet died.

In contrast to isRunning() isAlive() will also return true for a process that has been suspended.

Attention:This method is not synchronized. This allows you to call it from within a gate or transition without fear for deadlocks, but there might be certain rare circumstances where the several isXXX() methods' return values give an seemingly inconsistent picture.

isRunning

public final boolean isRunning()

Return true if this process is currently running. The process is running, if it has been started, but not yet stopped nor suspended.

Attention:This method is not synchronized. This allows you to call it from within a gate or transition without fear for deadlocks, but there might be certain rare circumstances where the several isXXX() methods' return values give an seemingly inconsistent picture.

main

private void main()

The central control loop of the process.

onResumeOrStart

protected void onResumeOrStart(boolean fIsResume)

Hook method called on every start or resume of the process. Should perform any global process initializiation.

This method is called in the process' main thread and any uncaught exception raised in this method will lead to the process being stopped.

Parameters:

fIsResume - true if the process has not been started afresh, but rather has been resumed.

onSuspended

protected void onSuspended()

Hook method called whenever the process was suspended. This method is called in the process' main thread and any uncaught exception raised in this method will be reported from that thread.

This method is called in the process' main thread and any uncaught exception raised in this method will lead to the process being stopped.

onFinished

protected void onFinished()

Hook method called whenever the process was finished, independently of whether the process was really finished or just suspended.

You can find out whether the process was just suspended by calling isSuspended().

This method is called in the process' main thread and any uncaught exception raised in this method will be reported in this thread. This method must not call error(), however.

quit

public void quit(boolean fWaitQuit)
          throws java.lang.InterruptedException

Quit the process at the nearest gate. The process will jump to the "quit" gate.

quit() first calls suspend() then sets the current gate to be the "quit" gate and finally resume()-s the process.

Parameters:

fWaitQuit - if true, quit will block until the process ended.

Throws:

java.lang.InterruptedException - if an interrupt occured in the calling thread while waiting for the process to quit.

See Also:

getQuitGate()

getLogData

public LogEntry getLogData()

Return information that describes the process for logging purposes.

Specified by:

getLogData in interface Loggable

Returns:

the data to be stored in the log file.

See Also:

SaleProcess.ProcessLogEntry

log

public void log(Loggable la)
         throws LogNoOutputStreamException,
                java.io.IOException

Logs the given data to a log file. If the process is in a process context, the data is logged to the process context's log file. Otherwise, the global log file is used.

Specified by:

log in interface LogContext

Parameters:

la - the event to be logged.

Throws:

LogNoOutputStreamException - if no OutputStream has been specified for the log file.

java.io.IOException - if an IOException occurs when writing to the log file.

getCurrentGate

public Gate getCurrentGate()

Return the gate at which the process currently stands or which it just left.

getInitialGate

protected abstract Gate getInitialGate()

Return the initial gate for this process.

By the time this method gets called, you can assume that the working basket and the process context have been properly initialized.

getQuitGate

public Gate getQuitGate()

Return the gate to jump to when quitting the process.

Transitions starting at this gate will usually perform a rollback and will then jump to the "stop" gate.

See Also:

getStopGate(), getRollbackGate()

getErrorGate

protected Gate getErrorGate(int nErrorNesting)

Return the gate to jump to when an error occurs.

Transition starting at this gate can perform any specific error handling and should then arrive at the "rollback" gate.

When this method is called, getCurrentGate() will still deliver the last valid gate.

Parameters:

nErrorNesting - a value that indicates nested errors. This value increases with every new error, so that values greater than 1 indicate errors that occured while other errors where handled.

Returns:

As a default returns the "rollback" gate, unless nErrorNesting is greater than 1, in which case null is returned to indicate the end of the process.

getRollbackGate

public Gate getRollbackGate()

Return the gate to jump to when performing a rollback.

Transitions starting from this gate must roll back any data structures the process used.

See Also:

getStopGate()

getCommitGate

public Gate getCommitGate()

Return the gate to jump to when performing a commit.

Transitions starting from this gate must commit any data structures the process used.

See Also:

getStopGate()

getLogGate

public Gate getLogGate()

Return the gate that the process must jump to if it wishes to be logged before finishing.

Transitions from this gate should log the process into a log file of their choice and then proceed to the "stop" gate.

getStopGate

public Gate getStopGate()

Return the last gate that this process should be at.

Transitions from this gate must return null instead of a next gate.