Documentation

An EGL JSF Handler part controls a user's runtime interaction with a Web page and can do any of these tasks:

• Assign data values for submission to a JavaServer Pages (JSP) file. Those values are ultimately displayed on a Web page.
• Change the data returned from the user or from a called program.
• Forward control to another JSP file.

The JSF handler itself includes variables and the following kinds of logic:

• An on construction function, which is invoked the first time that the JSP renders the Web page. For more information, see onConstructionFunction.
• A pre-render function, which is invoked before each time the page is rendered. For more information, see onPreRenderFunction.
• A post-render function, which is invoked after the page is rendered, but before it is displayed. For more information, see onPostRenderFunction.
• A set of event handler functions, each of which is invoked in response to a specific user action (specifically, by the user clicking a button or hypertext link).
• Optionally, validation functions that are used to validate input fields.
• Private functions that can be invoked only by other JSF handler functions.

The variables in the JSF handler are accessed in two ways:

• The runtime environment accesses the data automatically. If a field in the JSP is bound to a field in the JSF handler, the result is as follows:

o After the on construction function runs and before the Web page is displayed, each JSF handler field value is written to the JSP field to which the data is bound.
o When the user submits a form in which bound JSP fields reside, the value in each field of the submitted form is copied to the associated JSF handler field. Only then is control passed to an event handler. Validation may also be required before the event handler takes control; for more information, see "Validation" in this topic.)

• The event handlers and the on construction function can also interact with the data, data stores (such as SQL databases), and called programs.

Keep the JSF Handler part simple. Although the part might include lightweight data validations such as range checks, invoke other programs to perform complex business logic. For example, perform database access in a called program only.
Output associated with a JSF handler
When you save a JSF handler, EGL places a JSP file in the WebContent\WEB-INF folder, but only under the following conditions:

• You assigned a value to the JSF handler view property, which specifies a JSP file name
• The WebContent\WEB-INF folder does not contain a JSP file of the specified name

When generating a JSF handler, EGL never overwrites a JSP file.
If a Workbench preference is set to automatic build on save, JSF handler generation occurs whenever you save the JSF handler. In any case, when you generate a JSF handler, the output is composed of the following objects:

• The page bean is a Java™ class that contains data and that provides initialization, data validation, and event-handling services for the Web page. In the documentation that refers to runtime events, the phrase JSF handler is sometimes used to refer to the page bean.
• A <managed-bean> element is placed in the JSF configuration file in your project to identify the page bean at run time.
• A <navigation-rule> element is created in the JSF application configuration file to associate a JSF outcome (the name of the JSF handler) with the JSP file to be invoked. See "Page navigation."
• A JSP file is generated when you save the JSF handler.

All data tables and records that are used by the JSF handler are also generated.
Validation

If the JSP-based JSF tags perform data conversion, validation, or event handling, the JSF runtime does the necessary processing as soon as the user submits the Web page. If errors are found, the JSF runtime can redisplay the page without passing control to the JSF handler. If the JSF handler receives control, however, it might conduct a set of EGL-based validations.
The EGL-based validations occur if you specify the following details when you declare the JSF handler:

• The element edits (such as minimum input length) for individual input fields.
• The type-based edits (character, numeric) for individual fields.
• The DataTable edits (range, match valid, and match invalid) for individual input fields; see "DataTable part."
• The validator functions for individual input fields.
• The validator function for the JSF handler as a whole.

The JSF handler oversees the edits in the following order, but only for fields whose values the user changed:

1. All the elementary and type-based edits, even if some fail.
2. If the edits in Step 1 were successful, all the table edits, even if some fail.
3. If the edits in Step 2 were successful, all the field-edit functions, even if some fail
4. If all prior edits were successful, the JSF handler edit function

The validationOrder field-level property defines the order in which both the individual input fields are edited and the field validator functions are invoked.

If no validationOrder properties are specified, the default is the order of fields defined in the JSF handler, from top to bottom. If validationOrder is defined for some but not all of the fields in a JSF handler, validation of all fields with the validationOrder property occurs first, in the specified order. Then, validation of fields without the validationOrder property occurs in the order of fields in the JSF handler, from top to bottom.

If the EGL runtime finds an error outside of a validator function, the JSF runtime code redisplays the same Web page with embedded error messages. If a validator function finds an error, the function can forward control to another Web page, but the default behavior is to redisplay the same Web page.
Runtime scenario

This section gives a technical overview of the runtime interaction of the user with the Web application server.
When the user browses to a JSP page with a supporting JSF handler, the following steps occur:

1. The Web application server performs the following actions to initialize the environment:
1. Constructs a session object to retain data that is needed across multiple interactions with the user. The session object has the following characteristics:

• If the JSF handler scope property is set to session, the page bean is assigned to the session object. However, the data in that JSF handler is not necessarily available throughout the user session. For example, if JSF handler A forwards control to JSF handler B, the data in JSF handler A is no longer available unless you included the data in one of the following:

o Arguments that you passed to the new JSF handler
o The session or request object
o A relational database or other data store

• EGL provides the following system functions, which you can use to place data into the session object and retrieve or clear data from the session object:

o j2eeLib.setSessionAttr()
o j2eeLib.getSessionAttr()
o j2eeLib.clearSessionAttr()
2. Constructs a request object to retain data on the current interaction with the user. The request object has the following characteristics:

• If the JSF handler scope property is set to request, the page bean is assigned to the request object.
• EGL provides the following system functions, which you can use to place data into the request object and retrieve or clear data from the request object:

o j2eeLib.setRequestAttr()
o j2eeLib.RequestAttr()
o j2eeLib.clearRequestAttr()
3. Initializes the JSF runtime code
2. The JSF runtime performs the following actions:
1. Invokes the JSP file, which a JSF configuration table associates with a particular page bean
2. Creates the page bean
3. Assigns the page bean to the session or request object, depending on the value of the JSF handler scope property
4. Gives control to the on construction function of the page bean (if any), passing along any user-specified arguments
3. The JSP accesses data directly from the page bean for inclusion in the Web page, and then displays the Web page to the user, leaving the session object in place and (temporarily) leaving the request object in place
4. The Web page receives an event. For example, the user might supply data in the on-screen fields associated with an HTML <FORM> tag, then click the Submit button to invoke a JSF handler function.
5. The JSF runtime performs the following actions:
1. Destroys the request object. If the scope property for the JSF handler was set to request, removes the page bean
2. Constructs a new request object
3. Performs the following actions only if the JSF handler scope property is set to request:
1. Creates the page bean.
2. Assigns the page bean to the request object.
3. Gives control to the on construction function of the page bean (if any), passing along any user-specified arguments
4. Handles JSF validation (only a subset of JSF validation is possible in the context of EGL JSF handler processing) and then performs one of the following actions:

• Places the user data into the page bean (if the input was found to be valid from a JSF point of view).

*

• Redisplays the Web page with JSF messages (if the input was not valid). The subsequent steps in this scenario occur only if the input data is valid.

5. Places the data received from the submitted form into the page bean, for EGL validation (see "Validation" in this topic). If no error occurs, the JSF runtime code invokes the JSF handler function associated with the user's request:

• If the function ends without issuing a forward statement, the JSF runtime code redisplays the same Web page without invoking the on construction function again.
• If the function ends with a forward statement that refers to the same Web page, the situation is the same as in the previous case; the on construction function is not invoked again.
• If the function ends with a forward statement that refers to a different page, the data in the page bean is lost, although you can pass arguments and retain values in either the session or request object.