Developing Adapters

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:

This section includes information about the following subjects:

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:

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

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

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

AbstractInputTagSupport and Its Descendants

com.bea.web.tag.AbstractInputTagSupport

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

Submit Tag

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

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

This tag ensures 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:

Once these prerequisites are met, the JSP form is displayed, as shown in Listing 9-1.

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

The sequence is as follows:

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.

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:

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.

JSP Tag Attributes

You can further customize the JSP tags by applying the attributes listed in Table 9-4.

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 connections. See Step 2a: Set Up the Directory Structure. In addition to the structure described there, you should also be aware that:

Flow of Events

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

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:

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

Page 2. Managing Application Views

Once the user successfully logs in, the Application Integration Design 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.

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:

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:

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:

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

Page 8: Testing an Application View

After adding at least one service or event, the user can test the application view. When an application view is tested, it becomes available to process events and services for testing purposes. If the user chooses to test the application view, he or she has the following two choices:

Publishing an Application View

Once the user has successfully tested an application view, they can publish it from the Application View Summary page, thus making it available for use from within WebLogic Workshop applications.

Saving an Application View

The user can save an application view (even one which is untested and unpublished) and return to it later via the Application Integration Design Console. This process saves the application view to the application integration repository within your target WebLogic Workshop application. Testing an application view will automatically save it, so this step is only necessary if you wish to leave a design session before actually testing the application view.

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:

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:

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:

Methods to Include

To ensure that these actions are performed successfully, you must supply the following methods when you implement AbstractDesignTimeRequestHandler:

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

Step 4a. Supply the ManagedConnectionFactory Class

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

protected Class getManagedConnectionFactoryClass();

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

Step 4b. Implement initServiceDescriptor()

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

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 connections, you must implement initEventDescriptor() so that the adapter user can add events at design time. This method is implemented as shown in Listing 9-6.

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

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:

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

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 9-7:

Including the ADK Tag Library

Line 1 in Listing 9-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 9-3.

Posting the ControllerServlet

Line 2 in Listing 9-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 9-5:

Displaying the Label for the Form Field

Line 5 in Listing 9-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 9-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 9-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 9-8.

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

Posting the ControllerServlet

Line 2 in Listing 9-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 9-5, "ControllerServlet Parameters."

Displaying the Label for the Form Field

Line 5 in Listing 9-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 9-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 9-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 Adapters, 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 9-9.

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

Posting the ControllerServlet

Line 2 in Listing 9-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 9-5, "ControllerServlet Parameters."

Displaying the Label for the Form Field

Line 5 in Listing 9-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 9-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 9-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 Adapters, 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.

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:

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 9-10 shows an example of code used to load the 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 9-6.

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

Step 5e: Write the Web Application Deployment Descriptors

The web.xml and weblogic.xml descriptors for your adapter generally follow a very simple pattern, and list the names of all the JSP pages in your design-time web application, plus some other setup information for the design-time web application. Because most adapters contain very similar web descriptors, the ADK provides a means to automatically generate them. This frees the adapter developer from maintaining a large descriptor that is mostly identical to other adapters web descriptors.

The generation of the web application descriptors may be requested by including and calling a special Ant target in your Ant build.xml file for your adapter. If you clone the ADK sample adapter using GenerateAdapterTemplate, the resulting build.xml will already include the necessary Ant target, and a call to use that target. Look at WLI_HOME/adapters/sample/project/build.xml and find the generate_web_descriptors target. This Ant target takes in a file called web-gen.properties, and generates the web.xml and weblogic.xml descriptors from the information contained in it. Notice in the sample adapter build.xml, this target is called near the top of the packages target.

The sample adapter includes a web-gen.properties file that acts as a template for you to fill in for your adapter. Following is a list of properties in this file, and their meanings:

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:

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

Step 7. Implement Environment Variables

This is an optional step. Environment variables are intended to isolate environment-specific information within an application view in a way that allows system administrators and WebLogic Integration application deployers to specify new values for this information depending on the environment they are deploying to. If your adapter does not include any event or service properties that can be considered environment-specific, then you do not need to implement environment variables in your adapter. Examples of environment-specific information in event or service properties for the DBMS sample adapter are:

Event and service connection information should not be considered when deciding whether or not to implement environment variables. Connection information is, by its very nature, specific to the EIS instance being connected to. Environment variables are used only to isolate environment specific information in event and service definitions.

If you choose to implement environment variable support in your adapter, you must provide this support in both the design-time GUI and the runtime portion of the adapter. For more information on runtime considerations, see Developing a Service Adapter.

For the design-time GUI, environment variable support can be added in two major steps:

Step 7a - Displaying/Editing the Variable Set

The preferred method for displaying and editing the variable set for an application view is to include the varset.jsp JSP page in your event and service definition JSP pages. You can do this by including the following JSP code:

<p>
<hr>
<p>

<jsp:include page='varset.jsp'>
  <jsp:param name='mode' value='writeable'/>
  <jsp:param name='hostPage' value='addservc'/>
</jsp:include>

This will be shown as a horizontal line with a table below it for displaying and editing the environment variables for an application view. The varset.jsp table allows the user to add, remove, and edit variable definitions. See the DBMS sample adapter for examples of using the varset.jsp JSP. The mode parameter should always be writable, and the hostPage parameter should be the name of the JSP hosting the variable set JSP (without the .jsp extension).

import com.bea.wlai.common.IApplicationViewDescriptor;
import com.bea.connector.IMutableVariableSet;

IApplicationViewDescriptor avd = getApplicationViewDescriptor();
IMutableVariableSet varSet = avd.getMutableVariableSet();

// Add a variable
IVariable myVar = varSet.addVariable("myVariable", "string", "My Variable",
"the default value");

// And then remove it
varSet.removeVariable("myVariable");

Step 7b - Using the Variable Set

Once you have included the varset.jsp JSP page, you can begin using the environment variables it will allow you to define. How you use environment variables depends on the nature of your adapter and the environment-specific information it maintains.

In general, environment variables will be used to provide either a part of or the entire value for an event or service property. The value provided by the variable at runtime can be a default value or a specific value configured for the variable by a system administrator or application deployer. The decision of whether to use variables for part of a property's value, or the entire value is up to you.

For the DBMS sample adapter, variables are used in some cases as the entire property value (for example, catalog/schema name for events) or as a part of a property value (or example, catalog/schema name within a SQL statement for services). The DBMS sample adapter denotes the use of an environment variable by including the variable's name enclosed in curly braces: {var_name}. It uses this syntax for both events and services. The curly braces were chosen to delimit the variable name because curly braces are not reserved characters and are not legal characters in SQL syntax. This allows the DBMS sample adapter to reliably parse the curly braces within a SQL statement without risk of confusing the parser.

Your adapter may require different conventions to uniquely or safely identify variable references in your property values.

Once you have decided how to represent variable references in your event and service property values, you can write the code needed to validate variable use in those values. The following rules apply:

At runtime, the application integration engine will provide you with a set of variables and their values. Your runtime adapter code should substitute the variable's runtime value for any variable reference in the configured property value. For more information, see Developing a Service Adapter or Developing an Event Adapter.

To get a list of variables defined (at design-time) via the varset.jsp, obtain the IApplicationViewDescriptor being configured by calling the superclass (AbstractDesignTimeRequestHandler) method:

import com.bea.connector.IVariableSet;

IApplicationViewDescriptor avd = getApplicationViewDescriptor();
IVariableSet varSet = avd.getVariableSet();

// List variable names

String[] varNames = varSet.listVariableNames();

// Get the first variable

IVariable var = varSet.getVariable(varNames[0]);

Step 8. 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: