com.wrq.vhi.script.api

Class ModelEventHandler

java.lang.Object

com.wrq.vhi.script.api.ModelEventHandler

All Implemented Interfaces:

EventHandler

public abstract class ModelEventHandler
extends java.lang.Object
implements EventHandler

Abstract base class for a model event handler. All classes that extend this class appear as model event handlers in the VHI design tool.

Field Summary

Fields inherited from interface com.wrq.vhi.script.api.EventHandler

DEFAULT_TIMEOUT

Constructor Summary

Constructors

Constructor and Description
ModelEventHandler()

Method Summary

Modifier and Type	Method and Description
void	clientConnected(ClientConnectedEvent event) Called when a client connects to the host session.
void	clientDisconnected(ClientDisconnectedEvent event) Called when a client disconnects from the host session.
void	errorReported(ErrorReportedEvent event) Called the moment a top level error outside the context of an event handler.
void	executeLogin(ExecuteLoginEvent event) Called immediately after a network connection has been established with the host system.
void	executeLogout(ExecuteLogoutEvent event) Called before a network connection with the host system is dropped.
java.util.List	formatError(FormatErrorEvent event) Called before an error is returned to a client.
void	moveCursor(ModelMoveCursorEvent event) Called when the cursor needs to move to a specific location on the terminal screen and the current entity, if any, has not defined how to move the cursor.
void	moveCursorBackward(ModelMoveCursorBackwardEvent event) Called when VHI wants to move the cursor to the previous rest position on the screen and the current entity, if any, has not defined a move cursor backward operation.
void	moveCursorForward(ModelMoveCursorForwardEvent event) Called when VHI wants to move the cursor to the next at rest position on the screen and the current entity, if any, has not defined a move cursor forward operation.
java.lang.String	processString(ProcessStringEvent event) Called to process a string from the client.
void	unrecognizedScreen(UnrecognizedScreenEvent event) Called to handle the arrival at an unrecognized screen.

Methods inherited from class java.lang.Object

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

Constructor Detail

ModelEventHandler

public ModelEventHandler()

Method Detail

errorReported

public void errorReported(ErrorReportedEvent event)
                   throws ApptrieveException

Called the moment a top level error outside the context of an event handler. This event will not fire in the VHI design tool, nor will the event fire if there is already an event in progress in the VHI server. This event provides the opportunity to capture screen state.

Any exception thrown from this event will be logged but otherwise ignored.

Parameters:

event - the event instance

Throws:

ApptrieveException

formatError

public java.util.List formatError(FormatErrorEvent event)
                           throws ApptrieveException

Called before an error is returned to a client. In the VHI design tool this event is fired before reporting the error to the user. The list of error messages returned from this event will be returned to the client or reported to the user.

Error messages can be created using one of the Event.createErrorMessage(int) methods.

Note that upon returning from this event, the connector used by the client to connect to VHI will often append an additional error message onto the stack. This error message provides information about which API method was invoked.

Any exception thrown from this event will be logged but otherwise ignored.

Parameters:

event - the event instance

Returns:

a list of ErrorMessage objects

Throws:

ApptrieveException

clientConnected

public void clientConnected(ClientConnectedEvent event)
                     throws ApptrieveException

Called when a client connects to the host session. This event fires after the client session has been created but before the client can make any requests. The host application will be at the model's home entity at the time the event fires.

If an exception is thrown from this event the VHI server will log the error and fail the client connection. The design tool will simply report the exception and move on.

Parameters:

event - the event instance

Throws:

ApptrieveException

clientDisconnected

public void clientDisconnected(ClientDisconnectedEvent event)
                        throws ApptrieveException

Called when a client disconnects from the host session. This event fires before the client session is destroyed. The host application will be at whatever entity the client was at when the client disconnected. Upon returning from the event, VHI will navigate to the home entity if not already there.

Any exception thrown from this event will be logged but otherwise ignored.

Parameters:

event - the event instance

Throws:

ApptrieveException

unrecognizedScreen

public void unrecognizedScreen(UnrecognizedScreenEvent event)
                        throws ApptrieveException

Called to handle the arrival at an unrecognized screen. The event handler should do whatever is needed in order to recover the host session or to return an intelligible error message:

• Send one or more keystrokes that will return the application to a recognized screen.
• Throw an exception describing a problem that cannot be handled.

If the host application is still at an unrecognized screen upon returning from the event, the current client request will fail with a dead session error.

Parameters:

event - the event instance

Throws:

ApptrieveException

executeLogin

public void executeLogin(ExecuteLoginEvent event)
                  throws ApptrieveException

Called immediately after a network connection has been established with the host system. The host system may or may not be displaying a login prompt when this event is fired. Regardless, it is the responsibility of this method to position the host application at a recognized screen. Upon returning from the event, VHI will attempt to navigate to the model's home entity if not already there.

Parameters:

event - the event instance

Throws:

ApptrieveException

executeLogout

public void executeLogout(ExecuteLogoutEvent event)
                   throws ApptrieveException

Called before a network connection with the host system is dropped. The application will be positioned at the model's home entity. This method should do whatever is needed in order to logout from the host in an orderly fashion. Upon returning from the event, the host connection will be immediately dropped.

Parameters:

event - the event instance

Throws:

ApptrieveException

moveCursorForward

public void moveCursorForward(ModelMoveCursorForwardEvent event)
                       throws ApptrieveException

Called when VHI wants to move the cursor to the next at rest position on the screen and the current entity, if any, has not defined a move cursor forward operation.

VHI will iteratively fire this event while writing attributes on a character mode host. Upon returning from the event, VHI will check if the new cursor position corresponds to an attribute that needs writing and write to it.

This event will fire in the situation where the move cursor event is not defined on either the current entity or the model. Calling defaultMoveCursor in either of these events would also cause this event to fire. See moveCursor(com.wrq.vhi.script.api.ModelMoveCursorEvent) for the list of commands.

If this event leaves the cursor position unchanged, VHI will begin iteratively calling the move cursor backwards event or command list, if defined, in lieu of this event.

Any exception thrown from this event will cause the current attribute write or command to fail.

Parameters:

event - the event instance

Throws:

ApptrieveException

moveCursorBackward

public void moveCursorBackward(ModelMoveCursorBackwardEvent event)
                        throws ApptrieveException

Called when VHI wants to move the cursor to the previous rest position on the screen and the current entity, if any, has not defined a move cursor backward operation.

If the move cursor forward event or command list ever leaves the cursor position unchanged this event will begin to iteratively fire. See moveCursorForward(com.wrq.vhi.script.api.ModelMoveCursorForwardEvent) for details.

Any exception thrown from this event will cause the current attribute write or command to fail.

Parameters:

event - the event instance

Throws:

ApptrieveException

moveCursor

public void moveCursor(ModelMoveCursorEvent event)
                throws ApptrieveException

Called when the cursor needs to move to a specific location on the terminal screen and the current entity, if any, has not defined how to move the cursor. This event will fire in response to the following commands if the cursor is not already at the requested location:

• DefaultValue
• DefaultValueEncrypted
• MoveCursor
• ShiftCursor
• TransmitToAttr
• TransmitToAttrEncrypted
• TransmitToField
• TransmitToFieldEncrypted
• TransmitToLocation
• TransmitToLocationEncrypted
• TransmitToOffset
• TransmitToOffsetEncrypted
• UpdateAttribute
• UpdateRecordSetField

If no method to move the cursor forward or backward is defined for a character mode model, this event will fire to position the cursor at each attribute and field before writing.

If the cursor is not positioned at the specified location upon returning from the event, VHI will fail the current client request.

Any exception thrown from this event will cause the current attribute write or command to fail.

Parameters:

event - the event instance

Throws:

ApptrieveException

processString

public java.lang.String processString(ProcessStringEvent event)
                               throws ApptrieveException

Called to process a string from the client. The client provided string in the processString() method will be passed unmodified to this event. The results from this event will likewise be passed unmodified back to the client.

Any exception thrown from this event will be propagated back to the client.

Parameters:

event - the event instance

Returns:

the result string

Throws:

ApptrieveException