Developing a Design-Time GUI

The ADK's design-time framework provides tools for building a web-based GUI for defining, deploying, and testing adapter users' application views. Although each adapter has EIS-specific functionality, adapters require a GUI for deploying application views. The design-time framework minimizes the effort required to create and deploy such a GUI, primarily through the use of the following 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 WebLogic Server.

This section includes information about the following subjects:

• Introduction to Design-Time Form Processing

• Design-Time Features

• File Structure

• Flow of Events

• Step 1: Defining the Design-Time GUI Requirements

• Step 2: Defining the Page Flow

• Step 3: Configuring the Development Environment

• Step 4: Implement the Design-Time GUI

• Step 5: Write the HTML Forms

• Step 6. Implement the Look and Feel

 

---

Introduction to Design-Time Form Processing

A variety of approaches are available for processing forms using Java Servlets and JSPs. All approaches share several basic requirements, however:

• Displaying an HTML form.

  To create this functionality, you must:

  • Generate the form layout using HTML.

  • Indicate to the user which fields are mandatory.

  • Prepopulate fields with defaults, if any.

• Validating the field values in the HTTP request included in the data on a form submitted by a user.

  To create this functionality, you must:

  • Supply logic that can determine whether all mandatory fields contain a value.

  • Validate each value submitted against a set of constraints. For example, you may want your Web application to determine whether the value in an age field is a valid integer between 1 and 120.

• Redisplaying a form on which an invalid value has been entered, along with an error message beside each erroneous field on the form. If the Web application supports multiple locales, the error message should be localized for the user's preferred locale.

  The Web application must also be capable of redisplaying the last input of the user is not required to re-enter valid information. The Web application should continue with Step 2 and loop as many times as necessary until the values entered in all fields are valid.

• Processing the form data after all fields have passed coarse-grained validation. While processing the data, the Web application may encounter an error condition that is unrelated to individual field validation, such as a Java exception. The form must be redisplayed to the user with a localized error message at the top of the page. As stipulated in step 3, all input fields should be saved so the user is not required to re-enter any valid information.

  The Web application developer must determine:

  • Which object or method implements the form-processing API.

  • How and when to advance the user to the next page in the Web application.

• If the form is processed successfully, the next page in the Web application is displayed to the user.

Form Processing Classes

Implementing all the form-processing functionality for every form in a Web application is a tedious and error-prone process. The ADK design-time framework simplifies this process by using a Model-View-Controller (MVC) paradigm. This paradigm, in turn, is based on the following five classes:

• RequestHandler

• ControllerServlet

• ActionResult

• Word and Its Descendants

• AbstractInputTagSupport and Its Descendants

RequestHandler

com.bea.web.RequestHandler

This class provides HTTP request-processing logic. It is the model component of the MVC-based mechanism. The RequestHandler 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 the functionality needed to deploy an application view that is common to all adapters. You must extend this class to supply adapter or 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 are not required to provide any code to use the ControllerServlet. However, you must supply the initial parameters listed in Table  8-5 on page  34.

ActionResult

com.bea.web.ActionResult

ActionResult encapsulates the outcome of processing a request. It also provides information to the ControllerServlet to help that class determine which page to display next to the user.

Word and Its Descendants

com.bea.web.validation.Word

All fields in a Web application require validation. The com.bea.web.validation.Word class 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 or 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	Determines whether the value for a field
Integer	Is an integer within a specified range
Float/Double	Is a floating point value within a specified range
Identifier	Is a valid Java identifier
Perl 5 Regular Expression	Matches a Perl 5 regular expression
URL	(Supplied by the user) is a valid URL
Email	(Supplied by the user) contains a list of valid e-mail addresses
Date	(Supplied by the user) is a valid date using a specified date/time forma

 

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 prepopulating it with a default value, if applicable.

• Displaying a localized error message beside 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 name of the field on the form.

Submit Tag

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

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

This tag ensures that the doAction parameter is passed to the ControllerServlet in the request. As a result, the ControllerServlet invokes the xyz() method on the registered RequestHandler.

Form Processing Sequence

This section discusses the sequence in which forms are processed.

Prerequisites

Before a form can be processed, the following must occur:

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

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

2. The HTML for this tag is generated when the JSP engine invokes the doStartTag() method on an instance of com.bea.web.tag.IntegerTagSupport. The IntegerTagSupport instance instantiates a new instance of com.bea.web.validation.IntegerWord and adds it to Web application scope under the key age. Consequently, the ControllerServlet can retrieve the IntegerWord instance from its ServletContext whenever it must validate a value for age. The validation ensures that any value passed for age is greater than or equal to one, and less than or equal to 120.

3. The HTML form must also submit a hidden field named doAction. The value of this field is used by the ControllerServlet to determine which method on the RequestHandler can process the form.

Once these prerequisites are met, the JSP form is displayed, 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 following diagram illustrates, step by step, how form processing is performed.

Figure 8-1 UI Form Processing

 

The sequence is as follows:

1. A user submits a form with the following data: 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 age as the key. The object is an instance of com.bea.web.validation.IntegerWord.

4. The 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 it 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 which page to display next to the user. The next page information should be the name of another JSP or HTML page in your Web application. For example, thanks might display the thanks.jsp page to the user.

9. If 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 page includes the JSP indicated by the content parameter (for example, thanks.jsp). It displays that JSP 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 comprises a set of Java Server Pages (JSPs). JSPs are simply HTML pages that call Java servlets to invoke a transaction. To the user, a JSP looks like any other web page.

The following table describes the JSPs that make up a design-time GUI.

Table 8-2 Design-Time GUI JSPs  

Filename	Description
display.jsp	The display page, also called the Adapter Home Page, contains the HTML necessary to create the look-and-feel.
login.jsp	The Adapter Design-Time Login page.
confconn.jsp	The Confirm Connection page provides a form on which the user can specify connection parameters for the EIS.
appvwadmin.jsp	The Application View Administration page provides a summary of an undeployed application view.
addevent.jsp	The Add Event page allows the user to add an event to the application view.
addservc.jsp	The Add Service page allows the user to add a 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 allows users to specify deployment properties.

 

For a discussion of how to implement these JSPs, see Step 2: Defining the Page Flow.

JSP Templates

A template is an HTML page that is dynamically generated by a Java Servlet based on parameters provided in an HTTP request. Templates are used to minimize the number of custom pages and the amount of custom HTML needed for a Web application.

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. The templates supplied by the ADK offer three advantages to adapter developers:

• They provide most of the HTML forms needed to deploy an application view. In most cases, you need to supply only three custom forms:

  • Form that collects the EIS-specific connection parameters

  • Form that collects the EIS-specific information needed to add an event. You can use either the same form or a different form to collect the information needed to edit an event.

  • Form that collects the EIS-specific information needed to add a service. You also have the option of supplying a JSP for browsing a metadata catalog for an EIS. You can use either the same form or a different form to collect the information needed to edit a service.

• They 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 internationalized quickly.

• They guarantee a consistent look and feel for all templates

For a complete list of JSP templates provided by the ADK, see JSP Templates.

ADK Library of JSP Tags

The custom JSP tag library provided by the ADK helps developers create user-friendly HTML forms. Custom tags for HTML form input components allow page developers to seamlessly link to a validation mechanism. The following table describes the custom tags provided by the ADK.

Table 8-3 ADK JSP Tags  

Tag	Description
adk:check box	Determines whether 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 a message bundle.
adk:date	Verifies that the user's input is a date value in a specific format.
adk:double	Verifies that the user's input is a double value.
adk:email	Verifies that the user's input is a valid list of e-mail addresses (one or more).
adk:float	Verifies that the user's input is a float value.
adk:identifier	Verifies that the user's input is a valid Java identifier.
adk:int	Verifies that 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 a validation mechanism.
adk:text	Verifies the user's input against a Perl 5 regular expression.
adk:textarea	Verifies that the user's input in a text area matches a Perl 5 regular expression.
adk:url	Verifies that the user's input is a valid URL.

 

JSP Tag Attributes

You can further 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 - value displayed  on the page by default maxlength - maximum length of value size - size of display 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 - true or false (default is false, meaning field is not required) attrs - additional HTML attributes
adk:date	name - field name	default - value displayed  on the page by default maxlength - maximum length of value size - size of display required - true or false (default is false, meaning field is not required) attrs - additional HTML attributes lenient - true or false (default is false, meaning the date formatter should not be lenient in its parsing) format - expected format of the user input (default is mm/dd/yyyy)
adk:email, adk:url, adk:identifier	name - field name	default - value displayed  on the page by default maxlength - maximum length of value size - size of display required - true or false (default is false, meaning field is not required) attrs - additional HTML attributes
adk:text, adk:password	name - field name	default - value displayed  on the page by default maxlength - maximum length of value size - size of display required - true or false (default is false, meaning field is not required) attrs - additional HTML attributes pattern - a Perl 5 regular expression
adk:textarea	name - field name	default - value displayed  on the page by default required - true or false (default is false, meaning field is not required) attrs - additional HTML attributes pattern - a Perl 5 regular expression rows - number of rows to be displayed columns - number of columns to be displayed

 

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

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

The Application View

An application view is a business-level interface to the functionality specific to an application. For more information, see Application Views.

 

---

File Structure

The file structure necessary to build a design-time GUI adapter is the same as that required for service adapters. See Step 2a: Set Up the Directory 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.

 

---

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: Defining the Design-Time GUI Requirements

Before you start developing your design-time GUI, you must define your requirements for it by answering the following questions:

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

• How does the user browse event and service catalogs?

  The EIS must supply functions to access the event and service catalogs. If the EIS does not supply these, the user cannot browse the catalogs. If the EIS does supply them, we recommend the following design principle: invoke a call from the design-time UI to get metadata from the EIS. Such a call is really no different from a call from a run-time component. Both types of call execute functions on the back-end EIS.

  Consequently, you need to leverage your run-time architecture as much as possible to provide 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 or framework of this approach. You can find the sample adapter in WLI_HOME/adapters/sample.

• 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, an adapter must 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 process happen, you must invoke the SOM API. Again, the sample adapter provides instructions for implementing the SOM API. For more information about this API, see ADK Library of JSP Tags.

• Will some sort of service testing be supported? If your design-time GUI will support service testing, you must 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, see: WLI_HOME/adapters/dbms/src/war/

 

---

Step 2: Defining the Page Flow

You must specify the order in which the JSPs will be displayed when the user invokes an application view. This section describes the basic, required flow of pages for a successful application view. Note that these are requirements are minimal; you can also add pages to the flow to meet your specific needs.

Page 1: Logging In

Because an application view is a secure system, the user must log in before implementing the view. Thus, the Application View Console - Logon page 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 requirements for Application View Web applications are specified in the WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml file, which is available in the adapter.war file.

Page 2. Managing Application Views

Once the user successfully logs in, the Application View Console page is displayed. This page lists the folders that contain application views, the status of these folders, and any actions 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 selects the appropriate folder and drills down to the desired application view. The user then selects the desired application view and the Application View Summary page is displayed (appvwsum.jsp). For details about this page, see Page 9: Summarizing an Application View).

• To add a new application view, the user clicks Add Application View. The Define New Application View page is displayed.

Page 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 must provide a description that associates the application view with an adapter. This form provides fields in which the user can enter the application view name and a description of it, and a drop-down list of adapters with which the user can associate the application view.

Once the new application view is defined, the user selects OK and the Configure Connection page is displayed.

Page 4: Configuring the Connection

If the new application view is valid, the user must configure the connection. Therefore, once the application view is validated, the Configure Connection Parameters page (confconn.jsp) should be displayed. This page provides a form on which the user can specify connection parameters for the EIS. Because connection parameters are EIS-specific, the appearance of this page differs from one adapter to another.

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

Page 5: Administering the Application View

The user needs a means of administering the new application view. The Application View Administration page (appvwadmin.jsp) 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 listed in the application view, the user can do the following:

  • View the XML schema

  • Remove the event

  • Provide event properties

• List of services—For each service listed in the application view, the user can do the following:

  • View the request XML schema

  • View the response XML schema

  • Remove the service

  • Provide service properties

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

Page 6: Adding an Event

Now the user needs to add events to the application view. The Add Event page (addevent.jsp) allows the user to do so.

The following rules apply to a new event:

• Every event must have a unique name.

  • The event name can contain only the following characters: a-z, A-Z, 0-9, and underscore (_). It must begin with a letter. No other characters are valid.

  • The length of the name may not exceed 256 characters.

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

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

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

• Optionally, the adapter can provide a mechanism for browsing the event catalog for an EIS.

After defining and saving a new event, the user is returned to the Application View Administration page.

Page 7: Adding a Service

The user also needs to add new services to an application view. The Add Service page (addservc.jsp) allows the user to do so.

The following rules apply to a new event:

• Every service must have a unique name.

  • The service name can contain only the following characters: a-z, A-Z, 0-9, and underscore (_). It must begin with a letter. No other characters are valid.

  • The length of the name may not exceed 256 characters.

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

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

• In addition to a name and a description, every service requires EIS-specific parameters. The collection of EIS specific parameters defines an service type for the adapter.

• Optionally, the adapter can provide a mechanism for browsing the service catalog for an EIS.

After defining and saving a new service, the user is returned to the Application View Administration page.

Page 8: Deploying an Application View

After adding at least one service or event, the user can deploy the application view. When an application view is deployed, it becomes available to process events and services. If the user chooses to deploy the application view, he or she is forwarded to the Deploy Application View page (depappvw.jsp).

This page allows the user to specify the following deployment properties:

• 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 0 and less than 1.

  • Allow Pool to Shrink: controls whether the connection pool is allowed to shrink.

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

  • Log all messages

  • Log informational messages, 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 the Restrict Access link.

Controlling User Access

The user can grant or revoke another user's access privileges by specifying a user or group name in the form provided. Each application view controls access to two functions: reading and writing.

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

• Write access allows a user to deploy, edit, and undeploy the application view.

Deploying an Application View

The user deploys an application view by selecting the deploy option. The user must decide whether the application view should be deployed persistently. If persistent deployment is selected, the application view is redeployed whenever the application server is restarted.

Saving an Application View

The user can save an undeployed application view and return to it later via the Application View 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.

Page 9: Summarizing an Application View

When an application view is deployed successfully, the user is 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 includes an option to undeploy the application view. If the user clicks the Undeploy link, a child window is displayed, prompting the user to confirm this choice. If the user confirms, the application view is undeployed and the summary page is redisplayed. Application views that are undeplayed in this way continue to be saved in the repository. As a result, the user can 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 supported directly by the ADK.

    If the adapter supports the testing of services, the Summary page displays 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 includes an option to deploy the application view. If the user clicks the Deploy link, the application view is deployed and the Application View Summary page is reloaded.

    The page includes an option to edit the application view. If the user clicks the Edit link, the Application View Administration page is displayed.

    The page includes an option to remove the application view. If the user clicks the Remove link, a child window is displayed, prompting the user to confirm the choice to remove the application view from the ADK repository. If the user confirms, the application view is deleted from the repository and the user is redirected to the Application View Console.

• Connection criteria

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

• List of events: For each event, the Summary page offers the option of viewing the schema and, if event testing is supported, the option of testing. The user cannot remove events from this page; instead the user must choose to edit first.

• List of services: For each service, the Summary page offers the option of viewing the request schema and the response schema, and, if service testing is supported, the option of testing. The user cannot remove services from this page; instead the user must undeploy and edit first.

 

---

Step 3: Configuring the Development Environment

In this step, you set up your software environment to support design-time GUI development.

Step 3a: Create the Message Bundle

Any message destined for an end-user should be placed in a message bundle. A message 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 for a message at run time, the contents of the message are interpreted, on the basis of the key=value pair, and the message is presented to the user in the language appropriate for the specified locale.

For instructions on creating a message bundle, see 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 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 recompile JSPs on the fly. Consequently, you normally have to restart WebLogic Server just to change a JSP file. Because this approach contradicts the spirit of JSP, the ADK suggests the following workaround for updating JSPs without restarting WebLogic Server:

1. Construct a valid WAR file for your adapter's design-time UI. For the sample adapter, you can do so by using Ant. Listing  8-2 shows the target that produces the J2EE WAR file.

Listing 8-2 Target that Creates a WAR File

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

<!-- Clean-up existing environment -->
  <delete file='${LIB_DIR}/${WAR_FILE}'/>
   
<war warfile='${LIB_DIR}/${WAR_FILE}' 
webxml='${SRC_DIR}/war/WEB-INF/web.xml'
manifest='${SRC_DIR}/war/META-INF/MANIFEST.MF'>

<!--
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" >
        <patternset >
          <include name="WEB-INF/weblogic.xml"/>
          <include name="**/*.html"/>
          <include name="**/*.gif"/>
        </patternset>
      </fileset>

<!-- 
IMPORTANT! Include the ADK design time framework into the adapter's
design time Web application.
-->
      <fileset dir="${WLI_HOME}/adapters/src/war" >
        <patternset >
          <include name="**/*.css"/>
          <include name="**/*.html"/>
          <include name="**/*.gif"/>
          <include name="**/*.js"/>
        </patternset>
      </fileset>

<!-- 
Include classes from the adapter that support the design time UI 
-->
<classes dir='${SRC_DIR}' includes='sample/web/*.class'/>

<classes dir='${SRC_DIR}/war' includes='**/*.class'/>
<classes dir='${WLI_HOME}/adapters/src/war'
 includes='**/*.class'/>

<!-- 
Include all JARs required by the Web application under the
WEB-INF/lib directory of the WAR file that are not shared in the EAR
-->
<lib dir='${WLI_LIB_DIR}'
 includes='adk-web.jar,webtoolkit.jar,wlai-client.jar'/>
  </war>
</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 sample adapter is being constructed in:

WLI_HOME/adapters/DBMS

2. Load your Web application into WebLogic Server using the WebLogic Server Administration Console.

3. Configure the development environment. Sample development environment information is shown in Listing  8-3.

Listing 8-3 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>

Set the adapter logical name and directory values as follows:

1. Replace BEA_WLS_SAMPLE_ADK_Web with the logical name of your adapter.

2. Replace WLI_HOME with the pathname of the directory in which WebLogic Integration is installed. Replace PROJECT_ROOT with the name of the top-level directory of your adapter development tree, as shown in Listing  8-3.

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

4. To change a JSP, do so in the src/war directory and then rebuild the WAR target. Do not change a JSP in the temporary directory; change it from When the WAR file is created, it is also extracted into the directory monitored by WebLogic Server, which picks up changes only to a specific JSP. The duration of the monitoring operation performed by WebLogic Server is set by the pageCheckSeconds parameter in WEB-INF/weblogic.xml. Listing  8-4 shows how this parameter is set.

Listing 8-4 Setting the Monitoring 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.

 

---

Step 4: Implement the Design-Time GUI

Implementing the procedure provided in Introduction to Design-Time Form Processing for every form in a Web application is a tedious and error-prone process. The design-time framework simplifies this process by supporting a Model-View-Controller paradigm.

To implement the design-time GUI, you must 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. For a detailed overview of the methods provided by this object, see the Javadoc for the DesignTimeRequestHandler class.

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 to all adapters. These actions include:

• Defining an application view

• Configuring the connection

  Note: The ADK provides a method for processing connection parameters to obtain a CCI connection, but it does not supply the confconn.jsp page. For instructions on creating this form, see Step 5a: Create the confconn.jsp Form.

• Deploying an application view

• Providing application view security

• Editing an application view

• Undeploying an application view

Methods to Include

To ensure that these actions are performed successfully, you must supply the following methods when you implement 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().)

In every concrete implementation of AbstractDesignTimeRequestHandler, you also need to provide the following two methods:

• protected String getAdapterLogicalName();

  This method returns the logical name of the adapter. It is used to deploy an application view under that 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 it tries 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-5.

Listing 8-5 initServiceDescriptor() Implementation

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

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

Step 4c. Implement initEventDescriptor()

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

Listing 8-6 initEventDescriptor() Implementation

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

This method is invoked by the addevent() implementation of the AbstractDesignTimeRequestHandler. It is responsible for initializing the EIS-specific information associated with 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, make sure that the names you give them conform to the bean attribute naming standard. When property names do not conform to that standard, 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 the interface comprises. To familiarize yourself with the forms you must create, see the following sections:

• See Java Server Pages for a list of the necessary forms and a high-level description of them.

• See Step 2: Defining the Page Flow for details about each form.

The following sections describe how to write code for these forms. A sample of code for a form is included.

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

Listing 8-7 Coding confconn.jsp

1  <%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
2  <form method='POST' action='controller'>
3    <table>
4      <tr>
5        <td><adk:label name='userName' required='true'/></td>
6        <td><adk:text name='userName' maxlength='30' size='8'/></td>
7      </tr>
8      <tr>
9        <td><adk:label name='password' required='true'/></td>
10        <td><adk:password name='password' maxlength='30'size='8'/></td>
11     </tr>
12     <tr>
13       <td colspan='2'><adk:submit name='confconn_submit'
 	                         doAction='confconn'/></td>
14     </tr>
15   </table>
16 </form>

The following sections describe the contents of Listing  8-7:

• Including the ADK Tag Library

• Posting the ControllerServlet

• Displaying the Label for the Form Field

• Displaying the Text Field Size

• Displaying a Submit Button on the Form

• Implementing confconn()

Including the ADK Tag Library

Line 1 in Listing  8-7 instructs the JSP engine to include the ADK tag library:

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

The tags provided by the ADK are listed in Table  8-3.

Posting the ControllerServlet

Line 2 in Listing  8-7 instructs the form to post to the ControllerServlet:

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

The ControllerServlet is configured in the web.xml file for the Web application. It is responsible for delegating HTTP requests to a method on a RequestHandler. You are not required to provide any code to use the ControllerServlet; however, you must supply the initial parameters, which are described in Table  8-5:

Table 8-5 Initial Parameters for ControllerServlet  

Parameter	Description
MessageBundleBase	Specifies the base name for all message bundles supplied with an adapter. The ADK always uses the logical names for its sample adapters. However, you are free to choose your own naming convention for message bundles. This property is also established in the ra.xml file.
DisplayPage	Specifies the name of the JSP that controls both the flow and the look-and-feel of the pages in the application. In the sample adapter, this page is display.jsp.
LogConfigFile	Specifies the log4j configuration file for the adapter.
RootLogContext	Specifies the root log context. Log context is helpful for classifying 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 are classified accordingly.
RequestHandlerClass	Provides the fully qualified name of the request handler class for the adapter. In the sample adapter, this value is sample.web.DesignTimeRequestHandler.

 

Displaying the Label for the Form Field

Line 5 in Listing  8-7 displays a label for a field on the form:

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

The value that is displayed is retrieved from the message bundle for the user. The required attribute indicates whether the user must supply this parameter to be successful.

Displaying the Text Field Size

Line 6 in Listing  8-7 sets a text field of size 8 with a maximum length (max length) of 30:

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

Displaying a Submit Button on the Form

Line 13 in Listing  8-7 displays a button on the form that allows an adapter user to submit input:

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

The label on the button is retrieved from the message bundle using the confconn_submit key. When the form data is submitted, the ControllerServlet locates the confconn method on the registered request handler (see the RequestHandlerClass property) and passes 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 need to supply only one item: the concrete class for your adapter's ManagedConnectionFactory. To provide this class, implement the following method:

public Class getManagedConnectionFactoryClass()

Step 5b: Create the addevent.jsp form

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

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

1  <%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
2  <form method='POST' action='controller'>
3      <table>
4          <tr>
5              <td><adk:label name='eventName' required='true'/></td>
6              <td><adk:text name='eventName' maxlength='100' size='50'/></td>
7          </tr>
8          <tr>
9              <td colspan='2'><adk:submit name='addevent_submit'
               doAction='addevent'/></td>
10          </tr>
11     </table>
12  </form>

The following sections describe the contents of addevent.jsp.

Including the ADK Tag Library

Line 1 in Listing  8-8 instructs the JSP engine to include the ADK tag library.

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

The tags provided by the ADK are described in Table  8-3.

Posting the ControllerServlet

Line 2 in Listing  8-8 instructs the form to post to the ControllerServlet.

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

The ControllerServlet is configured in the web.xml file for the Web application. It is responsible for delegating HTTP requests to a method on a RequestHandler. You are not required 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

Line 5 in Listing  8-8 displays a label for a field on the form.

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

The value that is displayed is retrieved from the message bundle for the user. The required attribute indicates whether the user must supply this parameter to be successful.

Displaying the Text Field Size

Line 6 in Listing  8-8 sets a text field of size 50 with a maximum length (max length) of 100.

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

Displaying a Submit Button on the Form

Line 9 in Listing  8-8 displays a button on the form that allows an adapter user to submit input.

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

The label on the button is retrieved from the message bundle using the addevent_submit key. When the form data is submitted, the ControllerServlet locates the addevent() method on the registered request handler (see the RequestHandlerClass property) and passes the request data to it.

Adding Additional Fields

You must also add any additional fields that the user requires for defining an event. See Learning to Develop Adapters Using the DBMS Sample Adapter, for examples of forms with multiple fields.

Step 5c: Create the addservc.jsp form

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

Listing 8-9 Coding addservc.jsp

1  <%@ taglib uri='/WEB-INF/taglibs/adk.tld' prefix='adk' %>
2  <form method='POST' action='controller'>
3      <table>
4          <tr>
5             <td><adk:label name='serviceName' required='true'/></td>
6             <td><adk:text name='serviceName' maxlength='100' size='50'/></td>
7          </tr>
8          <tr>
9             <td colspan='2'><adk:submit name='addservc_submit'
               doAction='addservc'/></td>
10          </tr>
11      </table>
12  </form>

Including the ADK Tag Library

Line 1 in Listing  8-9 instructs the JSP engine to include the ADK tag library.

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

The 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

Line 2 in Listing  8-9 instructs the form to post to the ControllerServlet.

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

The ControllerServlet is configured in the web.xml file for the Web application. It is responsible for delegating HTTP requests to a method on a RequestHandler. You are note required 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

Line 5 in Listing  8-9displays a label for a field.

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

The value that is displayed is retrieved from the message bundle for the user. The required attribute indicates whether the user must supply this parameter to be successful.

Displaying the Text Field Size

Line 6 in Listing  8-9 sets a text field of size 50 with a maximum length (max length) of 100.

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

Displaying a Submit Button on the Form

Line 9 in Listing  8-9 displays, on a form, a button that allows an adapter user to submit input.

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

The label on the button is retrieved from the message bundle using the addservc_submit key. When the form data is submitted, the ControllerServlet locates the addservc method on the registered RequestHandler (see the RequestHandlerClass property) and passes 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 Learning to Develop Adapters Using the DBMS Sample Adapter, for examples of forms with multiple fields.

Step 5d: Implement Editing Capability for Events and Services (optional)

If you want to give adapter users the ability to edit events and services at design time, you must edit the adapter properties, create edtservc.jsp and edtevent.jsp forms, and implement some specific methods. This step describes those tasks.

Note: This step is optional. You are not required to provide users with these capabilities.

Update the Adapter Properties File

First, update the system properties in the adapter properties file 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 the adapter properties file, compare your new version of the file to the original file and make sure that they are now 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 JSP file and the add JSP file is the loading of descriptor values; the edit JSP file loads the existing descriptor values. For this reason, the same HTML files are used for both editing and adding in the DBMS sample adapter.

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

To initialize the controls with values defined in the descriptor, call the loadEvent/ServiceDescriptorProperties() method on the AbstractDesignTimeRequestHandler. This method sets all the service's properties in 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 use values other than the ADK tag names to map the properties for a service or event, you must override these values to provide the descriptor to the ADK tag-name mapping.

You must also initialize the RequestHandler before the HTML is resolved. This initialization should be performed only once. Listing  8-10 shows an example of code used to load the edtevent.jsp.

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

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

The edtservc.jsp file should submit to edtservc:

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

The edtevent.jsp file should submit to edtevent:

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

For examples, see the DBMS sample adapter at the following location:

WLI_HOME/adapters/dbms/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, to provide these mappings, the developer must override these methods in DesigntimeRequestHandlers.
boolean supportsEditableServices() and boolean supportsEditableEvents()	These 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 supported.
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.

 

For an example of how these methods are implemented, see the sample adapters.

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

You must 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 the new adapter is generated automatically.

The important components of this file are described in the following code listings (Listing  8-11 through Listing  8-15).

Listing 8-11 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>

The component shown in Listing  8-12 maps the ControllerServlet to the name controller. This action is important because the ADK JSP forms are based on the assumption that the ControllerServlet is mapped to the logical name controller.

Listing 8-12 web.xml ControllerServlet Mapping Component

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

The component shown in Listing  8-13 declares the ADK tag library.

Listing 8-13 web.xml ADK Tab Library Component

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

The component shown in Listing  8-14 declares the security constraints for the Web application. In previous releases, the user had to belong to the adapter group. In release 7.0 and higher, the user must belong to the Administrators group (see the role names in Listing  8-14 and Listing  8-15). This is because deployment requires access to MBeans, which requires that the user belong to the Administrators group.

Listing 8-14 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>Administrators</role-name>
    </auth-constraint>

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

The component shown in Listing  8-15 declares the login configuration.

Listing 8-15 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>Administrators</role-name>
</security-role>

 

---

Step 6. Implement 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 in all the pages of your application view. The look-and-feel is determined by display.jsp. This page, included with the ADK, provides the following benefits for a design-time Web application:

• Creates a template that establishes the look and feel for all pages.

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

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

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

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

2. Using HTML, alter the look-and-feel markup on this page to reflect your own look and feel or your company's 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 page in the display page. sbPage.toString() evaluates to the value of content (the HTTP request parameter) at run time.

 

---

Step 7. Test the Sample Adapter Design-Time Interface

WebLogic Integration provides a test driver that verifies 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 also included with WebLogic Integration.

The test driver executes a number of tests. It creates application views, adds both events and services to application views, deploys and undeploys application views, and tests both events and services. After if finishes running successfully, the test driver removes all application views.

Files and Classes

All test cases are available in the DesignTimeTestCase class or its parent class, AdapterDesignTimeTestCase. The DesignTimeTestCase class (in the sample.web package and the WLI_HOME/adapters/sample/src/sample/web folder) contains tests specific to the sample adapter. AdapterDesignTimeTestCase (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 test the design-time interface, complete the following 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, as shown in the following steps.

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

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

3. Go to the web folder for the sample adapter by entering the following at the command prompt:

   cd WLI_HOME/adapters/sample/project

4. Edit the designTimeTestCase.properties file: in the line containing the list of test cases to be executed, add web.DesignTimeTestCase. The line should read:

   test.case=web.DesignTimeTestCase

5. Near the end of the file, you might need to change the value of 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 the following command at the command prompt:

   ant designtimetest