Migrating Adapters to WebLogic Integration 7.0

e-docs > WebLogic Platform > WebLogic Integration > AI Topics > Developing Adapters > Migrating Adapters to WebLogic Integration 7.0

Developing Adapters

Migrating Adapters to WebLogic Integration 7.0

You are not required to perform adapter migration tasks when migrating from WebLogic Integration 2.1 to WebLogic Integration 7.0. Adapters developed and tested against WebLogic Integration 2.1 can run without changes against WebLogic Integration 7.0. However, you may want to perform the tasks outlined in this section to take full advantage of new features in this release.

This section contains information about the following subjects:

Rebuilding Adapters Against the WebLogic Integration 7.0 ADK

If you need to rebuild an adapter against the WebLogic Integration 7.0 ADK, you must change your build procedure to reference the new binary files delivered with WebLogic Integration 7.0. Specifically, you must reference the following new JAR files:

<property name='WLAI_CORE' value='${WLI_LIB_DIR}/wlai-core.jar'/>
<property name='WLAI_CLIENT' value='${WLI_LIB_DIR}/wlai-client.jar'/>
<property name='WLAI_EVENTROUTER' value='${WLI_LIB_DIR}/wlai-eventrouter.jar'/>

The following JAR files are no longer valid for adapters:

<property name='WLAI_CLIENT'   value='${WLI_LIB_DIR}/wlaiclient.jar'/>
<property name='WLAI_COMMON'   value='${WLI_LIB_DIR}/wlai-common.jar'/>
<property name='WLAI_EJB_CLIENT' value='${WLI_LIB_DIR}/wlai-ejb-client.jar'/>
<property name='WLAI_SERVLET_CLIENT'
          value='${WLI_LIB_DIR}/wlai-servlet-client.jar'/>
<property name='WLAI_EVENTROUTER_CLIENT'
          value='${WLI_LIB_DIR}/wlai-eventrouter-client.jar'/>

You must also change how you declare the environment property to match the following form:

<property environment='env'/>

Statements such as the following are no longer valid Ant statements and must be removed:

<property name='WL_HOME' environment='env'/>

Note: Invalid Ant statements generate the following error message:

You must specify value, location or refid with the name attribute.

Application Integration CLASSPATH and Adapter Packaging Changes

Allowing Adapters to Support the Shared Connection Factory User Interface

WebLogic Integration supports shared connection factories. To allow adapters to interact with the associated user interfaces, add the following properties to the adapter properties file. The nav.jsp properties correspond to the toolbar items displayed in the Application View Console while the remainder of the properties are used as labels for the display of shared connection factories. To use shared connection factories, you must use the latest ADK and design-time interfaces.

#nav.jsp#
nav_label_summary=Summary
nav_label_service=Add&nbsp;Service
nav_label_main=Home
nav_label_event=Add&nbsp;Event
nav_label_deploy=Deploy&nbsp;Application&nbsp;View
nav_label_define=Define&nbsp;Application&nbsp;View
nav_label_connection=Configure&nbsp;Connection
nav_label_admin=Administration
nav_label_select=Select&nbsp;Connection&nbsp;Type

# owned connection hdr #
connhdr_label_username=User Name:
connhdr_label_eisproductname=EIS Product Name:
conndhr_label_eisproductversion=EIS Product Version:

# referenced connection hdr #
connhdr_label_referenceConnectionCaption=Referenced Connection
connhdr_label_connection=Connection:
connhdr_label_adaptername=Name:
connhdr_label_adapterdesc=Description:
connhdr_label_adapterversion=Version:
connhdr_label_adapterlocaltrans=Supports local transactions

depappvw_label_sharedconnection=Shared Connection
depappvw_label_adaptername=Name:
depappvw_label_adaptervendor=Vendor:
depappvw_label_adapterdesc=Description:
depappvw_label_adapterversion=Version:

To support backwards compatibility for WebLogic Integration 2.1 adapters the, application integration engine needs to identify the version of the user interface. Make the following changes to mark the user interface with a version number:

Add the following entries into your adapter Web component's web.xml file:

<context-param>
    <param-name>version</param-name>
    <param-value>7.0</param-value>
</context-param>

<servlet>
    <servlet-name>contextinfo</servlet-name>
    <servlet-class>jsp_servlet.__contextinfo</servlet-class>
</servlet>

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

The contextinfo JSP allows the application integration engine to identify the version for the user interface framework. This JSP is added when you recompile your adapter using WebLogic Integration 7.0.

Changes in Security Constraints and Login Configuration

Adapter developers must update their design-time role restriction to use the Administrators group rather than the adapter group. 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 in Developing a Design-Time GUI.). This change is made because deployment requires access to MBeans, which requires that the user belong to the Administrators group.

Changes to DBMS Sample Adapter for Services Not Requiring Request Data

In WebLogic Integration 7.0, the DBMS sample adapter produces an empty or null request document definition for any service that does not require request data. For example, services based on simple SQL select statements that do not provide parameters for the where clause do not require a request document to execute at runtime. Such services are associated with an empty or null document definition. This appears as a No Request Required label on the Summary and Administration pages of the DBMS sample adapter design-time Web interface.

Calling ApplicationView.getRequestDocumentDefinition() on an ApplicationView instance with a service name for a service that does not require request data, returns an IDocumentDefinition instance for which the isNull() method returns true. Calling getDocumentSchema(), getDocumentSchemaName(), or getRootElementName() on the IDocumentDefinition instance will cause an IllegalStateException to be thrown.

These changes affect only application views defined with the DBMS sample adapter provided with WebLogic Integration 7.0. Existing application views are not affected by this change, however, the change in behavior of the sample adapter should be considered in on-going development.

Using WebLogic Integration 2.1 Adapters with WebLogic Integration 7.0

An adapter developed using WebLogic Integration 2.1 can be used with WebLogic Integration 7.0 without recompiling any components. However, the following configuration changes must be made before using these adapters with WebLogic Integration 7.0.

Add wlai-client.jar to the classpath
Prime the event router

First, add wlai-client.jar to the classpath. Edit your startWeblogic script to add the following text to your start command for Windows systems:

%WLI_HOME%\lib\wlai-client.jar

%JAVA_HOME%\bin\java -classic %DB_JVMARGS% -Xmx256m -classpath
%WLI_HOME\lib\wlai-client.jar;%SVRCP%

or, for UNIX systems, add the following text:

$WLI_HOME\lib\wlai-client.jar

In addition to classpath changes, you must prime the event router before deploying any WebLogic Integration 2.1 application views. This is only required for WebLogic Integration 2.1 adapters running in a WebLogic Integration 7.0 environment, and only required prior to deployment of any Application Views. Priming the event router allows the router to reinitialize itself if it loses communications with the server.

To prime the event router, you need to access the event router servlet. To access the event router servlet, use the URL of your deployed event router. In some cases, the event router is deployed on the same physical machine as the application integration engine, in other cases, it is deployed to a separate WebLogic Server instance. The URL for a locally deployed event router typically follows this pattern:

http://localhost:7001/EventRouterContext/EventRouter

Where EventRouterContext is the context defined in your application.xml file. For example, the configuration page for the DBMS sample adapter event router is as follows:

http://localhost:7001/DbmsEventRouter/EventRouter

The event router can also be deployed as a standalone module by compiling the router into a WAR file. The DBMS sample adapter uses this method in the build.xml file, as shown in the eventrouter_war target. The following excerpt from the build.xml file for the DBMS sample adapter shows how the router is compiled into a WAR file.

<target name='eventrouter_war' depends='jar,eventrouter_jar'>
    <delete dir='${SRC_DIR}/eventrouter/WEB-INF/lib'/>
    <war warfile='${LOCAL_LIB_DIR}/${EVENTROUTER_WAR_FILE}'
        webxml='${SRC_DIR}/eventrouter/WEB-INF/web.xml'>
        <fileset dir='.' includes='version_info.xml'/>
        <fileset dir='${SRC_DIR}/eventrouter'         excludes='WEB-INF/web.xml'/>
        <lib dir='${LOCAL_LIB_DIR}'
        includes='${JAR_FILE},${EVENTROUTER_JAR_FILE}'/>
        <lib dir='${WLI_LIB_DIR}'
        includes='adk.jar,adk-eventgenerator.jar,
        wlai-eventrouter.jar,wlai-core.jar,wlai-client.jar'/>
    </war>
</target>

When you access the event router servlet using the URL, the event router configuration page is displayed.

This page allows you to configure a server for the event router. To add the server information for the event router:

Select the Add radio button.
Enter a server name (DNS or TCPIP) and port.
Enter the user id and password.

Note: The user must have administrator privileges.
Click Do it.
Click Save Changes. Information on the parameters changed and a confirmation that the changes have been saved is displayed.

You can verify that the event router has been initialized if an initialization file exists. This file typically has a long file name beginning with _Servletcontextidname. This file can safely be deleted and recreated as often as necessary.