Connector-module Deployment

This article explains how to deploy a standalone Connector-module to the Orion Application Server.

1 Introduction

    This article provides a step-by-step guide to deploying an existing standalone Connector-module to an Orion Application Server. It also gives a brief view of the structure of a Connector-module. Information about deploying full J2EE application can be found in the Application Deployment document.

2 Connector-module overview

    Connector-modules with Resource Adapters were added to J2EE in order to simplify interaction with heterogeneous Enterprise Information Systems (EIS). This was done by hiding the EIS complexity behind a DataSource-like API for the EIS vendors to implement and for the J2EE developers to utilize.

    Not only EIS vendors produce Resource Adapters for their systems, DBMS and Messaging systems vendors among others have also seen the benefits of providing a common interface for their systems.

    From the J2EE developer's point of view, most Resource Adapters are similar in that they are normally exposing the same simple interface (CCI) for the developer to utilize. The Common Client Interface (CCI) is a request driven interface that highly resembles using stored procedures in JDBC.

3 The Structure of a Connector-module in brief

    A Connector-module is made up of one or more classes and a descriptor (ra.xml) that contains the descriptor entries for one or more resource adapters.

    Regardless of whether the Connector-module is packaged or not, the file structure should look something like the following example: 


        /classes.jar
        /META-INF/ra.xml
    Listing 1: Connector-module file structure example

    The example Connector-module has all of its classes in the jar file classes.jar. This could of course be multiple jar files (one jar file per Resource Provider is not uncommon) or classes outside a jar file.

    The Connector-module is described in the META-INF/ra.xml descriptor, which contains settings for all included Resource Adapters (one Connector-module can span multiple Resource Adapters).

    As this article is about deploying Connector-modules and not about creating them, the structure of Connector-modules will not be further explored here. Please refer to the Connector API or the J2EE tutorial for further information.

4 Deploying a standalone Connector-module manually

    If the Connector-module to deploy is not part of a J2EE application, the following steps can be followed to add it to the default application shipped with Orion:

    4.1 Step 1: Add Connector-module to the default Application

      Add an entry like the one given below to the application.xml file of the Server you are deploying to: 


          <connector-module
              name="name"
              path="../applications/name.rar"
              default-location="env/eis/name"/>
      Listing 2: Adding a connector entry to application.xml

      The syntax of the connector-module tag can be found here.

      Replace name with the deployment name of the Connector-module used to reference it.

      Replace path with the path to the Connector-module.

      If needed, state a default-location that will be used as a base for JNDI-names for resource-adapters in the Connector module.

5 Deployment configuration

    After that a Connector-module has been deployed, it is possible to modify its configuration by editing the generated orion-ra.xml file. This file is normally located in the deployment directory of the Application that the Connector-module is part of (The default Application when adding standalone Connector-modules).


        /orion/application-deployments/default/connector-module name/orion-ra.xml
    Listing 3: Location of the deployment configuration file if the Connector-module was added to the default Application. Notice that "connector-module name" should be replaced with the actual name of the Connector-module (including the .rar suffix if was a packaged archive).

    Deployment configurations can be distributed with the Connector-module by placing the orion-ra-xml file within the META-INF directory (next to the ra.xml file) of the Connector-module. The container will then use the distributed deployment configuration file as base when deploying the Connector-module for the first time. When re-deploying the Connector-module the deployment configuration file of the Connector-modules deployment directory will be used as base.

    The settings available for deployment configuration of a Connector-module are:

    5.1 Specifying the JNDI location of a resource adapter

      The JNDI location of a resource adapter can be specified in the location attribute of the resource-adapter-deployment node of the orion-ra.xml file, as exemplified in listing 4 below:


      <orion-connector ...>
          ...
          <resource-adapter-deployment name="MyResourceAdapter" location="resource/myResourceAdapter"/>
          ...
      </orion-connector>
      Listing 4: Example of specifying the JNDI location in the resource-adapter-deployment tag of an orion-ra.xml file.

      The example in listing 4 above would bind the resource adapter named "MyResourceAdapter" to the JNDI location "resource/myResourceAdapter.

    5.2 Specifying property names and values for a resource adapter

      Name-value pairs can be configured per resource-adapter by using the config-property tag with the name of the property to configure as the name attribute and the value as content of the tag, as exemplified in listing 5 below:


      <orion-connector ...>
          ...
          <resource-adapter-deployment name="MyResourceAdapter" location="resource/myResourceAdapter">
              <config-property name="propertyName">propertyValue</config-property>
          </resource-adapter-deployment>
      ...
      </orion-connector>
      Listing 5: Example of specifying JNDI location in the resource-adapter-deployment tag of an orion-ra.xml file.

      In listing 5 above, the resource adapter named MyResourceAdapter has been configured with a property named propertyName with a value of propertyValue.

6 Example usage

    A resource adapter can be utilized as shown in listing 6 below:


        String username="username";
        String password="password";
        InitialContext context=new InitialContext();
        ConnectionFactory factory=(ConnectionFactory)context.lookup("java:comp/env/eis/TXWriter");
        ConnectionSpec spec=new FileConnectionSpec(user,password);
        Connection con=factory.getConnection(spec);
        Interaction interaction=con.createInteraction();
        FileInteractionSpec interactionSpec=new FileInteractionSpec();
        interactionSpec.setFunctionName("WRITE");
        interactionSpec.setFilename("helloworld1-1.txt");
        interactionSpec.setData("helloworld1-1!".getBytes());
        FileRecordFactory recordFactory=new FileRecordFactory();
        Record record=recordFactory.createMappedRecord("InputRecord");
        Record output=interaction.execute(interactionSpec,record);
    Listing 6: Resource adapter sample usage

    The sample code in listing 6 above looks up a ConnectionFactory from the application's context and uses this to communicate with the resource adapter. The communication is carried out through the use of Interaction specifications passed in to the resource adapter and Records returned by the Connector.

    The location used to get hold of the ConnectionFactory needs to be specified in the module's descriptor with an entry like in listing 7 below:


        ...
        <resource-ref>
            <res-ref-name>eis/TXWriter</res-ref-name>
            <res-type>javax.resource.cci.ConnectionFactory</res-type>
            <res-auth>Container</res-auth>
            <res-sharing-scope>Shareable</res-sharing-scope>
        </resource-ref>
        ...
    Listing 7: Resource adapter reference in the modules descriptor file.

    Listing 7 above shows a resource reference from a J2EE module descriptor. It could be located in web.xml or for a certain EJB in ejb-jar.xml.

    The resource reference needs to be mapped to the JNDI location of the resource adapter in question. This is done through an entry like the example given in listing 8 below:


            ...
            <resource-ref-mapping name="eis/TXWriter" location="resource/myResourceAdapter">
            ...
    Listing 8: Example of resource reference mapping in a module deployment configuration file.

    In listing 8 above, the name of the resource reference is mapped to the JNDI location of a resource adapter. The entry should be located in the deployment configuration file of the module.

    For more information about how to write resource adapter interaction code, please refer to the Connector API or the J2EE tutorial.

Copyright © 2005 IronFlare AB