Developing Adapters

Deploying Adapters

After you create an adapter, you must deploy it by using an Enterprise Archive (EAR) file. An EAR file simplifies this task by deploying all adapter components in a single step. You can deploy an EAR file from the WebLogic Server Administration Console.

This section contains information about the following subjects:

Using Enterprise Archive (EAR) Files

Each adapter is deployed from a single Enterprise Archive (EAR) file. An EAR file contains a design-time Web application WAR file, an adapter RAR file, an adapter JAR file, and any shared JAR files required for deployment. The EAR file should be structured as shown in Listing 10-1.

Listing 10-1 EAR File Structure

adapter.ear
     application.xml
     sharedJar.jar
     adapter.jar
     adapter.rar
          META-INF
               ra.xml
               weblogic-ra.xml
               MANIFEST.MF
     designtime.war
          WEB-INF
               web.xml
          META-INF
               MANIFEST.MF

The EAR file for the sample adapter is shown in Listing 10-2.

Listing 10-2 EAR File for the Sample Adapter

sample.ear
 application.xml
   adk.jar (shared .jar between .war and .rar)
   bea.jar (shared .jar between .war and .rar)
   BEA_WLS_SAMPLE_ADK.jar (shared .jar between .war and .rar)

    BEA_WLS_SAMPLE_ADK.war (Web application with
         META-INF/MANIFEST.MF entry Class-Path:
      BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar 
        logtoolkit.jar xcci.jar xmltoolkit.jar)

    BEA_WLS_SAMPLE_ADK.rar (Resource Adapter with
      META-INF/MANIFEST.MF entry Class-Path: 
       BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar
       logtoolkit.jar xcci.jar xmltoolkit.jar)

	log4j.jar (shared .jar between .war and .rar)
	logtoolkit.jar (shared .jar between .war and .rar)
	xcci.jar (shared .jar between .war and .rar)
	xmltoolkit.jar (shared .jar between .war and .rar)

Notice that neither the RAR nor WAR file includes the shared JAR files; them; instead, both types of files refer to the shared JAR files using the <manifest.classpath> attribute.

Using Shared JAR Files in an EAR File

The design-time application uses an adapter's SPI classes in an unmanaged scenario. Consequently, an adapter's SPI and CCI classes should be contained in a shared JAR file that resides in the same directory as the EAR file. To allow the WAR and RAR classloaders to access the classes in the shared JAR, you must specify, in the MANIFEST.MF files, a request for inclusion of the shared EAR files. For more information about MANIFEST.FM, see either Manifest File or "Understanding the Manifest" at the following URL:

http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html

The BEA_WLS_SAMPLE_ADK.rar and BEA_WLS_SAMPLE_ADK.war files contain META-INF/MANIFEST.MF, as shown in Listing 10-3:

Listing 10-3 Manifest File Example

Manifest-Version: 1.0

Created-By: BEA Systems, Inc.

Class-Path: BEA_WLS_SAMPLE_ADK.jar adk.jar wlai-core.jar
 wlai-client.jar

Note: The name of the file, MANIFEST.MF, is spelled in all uppercase. If it is not spelled correctly, it is not recognized on a UNIX system and an error occurs.

EAR File Deployment Descriptor

Listing 10-4 shows the deployment descriptor, which declares the components of an EAR file. In this case, these components include the design-time WAR and adapter RAR modules.

Listing 10-4 Deployment Descriptor for the EAR File

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN'
'http://java.sun.com/dtd/application_1_3.dtd'>

<application>
   <display-name>BEA_WLS_SAMPLE_ADK</display-name>
   <description>This is a J2EE application that contains a sample
      connector and Web application for configuring 
      application views for the adapter.</description>
   <module>
      <connector>BEA_WLS_SAMPLE_ADK.rar</connector>
   </module>
   <module>
      <web>
        <web-uri>BEA_WLS_SAMPLE_ADK.war</web-uri>
        <context-root>BEA_WLS_SAMPLE_ADK_Web</context-root>
      </web>
   </module>
   </application>

You can deploy the adapter via the WebLogic Server Administration Console. This procedure is described in Deploying Adapters Using the WebLogic Server Administration Console.

Deploying Adapters Using the WebLogic Server Administration Console

To configure and deploy an adapter from the WebLogic Server Administration Console, complete the following procedure:

Open the WebLogic Server Administration Console.

In the navigation tree (in the left pane), choose Deployments—>Applications.

The Applications page is displayed.

Select Configure a new application.

The Configure a new Application page is displayed.

Enter values in the following fields:

In the Name field, enter the logical name of the adapter.
In the Path field, enter the path for the appropriate EAR file.
In the Deployed field, make sure that the check box is selected.

Click Apply to create the new entry.

Select Configure Components.

Set the target for each component individually.

When you install an application (or application component) via the WebLogic Server Administration Console, you also create entries for that application or component in the configuration file for the relevant domain (/config/DOMAIN_NAME/config.xml, where DOMAIN_NAME is your domain). WebLogic Server also generates JMX Management Beans (MBeans) that enable you to configure and monitor the application and application components.

Adapter Auto-registration

WebLogic Integration uses an automatic registration process during adapter deployment. Autoregistration is performed during the adapter deployment phase. You can invoke this process in either of two ways:

Using a Naming Convention

The preferred approach is to use a naming convention for the design-time Web application and connector deployment.

When deploying an EAR file in a WebLogic Integration environment, identify the file in config.xml by using the logical name of the adapter as the filename, as shown in the example, in Listing 10-5.

Listing 10-5 Adding the Adapter Logical Name to config.xml

<Application Deployed="true" Name="ALN"
      Path="WLI_HOME/adapters/ADAPTER/lib/ALN.ear">
    <ConnectorComponent Name="ALN" Targets="myserver"
     URI="ALN.rar"/>
   <WebAppComponent Name="ALN_EventRouter" Targets="myserver"
      URI="ALN_EventRouter.war"/>
   <WebAppComponent Name="ALN_Web" Targets="myserver"
      URI="ALN_Web.war"/>
</Application>

In this listing, ALN is the logical name of the adapter. You must use this name as the value of the Name attribute of the <ConnectorComponent> element.

If you assign the name ALN_Web to your design-time Web application deployment, the design-time Web application is registered automatically, through the Weblogic Server Administration Console, during deployment. This naming convention is used in the DBMS and sample adapters.

Using a Text File

Alternatively, you can include a text file named webcontext.txt in the root directory of the pathname for your EAR file. The webcontext.txt file should contain the context for the design-time Web application for your adapter. This file must be encoded in UTF-8 format.

Editing Web Application Deployment Descriptors

For some adapters, you may need to change the deployment parameters of the Event Router Web application. For the DBMS sample adapter, for example, you might need to change the database URL used by its event generator.

This section explains how to use the Deployment Descriptor Editor provided by the WebLogic Server Administration Console to edit the following Web application deployment descriptors:

web.xml
weblogic.xml

Deployment Parameters

You can change any parameter of the Event Router Servlet. These parameters are:

eventGeneratorClassName
userID
password
dataSource
jdbcDriverClassName
dbURL
dbAccessFlag
eventCatalog
eventSchema
RootLogContext
AdditionalLogContext
LogConfigFile
LogLevel
MessageBundleBase
LanguageCode
CountryCode
sleepCount

Editing the Deployment Descriptors

To edit the Web application deployment descriptors, complete the following procedure:

Open the WebLogic Server Administration Console in your browser by accessing the following URL:

http://host:port/console
In this URL, replace host with the name of the computer on which WebLogic Server is running, and port, with the number of the port on which WebLogic Server is listening. For example: http://localhost:7001/console

In the left pane, expand two nodes: the Deployments node and the Web Applications node below it.

Right-click the name of the Web application for which you want to edit the deployment descriptors. From the drop-down menu select Edit Web Application Descriptor. The WebLogic Server Administration Console is displayed in a new browser.

The Console consists of two panes. The left pane contains a navigation tree composed of all the elements in the two Web application deployment descriptors. The right pane contains a form for the descriptive elements of the web.xml file.

To edit, delete, or add elements in the Web application deployment descriptors, expand the node in the left pane that corresponds to the deployment descriptor file you want to edit. The following nodes are available:

The WebApp Descriptor node contains the elements of the web.xml deployment descriptor.
The WebApp Ext node contains the elements of the weblogic.xml deployment descriptor.

To edit an existing element in one of the Web application deployment descriptors, complete the following procedure:

Navigate the tree in the left pane, clicking parent elements until you find the element you want to edit.

Click the name of the appropriate element. A form is displayed in the right pane with a list of either the attributes or the subelements of the selected element.

Edit the text in the form in the right pane.

Click Apply.

To add a new element to one of the Web application deployment descriptors, complete the following procedure:

Navigate the tree in the left pane, clicking parent elements until you find the name of the element you want to create.

Right-click the name of the appropriate element and select Configure a New Element from the drop-down menu. A form is displayed in the right pane.

Enter the element information in the form in the right pane.

Click Create.

To delete an existing element from one of the Web application deployment descriptors, complete the following procedure:

Navigate the tree in the left pane, clicking parent elements until you find the name of the element you want to delete.

Right-click the name of the appropriate element and select Delete Element from the drop-down menu. A confirmation page is displayed.

Click Yes on the Delete confirmation page to verify that you want to delete the element.

Once you have made all your changes to the Web application deployment descriptors, click the root element of the tree in the left pane. The root element is either the name of the Web application *.war archive file or the name that is displayed for the Web application.

Click Validate if you want to ensure that the entries in the Web application deployment descriptors are valid.

Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server memory.

Deploying Adapters in a WebLogic Integration Cluster

Adapters can be deployed to a WebLogic Integration cluster. For more information about deploying adapters in a clustered WebLogic Integration environment, see Understanding WebLogic Integration Clusters in Deploying BEA WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/deploy/cluster.html

Redeploying Adapter Instances

If you have made changes to the event connection or service connection for an adapter instance, you must redeploy the instance for those changes to take effect. Redeploying an adapter instance causes its dependent application views to be redeployed, as well. You can reploy adapter instances using the WebLogic Integration Administration Console. For more information, see Redeploying an Adapter Instance in Managing WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/manage/ai.html

Warning: The adapter instance redeploy operation does not guarantee any transaction recovery for in-flight transactions or transaction requests during undeployment and redeployment. Redeploying during transaction processing may result in unpredictable behavior and data mismatches between the database and the WebLogic Integration Administration Console.