com.wrq.vhi.script.api
Class RecordSetEventHandler

java.lang.Object
  com.wrq.vhi.script.api.RecordSetEventHandler

All Implemented Interfaces:

EventHandler

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

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

No recordset events will fire until a client makes a recordset request such as fetchRecords(). Once such a request is received, VHI will read the contents of the recordset on a screen by screen basis until enough data has been read to fulfill the client request.

The first step when reading a recordset screen is to determine its location and size. This step cannot be overridden by an event handler, but a recordset can be defined in the model to be the entire screen if need be.

The second step is to determine the location and size of each record. If the parseScreen(com.wrq.vhi.script.api.ParseScreenEvent) method is defined, VHI will defer to this method for determining the record locations and sizes.

The third step is to determine the location and size of each field within each record. If the parseRecord(com.wrq.vhi.script.api.ParseRecordEvent) method is defined, VHI will defer to this method for determining the field locations and sizes. The method will be called for each record found on the screen.

The fourth step is to read the contents of each field in each record. If a FieldEventHandler.readField(com.wrq.vhi.script.api.ReadFieldEvent) method is defined, VHI will defer to this method for reading each field in the recordset. The method will be called for each field that needs to be read. This provides the opportunity to do any needed data translation.

The fifth step is to determine if the current screen is the first or last of the recordset. If an isTerminated(com.wrq.vhi.script.api.IsTerminatedEvent) method is defined, VHI will defer to this method for making the first and last screen determination.

The sixth step is to designate which records should be visible to the client application and which records are eligible for record insertion. If a getRecordType(com.wrq.vhi.script.api.GetRecordTypeEvent) method is defined, VHI will defer to this method for categorizing the records. Typically blank and repeated records are excluded at this stage so that they will not be visible to client applications, regardless of any client provided filter expression.

As part of a recordset fetch or update API call, the client application can provide a filter expression that constrains the records retrieved or updated. The evaluation of this filter expression can be overridden by defining an applyFilter(com.wrq.vhi.script.api.ApplyFilterEvent) method. If this method is defined, VHI will defer evaluation of all client filter expressions to this method.

Field Summary

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

DEFAULT_TIMEOUT

Constructor Summary

RecordSetEventHandler()

Method Summary

boolean	applyFilter(ApplyFilterEvent event) Called to apply a client provided filter expression to a record.
int	getCurrentHostRecord(GetCurrentHostRecordEvent event) Called to get the current host record index.
int	getRecordType(GetRecordTypeEvent event) Called to identify the type of record.
void	insertRecord(InsertRecordEvent event) Called to insert a record into the recordset.
boolean	isTerminated(IsTerminatedEvent event) Called to check if this is the last screen in a scroll direction.
java.util.Map	parseRecord(ParseRecordEvent event) Called to obtain the field location and sizes for the specified record.
java.util.List	parseScreen(ParseScreenEvent event) Called to obtain the location and size of records on the current screen.
void	updateRecord(UpdateRecordEvent event) Called to update the contents of the current record.

Methods inherited from class java.lang.Object

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

Constructor Detail

RecordSetEventHandler

public RecordSetEventHandler()

Method Detail

parseScreen

public java.util.List parseScreen(ParseScreenEvent event)
                           throws ApptrieveException

Called to obtain the location and size of records on the current screen. Records will only be created from the record locations returned by this method. Indices will be assigned to the records in the order that the record locations are returned.

Any record marked as partial will be combined by VHI with adjacent partial records upon return from this event. If the last record is marked as partial it will be combined with the first record of the next screen if partial.

See RecordSetEventHandler for details about when this event is fired in relation to other recordset events.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

A list of RecordLocation objects

Throws:

ApptrieveException

parseRecord

public java.util.Map parseRecord(ParseRecordEvent event)
                          throws ApptrieveException

Called to obtain the field location and sizes for the specified record. This event will fire for each whole and combined record. The default field location will be used for any fields not returned.

See RecordSetEventHandler for details about when this event is fired in relation to other recordset events.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

A map of field names to FieldLocation objects

Throws:

ApptrieveException

isTerminated

public boolean isTerminated(IsTerminatedEvent event)
                     throws ApptrieveException

Called to check if this is the last screen in a scroll direction. This event will be fired twice per screen in the recordset: once for page up termination and once for page down termination.

See RecordSetEventHandler for details about when this event is fired in relation to other recordset events.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

true if this is the last screen in the direction specified by IsTerminatedEvent.getScrollDirection()

Throws:

ApptrieveException

getRecordType

public int getRecordType(GetRecordTypeEvent event)
                  throws ApptrieveException

Called to identify the type of record. The record type affects which records are visible to the client application and which records are considered valid insertion locations.

See RecordSetEventHandler for details about when this event is fired in relation to other recordset events.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

one of the following constants:

• GetRecordTypeEvent.NORMAL_RECORD - Visible to client applications and not an insert location
• GetRecordTypeEvent.BLANK_RECORD - Visible to client applications and an insert location
• GetRecordTypeEvent.EXCLUDED_RECORD - Not visible to client applications and not an insert location
• GetRecordTypeEvent.EXCLUDED_BLANK_RECORD - Not visible to client applications and an insert location

Throws:

ApptrieveException

applyFilter

public boolean applyFilter(ApplyFilterEvent event)
                    throws ApptrieveException

Called to apply a client provided filter expression to a record. This event will only be called if a client provides a non-empty filter expression in its recordset request.

When this event is defined, VHI will bypass its own filter expression processing and defer to this event.

See RecordSetEventHandler for details about when this event is fired in relation to other recordset events.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

true if the record matches the filter, otherwise false

Throws:

ApptrieveException

getCurrentHostRecord

public int getCurrentHostRecord(GetCurrentHostRecordEvent event)
                         throws ApptrieveException

Called to get the current host record index. The current host record is the record that the host identifies as current via some indicator on screen (cursor position, reverse video, etc). This is called before a record is selected or updated and in response to a client request to make the current recordset index the same as the current host record index.

NOTE: ScriptHostSession methods that change the terminal screen cannot be called within this event.

Parameters:

event - the event instance

Returns:

the one-based current host record index on the screen

Throws:

ApptrieveException

updateRecord

public void updateRecord(UpdateRecordEvent event)
                  throws ApptrieveException

Called to update the contents of the current record. This event encompasses executing the before update operation, writing the fields and executing the after insert operation.

Parameters:

event - the event instance

Throws:

ApptrieveException

insertRecord

public void insertRecord(InsertRecordEvent event)
                  throws ApptrieveException

Called to insert a record into the recordset. This event encompasses finding the insert location, executing the before insert operation writing the fields and executing the after insert operation.

Parameters:

event - the event instance

Throws:

ApptrieveException