Resource-Providers

This article explains what an Resource-Provider is, how to configure it and shows sample usage with Resource-Providers such as SwiftMQ, MQ Series or SonicMQ with an Application deployed on the Orion Application Server.

1 Introduction

    The Resource-Provider interface is meant to add better support for plugging in components that make any sort of J2EE resource available (The specified resource types in J2EE 1.2 are JDBC DataSource references, JMS Connection factories, JavaMail Connection factories and URL Connection factories).

    Orion already provides a special-case for adding JDBC DataSources through data-sources.xml, since the case of adding JDBC DataSources from different vendors is a very common one and has been there for a long time. However, this special-case is pretty limited and certain DataSource implementations require additional setup and not just what can be done through data-sources.xml.


    Figure 1: The ResourceProvider interface.

    The API documentation for the Resource-Provider interface is available here.

    Furthermore, the Resource-Provider is needed to be able to transparently add third party implementations of for example JMS and JavaMail implementations.

2 Configuring a custom Resource-Provider

    To add a custom Resource-Provider, add an entry like the following to your Applications orion-application.xml:


        <resource-provider
            class="providerClassName"
            display-name="sample"
            name="JNDI name">
            <description>
                description
            </description>
            <property name="name"
                         value="value" />
        </resource-provider>
    Listing 1: Adding a Resource-Provider to the Application

    Replace the value providerClassName of the class attribute with the name of the Resource-Provider class.

    Replace the value sample of the display-name attribute with the name you want to use when displaying the resource in tools.

    Replace the value JNDI name of the name attribute with a name to identify the Resource-Provider by. This name will be used in finding the Resource-Provider in the application's JNDI as "java:comp/resource/name/"

    Replace the value description of the description tag with a description of the Resource-Provider in question.

    Replace the value name and value of the attributes with the same name in any property tags that the Resource-Provider in question needs to be given as parameters.

    Note that the first listed Resource-Provider becomes the default for the types it handles.

    The file orion-application.xml is normally found in the deployment directory of the Application.

3 Using a custom Resource-Provider

    A Resource-Providers resources is retrieved by the following lookup syntax:


        java:comp/resource/providerName/resourceName
    Listing 2: Retrieving the Resource-Provider

    Where providerName is the name of the Resource-Provider (as given in the attribute display-name described in the previous section) and resourceName is the name of a resource this Resource-Provider provides.

    As the first Resource-Provider registered for handling a certain resource will become the default for the Application, no special deployment configuration of Container managed elements such as for example a MDB using a JMS Resource-Provider or a CMP using a DataSource Resource-Provider is needed.

    If different Resource-Providers needs to be used for different Container managed elements, the ResourceProvider that a certain element should use must be configured. How this is done is covered in the example section below.

4 Sample Resource-Providers

    Below are a couple of sample Resource-Providers to use as templates for developing custom ResourceProviders.

    4.1 Sample 1: ContextScanningResourceProvider

      The ContextScanningResourceProvider is an example Resource-Provider shipped with Orion that can be used to bind a resource existing in another naming context into the local naming tree. This is useful for example with JMS, since the JMS server normally binds the resources in its own JNDI tree. Using this Resource-Provider any such resource can be bound to the local Orion JNDI tree.


      Figure 2: The ContextScanningResourceProvider class.

      Download the ContextScanningResourceProvider Resource-Provider here.

      To use this Resource-Provider, the entry in orion-application.xml could look like:


          <resource-provider
                  class="com.evermind.server.deployment.ContextScanningResourceProvider"
                  display-name="SwiftMQ resource"
                  name="SwiftMQ" >
              <description>
                  SwiftMQ resource provider.
              </description>
              <property name="java.naming.factory.initial"
                           value="com.swiftmq.jndi.InitialContextFactoryImpl" />
              <property name="java.naming.provider.url"
                           value="smqp://localhost:4001" />
              <property name="resource.names"
                           value="testqueue@router1,plainsocket@router1" />
          </resource-provider>
      Listing 3: Setting the default Resource-Provider for a JSM connection

      This example adds SwiftMQ to be the default Resource-Provider for JMS connections. Adding this will make the resources available in the Orion JNDI under java:comp/resource/SwiftMQ/resourceName as well as making these the default JMS resources for example when a MessageDriven Bean is deployed.

      The file orion-application.xml is normally found in the deployment directory of the Application.

      Notice that the ContextScanningResourceProvider uses the value of a "resource.names" property to bind named resources (separate with a comma) to the Resource-Provider. If the Resource-Provider does not allow Context browsing, this parameter should be used to bind the resources.

5 Examples

    Below are various examples of Resource-Provider usage.

    Examples:

    5.1 Example 1: Using a SwiftMQ ResourceProvider

      This example shows how to setup a ResourceProvider for SwiftMQ release 2.1.3. The example uses the ContextScanningResourceProvider sample Resource-Provider implementation. This class is an example Resource-Provider that can be used to bind a resource existing in another naming context into the local naming tree. This is useful for example with JMS, since the JMS server normally binds the resources in its own JNDI tree. Using this Resource-Provider any such resource can be bound to the local Orion JNDI tree.

      The example covers the following steps:

      5.1.1 Step 1: Download and install SwiftMQ

        Download and install SwiftMQ.

        Install SwiftMQ according to their instructions

      5.1.2 Step 2: Stop Orion

        Stop the Orion server.

      5.1.3 Step 3: Configure the Application

        Edit your Applicaion's orion-application.xml and add an entry similar to this one:


            <resource-provider
                class="com.evermind.server.deployment.ContextScanningResourceProvider"
                display-name="SwiftMQ resource"
                name="SwiftMQ" >
                <description>
                    SwiftMQ resource provider.
                </description>
                <property name="java.naming.factory.initial"
                             value="com.swiftmq.jndi.InitialContextFactoryImpl" />
                <property name="java.naming.provider.url"
                             value="smqp://localhost:4001" />
                <property name="resource.names"
                             value="testtopic,testqueue@router1,plainsocket@router1" />
            </resource-provider>
        Listing 4: Adding SwiftMQ as the default Resource-Provider for JMS connections

        This adds SwiftMQ to be the default Resource-Provider for JMS connections.

        Notice that as SwiftMQ does not allow Context browsing by default, the resources are named above.

        The following resources will be made available to the Application:

          "java:comp/resource/SwiftMQ/testtopic" - a test Topic set up by SwiftMQ by default.

          "java:comp/resource/SwiftMQ/testqueue@router1" - a test Queue set up by SwiftMQ by default.

          "java:comp/resource/SwiftMQ/plainsocket@router1" - Topiq and Queue connection factory set up by SwiftMQ by default.

      5.1.4 Step 4: Include SwiftMQ classes in Application

        Add the swiftmq.jar to your Application or to your Orion servers /lib/ directory for global usage.

        The swiftmq.jar can usually be found in the /[Swift installation directory]/jars/ directory.

      5.1.5 Step 5: Start a SwiftMQ router

        Start a SwiftMQ router.

        On Win32 machines, a script is available at "/[Swift installation directory]/scripts/win32/smqr1.bat".

        On Unix machines, a scripts is available at "[Swift installation directory]/scripts/unix/smqr1".

        The scripts starts up a router at port 4001 with a demo Queue ("testqueue@router1"), Topic ("testtopic") and Factory for Queue and Topic (plainsocket@router1).

      5.1.6 Step 6: Start Orion

        Start Orion.

        Orion should now start and (re)deploy the Application.

      5.1.7 Step 7: MDB deployment

        Any MDB present in the Application will be configured to use the default JMS (SwiftMQ in this case as this is the only Resource-Provider configured to handle the Applications JMS). Their deployment descriptor entries in orion-ejb-jar.xml will look similar to the example given below:


            <message-driven-deployment
                name="logger">
                <ejb-ref-mapping name="log" />
            </message-driven-deployment>
        Listing 5: Deployment descriptor

      5.1.8 Step 8: Configuring MDB's (optional)

        If one or more MDB's in the application should not use the default JMS, the deployment descriptor entries for these MDB's must now be configured.

        Open the Applicatons orion-ejb-jar.xml file and configure the connection-factory-location and destination-location to the non-default JMS as in the following example:


            <message-driven-deployment
                name="logger"
                connection-factory-location="jms/myQueueConnection"
                destination-location="jms/myQueue">
                <ejb-ref-mapping name="log" />
            </message-driven-deployment>
        Listing 6: Configuring the connection-factory-location and destination-location

        Replace jms/myQueueConnection with the JNDI location of the connection factory to use, such as "java:comp/resource/SwiftMQ/plainsocket@router1" or "jms/TopicConnectionFactory".

        Replace jms/myQueue with the JNDI location of the Topic/Queue to use, such as "java:comp/resource/SwiftMQ/testtopic" or "jms/demoTopic".

        The file orion-ejb-jar.xml is normally found in the deployment directory of the Applications EJB-module.

Copyright © 2005 IronFlare AB