Recovery
System

Subsystem
list

Top
level

The RECbase Class

This is an abstract base class for all recovery objects. The purpose of a recovery object is to encapsulate error recovery behaviour. This behaviour happens, predictably, at the following times:

ScriptEnter
TestcaseEnter
TestcaseExit
ScriptExit

The sorts of things that a recovery object might do are:

Check to see if a particular window is open, and open it if necessary.
Check to see if an error dialog is active, and dismiss it if necessary.
Check to see if a window is in a particular state, and restore that state if necessary. "State" may include position, size, and other options, settings or attributes.
Check to see that the application is running, and launch it if necessary.

The intent of the recovery system is that a single recovery object concern itself with a relatively narrow slice of the application, called the Recovery Target. The examples given above would typically be handled by separate recovery objects.

Methods

`boolean`	`IsHappy`	`(RECphase ePhase, boolean logFirstFailure)`
`void`	`BeHappy`	`(RECphase ePhase)`
`list of RECwindowUid`	`VetoWindowClosure`	`(RECphase ePhase, list of RECwindowUid luWindowsToClose)`
`void`	`WelcomeToGroup`	`(RECobject rGroup)`

Example of Usage

RECbase::IsHappy

This method returns whether the recovery object's recovery target is in its base state. If the recovery target is in its base state, this method returns TRUE. If the recovery target is not in its base state, this method logs the discrepancy to the results file (see below) and returns FALSE.

By convention, this method is not permitted to alter the state of the application. Also by convention, the recovery object for a specific window is not permitted to return FALSE simply because the window is obscured by another window.

The IsHappy method of RECbase alway returns TRUE, and does nothing else.

Declaration

boolean IsHappy (RECphase ePhase, boolean logFirstFailure)

Inputs

ePhase: Identifies the recovery phase during which this method is called. Typically, this is only useful for optimizing the recovery process so that some recovery is done during TestcaseEnter (usually making sure windows are open) and some is done during TestcaseExit (usually making sure dialogs go away).
logFirstFailure: If TRUE, then the first problem found should be logged as an error. If FALSE, then the first problem should be logged, but not as an error. Subsequent problems should be logged, but not as errors.
This parameter is set to FALSE during ScriptEnter, and TRUE during the other recovery phases. Recovering from whatever state the application happened to be left in, prior to running a script, should not be considered an error of that script.

Outputs

Returns: TRUE if the recovery target is in its base state; otherwise FALSE.

Overriding

In general, you should always call the inherited method before performing additional checking. (You can omit this if you derive directly from RECbase which does nothing.) If the inherited method returns FALSE, there's probably no point in continuing, and your overridden method should just return FALSE as well.

RECbase::BeHappy

This method attempts to return the recovery target to its base state. If it was unsuccessful, it raises an exception. If this recovery object is contained within a recovery object derived from RECgroup, some exceptions may be handled by that container object. For more information, see RECgroup::MakeHappy and RECapplication::MakeHappy.

This method can assume that the object's IsHappy method was called immediately before calling BeHappy.

The BeHappy method of RECbase does nothing; it is intended to be overridden.

Declaration

void BeHappy (RECphase ePhase)

Inputs

ePhase: Identifies the recovery phase during which this method is called. Typically, this is only useful for optimizing the recovery process so that some recovery is done during TestcaseEnter (usually making sure windows are open) and some is done during TestcaseExit (usually making sure dialogs go away).

Outputs

(none)

Exceptions

X_REC_OBSCURED_BY_WINDOW: This exception means that the recovery object could not restore the base state because its window was obscured by a floating window or modal dialog. The exception data, which can be obtained from the built-in 4Test function ExceptData, is the RECwindowUid for the window that's in the way.
X_REC_TRY_AGAIN_LATER: This exception means that the recovery object could not restore the base state, but expects to be able to restore it after other recovery objects have been invoked.

Overriding

In general, you should always call the inherited method before performing additional processing. (You can omit this if you derive directly from RECbase which does nothing.)

RECbase::VetoWindowClosure

This method takes a list of windows that are currently open, and removes from that list any windows that the recovery object does not want to be closed. Failure to remove a window from the list does not guarantee its closure, as some other recovery object may remove it from the list.

If you need or want to know why this data type is necessary, look here.

Declaration

list of RECwindowUid 
	VetoWindowClosure (RECphase ePhase, 
		list of RECwindowUid luWindowsToClose)

Inputs

ePhase: Identifies the recovery phase during which this method is called.
luWindowsToClose: A list of window identifiers for currently open windows.

Outputs

Returns: The list of windows (from luWindowsToClose) that the recovery object doesn't care about.

RECbase::WelcomeToGroup

This method is called when the object becomes part of a RECgroup. It gives the object a chance to do anything special that it might need to do as a result of being included in a group. The WelcomeToGroup method of RECbase does nothing.

Declaration

void WelcomeToGroup (RECobject rGroup)

Inputs

rGroup: The group of which this object is now a part.

Outputs

(none)

Overriding

In general, you should always call the inherited method before performing additional processing. (You can omit this if you derive directly from RECbase which does nothing.)

Example of Usage

This is an example of a recovery object whose recovery target is a window called gwMyWindow, and whose base state is defined by gwMyWindow being open. Note that you should typically not be concerned with whether the window is active; that is handled by RECapplication.

winclass MyRecoveryClass : RECbase
{
    boolean IsHappy (RECphase ePhase, boolean logFirstFailure)
    {
        if (gwMyWindow.Exists())
            return TRUE;
        if (logFirstFailure) 
            CUlogError((string) gwMyWindow, " does not exist");
        return FALSE;
    }

    void BeHappy (RECphase ePhase)
    {
        if (!gwMyWindow.Exists())
        {
            gwMyWindow.Invoke();
            if (! gwMyWindow.Exists())
                raise 1, "can't open window";
        }
    }

    list of RECwindowUid VetoWindowClosure (RECphase ePhase, list of RECwindowUid luToClose)
    {   
        integer i = ListFind(luToClose, "AMyWindow::MyWindow");
        if (i != 0) ListDelete(luToClose, i);
        return luToClose;
    }
}

This page is maintained by (REMOVED).
Last updated 28 January 1999.