Package com.bea.web

The com.bea.web package provides classes that implement form processing framework.

See:
Description

Class Summary

ActionResult	Encapsulates information about the outcome of processing a request.
ControllerServlet	A servlet that delegates user input (in the HTTP request object) from an HTML form to a handler method on a com.bea.web.RequestHandler instance.
FormFieldPair	Encapsulates a value and an error for a form field
RequestHandler	A base class for developing HTML form handlers.
UserAgent	Identifies a user's Web browser by inspecting the USER-AGENT field of an HTTP request.

Package com.bea.web Description

The com.bea.web package provides classes that implement form processing framework.

There are a variety of approaches to processing forms using Java Servlets and Java Server Pages (JSP). The basic requirements of any form processing approach are:

1. Display an HTML form

To accomplish this task, the developer must:

• Generate the form layout using HTML
• Indicate to the user which fields are mandatory
• Prepopulate fields with defaults, if any

1. When the user submits the form data, validate the field values in the HTTP request

To accomplish this task, the developer must:

• Supply logic to determine if all mandatory fields have a value
• For each value submitted, validate it against a set of constraints, e.g. seeing if an age field is a valid integer between 1 and 120.

1. If any field values are invalid, the form must be redisplayed to the user with an error message next to each erroneous field on the form. The error message should be localized for the user’s preferred locale if the Web application supports multiple locales. In addition, the user’s last input should be redisplayed so they do not have to re-input any valid information. The Web application should continue with Step 2 and loop as many times as needed until all fields submitted are valid.
2. Once all fields have passed coarse-grained validation, the form data must be processed. While processing the form data, an error condition may be encountered that does not relate to individual field validation, such as a Java exception. The form will need to be re-displayed to the user with a localized error message at the top of the page. As with step 3, all input fields should be saved so the user does not have to re-enter any valid information.

To accomplish this task, the Web application developer must:

• Determine which object/method implements the form processing API.
• Determine how and when to advance the user to the next page in the Web application.

1. If the form processing succeeds, the next page in the Web application is displayed to the user.

As you can imagine, or have experienced, implementing all these steps for every form in a Web application is quite a tedious and error prone development process. The ADK Design Time Framework simplifies this process for adapter developers using a Model-View-Controller paradigm. There are five classes involved in the form processing mechanism:

com.bea.web.RequestHandler

This class provides HTTP request processing logic. This class is the Model component of the MVC-based mechanism. This object is instantiated by the ControllerServlet and saved in the HTTP session under the key "handler". The ADK provides the com.bea.adapter.web.AbstractDesignTimeRequestHandler. This abstract base class implements functionality needed to deploy an application view that is common across all resource adapters. Adapter developers will need to extend this class to supply adapter/EIS specific logic.

com.bea.web.ControllerServlet

This class is responsible for receiving an HTTP request, validating each value in the request, delegating the request to a RequestHandler for processing, and determining which page to display to the user. The ControllerServlet uses Java Reflection to determine which method to invoke on the RequestHandler. The ControllerServlet uses looks for an HTTP request parameter named "doAction" to indicate the name of the method that implements the form processing logic. If this parameter is not available, the ControllerServlet does not invoke any methods on the RequestHandler.

The ControllerServlet is configured in the web.xml file for the Web application. The controller servlet is responsible for delegating HTTP requests to a method on a RequestHandler. The adapter developer does not need to provide any code to use the controller servlet. However, they must supply the following initial parameters:

MessageBundleBase: This property specifies the base name for all message bundles supplied with a resource adapter. The ADK always uses the adapter logical name for its sample adapters. However, the adapter developer is free to choose their own naming convention for message bundles. Notice that this property is also established in the ra.xml.

DisplayPage: This property specifies the name of the JSP page that controls screen flow and look-and-feel. In the sample adapter, this page is display.jsp

LogConfigFile: This property specifies the LOG4J configuration file for the adapter.

RootLogContext: This property specifies the root log context. Log context helps categorize log messages according to modules in a program. The ADK uses the adapter logical name for the root log context so that all messages from a specific adapter will be categorized accordingly.

RequestHandlerClass: This property provides the fully qualified name of the request handler class for the adapter. In the sample adapter, this value is "sample.web.DesignTimeRequestHandler".

com.bea.web.ActionResult

Encapsulates information about the outcome of processing a request. Also provides information to the ControllerServlet to help it determine the next page to display to the user.

com.bea.web.validation.Word and its descendants

All fields in a Web application require some validation. The com.bea.web.validation.Word and its descendants supply logic to validate form fields. If any fields are invalid, the Word object uses a message bundle to retrieve an internationalized/localized error message for the field. The ADK supplies the following custom validators:

Integer: determines if the value for a field is an integer within a specified range.

Float/Double: determines if the value for a field is a floating point value within a specified range.

Identifier: determines if the value for a field is a valid Java identifier.

Perl 5 Regular Expression: determines if the value for a field matches a Perl 5 regular expression.

URL: determines if the supplied value is a valid URL

Email: determines if the supplied value contains a list of valid email addresses.

Date: determines if the supplied value is a valid date using a specified date/time format

com.bea.web.tag.AbstractInputTagSupport and its descendants

The tag classes provided by the Web toolkit are responsible for:

1. Generating the HTML for a form field and pre-populating its value with a default, if applicable
2. Displaying a localized error message next to the form field if the supplied value is invalid
3. Initializing a com.bea.web.validation.Word object and saving it in Web application scope so that the validation object is accessible by the ControllerServlet using the form field’s name.

Additionally, the ADK provides a submit tag, such as:

<adk:submit name=’xyz_submit’ doAction=’xyz’/>

This tag ensures the doAction parameter is passed to the ControllerServlet in the request. This results in the ControllerServlet invoking the xyz method on the registered RequestHandler.

Form Processing Sequence

Pre-requisites

When a JSP page that contains a custom ADK input tag is being written to the HTTP response object, the tag ensures that it initializes an instance of com.bea.web.validation.Word and places it into Web application scope, keyed by the input field name. This makes the validation object available to the ControllerServlet so that it can perform coarse-grained validation on an HTTP request prior to submitting the request to the RequestHandler. For example,

<adk:int name=’age’ minInclusive=’1’ maxInclusive=’120’ required=’true’/>

The HTML for this tag will be generated when the JSP engine invokes the doStartTag method on an instance of com.bea.web.tag.IntegerTagSupport. The IntegerTagSupport instance will instantiate a new instance of com.bea.web.validation.IntegerWord and add it to Web application scope under the key "age". Consequently, the ControllerServlet can retrieve the IntegerWord instance from its ServletContext whenever it needs to validate a value for age. The validation will ensure that any value passed for age is greater than or equal to 1 and less than or equal to 120.

Lastly, the HTML form must also submit a hidden field named "doAction". The value of this parameter is used by the ControllerServlet to determine the method on the RequestHandler that can process the form.

To summarize, our JSP form looks like:

<form method=’POST’ action=’controller’>

Age: <adk:int name=’age’ minInclusive=’1’ maxInclusive=’120’ required=’true’/>

<adk:submit name=’processAge_submit’ doAction=’processAge’/>

</form>

Steps in the Sequence (also see diagram formProc.jpg)

1. User submits the form with age=10, doAction=processAge
2. ControllerServlet retrieves the age field from the HTTP request
3. ControllerServlet retrieves a com.bea.web.validation.Word object from its ServletContext using key "age". The object is an instance of com.bea.web.validation.IntegerWord.
4. ControllerServlet invokes the validate method on the Word instance and passes "10" as a parameter.
5. The Word instance determines that the value 10 is greater than or equal to 1 and is less than or equal to 120. The Word instance returns true to indicate that the value is valid.
6. The ControllerServlet retrieves the RequestHandler from the session or creates it and adds it to the session as "handler".
7. The ControllerServlet uses the Java Reflection API to locate and invoke the "processAge" method on the RequestHandler. An exception is generated if the method does not exist. The method signature is:

public ActionResult processAge(HttpServletRequest request) throws Exception

8. The RequestHandler processes the form input and returns an ActionResult object to indicate the outcome of the processing. The ActionResult contains information used by the ControllerServlet to determine the next page to display to the user. The next page information should be the name of another JSP or HTML page in your Web application, e.g. thanks would display the thanks.jsp page to the user.
9. The the ActionResult is a success, then the ControllerServlet redirects the HTTP response to the display page for the Web application. In the ADK, the display page is typically display.jsp.
10. The display.jsp includes the JSP page indicated by the content parameter, e.g. thanks.jsp, and displays it to the user.

ADK Custom Tag Library

CheckBoxTag: This tag should be used for checkboxes that require validation and state memory (i.e. whether it should be checked or not when the form is displayed).

ContentTag: This tag should be used to retrieve a localized message from the message bundle associated with the user.

LabelTag: This tag should be used to display a label for a form field. Allows the developer to specify if the field is mandatory or not. Additionally, the adapter developer can provide an image to indicate if the field is mandatory.

PasswordTag: This tag should be used to accept a password. This tag is responsible for displaying error information if a password is not valid.

RadioTag: This tag should be used to accept a radio button. This tag is responsible for saving state information (i.e. whether the tag should be checked or not).

SubmitTag: This tag should be used for a submit button on a form. It provides a hidden field that indicates the action associated with the form.

TextareaTag: This tag should be used for a textarea that requires validation.

TextTag: This tag should be used for a text field that requires validation.