Upgrade Guide

Upgrading an Adapter Development Project

This section describes the steps for converting a WebLogic Integration 7.0 SP2 Adapter Development Kit (ADK) adapter development tree to an 8.1 ADK adapter development tree.

Note: In WebLogic Integration 8.1 SP2, connection factories are now part of the adapter instances. For more information, see Upgrading WebLogic Integration 7.0 SP2 Adapters Developed by ADK to WebLogic Integration 8.1 SP2

Implement WebLogic Integration Resource Adapter by extending AbstractWLIResourceAdapter using BEA_HOME/weblogic81/integration/adapters/sample/src/sample/spi/ResourceAdapterImpl.java as a guide, where BEA_HOME represents the WebLogic Platform 8.1 home directory. Keep the following in mind as you implement the adapter.

The AbstractResourceAdapter class defines the properties needed for the generic adapter object that will hold both the inbound and outbound adapter sections. For use in this situation, this property set is the set of properties you have in your Event Router web.xml without the ADK standard properties.
Generally, if the sample adapter's ResourceAdapterImpl does not have a particular property from your event router web.xml and the property is not specific to your adapter, do not include it on the ResourceAdapterImpl class.
You must have a setter/getter pair of methods for each property on the ResourceAdapterImpl class.
Using BEA_HOME/weblogic81/integration/adapters/sample/src/wli-ra.xml as a guide, add the wli-ra.xml file to your <adapter root>/src directory (for example, MyAdapter/src/wli-ra.xml). This file has the format of the Connector 1.5 draft specification and describes the ResourceAdapterImpl class you are creating.

To learn about this specification, see JSR 112: J2EE Connector Architecture 1.5 in the Java Community Process (JCP) program at the following URL: http://jcp.org/en/jsr/detail?id=112

The following steps prepare your WebLogic Integration 7.0 SP2 adapter properties file to work in the build scheme for WebLogic Integration 8.1. The new scheme separates the adapter-specific properties from the ADK-defined properties into separate files. These files are merged at build time. See step 5 below for the build changes.

Rename the adapter properties file named <Adapter Logical Name>.properties to <Adapter Logical Name>-base.properties (for example, MyAdapter_1_0.properties is renamed to MyAdapter_1_0-base.properties).

In the renamed file, remove all properties not related to the JSP pages in your adapter's source tree. For example remove any properties starting with depappvw_ because the depappvw.jsp exists in the ADK, not your adapter.

Remove all properties not related to the run-time messages that your adapter explicitly defines. The rule of thumb is that if the property or message exists in ADK.properties do not include it in your adapter properties file.

The following steps prepare your WebLogic Integration 7.0 SP2 design-time Web application's web descriptors (web.xml, weblogic.xml) to work in WebLogic Integration 8.1 build scheme. The new scheme separates the adapter-specific information in these descriptors into separate files from the generic (ADK or WebLogic Server defined) information. The new scheme generates the web.xml and weblogic.xml files based on a simple properties file that you provide in your adapter source. See step 5 below for the build changes.

Create a new .properties file called web-gen.properties in your WebLogic Integration 8.1 <adapter root>/src/war/WEB-INF directory. The properties that go into this file are described in the steps that follow. Basically, these properties will be derived from the contents of the web.xml file in the same directory.

Add a property called display-name, and give it the value you used for the display-name of you web.xml descriptor. For example, the following display-name element in the web.xml:

<web-app>
<display-name>BEA_WLS_SAMPLE_ADK</display-name>

becomes display-name=BEA_WLS_SAMPLE_ADK

Add a property called version, and give it the value of the context-param element in web.xml with param-name of version.

Add a property called request-handler-class and give its value as the class name for your design-time request handler. This value can be found in the existing web.xml file in the controller servlet definition's RequestHandlerClass init-param. It looks like this in the web.xml file:

<!-- Controller servlet -->
  
<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></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>
    
    
  <load-on-startup>1</load-on-startup>
  
</servlet>

Add a property called adapter-logical-name and give its value as the logical name for your adapter (for example, MyAdapter_1_0).

Add a property called debug-setting and give it the value on or off. This should be the same value as the value in your controller servlet's init-params in the old web.xml file.

Add a property called extra-jsp-list that lists the JSP pages you have added for your adapter. This is in addition to those JSP pages already defined in the ADK. This list is a comma-separated list of extra JSPs. The standard JSPs are addevent, addservc, confconn, edtevent, edtservc, event, service, and testform; do not include them in the extra-jsp-list. For example if you add a JSP called mybrowser.jsp, your extra-jsp-list would look like the following:

extra-jsp-list=mybrowser

Delete your existing web.xml and weblogic.xml descriptors. You can back up these files if you have customized them. Most adapters do not have custom web.xml and weblogic.xml descriptors.

Edit the <adapter root>/src/ear/META-INF/application.xml file and remove the web module definition for the event router. For example, the text removed for the sample adapter is as follows:

<module>
  <web>
    <web-uri>BEA_WLS_SAMPLE_ADK_EventRouter.war</web-uri>
    <context-root>BEA_WLS_SAMPLE_ADK_EventRouter</context-root>
  </web>
</module>

Modify your <adapter root>/build.xml file, as follows:

Note: The following instructions assume that your build.xml file is based on the build.xml file provided with the ADK. If your build.xml file in not based on the ADK's build.xml file or if you have extensively modified it, you will need to adjust these instructions to account for these differences.

Eliminate the event router JAR and WAR.

In build.xml, delete the eventrouter_jar and eventrouter_war targets and any references to them.

Add <your adapter package>/event/*.class to the class includes definition of the JAR target. It looks like this:

...

<!--
From the adapter's source directory, include the "includes" list
For this adapter, all the classes in the sample/cci, sample/event
and sample/spi packages are included as well as the log configuration
file and message bundles
-->
<fileset dir='${SRC_DIR}'
         includes='sample/cci/*.class,sample/event/*.class,
                   sample/spi/*.class, sample/eis/*.class,
                   *.xml,*.properties'/>

...

Add the following to the JAR command under your EAR target after the zipfileset element for the adk.jar file:

<zipfileset src='${WLI_LIB_DIR}/adk-eventgenerator.jar'>
  <exclude name='META-INF/MANIFEST.MF'/>
</zipfileset>

Add the following text to the top of your packages build target. This text calls ant tasks in the ADK that generate the web descriptors (web.xml and weblogic.xml) for your adapter. It also merges your adapter-specific properties file with the ADK.properties properties file to yield the final merged properties file required for proper operation of the adapter.

<!-- Generate web descriptors. NOTE: You can turn this off if you want
         to tightly control your web.xml/weblogic.xml. In this case,
         simply maintain these files in your src/war/WEB-INF instead of
         web-gen.properties -->
    <ant dir='${WLI_HOME}/adapters/utils/ant'
         target='generate_web_descriptors'
         inheritAll='false'>
      <property name='web_gen_props_file'
                value='${SRC_DIR}/war/WEB-INF/web-gen.properties'/>
    </ant>
    
    <!-- Merge the ADK.properties file and your adapter-specific properties
         into the final properties file that will be used by the adapter
     -->
    <ant dir='${WLI_HOME}/adapters/utils/ant'
         target='merge_properties'
         inheritAll='false'>
      <property name='props_dir' value='${SRC_DIR}'/>
      <property name='adapter_props_file'
                value='BEA_WLS_DBMS_ADK-base.properties'/>
      <property name='target_props_file'
                value='BEA_WLS_DBMS_ADK.properties'/>
    </ant>

Remove the entire <adapter root>/src/eventrouter directory.

Change the SYSTEM identifier in <adapter root>/src/rar/META-INF/weblogic-ra.xml from

PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 Connector//EN'
'http://www.bea.com/servers/wls600/dtd/weblogic600-ra.dtd'

to PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 8.1.0 Connector//EN' 'http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd'

Change the <shrink-period-minutes> element in <adapter root>/src/weblogic-ra.xml to <shrink-frequency-seconds> and multiply the current element's value by 60.

This completes upgrading your ADK.