Deploying Adapters

 

Once you have created 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 either from the WebLogic Server Administration Console or manually, by manipulating the config.xml file.

This section contains information about 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. 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. Optionally, it can also include an event router Web application file. The .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 

The .ear file for the sample adapter 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 file includes the shared .jar files; them; rather, Instead, both types of files refer to the shared .jar files by 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 .jar files. For more information about 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

The BEA_WLS_SAMPLE_ADK.rar and BEA_WLS_SAMPLE_ADK.war files contain META-INF/MANIFEST.MF, as 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: 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 9-4 shows the deployment descriptor, which declares the components of an .ear file. In this case, these components include 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 included in the system classpath.

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

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

 

---

Deploying Adapters

You can deploy adapters by either of the following methods:

• By using the WebLogic Server Administration Console

• By manually editing config.xml

This section provides procedures for both methods.

Deploying Adapters by Using the WebLogic Server Administration Console

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

1. Open the WebLogic Server Administration Console.

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

   The Applications page is displayed.

3. Select Configure a new application.

   The Configure a new Application page is displayed.

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

5. Click Apply to create the new entry.

6. Select Configure Components.

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

Deploying Adapters Manually

To deploy the adapter manually, you must first modify the config.xml file. Within the <Application> element, you must set the Deployed= value to true and specify the logical name of the adapter with the Name= value parameter setting. Additionally, you must:

• Set the pathname for the .ear file.

• Specify the appropriate connector component and Web application components.

Listing 9-5 shows how the config.xml file is 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 must replace WLI_HOME with the correct path for the WebLogic Integration root directory for your environment.

Once config.xml is updated, deploy the adapter by completing 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. Add the adapter group to the default WebLogic Server security realm using the WebLogic Server Administration Console at the following URL: http://<host>:<port>/

4. Add a user to the adapter group using the WebLogic Server Administration Console. Save your changes.

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

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

   In this URL, replace <host> with the name of your server and <port> with the listening port. For example:

   http://localhost:7001/wlai

   Now complete the procedures provided in Defining Application Views in Using Application Integration.

   Note: You will be prompted to log in by supplying a username and password. Use the password you added earlier.

Adapter Auto-registration

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

 

---

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 adapter, for example, you might need to change the data source 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:

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

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

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

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

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

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

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

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

   4. Click Apply.

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

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

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

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

   4. Click Create.

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

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

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

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

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

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

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