Deploying Adapters

 

Once you have created an adapter, you will need to deploy it by using an Enterprise Archive (.ear) file. .ear files simplify adapter deployment by deploying all adapter components in a single step. You can deploy an .ear file either from the WebLogic Server Console or manually, by manipulating the config.xml file.

This section contains information on the following subjects:

• Using Enterprise Archive (.ear) Files

• Deploying Adapters

• Editing Web Application Deployment Descriptors

 

---

Using Enterprise Archive (.ear) Files

Each adapter is deployed from a single Enterprise Archive (.ear) file. The .ear file will contain the design-time Web application .war file, the adapter .rar file, the adapter .jar file, and any shared .jar file required for deployment. Optionally, it can include the Event Router Web application file. This .ear file should be structured as shown in Listing 9-1.

Listing 9-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
     eventrouter.war
          WEB-INF
               web.xml
          META-INF
               MANIFEST.MF 

For example, the sample adapter's .ear file is shown in Listing 9-2.

Listing 9-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 files includes the shared .jar files inside of them; rather, they both refer to the shared .jar files by using the <manifest.classpath> attribute.

Using Shared .jar Files in an .ear File

The design time uses an adapter's SPI classes in a non-managed scenario. Consequently, an adapter's SPI and CCI classes should be contained in a shared .jar file off the root of the .ear. To allow the .war and .rar classloaders to access the classes in the shared .jar, you need to make an entry in the MANIFEST.MF files to include the shared .jar files. For more information on MANIFEST.FM, see either The Manifest File or "Understanding the Manifest" at the following URL:

http://developer.java.sun.com/developer/Books/JAR/basics/
   manifest.html

BEA_WLS_SAMPLE_ADK.rar and BEA_WLS_SAMPLE_ADK.war contain META-INF/MANIFEST.MF, which is shown in Listing 9-3:

Listing 9-3 Manifest File Example

Manifest-Version: 1.0

Created-By: BEA Systems, Inc.

Class-Path: BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar logtoolkit.jar xcci.jar xmltoolkit.jar

Note: When the filename MANIFEST.MF appears in a .war file, it must appear in uppercase letters. If it does not, Unix will not recognize it and an error will occur.

.ear File Deployment Descriptor

Listing 9-4 is the deployment descriptor for the .ear file. It declares the components of an .ear file. In this case, that is the design-time .war, event router .war, and adapter .rar modules.

Listing 9-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, Web application for configuring 
      application views for the adapter, and an 
      event router Web application.</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>
   <module>
      <web>
         <web-uri>BEA_WLS_SAMPLE_ADK_EventRouter.
            .war</web-uri>
         <context-root>BEA_WLS_SAMPLE_ADK_
            EventRouter</context-root>
      </web>
   </module>
</application>

Note: The adapter .jar files must be on the system classpath.

You can deploy the adapter via the WebLogic Server Console or by adding an application component to config.xml. These procedures are described in Deploying Adapters.

You will also need to configure the event router Web application using the WebLogic Server Console. For more information, see Editing Web Application Deployment Descriptors.

 

---

Deploying Adapters

You can deploy adapters by using either of two methods:

• Using the WebLogic Server Console

• Manually, by manipulating config.xml.

This section describes both procedures.

Deploying Adapters by Using the WebLogic Server Console

To configure and deploy an adapter from the WebLogic Server Console, do the following:

1. Open the WebLogic Server Console.

2. In the left pane, select Deployments—>Applications from the navigation tree.

   The Applications page appears:

3. Select Configure a new application.

   The Configure a new Application page appears.

4. Fill in the fields for this configuration entry for the application:

   • In Name, enter the adapter logical name.

   • In Path, enter the path to the appropriate .ear file.

   • In Deployed, ensure that the checkbox is selected.

5. Select Apply to create the new entry.

6. Select Configure Components.

7. Set the target for each component individually.

Installing an application (or application component) via the WebLogic Server Console also creates entries for that application and application components in the configuration file for the 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.

Deploying Adapters Manually

To manually deploy the adapter, you first need to modify the config.xml file. Within the <Application> element, you need to set the Deployed= value to "true" and specify the adapter logical name as the Name= value. Additionally, you need to:

• Set the actual path to the .ear file.

• Include the appropriate connector component and Web application components.

Listing 9-5 shows how the config.xml file was modified to deploy the sample adapter. In this listing, the path directive points to the .ear file and each component describes the URI of its own deployment.

Listing 9-5 Sample Code for Deploying an Adapter by Using config.xml

<!-- This deploys the EAR file -->

<Application Deployed="true" Name="BEA_WLS_SAMPLE_ADK"          Path="WLI_HOME/adapters/sample/lib/BEA_WLS_SAMPLE_ADK.ear">
    <ConnectorComponent Name="BEA_WLS_SAMPLE_ADK"             Targets="myserver" URI="BEA_WLS_SAMPLE_ADK.rar"/>
    <WebAppComponent Name="BEA_WLS_SAMPLE_ADK_EventRouter"              Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_
       EventRouter.war"/>

    <WebAppComponent Name="BEA_WLS_SAMPLE_ADK_Web"                  Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_Web.war"/>
</Application>

Note: You will need to replace WLI_HOME with the correct path to WebLogic Integration root directory for your environment.

Once config.xml has been updated, deploy the adapter by using the following procedure:

1. Add the adapter .jar file(s) to the classpath and restart WebLogic Server. This step is required because WebLogic Server does not currently load an .ear file with a single classloader.

2. Restart the server.

3. Once the server restarts, add the adapter group to the default WebLogic security realm using the WebLogic Server Console Web application. http://<host>:<port>/ console.

4. After you have added the adapter group, add a user to the adapter group using the WebLogic Server Console Web application and save your changes.

5. To configure and deploy application views, navigate to:

   http://<host>:<port>/wlai

   where <host> is the name of your server and <port> is the listening port; for example:

   http://localhost:7001/wlai

   Configure and deploy the application views by using the procedures described in Defining Application Views in Using Application Integration.

   Note: You will be prompted to login by supplying a username and password. For a password, use the one you have previously added.

Adapter Auto-registration

This versioin of WebLogic Integration uses an automatic registration process during adapter deployment. To implement the automatic registration process, use one of the procedures described in Registering the Design-time Web Application.

 

---

Editing Web Application Deployment Descriptors

You might need to change the deployment parameters of the Event Router Web application; for example, for the DBMS adapter, you might need to change the data source used by its event generator.

This section describes how to use the WebLogic Server Console Deployment Descriptor Editor to edit the 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, use this procedure:

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

   http://host:port/console

   where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening; for example:

   http://localhost:7001/console

2. Click to expand the Deployments node in the left pane.

3. Click to expand the Web Applications node under the Deployments node.

4. Right-click the name of the Web application whose deployment descriptors you want to edit and choose Edit Web Application Descriptor from the drop-down menu. The WebLogic Server Administration Console appears in a new browser.

   The left pane contains a tree structure that lists all the elements in the two Web application deployment descriptors and the right pane contains a form for the descriptive elements of the web.xml file.

5. To edit, delete, or add elements in the Web application deployment descriptors, click to expand the node in the left pane that corresponds to the deployment descriptor file you want to edit, as described in the following list:

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

6. To edit an existing element in one of the Web application deployment descriptors, follow these steps:

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

   2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

   3. Edit the text in the form in the right pane.

   4. Click Apply.

7. To add a new element to one of the Web application deployment descriptors, follow these steps:

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

   2. Right-click the element and chose Configure a New Element from the drop-down menu.

   3. Enter the element information in the form that appears in the right pane.

   4. Click Create.

8. To delete an existing element from one of the Web application deployment descriptors, follow these steps:

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

   2. Right-click the element and chose Delete Element from the drop-down menu.

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

9. 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 the either the name of the Web application *.war archive file or the display name of the Web application.

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

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