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

The Application View

File Structure

Flow of Events

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:

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.

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

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.

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:

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:

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:

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>

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>

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>

Step 4: Implement the Design-Time GUI

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

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

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:

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.

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>

Including the ADK Tag Library

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

Posting the ControllerServlet

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

Displaying the Label for the Form Field

<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

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

Displaying a Submit Button on the Form

<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

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

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

Posting the ControllerServlet

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

Displaying the Label for the Form Field

<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

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

Displaying a Submit Button on the Form

<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

Step 5c: Create the addservc.jsp form

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

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

Posting the ControllerServlet

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

Displaying the Label for the Form 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

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

Displaying a Submit Button on the Form

<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

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:

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.

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

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.

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>

Listing 8-12 web.xml ControllerServlet Mapping Component

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

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>

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>

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:

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

Step 7. Test the Sample Adapter Design-Time Interface

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: