sale
Class SaleProcess

java.lang.Object
  sale.SaleProcess

All Implemented Interfaces:

Serializable, LogContext, Loggable, ProcessErrorCodes

public abstract class SaleProcess
extends Object
implements LogContext, Loggable, ProcessErrorCodes, Serializable

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

Author:

Steffen Zschaler

See Also:

Serialized Form

Nested Class Summary

static class

SaleProcess.ProcessLogEntry A log entry describing a process that was executed.

Field Summary

static LogEntryFilter	LOGENTRYFILTER_PROCESSES_ONLY A LogEntryFilter that will accept only such LogEntries that stem from a process.
protected Gate	m_gCurGate The current gate, if any.
protected Transition	m_tCurTransition The current transition, if any.

Fields inherited from interface sale.ProcessErrorCodes

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

Constructor Summary

SaleProcess(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, Object oExtraInfo) Raise an error in this process.
void	error(int nErrorCode, Throwable tExtraInfo) Raise an error in this process.
DataBasket	getBasket() Get the currently attached DataBasket.
Gate	getCommitGate() Return the gate to jump to when performing a commit.
ProcessContext	getContext() Return the process context attached to this process.
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.
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.
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.
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, 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_gCurGate

protected Gate m_gCurGate

The current gate, if any.

m_tCurTransition

protected Transition m_tCurTransition

The current transition, if any.

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(String sName)

Create a new SaleProcess with a given name.

Parameters:

sName - the name of this process.

Method Detail

getName

public String getName()

Return the name of this process.

Returns:

the name of the process.

Override:

Never

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.

Override:

Never

detachContext

public ProcessContext detachContext()

Detach and return the current process context.

Override:

Never

getContext

public ProcessContext getContext()

Return the process context attached to this process.

Override:

Never

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.

Override:

Never

detachBasket

public DataBasket detachBasket()

Detach and return the current DataBasket.

Override:

Never

getBasket

public DataBasket getBasket()

Get the currently attached DataBasket.

Override:

Never

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.

Override:

Sometimes The default implementation will return !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.

Override:

Never

error

public void error(int nErrorCode,
                  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.

Override:

Never

error

public void error(int nErrorCode,
                  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.

Override:

Never

printErrorInfo

protected void printErrorInfo(int nErrorCode,
                              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.

Override:

Never

getErrorMsg

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

Override:

Sometimes Override this method whenever you define new error codes for a process.

suspend

public void suspend()
             throws InterruptedException

Suspend the process.

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

Throws:

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

Override:

Never

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.

Override:

Never

resume

public void resume()

Resume a previously suspended process.

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

Override:

Never

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.

Override:

Never

start

public void start()

Start the process.

Override:

Never

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.

Override:

Never

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.

Override:

Never

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.

Override:

Sometimes Override this method if you need special initialization code.

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.

Override:

Sometimes Override this method if you need special cleanup code for suspended processes.

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.

Override:

Sometimes Override this method if you need special cleanup code at the end of a process.

quit

public void quit(boolean fWaitQuit)
          throws 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:

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

See Also:

getQuitGate()

Override:

Never

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

Override:

Always The default implementation produces a log entry that will simply give the name of the process and the time when logging happened.

log

public void log(Loggable la)
         throws LogNoOutputStreamException,
                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.

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

Override:

Sometimes Override if you want to personalize log entries from the DataBasket.

getCurrentGate

public Gate getCurrentGate()

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

Override:

Never

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.

Override:

Always The process will start at the gate that is returned by this method. Therefore, in order to do anything sensible, you must override this method.

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

Override:

Sometimes As a default, returns the "rollback" gate.

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.

Override:

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

Override:

Sometimes As a default returns a gate with a transition that will roll back the DataBasket attached to the process and will eventually jump to the "log" gate.

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

Override:

Sometimes As a default returns a gate with a transition that will commit the DataBasket attached to the process and will eventually jump to the "log" gate.

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.

Override:

Sometimes As a default returns a gate with a transition that will log the process using the process context's log() method.

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.

Override:

Sometimes As a default just return null, indicating no further processing is to be performed.