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:

• A web application component that allows you to build an HTML-based GUI by using Java Server Pages (JSP). This component is augmented by tools such as the JSP templates and tag library and the JavaScript library.

• The abstractDesignTimeRequestHandler class, which provides a simple API for deploying, undeploying, copying, and editing application views on a WebLogic Server.

This section includes information on the following subjects:

• Introduction to Design-Time Form Processing

• Design-Time Features

• File Structure

• The Flow of Events

• Step 1: Development Considerations

• Step 2: Determining the Screen Flow

• Step 3: Configuring the Development Environment

• Step 4: Implementing the Design-Time GUI

• Step 5: Write the HTML Forms

• Step 6. Implementing the Look-and-Feel

 

---

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:

1. Display an HTML form.

   To accomplish this task, you must:

   • Generate the form layout using HTML.

   • Indicate to the user which fields are mandatory.

   • Prepopulate fields with defaults, if any.

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

   To accomplish this task, you must:

   • Supply logic to determine if all mandatory fields have a value.

   • For each value submitted, validate it against a set of constraints; for example, seeing if an age field is a valid integer between 1 and 120.

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

4. 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 or method implements the form processing API.

   • Determine how and when to advance the user to the next page in the web application.

5. If the form processing succeeds, the next page in the web application is displayed to the user.

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.

The ControllerServlet is configured in the web.xml file for the web application. The ControllerServlet is responsible for delegating HTTP requests to a method on a RequestHandler. You do not need to provide any code to use the ControllerServlet. However, you must supply the initial parameters listed in Table 8-5.

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

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 custom validators described in Table 8-1.

Table 8-1 Custom Validators for Word Object

Validator	Description
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 e-mail addresses.
Date	Determines if the supplied value is a valid date using a specified date/time format

 

AbstractInputTagSupport and Its Descendants

com.bea.web.tag.AbstractInputTagSupport

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

• Generating the HTML for a form field and pre-populating its value with a default, if applicable.

• Displaying a localized error message next to the form field if the supplied value is invalid.

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

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

This section discusses the sequence in which forms are processed. Figure 8-1 shows how forms are processed.

Prerequisites

Before forms can be processed, the following must occur:

1. When a JSP containing 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 the 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'/>

2. 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 one and less than or equal to 120.

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

Following these prerequisites, the JSP form appears as shown in Listing 8-1:

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

The sequence diagram shown in Figure 8-1 illustrates the transactions that occur during form processing.

Figure 8-1 UI Form Processing Sequence Diagram

 

The sequence is as follows:

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; for example, 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 indicated by the content parameter; for example, thanks.jsp, and displays it to the user.

 

---

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:

Table 8-2 Design-Time GUI JSPs

Filename	Description
display.jsp	The display page, also called the Adapter Home Page; this page contains the HTML necessary to create the look-and-feel of the application view.
login.jsp	The Adapter Design-Time Login page.
confconn.jsp	The Confirm Connection page; this page provides a form for the user to specify connection parameters for the EIS.
appvwadmin.jsp	The Application View Administration page; this page provides a summary of an undeployed application view.
addevent.jsp	The Add Event page; this page allows the user to add a new event to the application view.
addservc.jsp	The Add Service page; this page allows the user to add a new service to the application view.
edtevent.jsp	The Edit Event page is an optional page that allows users to edit events.
edtservc.jsp	The Edit Service page is an optional page that allows users to edit services.
depappvw.jsp	The Deploy Application View page; this page allows the user to specify deployment properties.
appvwsum.jsp	The Summary page; this page displays the following information about an application view: Deployed State; that is, whether the application view is deployed or undeployed Connection Criteria Deployment Information (pooling configuration, log level, and security) List of Events List of Services

 

For a discussion on how to implement these JSPs, please refer to Step 2: Determining the Screen Flow.

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 design-time templates provide most of the HTML forms needed to deploy an application view. In most cases, you will only have to supply three custom forms:

  • One to collect the EIS-specific connection parameters.

  • A second to collects the EIS-specific information needed to add an event.

  • A third to collect the EIS-specific information needed to add a service. In addition, you can supply a custom JSP for browsing a metadata catalog for an EIS.

• The templates also leverage the internationalization and localization features of the Java platform. The content of every page in the web application is stored in a message bundle. Consequently, the web interface for an adapter can be quickly internationalized.

• The templates centralize look-and-feel into a single location.

Refer to JSP Templates for a complete list of JSP templates provided by the ADK.

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:

Table 8-3 ADK JSP Tags

Tag	Description
adk:check box	Determines if the checkbox form field should be checked when a form is displayed; this tag does not perform validation.
adk:content	Provides access to a message in the message bundle.
adk:date	Verifies the user's input is a date value that meets a specific format.
adk:double	Verifies the user's input is a double value.
adk:email	Verifies the user's input is a vaADKlid list of e-mail addresses (one or more).
adk:float	Verifies the user's input is a float value.
adk:identifier	Verifies the user's input is a valid Java identifier.
adk:int	Verifies the user's input is an integer value.
adk:label	Displays a label from the message bundle.
adk:password	Verifies the user's input in a text field against a Perl 5 regular expression and marks the input with an asterisk (*).
adk:submit	Links the form to the validation mechanism.
adk:text	Verifies the user's input against a Perl 5 regular expression.
adk:textarea	Verifies the user's input into a text area matches a Perl 5 regular expression.
adk:url	Verifies the user's input is a valid URL.

 

JSP Tag Attributes

You can customize the JSP tags by applying the attributes listed in Table 8-4:

Table 8-4 JSP Tag Attributes

Tag	Requires Attributes	Optional Attributes
adk:int, adk:float, adk:double	name - field name	default - default value on page display maxlength - maximum length of value size - display size minInclusive - value supplied by user must be greater than or equal to this value maxInclusive - value supplied by user must be less than or equal to this value minExclusive - value supplied by user must be strictly greater than this value maxExclusive - value supplied by user must be strictly less than this value required - (default is false, not required) attrs - additional HTML attributes
adk:date	name - field name	default - default value on page display maxlength - maximum length of value size - display size required - (default is false, field is not required) attrs - additional HTML attributes lenient - should the date formatter be lenient in its parsing? default is false format - the expected format of the user's input, default is "mm/dd/yyyy"
adk:email, adk:url, adk:identifier	name - field name	default - default value on page display maxlength - maximum length of value size - display size required - (default is false, field is not required) attrs - additional HTML attributes
adk:text, adk:password	name - field name	default - default value on page display maxlength - maximum length of value size - display size required - (default is false, field is not required) attrs - additional HTML attributes pattern - a Perl 5 regular expression
adk:textarea	name - field name	default - default value on page display required - (default is false, field is not required) attrs - additional HTML attributes pattern - a Perl 5 regular expression rows - number of rows to display columns - number of columns to display

 

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

The application view represents a business-level interface to the specific functionality in an application. For more information, see The Application View.

 

---

File Structure

The file structure necessary to build a design-tim GUI adapter is the same as that required for service adapters. See Step 2a: Set Up the File Structure. In addition to the structure described there, you should also be aware that:

• The design-time interface for each adapter is a J2EE web application that is bundled as a .war file.

• A web application is a bundle of .jsp, .html and image files.

• The Web application descriptor is WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml. This descriptor instructs the J2EE web container how to deploy and initialize the web application.

 

---

The Flow of Events

Figure 8-2 outlines the steps required to develop a design-time GUI.

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:

• Determine the adapters to be supported.

  Will this GUI support event adapters? Service adapters? Both?

• Determine browsing.

  The EIS must supply functions to access the event/service catalog. If the EIS does not supply these, the user can't browse the catalogs. If the EIS does supply them, we recommend the following design principle: a call from the design-time UI to get metadata from the EIS is really no different than a call from a run-time component. Both execute functions on the back-end EIS.

  Consequently, you need to leverage your run-time architecture as much as possible to provide the design-time metadata features. You should invoke design-time specific functions that use a CCI Interaction object. The sample adapter included with the ADK provides an example/framework of this approach. You can find the sample adapater in WLI_HOME/adapters/sample.

• Determine schema generation.

  How will the adapter generate the request/response schema for a service? Will it make a call to the EIS or use some other methodology? Generally, the adapter needs to call the EIS to get metadata about a function or event. The adapter then transforms the EIS metadata into XML schema format. To make this happen, you need to invoke the SOM API. Again, the sample adapter provides instructions for implementing the SOM API. For more information on this API, see The ADK Tag Library.

• Determine the testing prerequisites.

  Will some sort of service testing be supported? If so, you need to provide:

  • A class that transforms the XML response schema into an HTML form. For an example, see:

    WLI_HOME/adapters/dbms/docs/api/com/bea/adapter/dbms/utils/class-use/TestFormBuilder.html

  • A JSP named testform.jsp that invokes the transformation and displays the HTML form. To see an example of this file, go to WLI_HOME/adapters/dbms/src/war/.

 

---

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.

• To view an existing application view, the user clicks the appropriate folder and drills down to the desired application view. The user then selects the application view and the Application View Summary page appears (appvwsum.jsp; see Screen 9: Summarizing the Application View).

• To add a new application view, the user clicks Add Application View, which will display the Define New Application View page.

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:

• Connection criteria

  The connection criteria section provides a link that returns the user to the Configure Connection page so that he or she can change connection parameters.

• List of events

  For each event on the application view, the user can do the following:

  • View the XML schema.

  • Remove the event. When the user chooses to remove the event, the system confirms this before removing the event.

  • Provide event properties.

• List of services

  For each service on the application view, the user can do the following:

  • View the request XML schema.

  • View the response XML schema.

  • Remove the service. When the user chooses to remove the service, the system will confirm that choice before removing the event.

  • Provide service properties.

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:

• Every event must have a unique name.

  • The event name can only contain a-z, A-Z, 0-9, and underscore (_) and must begin with a letter. Spaces, dots, commas, and so on are not allowed.

  • The length of the name cannot exceed 256 characters.

  • The event name must be unique to the application view. If the user specifies an event name that is not unique, the form will reload with an error message indicating that the event is already defined.

• Optionally, the user can specify a description for the event. This description cannot exceed 2048 (2K) characters.

• In addition to name and description, every event has EIS specific parameters. The collection of EIS-specific parameters define an event type for the adapter.

• Optionally, some adapters provide a mechanism for browsing the event catalog for an EIS.

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:

• Every service must have a unique name.

  • The service name can only contain a-z, A-Z, 0-9, and underscore (_) and must begin with a letter. Spaces, dots, commas, and so on are not allowed.

  • The length of the name cannot exceed 256 characters.

  • The service name must be unique to the application view. If the user specifies a service name that is not unique, the form will reload with an error message indicating that the service is already defined.

• Optionally, the user can specify a description for the service. This description cannot exceed 2048 (2K) characters.

• In addition to name and description, every service has EIS specific parameters. The collection of EIS specific parameters define an service type for the adapter.

• Optionally, some adapters provide a mechanism for browsing the service catalog for an EIS.

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:

• Connection pooling parameters

  • Minimum pool size: must be greater than or equal to 0.

  • Maximum pool size: must be greater than or equal to one.

  • Target fraction of maximum pool size: must be greater than zero and less than one.

  • Allow Pool to Shrink: is the connection pool allowed to shrink?

• Logging level: The user can specify one of four logging levels

  • Log all messages

  • Log informationals, warnings, errors, and audit messages

  • Log warnings, errors, and audit messages

  • Log errors and audit messages

• Security: The user can access a form to apply security restrictions for the application view by clicking on the link that reads Restrict Access. This creates a child window.

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.

• Read access allows the user to execute services and subscribe to events.

• Write access allows the user to deploy/edit/undeploy the application view.

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:

• Deployed state: Deployed or Undeployed

  • If the application view is deployed:

    The page will show a link to undeploy the application view. If the user chooses the Undeploy link, a child window will ask the user to confirm his choice to undeploy the application view. If the user confirms, the application view will be undeployed and the summary page will be redisplayed. Undeployed application views are still saved in the repository. This allows the user to edit or remove the application view.

    If the adapter supports the testing of events, the Summary page displays a test link for each event. Testing of events is not directly supported by the ADK. Also, if the adapter supports the testing of services, the summary page will display a test link for each service. The ADK demonstrates one possible approach to testing services by providing the testservc.jsp and testrslt.jsp files. You are free to use these pages to devise your own service testing strategy.

  • If the application view is not deployed:

    The page will show a Link to Deploy the application view. If the user chooses the Deploy link, the application view will be deployed and the application view summary page will reload.

    The page will show a link to edit the application view. If the user chooses the Edit link, a child window ask the user to confirm his or her choice to edit the application view. If the user confirms the choice to edit, the Application View Administration page appears.

    The page will show a link to remove the application view. If the user chooses the Remove link, a child window will ask the user to confirm his or her choice to remove the application view from the ADK repository. If the user confirms, the application view will be deleted from the WebLogic Integration repository and the user will be redirected to the adapter main page.

• Connection criteria

• Deployment information (pooling configuration, log level, and security)

• List of events: For each event, there will be a link to view the schema and, if supported, to test the event. The user cannot remove events from this page; they must choose to edit first.

• List of services: For each service, the page will contain a link to view the request schema and the response schema, and, if supported, to test the service. The user cannot remove services from this page; they must undeploy and edit first.

 

---

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:

http://java.sun.com/docs/books/tutorial/i18n/index.html

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:

1. Construct a valid .war file for your adapter's design-time UI. For the sample adapter, this is accomplished by using Ant. Listing 8-2 shows the target that produces the J2EE .war file:

   Listing 8-2 Sample Code Showing Target that Creates a .war File

   <target name='war' depends='jar'>

   <!-- Clean-up existing environment -->

   <delete file='${LIB_DIR}/${WAR_FILE}'/>
   <delete dir='${SRC_DIR}/war/WEB-INF/lib'/>
   <delete dir='${SRC_DIR}/war/WEB-INF/classes'/>

   <war warfile='${LIB_DIR}/${WAR_FILE}'
      webxml='${SRC_DIR}/war/WEB-INF/web.xml'>
       <fileset dir='${PROJECT_DIR}' includes='version_info.xml'/>

       <!--

       IMPORTANT! Exclude the WEB-INF/web.xml file from the WAR 
       as it already gets included via the webxml attribute above

       -->

       <fileset dir='${SRC_DIR}/war' excludes='WEB-INF/web.xml'/>

       <!--

       IMPORTANT! Include the ADK design time framework into the
       adapter's design time Web application.
       -->

       <fileset dir='${ROOT}/adk/src/war'/>

        <!-- Include classes from the adapter that support the design
       time UI -->

       <classes dir='${SRC_DIR}' includes='sample/web/*.class'/>

       <!--

       Include all JARs required by the Web application under 
       the WEB-INF/lib directory of the WAR file

       -->

      <lib dir='${LIB_DIR}' includes='${JAR_FILE}'/>

      <lib dir='${WLAI_LIB_DIR}'
         includes='adk.jar,adk-web.jar,bea.jar,
         logtoolkit.jar,webtoolkit.jar,wlai-common.jar,
         wlai-ejb-client.jar,xcci.jar,xmltoolkit.jar'/>

       <lib dir='${RESOURCE_DIR}/log4j' includes='log4j.jar'/>
       <lib dir='${RESOURCE_DIR}/OROMatcher-1.1.0a' includes=
          'oromatcher.jar'/>
       <lib dir='${RESOURCE_DIR}/xml' includes='xerces_dp1.jar'/>
       <lib dir='${RESOURCE_DIR}/xml' includes='xalan.jar'/>
   </war>

   <!-- Unjar the WAR into a temp directory; for development -->

   <unjar src='${LIB_DIR}/${WAR_FILE}' dest='${LIB_DIR}/
      BEA_WLS_SAMPLE_ADK_Web'/>

   </target>

   This Ant target constructs a valid .war file for the design-time interface in the PROJECT_ROOT/lib directory, where PROJECT_ROOT is the location under the WebLogic Integration installation where the developer is constructing the adapter; for example, the DBMS adapter is being constructed in:

   WLI_HOME/adapters/DBMS

   In addition, this target performs an "unjar" operation in the /lib directory. This extracts the .war into a temporary directory. This is the key to having WebLogic Server recompile JSPs without restarting.

   Next, load your web application into WebLogic Server and configure the development environment. Do the following:

2. To load your web application into WebLogic Server, you can use the WebLogic console, but we recommend that you edit the config.xml file for your domain; for example:

   BEA_HOME/wlserver6.1/config/mydomain/config.xml.

   Note: If you choose to edit your config.xml file, you will need to add an <application> element under the domain element:

3. Replace BEA_WLS_SAMPLE_ADK_Web with your adapter's logical name.

4. Replace WLI_HOME with the location of your WebLogic Integration installation; replace PROJECT_ROOT with the directory name of your adapter development tree, as shown in Listing 8-3.

   Listing 8-3 Sample Code Showing Name of Adapter Development Tree

   <Application Deployed="true" Name="BEA_WLS_SAMPLE_ADK_Web"
      Path="WLI_HOME\adapters\PROJECT_ROOT\lib">

       <WebAppComponent Name="BEA_WLS_SAMPLE_ADK_Web"
          ServletReloadCheckSecs="1" Targets="myserver" URI=
          "BEA_WLS_SAMPLE_ADK_Web"/>

   </Application>

   Note: If you run GenerateAdapterTemplate, the information in Listing 8-3 will be automatically updated. You can then open WLI_HOME/adapters/ ADAPTER/src/overview.html and copy and paste it as your config.xml entry.

   The key is the URI attribute of the <WebAppComponent> element. Notice that it points to BEA_WLS_SAMPLE_ADK_Web and not BEA_WLS_SAMPLE_ADK_Web.war. This is the temporary directory that you created when you created the .war file. It contains your extracted .war file contents. WebLogic Server will watch this directory for JSP changes.

5. To change a JSP, do not change it in the temporary directory; change it from the src/war directory and then rebuild the war target. Remember, when the .war file is created, it is also extracted into the directory WebLogic Server is watching. WebLogic Server will pick up the changes to the specific JSP only. The watch interval used by WebLogic Server is set by the pageCheckSeconds in WEB-INF/weblogic.xml. Listing 8-4 shows how this is done:

   Listing 8-4 Sample Code Showing How to Set the Watch Interval

   <jsp-descriptor>
       <jsp-param>
           <param-name>compileCommand</param-name>
           <param-value>/jdk130/bin/javac.exe</param-value>
       </jsp-param>
       <jsp-param>
           <param-name>keepgenerated</param-name>
           <param-value>true</param-value>
       </jsp-param>
       <jsp-param>
           <param-name>pageCheckSeconds</param-name>
           <param-value>1</param-value>
       </jsp-param>
       <jsp-param>
           <param-name>verbose</param-name>
           <param-value>true</param-value>
       </jsp-param>
   </jsp-descriptor>

   This approach also tests whether your .war file is being constructed correctly.

6. Finally, you should precompile JSPs when the server starts. This saves you from having to load every page before knowing if they will compile correctly. To enable precompilation you will need to have weblogic.xml from the sample adapter and the following element in your WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml file. Listing 8-5 shows how this is done:

   Listing 8-5 Sample Code Showing How to Enable Precompilation of JSPs

   <context-param>
       <param-name>weblogic.jsp.precompile</param-name>
       <param-value>true</param-value>
   </context-param>

You can also pre-compile your JSPs using the WebLogic JSP compiler when you build your .war target using Ant. This is accomplished by performing the tasks outlined in Listing 8-6 and described here:

• The first task creates the directory where WebLogic Server looks for JSP servlet classes at run time. Please note one caveat to using this approach: you have to specify the target server name. Consequently, it may not suffice as a deployment strategy.

• The second task invokes the JSP compiler jspc, provided in WebLogic Server. This task pre-compiles all the JSPs for your web application and places them in the WLI_HOME/adapters/ADAPTER/lib/BEA_WLS_SAMPLE_ADK_Web/ WEB-INF/_tmp_war_myserver_ myserver_BEA_WLS_SAMPLE_ADK_Web directory for your web application (this directory does not exist until you build the adapter specified in ADAPTER. Consequently, this allows you to ensure your JSPs will compile every time you build your adapter.

  Listing 8-6 Sample Code Showing an Alternate Way to Enable Precompilation of JSPs

<mkdir dir='${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web/
   WEB-INF/_tmp_war_myserver_myserver_BEA_WLS_SAMPLE_ADK_Web/
   jsp_servlet'/>

<!--
This precompiles the JSPs in the Web application during the build.
However, this will only prevent WebLogic from precompiling if the
target server is 'myserver'. If the user is using any other target
server name, the JSP pages will be re-precompiled when the server
starts
-->

<java classname='weblogic.jspc' fork='yes'>
    <arg line='-d ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web/WEB-INF/
       _tmp_war_myserver_myserver_BEA_WLS_SAMPLE_ADK_Web -webapp
       ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web -compileAll -contextPath
       BEA_WLS_SAMPLE_ADK_Web -depend -keepgenerated'/>
<classpath refid='CLASSPATH'/>
</java>

For more information on precompiling JSPs, see:

http://download.oracle.com/docs/cd/E13222_01/wls/docs61/jsp/reference.html#precompile

 

---

Step 4: Implementing the Design-Time GUI

Implementing the steps described in Introduction to Design-Time Form Processing for every form in a web application is a tedious and error prone development process. The design-time framework simplifies this process when you are using a Model-View-Controller paradigm.

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:

• Define the application view.

• Configure the connection.

  Note: The ADK provides the method to process connection parameters to obtain a CCI connection but does not supply the confconn.jsp. See Step 5a: Create the confconn.jsp Form for instructions on creating this form.

• Deploy the application view.

• Provide application view security.

• Edit the application view.

• Undeploy the application view.

Methods to Include

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

• initServiceDescriptor();

  This method adds a service to an application view at design time (see Step 4b. Implement initServiceDescriptor()).

• initEventDescriptor();

  This method adds an event to an application view at design time (see Step 4c. Implement initEventDescriptor()).

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

• protected String getAdapterLogicalName();

  This method returns the adapter logical name and is used to deploy an application view under an adapter logical name.

• protected Class getManagedConnectionFactoryClass();

  This method returns the SPI ManagedConnectionFactory implementation class for the adapter.

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()

For service adapters, you need to implement initServiceDescriptor() so that the adapter user can add services at design time. This method is implemented as shown in Listing 8-7:

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()

For event adapters, you will need to implement initEventDescriptor() so that the adapter user can add events at design time. This method is implemented as shown in Listing 8-8:

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.

• See Java Server Pages for a list and description of the necessary forms.

• See Step 2: Determining the Screen Flow for the specific details of each form.

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.

The confconn form for the sample adapter is shown in Listing 8-9:

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>

The following paragraphs describe the contents of Listing 8-9.

Including the ADK Tag Library

The line:

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

instructs the JSP engine to include the ADK tag library. These tags are listed in Table 8-3.

Posting the ControllerServlet

The line:

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

instructs the form to post to the ControllerServlet. The ControllerServlet is configured in the web.xml file for the web application and is responsible for delegating HTTP requests to a method on a RequestHandler. You do not need to provide any code to use the ControllerServlet; however, you must supply the initial parameters, described in Table 8-5:

Table 8-5 ControllerServlet Parameters

Parameter	Description
MessageBundleBase	This property specifies the base name for all message bundles supplied with an adapter. The ADK always uses the adapter logical name for its sample adapters. However, you are free to choose your 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 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". See below for details on implementing a DesignTimeRequestHandler.

 

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

This form allows the user to add a new event to an application view. This form is EIS specific. The addevent.jsp form for the sample adapter is shown in Listing 8-10:

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'%>

instructs the JSP engine to include the ADK tag library. These tags are described in Table 8-3.

Posting the ControllerServlet

The line:

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

instructs the form to post to the ControllerServlet. The ControllerServlet is configured in the web.xml file for the web application and is responsible for delegating HTTP requests to a method on a RequestHandler. You do not need to provide any code to use the ControllerServlet; however, you must supply the initial parameters, as described in Table 8-5, "ControllerServlet Parameters."

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

This form allows the user to add a new service to an application view. This form is EIS-specific. The addservc.jsp form for the sample adapter is shown in Listing 8-11:

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' %>

instructs the JSP engine to include the ADK tag library. The ADK tag library supports the user-friendly form validation provided by the ADK. The ADK tag library provides the tags described in Table 8-3.

Posting the ControllerServlet

The line:

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

instructs the form to post to the ControllerServlet. The ControllerServlet is configured in the web.xml file for the web application and is responsible for delegating HTTP requests to a method on a RequestHandler. You do not need to provide any code to use the ControllerServlet; however, you must supply the initial parameters as described in Table 8-5, "ControllerServlet Parameters."

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:

• Add the following properties:

  edtservc_title=Edit Service

  edtservc_description=On this page, you edit service properties.

  edtevent_description=On this page, you edit event properties.edtevent_title=Edit Event

  glossary_description=This page provides definitions for commonly

  used terms.

  service_submit_add=Add

  service_label_serviceDesc=Description:

  service_submit_edit=Edit

  service_label_serviceName=Unique Service Name:

  event_submit_add=Add

  event_label_eventDesc=Description:

  event_label_eventName=Unique Event Name:

  event_submit_edit=Edit

  eventLst_label_edit=Edit

  serviceLst_label_edit=Edit

  event_does_not_exist=Event {0} does not exist in application view {1}.

  service_does_not_exist=Service {0} does not exist in Application View {1}.

  no_write_access={0} does not have write access to the Application View.

• Remove the following properties:

  addservc_submit_add=Add

  addevent_label_eventDesc=Description:

  addservc_label_serviceName=Unique Service Name:

  addevent_submit_add=Add

  pingTable_invalid=The ping table cannot be reached. Please enter a valid table in the existing database to ping.

  pingTable=Ping Table

  addevent_label_eventName=Unique Event Name:

  addservc_label_serviceDesc=Description:

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.

Initialize the RequestHandler prior to the resolution of HTML. This initialization should only take place once. Listing 8-12 shows the code used to load the edtevent.jsp:

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

Finally, implement the methods described in Table 8-6.

Table 8-6 Methods to Implement with edtservc.jsp and edtevent.jsp

Methods	Description
loadServiceDescriptorProperties and loadEventDescriptorProperties	These methods load the RequestHandler with the ADK tag-to-value mapping. If the developer uses the same values to name the ADK tag and load the Service/Event Descriptor, then the mapping is free. Otherwise, the developer must override these methods in their DesigntimeRequestHandler to provide these mappings.
boolean supportsEditableServices() and boolean supportsEditableEvents()	These two methods are used as markers. If they return true, the edit link is displayed on the Application View Administration page. Override in the DesigntimeRequestHandler is provided.
editServiceDescriptor and editEventDescriptor	These methods are used to persist the edited service or event data. These methods extract the ADK tag values from the request and add them back into the Service or Event Descriptor. In addition, these methods handle any special processing for the schemas associated with the event or service. If the schemas need modification, they should be updated here. Once the values read in from the request are no longer needed, they should be removed from the RequestHandler.

 

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.

The important components of this file are described in Listing 8-13 through Listing 8-17:

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>

This component shown in Listing 8-14 maps the ControllerServlet to the name "controller". This action is important because the ADK JSP forms assume the ControllerServlet is mapped to the logical name "controller".

Listing 8-14 web.xml ControllerServlet Mapping Component

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

This component shown in Listing 8-15 declares the ADK tag library:

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>

This component shown in Listing 8-16 declares the security constraints for the web application. Currently, the user must belong to the adapter group:

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>

This component shown in Listing 8-17 declares the login configuration:

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:

• Establishes the look-and-feel template for all pages.

• Includes other JSPs based on the content HTTP request parameter. If the content HTTP request parameter is not supplied, display.jsp must include main.jsp.

• Registers the error page for Java exceptions as error.jsp from the ADK.

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

1. Use display.jsp from the sample adapter as a starting point. See WLI_HOME/adapters/sample/src/war/WEB-INF/web.xml for an example.

2. Using HTML, alter the look-and-feel markup in this page to reflect your own look-and-feel or company identity standards.

3. Somewhere in your HTML markup, be sure to include:

   <%pageContext.include(sbPage.toString());%>

   This code is a custom JSP tag used to include other pages. This tag uses the JSP scriptlet "sbPage.toString()" to include an HTML or JSP into the display page. sbPage.toString() evaluates to the value for the HTTP request parameter content at run time.

 

---

Step 7. Testing the Sample Adapter Design-Time Interface

A test driver has been created to verify the basic functionality of the sample adapter design-time interface. The test driver is based on HTTP Unit (a framework for testing web interfaces which is available from http://www.httpunit.org). HTTP Unit is related to the JUnit test framework (available from http://www.junit.org). Versions of both HTTP Unit and JUnit are included with WebLogic Integration.

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:

1. Start WebLogic Server with the sample adapter deployed. Next, change the current working folder to the specific project folder and execute the setenv command script, as shown in the following steps.

2. Go to WLI_HOME and, at the command prompt, enter setenv.

   The setenv command script creates the necessary environment for the next step.

3. Go to the sample adapter's web folder by entering at the command prompt:

   cd WLI_HOME/adapters/sample/project

4. Edit the designTimeTestCase.properties file. Change the line containing the list of test cases to execute so that it includes web.DesignTimeTestCase. The line should read:

   test.case=web.DesignTimeTestCase

5. Near the end of the file, you might need to change two entries, username and password. Specify the username and password that the test driver should use to connect to WebLogic Integration.

6. After editing the test.properties file, start WebLogic Server.

7. Run the tests by entering at the command prompt:

   ant designtimetest

 

Copyright © 2002 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.