Developing a Design-Time GUI

The ADKs design-time framework provides the tools you will use to build the web-based GUI that adapter users need to define, deploy, and test their application views. Although each adapter has EIS-specific functionality, all adapters require a GUI for deploying application views. The design-time framework minimizes the effort required to create and deploy these interfaces, primarily by using these two components:

This section includes information on the following subjects:

Introduction to Design-Time Form Processing

There are a variety of approaches to processing forms using Java Servlets and JSPs. The basic requirements of any form processing approach are:

Form Processing Classes

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 by using a Model-View-Controller paradigm. There are five classes involved in the form processing mechanism:

RequestHandler

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 adapters. You will need to extend this class to supply adapter/EIS specific logic.

ControllerServlet

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 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.

ActionResult

com.bea.web.ActionResult

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.

Word and Its Descendants

com.bea.web.validation.Word

AbstractInputTagSupport and Its Descendants

com.bea.web.tag.AbstractInputTagSupport

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

Submit Tag

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

Prerequisites

Before forms can be processed, the following must occur:

Listing 8-1 Sample JSP Form

<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

Figure 8-1 UI Form Processing Sequence Diagram

Design-Time Features

Design-time development has its own features, different from those associated with run-time adapter development. This section describes those features.

Java Server Pages

A design-time GUI is comprised of a set of ten Java Server Pages. JSPs are simply HTML pages that call Java servlets to invoke some transaction. To the user, the JSP looks just like any other web page.

The JSPs that comprise a design-time GUI are:

JSP Templates

The design-time framework provides a set of JSP templates for rapidly assembling a web application to define, deploy, and test a new application view for an adapter. A template is an HTML page that is dynamically generated by a Java Servlet based on parameters provided in the HTTP request. Templates are used to minimize the number of custom pages and custom HTML needed for a web application. The templates supplied by the ADK provide three primary features for adapter developers.

The ADK Tag Library

The JSP tag library helps to develop user-friendly HTML forms and abstracts complexity from the adapter page developers. Custom tags for form input components allow page developers to seamlessly link to the validation mechanism. Custom tags are provided for the following HTML input tags:

JSP Tag Attributes

Note: For more information on tag usage, see adk.tld in:

WLI_HOME/adapters/src/war/WEB-INF/taglibs

JavaScript Library

The ADK provides JavaScript for opening and closing child windows.

The Application View

File Structure

The Flow of Events

Figure 8-2 Design-Time GUI Development Flow of Events

Step 1: Development Considerations

These are the items you need to consider before commencing with design-time GUI development:

Step 2: Determining the Screen Flow

Next, you need to determine the order in which the JSPs will appear when the user displays the application view. This section describes the basic, required screen flow for a successful application view. Note that these are minimum requirements, as you can add more screens to the flow to meet your specific needs.

Screen 1: Logging In

The application view is a secure system, therefore, the user will need to log in before he or she can implement the view. The Application View Console - Logon page thus must be the first page the user sees.

To use this page, the user supplies a valid username and password. That information is then validated to ensure that the user is a member of the adapter group in the default WebLogic Server security realm.

Note: The security for the Application View web application is specified in the WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml file, which is shipped in the wlai.war file.

Screen 2. Managing Application Views

Once the user successfully logs in, the Application View Management Console page appears. This page lists the folders that contain the application views, the status of these folders, and any action taken on them. From this page, the user can either view existing application views or add new ones.

Screen 3: Defining the New Application View

The Define New Application View page (defappvw.jsp) allows the user to define a new application view in any folder in which the client is located. To do this, the user needs to provide a description that associates the application view with an adapter. This form provides text boxes for entering the application view name and description and a drop-down list box displaying adapters with which the user can associate the application view.

Once the new adapter is defined, the user selects OK and the Configure Connection page appears.

Screen 4: Configuring the Connection

If the new application view is valid, the user will need to configure the connection. Therefore, once the application view is validated, the next screen in the flow should be the Configure Connection Parameters page (confconn.jsp). This page provides a form for the user to specify connection parameters for the EIS. Since connection parameters are specific to every EIS, this page is different across all adapters.

When the user submits the connection parameters, the adapter attempts to open a new connection to the EIS using the parameters. If successful, the user is forwarded to the next page, Application View Administration.

Screen 5: Administering the Application View

With a new application view created, the user will need a way of administering it. Therefore, the next screen in the flow should be the Application View Administration page (appvwadmin.jsp). This page provides a summary of an undeployed application view. Specifically, it shows the following:

In addition to providing a list of events and a list of services on the application view, the page provides a link to add a new event or service.

Screen 6: Adding an Event

The user will obviously need to add new events to an application view. Therefore, the Application View Administration page contains a link to the Add Event page (addevent.jsp). This page allows the user to add a new event to the application view.

The following rules apply to a new event:

After adding and saving a new event, the user will be returned to the Application View Administration page.

Screen 7: Adding a Service

As with events, the user will also need to add new services to an application view. Therefore, the Application View Administration page contains a link to the Add Service page (addservc.jsp). This page allows the user to add a new service to the application view.

The following rules apply to a new event:

After adding and saving a new service, the user will be returned to the Application View Administration page.

Screen 8: Deploying an Application View

Once the user adds at least one service or event, he or she can deploy the application view. Deploying an application view makes it available to process events and services. If the user chooses to deploy the application view, he or she will be forwarded to the Deploy Application View page (depappvw.jsp).

This screen allows the user to specify deployment properties. The user can specify:

Controlling User Access

The user can grant or revoke a user's access privileges by specifying a user or group name in the form provided. Each application view has two types of access: read and write.

Deploying the Application View

The user deploys the application view by clicking the deploy button. He or she must decide whether or not the application view should be deployed persistently. Persistent deployment means that the application view will be redeployed whenever the application server is restarted.

Saving the Application View

The user can save an undeployed application view and return to it later via the Application View Management Console. This process assumes that all deployed application views are saved in the repository. In other words, deploying an unsaved application view will automatically save it.

Screen 9: Summarizing the Application View

Upon successful application view deployment, the user will be forwarded to the Application View Summary page (appvwsum.jsp). This page provides the following information about an application view:

Step 3: Configuring the Development Environment

This step describes the processes you must complete to prepare your computer for design-time GUI development.

Step 3a: Create the Message Bundle

Next, you need to create the message bundle. Any message destined for the end-user should be placed in a message bundle. This bundle is simply a .properties text file that contains key=value pairs that allow you to internationalize messages. When a locale and national language are specified at run time, the contents of the message is interpreted, based upon the key=value pair and the message is presented to the user in the correct language for his or her locale.

For instructions on creating a message bundle, please refer to the JavaSoft tutorial on internationalization at:

Step 3b: Configure the Environment to Update JSPs Without Restarting the WebLogic Server

The design-time UI is deployed as a J2EE web application from a .war file. A .war file is simply a .jar file with a web application descriptor in WEB-INF/web.xml in the .jar file. However, the .war file does not allow the J2EE Web container in WebLogic Server to re-compile JSP's on the fly. Consequently, you normally have to restart WebLogic Server just to change a JSP file. Since this goes against the spirit of JSP, the ADK suggests the following workaround to enable you to update JSPs without restarting WebLogic Server:

For more information on precompiling JSPs, see:

Step 4: Implementing the Design-Time GUI

To implement the design-time GUI, you need to implement the DesignTimeRequestHandler class. This class accepts user input from a form and performs a design-time action. To implement this class, you must extend the AbstractDesignTimeRequestHandler provided with the ADK; see the Javadoc for this class for a detailed overview of the methods provided by this object.

Extend AbstractDesignTimeRequestHandler

The AbstractDesignTimeRequestHandler provides utility classes for deploying, editing, copying, and removing application views on the WebLogic Server. It also provides access to an application view descriptor. The application view descriptor provides the connection parameters, list of events, list of services, log levels, and pool settings for an application view. The parameters are shown on the Application View Summary page.

At a high-level, the AbstractDesignTimeRequestHandler provides an implementation for all actions that are common across adapters. Specifically, these actions are:

Methods to Include

To ensure these actions, you must supply the following methods when you create the concrete implementation of AbstractDesignTimeRequestHandler:

You also need to provide in every concrete implementation of AbstractDesignTimeRequestHandler the following two methods:

Step 4a. Supply the ManagedConnectionFactory Class

To supply the ManagedConnectionFactory class, you need to implement the following method:

protected Class getManagedConnectionFactoryClass();

This method returns the SPI ManagedConnectionFactory implementation class for the adapter. This class is needed by the AbstractManagedConnectionFactory when attempting to get a connection to the EIS.

Step 4b. Implement initServiceDescriptor()

Listing 8-7 initServiceDescriptor() Implementation

protected abstract void initServiceDescriptor(ActionResult result,
                                   IServiceDescriptor sd,
                                   HttpServletRequest request)
     throws Exception

This method is invoked by the AbstractDesignTimeRequestHandler's addservc() implementation. It is responsible for initializing the EIS-specific information of the IServiceDescriptor parameter. The base class implementation of addservc() handles the error handling, etc. The addservc() method is invoked when the user submits the addservc JSP.

Step 4c. Implement initEventDescriptor()

Listing 8-8 initEventDescriptor() Implementation

protected abstract void
    initEventDescriptor(ActionResult result,
                        IEventDescriptor ed,
                        HttpServletRequest request)
    throws Exception;

This method is invoked by the AbstractDesignTimeRequestHandler's addevent() implementation. It is responsible for initializing the EIS-specific information of the IServiceDescriptor parameter. The base class implementation of addevent() handles such concepts as error handling. The addevent() method is invoked when the user submits the addevent JSP. You should not override addevent, as it contains common logic and delegates EIS-specific logic to initEventDescriptor().

Note: When adding properties to a service descriptor, the property names must follow the bean name standard otherwise the service descriptor does not update the InteractionSpec correctly.

Step 5: Write the HTML Forms

The final step to implementing a design-time GUI is to write the various forms that comprise the interface.

The following sections describe how to actually code these forms and include a sample of that code.

Step 5a: Create the confconn.jsp Form

This page provides an HTML form for users to supply connection parameters for the EIS. You are responsible for providing this page with your adapter's design-time web application. This form posts to the ControllerServlet with doAction=confconn. This implies that the RequestHandler for your design-time interface must provide the following method:

public ActionResult confconn(HttpServletRequest request) throws
   Exception

The implementation of this method is responsible for using the supplied connection parameters to create a new instance of the adapter's ManagedConnectionFactory. The ManagedConnectionFactory supplies the CCI ConnectionFactory, which is used to obtain a connection to the EIS. Consequently, the processing of the confconn form submission verifies that the supplied parameters are sufficient for obtaining a valid connection to the EIS.

Listing 8-9 Coding confconn.jsp

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
<form method='POST' action='controller'>
    <table>
        <tr>
            <td><adk:label name='userName' required='true'/></td>
            <td><adk:text name='userName' maxlength='30' size=
               '8'/></td>
        </tr>
        <tr>
            <td><adk:label name='password' required='true'/></td>
            <td><adk:password name='password' maxlength='30' 
                size='8'/></td>
        </tr>
        <tr>
            <td colspan='2'><adk:submit name='confconn_submit'
               doAction='confconn'/></td>
        </tr>
    </table>
</form>

Including the ADK Tag Library

The line:

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>

Posting the ControllerServlet

The line:

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

Displaying the Label for the Form Field

The line:

<adk:label name='userName' required='true'/>

displays a label for a field on the form. The value that is displayed is retrieved from the message bundle for the user. The "required" attribute indicates if the user must supply this parameter to be successful.

Displaying the Text Field Size

The line:

<adk:text name='userName' maxlength='30' size='8'/>

sets a text field of size 8 with maximum length (max length) of 30.

Displaying a Submit Button on the Form

The line:

<adk:submit name='confconn_submit' doAction='confconn'/>

displays a button on the form that allow the adapter user to submit the input. The label on the button will be retrieved from the message bundle using the confconn_submit key. When the form data is submitted, the ControllerServlet will locate the confconn method on the registered request handler (see the RequestHandlerClass property) and pass the request data to it.

Implementing confconn()

The AbstractDesignTimeRequestHandler provides an implementation of the confconn() method. This implementation leverages the Java Reflection API to map connection parameters supplied by the user to setter methods on the adapter's ManagedConnectionFactory instance. You only need to supply the concrete class for your adapter's ManagedConnectionFactory by implementing this method:

public Class getManagedConnectionFactoryClass()

Step 5b: Create the addevent.jsp form

Listing 8-10 Sample Code Creating the addevent.jsp Form

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
<form method='POST' action='controller'>
    <table>
        <tr>
            <td><adk:label name='eventName' required='true'/></td>
            <td><adk:text name='eventName' maxlength='100' 
               size='50'/></td>
        </tr>
        <tr>
            <td colspan='2'><adk:submit name='addevent_submit'
               doAction='addevent'/></td>
        </tr>
    </table>
</form>

The following paragraphs describe the contents of addevent.jsp:

Including the ADK Tag Library

The line:

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk'%>

Posting the ControllerServlet

The line:

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

Displaying the Label for the Form Field

The line:

<adk:label name='eventName' required='true'/>

displays a label for a field on the form. The value that is displayed is retrieved from the message bundle for the user. The "required" attribute indicates if the user must supply this parameter to be successful.

Displaying the Text Field Size

The line:

<adk:text name='eventName' maxlength='100' size='50'/>

sets a text field of size 50 with maximum length (max length) of 100.

Displaying a Submit Button on the Form

The line:

<adk:submit name='addevent_submit' doAction='addevent'/>

displays a button on the form that allow the adapter user to submit the input. The label on the button will be retrieved from the message bundle using the addevent_submit key. When the form data is submitted, the ControllerServlet will locate the addevent() method on the registered request handler (see the RequestHandlerClass property) and pass the request data to it.

Adding Additional Fields

You must also add any additional fields that the user requires for defining an event. See the DBMS or e-mail adapters for examples of forms with multiple fields.

Step 5c: Create the addservc.jsp form

Listing 8-11 Coding addservc.jsp

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
<form method='POST' action='controller'>
    <table>
        <tr>
            <td><adk:label name='serviceName' required='true'/>
               </td>
            <td><adk:text name='serviceName' maxlength='100' 
              size='50'/></td>
        </tr>
        <tr>
           <td colspan='2'><adk:submit name='addservc_submit'
               doAction='addservc'/></td>
        </tr>
    </table>
</form>

Including the ADK Tag Library

The line:

<%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>

Posting the ControllerServlet

The line:

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

Displaying the Label for the Form Field

The line:

<adk:label name='servcName' required='true'/>

displays a label for the form field. The value that is displayed is retrieved from the message bundle for the user. The "required" attribute indicates if the user must supply this parameter to be successful.

Displaying the Text Field Size

The line:

<adk:text name='eventName' maxlength='100' size='50'/>

sets a text field of size 50 with maximum length (max length) of 100.

Displaying a Submit Button on the Form

The line:

<adk:submit name='addservc_submit' doAction='addservc'/>

displays a button on the form that allow the adapter user to submit the input. The label on the button will be retrieved from the message bundle using the addservc_submit key. When the form data is submitted, the ControllerServlet will locate the addservc method on the registered RequestHandler (see the RequestHandlerClass property) and pass the request data to it.

Adding Additional Fields

You must also add any additional fields that the user requires for defining a a service. See the DBMS or e-mail adapters for examples of forms with multiple fields.

Step 5d: Implement Edit Events and Services (optional)

If you want to give adapter users the capability of editing events and services during design time, you will need to edit the wlai.properties file, create the edtservc.jsp and edtevent.jsp forms, and implement some specific methods. This step describes those tasks.

Note: This step is optional. You do not need to provide users with these capabilities.

Update wlai.properties

First, update the system properties in wlai.properties for the sample adapter by making the following changes to that file:

After updating wlai.properties, compare the files to ensure sure that they are synchronized.

Create edtservc.jsp and addservc.jsp

These Java server pages are called in order to provide editing capabilities. The main difference between the edit JSPs and the add JSP files is the loading of descriptor values. For this reason, the DBMS and e-mail adapters use the same HTML for both editing and adding.

These HTML files are statically included in the JSP page. This saves duplication of JSP/HTML and properties. The descriptor values are mapped into the controls displayed on the edit page. From there, you can submit any changes.

In order to initialize the controls with values defined in the descriptor, call the loadEvent/ServiceDescriptorProperties() method on the AbstractDesignTimeRequestHandler. This method sets all of the service's properties into the RequestHandler. Once these values are set, the RequestHandler maps the values to the ADK controls being used in the JSP file. The default implementation of loadEvent/ServiceDescriptorProperties() uses the property name associated with the ADK tag to map the descriptor values. If you used values other than the ADK tag names to map the properties for a service or event, override these methods to provide the descriptor to the ADK tag-name mapping.

Listing 8-12 Sample Code Used to Load edtevent.jsp

if(request.getParameter("eventName") != null){
handler.loadEventDescriptorProperties(request);
}

The edtservc.jsp should submit to edtservc. For example:

<adk:submit name='edtservc_submit' doAction='edtservc'/>

The edtevent.jsp should submit to edtevent. For example:

<adk:submit name='edtevent_submit' doAction='edtevent'/>

See the DBMS and e-mail adapters for specific examples. Go to either

WLI_HOME/adapters/dbms/src/war

or

WLI_HOME/adapters/email/src/war

Implement Methods

See the sample adapters for an example of how these methods are implemented.

Step 5e: Write the WEB-INF/web.xml Web Application Deployment Descriptor

You will need to create a WEB-INF/web.xml web application deployment descriptor for your adapter. When you clone an adapter from the sample adapter by using GenerateAdapterTemplate, a web.xml file for that adapter will be automatically generated.

Listing 8-13 web.xml Servlet Components

<servlet>
    <servlet-name>controller</servlet-name>
    <servlet-class>com.bea.web.ControllerServlet</servlet-class>
    <init-param>
        <param-name>MessageBundleBase</param-name>
        <param-value>BEA_WLS_SAMPLE_ADK</param-value>
            <description>The base name for the message bundles 
               for this adapter. The ControllerServlet uses this 
               name and the user's locale information to 
               determine which message bundle to use to 
               display the HTML pages.</description>
    </init-param>

    <init-param>
        <param-name>DisplayPage</param-name>
        <param-value>display.jsp</param-value>
            <description>The name of the JSP page 
               that includes content pages and provides 
               the look-and-feel template. The ControllerServlet 
               redirects to this page to let it determine what to 
               show the user.</description>
    </init-param>

    <init-param>
        <param-name>LogConfigFile</param-name>
        <param-value>BEA_WLS_SAMPLE_ADK.xml</param-value>
            <description>The name of the sample adapter's 
               LOG4J configuration file.</description>
    </init-param>

    <init-param>
        <param-name>RootLogContext</param-name>
        <param-value>BEA_WLS_SAMPLE_ADK</param-value>
            <description>The root category for log messages 
               for the sample adapter. All log messages created 
               by the sample adapter will have a context starting 
                with this value.</description>
    </init-param>

    <init-param>
        <param-name>RequestHandlerClass</param-name>
        <param-value>sample.web.DesignTimeRequestHandler
        </param- value>
            <description>Class that handles design 
               time requests</description>
    </init-param>

    <init-param>
        <param-name>Debug</param-name>
        <param-value>on</param-value>
            <description>Debug setting (on|off, off is
               default)</description>
    </init-param>

    <load-on-startup>1</load-on-startup>
</servlet>

Listing 8-14 web.xml ControllerServlet Mapping Component

<servlet-mapping>
    <servlet-name>controller</servlet-name>
    <url-pattern>controller</url-pattern>
</servlet-mapping>

Listing 8-15 web.xml ADK Tab Library Component

<taglib>
    <taglib-uri>adk</taglib-uri>
    <taglib-location>/WEB-INF/taglibs/adk.tld</taglib-location>
</taglib>

Listing 8-16 web.xml Security Constraint Component

<Security-constraint>
    <web-resource-collection>
        <web-resource-name>AdapterSecurity</web-resource-name>
            <url-pattern>*.jsp</url-pattern>
    </web-resource-collection>

    <auth-constraint>
        <role-name>adapter</role-name>
    </auth-constraint>

    <user-data-constraint>
        <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
</security-constraint>

Listing 8-17 web.xml Login Configuration Component

<login-config>
    <auth-method>FORM</auth-method>
    <realm-name>default</realm-name>
    <form-login-config>
        <form-login-page>/login.jsp</form-login-page>
        <form-error-page>/login.jsp?error</form-error-page>
    </form-login-config>

</login-config>

<security-role>
    <role-name>adapter</role-name>
</security-role>

Step 6. Implementing the Look-and-Feel

An important programming practice you should observe when developing a design-time GUI is to implement a consistent look-and-feel across all pages in the application view. The look-and-feel is determined by display.jsp. This page is included with the ADK and provides the following for the design-time web application:

To implement a look-and-feel across a set of pages, do the following:

Step 7. Testing the Sample Adapter Design-Time Interface

The test driver executes a number of tests. It creates application views, add both events and services to application views, deploy and undeploy application views, and test both events and services. The test driver removes all application views after completely successfully.

Files and Classes

All of the test cases are contained in the DesignTimeTestCase class or its parent class, AdapterDesignTimeTestCase. DesignTimeTestCase (located in the sample.web package and the WLI_HOME/adapters/sample/src/sample/web folder) contains the tests specific to the sample adapter. AdapterDesignTimeTestCase (located in the com.bea.adapter.web package and the WLI_HOME/lib/adk-web.jar file) contains tests that apply to all adapters and several convenience methods.

Run the tests

To the design-time interface, use this procedure: