The Navigator Framework

1. Introduction

This document describes the framework implemented in Java which can be used for servlet applications that query, insert, update, or delete database records. The idea is copied from the functionality obtained by the Oracle Designer 6, with the following improvements:

• If the number of records found is less than a certain threshold, the details of the first record are displayed immediately. No record list will be shown.
• Navigation between the details of the records obtained is done with the Next/Previous/First/Last buttons. No need to go back to the record list and select another record.
• A detail record can be inserted at the same time as the master record (parent-child relationship).
• A detail record can be updated at the same time as the master record.
• Multiple records can be inserted/deleted/updated in the record list at once.
• The screens implemented can be executed in List-Of-Value mode by just adding a few parameters to the servlet call.

2. Architecture

The interface for the user consists of one or more blocks. Basically a block corresponds to a table in the database or an EJB. A block contains the fields visible to and modifyable by the user, and forms the bridge between the user interface and the database. It has tw types of methods. Those to display the fields, depending on the state the block is in, and those to update the database (update,insert,delete). Blocks can be structured in a master-detail hierarchy, corresponding to the parent-child relationships in the database. A navigator keeps track of the states the individual blocks are in, and handles the user input. Per application, one servlet is running having one instantiation of the application's servlet class for all calls to the servlet. This object instantiates a navigator, the appropriate blocks, and tells the navigator to handle the call, based on the parameters passed. There are three types of parameters:

• The fields displayed on the screen with their values
• The function to be performed, defined by the button the user clicked on
• Internal parameters for the navigator, like the row number currently displayed

A call is handled by the navigator in two steps. First, it tells one or more blocks to perform an action, like inserting a new record into the database. Then, the appropriate methods are called in the blocks to generate the HTML for the page presented to the user as a result of his/her request.

One common servlet, called LOV, can be used by different applications. By passing the class name of the block to be instantiated and the names of the fields to paste from/to as parameters, the LOV servlet will do the necessary to navigate/display the proper block.

3. The Java code

3.1 The navigator

Different types of navigators and corresponding blocks exist, each giving more functionality than their predecessor (super). The methods a block needs to implement to be navigatable by a certain navigator are described in the following interfaces. All but the MasterDetailBlock operate on a single table in the database or EJB.

Interface name	Description	Navigator
Block	The root interface of all blocks.	Navigator (abstract)
RecordListBlock	This block queries the database and shows the resulting records in a list. The query is either static, or based on parameters passed to the servlet.	RecordListNavigator
QueryBlock	The query executed by this block is based on the critaria filled in by the user on a query screen.	QueryNavigator
LOVBlock	A QueryBlock, the records of which can be pasted back from the record list to the calling form.	LOVNavigator
UpdatableRecordListBlock	A RecordListBlock, where the user can insert/update/delete multiple records at the same time in the record list.	RecordListNavigator
SingleBlock	A record can be selected from the record list to display its full details. These details can then be modified, or the record can be deleted. Users can add new records by clicking on the 'New' button, displayed on the query screen, the record list, and the detail screen.	SingleBlockNavigator
MasterBlock	A master block has 1-n detail blocks, corresponding to child records in the database. The navigator synchronizes the different blocks. The child records are either displayed automatically in the detail block, or a query screen is diplayed for the detail block.	MasterDetailNavigator
DetailBlock	A detail block is a Block that has a master (parent)	MasterDetailNavigator
MasterDetailBlock	A MasterDetailBlock is both a MasterBlock and a DetailBlock. It's sitting somewhere in the middle of the hierarchy of Block's.	MasterDetailNavigator

A default implementation for the blocks, using the predefined fields (see 3.2) is also supplied in the framework. Note, however, that the Navigator can be reused without these implementations, they operate strictly on the Block interfaces defined.

A detailed description of the Java code can be found in the Javadoc and the description of the blocks and the navigators. In the latter UML, we see that the Navigator class holds a reference to the top master block. All detail blocks are accesible from this master block in a hierarchical manner.

3.2 The fields on the screen

A number of classes have been implemented to display fields on the pages. The basic class is the DisplayableField. A field has a label, printed in front of the field, a name, and a number of values. A field can have more than one value in the record list, for instance. Fields are displayed inside a table based on the mode the field is in (insert, update,...). For each field in a block, a DisplayableField object is created, based on a definition, and an object describing the possible values a user can enter in the field (a ValueSet). The definition contains a.o. the label, the name, and the number of rows/columns it occupies in the table.

When a field is read from the input, the ValueSet performs a check on the value and can transform the value entered by the user. This is done on the server. The check if an obligatory field is filled in by the user, and the transformation to upper case are done in the browser by a piece of JavaScript code. In addition, by specifying a maximum length for the field, the data length is forced by the browser. The ValueSet is also responsible for generating the HTML to display the field. The following ValueSet's exist:

• FreeText: the user can enter any string in an ordinary input field
• FreeTextAre: the user can enter any string in a text area
• PositiveInteger: a whole number >= 0 must be entered
• DomainField: The posible values depend on a domain. They are displayed as a select box, a radio button, or a check box (if the domain contains two and only two values). A number of predefined domains can be found in the StaticDomains and Domains classes.
• TelephoneNumber: The input field for the number is preceded by a select list of known countries. Selecting a country from the list will put its telephone code in the input field
• TextBoundByLOV (abstract): At the right of the input field, an LOV link will be generated. Clicking on this link will open a new window which will call the LOV servlet.

A number of static methods in the DisplayableField class display an array of fields for a block, based on the state of the block. A special subclass of the DisplayableField, the MultipleField, can be used for fields where the user can enter more than one value, for instance a multiple select box.

For more details, have a look at the Javadoc and UML descriptions of the fields and the value sets.

4. How to use