com.ibm.eNetwork.ECL
Class ECLScreenReco

java.lang.Object
  |
  +--com.ibm.eNetwork.ECL.ECLScreenReco

public class ECLScreenReco

extends java.lang.Object

An ECLScreenReco object is the engine in the screen recognition system. It contains the methods for adding and removing descriptions of screens. It also contains the logic for recognizing those screens and for asynchronously calling back to your handler code for those screens.

Think of an object of the ECLScreenReco class as a unique "recognition set". The object can have multiple ECLPS objects that it watches for screens, multiple screens to look for, and multiple callback points to call when it sees a screen in any of the ECLPS objects.

All you need to do is set up your ECLScreenReco objects at the start of your application, and when any screen appears in any ECLPS that you want to monitor, your code will get called by ECLScreenReco.

ECLScreenReco uses the following logic for recognizing, or matching ECLScreenDesc objects, which contain ECLScreenDescriptor-derived objects, against the data in an ECLPS object:

1. All ECLScreenDescriptor-derived objects in an ECLScreenDesc object registered with an ECLScreenReco object that are not optional must pass.
2. If there are no non-optional descriptors, at least one optional descriptor must match.

The following is a code fragment showing a common use of ECLScreenReco and ECLScreenDesc:

    // Set up a screen description object. In this example, the
    // screen is identified by a cursor position, a key word, and
    // the number of fields.
    myScreenDesc = new ECLScreenDesc();
    myScreenDesc.AddCursorPos(23,1);
    myScreenDesc.AddString("LOGON");
    myScreenDesc.AddNumFields(15);
 

    // Set up screen reco object
    myScreenReco = new ECLScreenReco();
    // myECLPS is an instance of ECLPS obtained from an instance of ECLSession
    myScreenReco.AddPS(myECLPS);
    // myCallback is a class that implements ECLRecoNotify.
    // myCallback will be notified if the screen defined by our
    // screen description object is recognized.
    myScreenReco.RegisterScreen(myScreenDesc, myCallback);
 

ECLScreenReco operates in a single-step mode. The recognition engine is activated, reviews screen updates, fires a recognition event and then turns itself off. Each recognition cycle is a single step: the recognition engine is on and then it is off. Therefore the application must build complex behavior from a series of single steps (which is the methodology underlying the Macro facility).

We recommend following these points to code a step:

• 1. Compose a set one or more ECLScreenDesc instances that describes the next likely screen to appear (the desired target) including transition screens.

• 2. Add that set of descriptors to a Vector.

• 3. Use RegisterScreen( Vector, ECLRecoNotify, boolean ) to activate the screenreco engine.

• 4. When the application's ECLRecoNotify handler method NotifyEvent(ECLPS, ECLScreenDesc) is called, react by first calling the ECLScreenReco.UnregisterAllScreens() to remove the vector of screen descriptors. The screenreco engine is then inactive.

• 5. Next take whatever action is appropriate to the specific combination of ECLScreenDesc and ECLPS instances that were passed to the handler.

• 6. Loop back to step #1. The smallest set of screen descriptions that accurately describes the next possible "state transition" will increase the accuracy and efficiency of the screen recognition process. The set that was just "unplugged" may not be the most appropriate set to be "plugged in" next.

If you are using ECLScreenReco to manage screen traversals, avoid mixing in the ECLPS and ECLOIA families of WaitForXxxx() and WaitWhileXxxx() methods.

If you are using ECLScreenReco because your application is non-GUI, consider that Session in tandem with Macro is also non-GUI. The Macro facility is highly refined and supports recording and editing. Using it may considerably reduce the development effort for screen traversal logic and actions.

Constructor Summary

ECLScreenReco()
Creates an instance of ECLScreenReco.

ECLScreenReco(boolean active)
Creates an instance of ECLScreenReco with monitoring initially turned off or on.

Method Summary

void	AddECLRecoDebugListener(ECLRecoDebugListener listener) Adds the given ECLRecoDebugListener to list of listeners.
void	AddPS(ECLPS ps) Adds an ECLPS object (Presentation Space) to the screen recognition system.
void	AddPS(ECLPS ps, int eventType) Adds an ECLPS object (Presentation Space) to the screen recognition system.
void	dispose() Cleans up the object's internal environment.
void	DoReco() Performs a recognition analysis for all the currently registered screens.
boolean	IsActive() Returns the ECLScreenReco monitoring process state.
static boolean	IsMatch(ECLPS ps, ECLScreenDesc sd) Compares the particular screen description to the current content of the indicated presentation space.
void	RegisterScreen(ECLScreenDesc sd, ECLRecoNotify notify) Register an ECLScreenDesc object with the screen recognition system.
void	RegisterScreen(ECLScreenDesc sd, ECLRecoNotify notify, boolean initEvent) Register an ECLScreenDesc object with the screen recognition system.
void	RegisterScreen(java.util.Vector sds, ECLRecoNotify notify, boolean initEvent) Registers a Vector ECLScreenDesc object with the screen recognition system.
void	RemoveECLRecoDebugListener(ECLRecoDebugListener listener) Removes the given ECLRecoDebugListener from list of listeners.
void	RemovePS(ECLPS ps) Removes an ECLPS object (Presentation Space) from the screen recognition system.
void	RemovePS(ECLPS ps, int eventType) Removes an ECLPS object (Presentation Space) from the screen recognition system.
void	SetActive(boolean active) Starts or stops the ECLScreenReco monitoring process.
void	UnregisterAllScreens() Removes all registered screens from the screen recognition object.
void	UnregisterScreen(ECLScreenDesc sd, ECLRecoNotify notify) Remove an ECLScreenDesc object and its corresponding ECLRecoNotify object from the screen recognition system.

Methods inherited from class java.lang.Object

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

Constructor Detail

ECLScreenReco

public ECLScreenReco()

Creates an instance of ECLScreenReco.

ECLScreenReco

public ECLScreenReco(boolean active)

Creates an instance of ECLScreenReco with monitoring initially turned off or on.

Parameters:

active - If false, ECLScreenReco will not start monitoring until ECLScreenReco.SetActive is called. If true, monitoring will start with the first call to ECLScreenReco.RegisterScreen

Method Detail

dispose

public void dispose()

Cleans up the object's internal environment.

RegisterScreen

public void RegisterScreen(ECLScreenDesc sd,
                           ECLRecoNotify notify)

Register an ECLScreenDesc object with the screen recognition system. When the system recognizes the screen it will call the NotifyEvent method in the notify object given. The notify object is an object of an ECLRecoNotify derived class that you defined. It contains the handler or "callback" code for the recognition event. It contains your screen handling code.

Parameters:

sd - ECLScreenDesc object to register

notify - ECLRecoNotify object defined by you

See Also:

ECLRecoNotify, ECLScreenDesc

RegisterScreen

public void RegisterScreen(ECLScreenDesc sd,
                           ECLRecoNotify notify,
                           boolean initEvent)

Register an ECLScreenDesc object with the screen recognition system. When the system recognizes the screen it will call the NotifyEvent method in the notify object given. The notify object is an object of an ECLRecoNotify derived class that you defined. It contains the handler or "callback" code for the recognition event. It contains your screen handling code.

Parameters:

sd - ECLScreenDesc object to register

notify - ECLRecoNotify object defined by you

initEvent - if true, the comparison logic for the screen registered will be run

See Also:

ECLRecoNotify, ECLScreenDesc

RegisterScreen

public void RegisterScreen(java.util.Vector sds,
                           ECLRecoNotify notify,
                           boolean initEvent)

Registers a Vector ECLScreenDesc object with the screen recognition system. When the system recognizes the screen it will call the NotifyEvent method in the notify object given. The notify object is an object of an ECLRecoNotify derived class that you defined. It contains the handler or "callback" code for the recognition event. It contains your screen handling code.

Parameters:

sds - vector of ECLScreenDesc objects to register

notify - ECLRecoNotify object defined by you

initEvent - if true, the comparison logic for the screen registered will be run

See Also:

ECLRecoNotify, ECLScreenDesc

UnregisterScreen

public void UnregisterScreen(ECLScreenDesc sd,
                             ECLRecoNotify notify)

Remove an ECLScreenDesc object and its corresponding ECLRecoNotify object from the screen recognition system. Calling this method will cause the NotifyStop method to be called on all ECLRecoNotify derived objects in the screen recognition system.

Parameters:

sd - ECLScreenDesc object to unregister

notify - ECLRecoNotify object to unregister

See Also:

ECLScreenDesc

AddPS

public void AddPS(ECLPS ps)

Adds an ECLPS object (Presentation Space) to the screen recognition system. The system will monitor all ECLPS objects added to it for all ECLScreenDesc objects added to it.

Parameters:

ps - ECLPS object to add

See Also:

ECLPS

AddPS

public void AddPS(ECLPS ps,
                  int eventType)

Adds an ECLPS object (Presentation Space) to the screen recognition system. The system will monitor all ECLPS objects added to it for all ECLScreenDesc objects added to it for the given event type.

Parameters:

ps - ECLPS object to add

eventType - monitor type for the ECLPS object.

• ECLPS.HOST_EVENTS : only host screen changes will fire recognition events
• ECLPS.USER_EVENTS : only user events (typing, mouse activity, etc.) will fire recognition events
• ECLPS.ALL_EVENTS : both user and host initiated screen changes will fire recognition events

See Also:

ECLPS

RemovePS

public void RemovePS(ECLPS ps)

Removes an ECLPS object (Presentation Space) from the screen recognition system.

Parameters:

ps - ECLPS object to remove

See Also:

ECLPS

RemovePS

public void RemovePS(ECLPS ps,
                     int eventType)

Removes an ECLPS object (Presentation Space) from the screen recognition system.

Parameters:

ps - ECLPS object to remove

eventType - monitor type for the ECLPS object.

• ECLPS.HOST_EVENTS : only host screen changes will fire recognition events
• ECLPS.USER_EVENTS : only user events (typing, mouse activity, etc.) will fire recognition events
• ECLPS.ALL_EVENTS : both user and host initiated screen changes will fire recognition events

See Also:

ECLPS

AddECLRecoDebugListener

public void AddECLRecoDebugListener(ECLRecoDebugListener listener)

Adds the given ECLRecoDebugListener to list of listeners.

Parameters:

listener - The ECLRecoDebugListener to be added

See Also:

RemoveECLRecoDebugListener(com.ibm.eNetwork.ECL.screenreco.event.ECLRecoDebugListener)

RemoveECLRecoDebugListener

public void RemoveECLRecoDebugListener(ECLRecoDebugListener listener)

Removes the given ECLRecoDebugListener from list of listeners.

Parameters:

listener - The ECLRecoDebugListener to be removed

See Also:

AddECLRecoDebugListener(com.ibm.eNetwork.ECL.screenreco.event.ECLRecoDebugListener)

SetActive

public void SetActive(boolean active)

Starts or stops the ECLScreenReco monitoring process.

Parameters:

active -

• true : monitoring will start with the first call to ECLScreenReco.RegisterScreen(...)
• false : stops monitoring until ECLScreenReco.SetActive(true) is called

IsActive

public boolean IsActive()

Returns the ECLScreenReco monitoring process state.

Returns:

state of monitoring process

DoReco

public void DoReco()

Performs a recognition analysis for all the currently registered screens. This runs on a separate thread to keep from hanging the caller's code for the duration of the analysis.

UnregisterAllScreens

public void UnregisterAllScreens()

Removes all registered screens from the screen recognition object.

IsMatch

public static boolean IsMatch(ECLPS ps,
                              ECLScreenDesc sd)
                       throws ECLErr

Compares the particular screen description to the current content of the indicated presentation space.

Parameters:

ps - Presentation Space object compared for a match

sd - Screen description object that defines a match

Returns:

True if the screen in PS matches, otherwise it is false.

Throws:

ECLErr - Thrown if error in comparing ECLScreenReco to PS.

See Also:

ECLScreenDesc, ECLPS