42 Packaging and Deploying a Custom Transport Provider

This chapter describes how to package and deploy a custom transport provider for use with Service Bus.

This chapter includes the following sections:

• Packaging the Transport Provider

• Deploying the Transport Provider

• Undeploying a Transport Provider

• Deploying to a Cluster

42.1 Packaging and Deployment Overview

Each custom transport provider requires two files: an EAR file and a JAR file. A third file, a transport plug-in, is required in order to use the custom transport provider in JDeveloper. You must package your custom transport provider as a self-contained JAR file, which defines the transport, and an EAR file, which can be deployed on the WebLogic Server. The EAR file can include the JAR file, or you can make the JAR file a library on which the EAR file depends. Using the latter method means you only need to maintain one copy of the JAR file.

To make the transport available to Service Bus, install the EAR file and, optionally, the JAR file, in /MW_HOME/osb/lib/transports. Typically, both the EAR file and the JAR file are placed in this directory for Service Bus transports, but it is not required that the JAR file be placed there. The plug-in file you create, which makes the custom transport provider available to offline tools, points to the JAR file.

To make the transport available to the Oracle Service Bus Console and runtime, deploy the EAR file to the server with the Service Bus Kernel EAR file and other Service Bus related applications. The sample socket transport provider example illustrates how a transport provider is organized and deployed. For more information, see Creating a Sample Socket Transport Provider.

42.1.1 Custom Transport Provider Components

Each transport provider consists of two distinct components:

• Configuration: The configuration part of a transport provider is used by the Oracle Service Bus Console to register endpoints with the transport provider. This configuration behavior is provided by the implementation of the user interfaces. For more information, see User Interface Configuration.

• Runtime: The runtime part of a transport provider implements the business logic of sending and receiving messages.

A best practice is to package the transport provider so the configuration and runtime parts are placed in separate deployment units. This practice makes cluster deployment simpler. For more information, see Deploying to a Cluster and Transport Provider Components .

42.1.2 Custom Transport Provider Resources

Your transport JAR file must include the following resources:

• A MANIFEST.MF file that contains key information about your transport plug-in. Use the sample socket transport MANIFEST.MF for reference.

• A TransportConfig.xml file, which configures the transport provider. Use the sample socket transport plug-in as a reference. See Step 5. Define the TransportProviderConfiguration XMLBean.

• The compiled Java classes containing your transport implementation.

• The compiled XML bean generated classes.

• (Optional) Resources for providing online help.

42.2 Packaging the Transport Provider

This section describes the structure of the JAR and EAR files for your custom transport providers. To see an example of any of the files listed in this section, build the sample socket transport provider, as described in Building and Deploying the Sample . You can then view all the packaged artifacts. You can also review the sample build.xml file to see an example of how to compile and deploy the custom transport provider.

42.2.1 Transport JAR File Packaging

You package your transport provider as a JAR file, which makes the transport portable. Use the following guidance for packaging your transport provider:

• To construct the plug-in JAR, append "transport" to the name of the custom transport to create the JAR file name. For example, the sample socket transport JAR file is named sock_transport.jar.

• Package the file with the following directory structure, as illustrated in Figure 42-1:

  • /com (transport classes and resources)

  • /help

    If you are providing help for your transport, include a /help directory for your help resources, as described in Creating Help for Custom Transports.

  • /META-INF/MANIFEST.MF

  • /schemaorg_apache_xmlbeans (XML bean classes and resources)

  • TransportConfig.xml (the XMLBean transport provider configuration; see Step 5. Define the TransportProviderConfiguration XMLBean)

The following figure shows the sample socket transport provider JAR directory.

Figure 42-1 Plug-In Packaging

Description of "Figure 42-1 Plug-In Packaging"

To see an example of plug-in packaging, build the sample socket transport, as described in Creating a Sample Socket Transport Provider. View the generated sock_transport.jar and sock_transport.ear.

42.2.2 Transport EAR File Packaging

You package the runtime components of the custom transport provider in an EAR file, which can then be deployed to the WebLogic Server. This file can either contain the JAR file or can depend on the JAR file as a library. A typical packaging structure for the EAR file would include the following:

• APP-INF/lib/name-transport.jar

• META-INF/MANIFEST.FM and additional schema files

• Any additional web application files, such as packaged help files

42.2.3 Transport Plug-in Registration for JDeveloper

In order for JDeveloper to pick up the new transport, you need to create a plug-in file that describes the transport provider implementation, transport ID, help ID (if any), and additional libraries that are required for the transport. You do not need to create this file if you do not plan to use the transport in JDeveloper. The naming convention for a plug-in file is transport-transport_name.xml.

Use the following format to create the plug-in registration file:

<plugin xmlns="http://www.bea.com/alsb/offline/extensions">
    <transport 
        class="transport_provider_class"
        id="transport_id"
        helpId="ID_to_access_help"/>
    <libraries>
        <library name='name_and_path_for_transport_jar'/>
    </libraries>
</plugin>

The following example shows the sample plug-in file provided with the sample socket transport provider installed with Service Bus.

Example - Sample Socket Transport Provider Plug-in File

<plugin xmlns="http://www.bea.com/alsb/offline/extensions">
    <transport 
        class="com.bea.alsb.transports.sock.SocketTransportProviderFactory"
        id="socket"
        helpId="contexts_socketTransport"/>
    <libraries>
        <library name='lib/transports/sock_transport.jar'/>
    </libraries><
</plugin>

42.3 Transport Plug-in Installation

Once you create your transport provider EAR file, JAR file, and optional plug-in for JDeveloper, you need to add the files to the JDeveloper installation so they can be picked up by JDeveloper.

• Copy the generated EAR and JAR files to /MW_HOME/osb/lib/transports.

• Copy the plug-in registration file to /MW_HOME/osb/config/plugins.

42.4 Deploying the Transport Provider

After you create a deployable EAR file for your transport provider, you need to deploy it to the Service Bus domain. You can deploy the EAR file by whichever of the following methods you prefer:

• Programmatically (using WebLogic Deployment Manager JSR-88 API)

• Using the Oracle WebLogic Server Administration Console

• Adding an entry similar to the following example to the Service Bus domain config.xml file

Example - Application Deployment Entry

<app-deployment>
    <name>My Transport Provider</name>
    <target>AdminServer, myCluster</target>
    <module-type>ear</module-type>
    <source-path>$MW_HOME$/osb/lib/transports/mytransport.ear</source-path>
    <deployment-order>6</deployment-order>
</app-deployment>

Note:

The deployment order of your transport provider EAR file should be high enough so that the entire Service Bus Kernel EAR is deployed before the transport provider.

42.4.1 Transport Registration

On server restart, you need to ensure that your deployed transport can immediately begin to handle service requests. To ensure immediate transport availability, extend the weblogic.application.ApplicationLifecycleListener class and use the preStart() method to register your transport using TransportManager.registerProvider().

For an example implementation, see the ApplicationListener class provided wiht the sample socket transport, located at OSB_ORACLE_HOME/samples/servicebus/sample-transport/src/com/bea/alsb/transports/sock. When extending ApplicationLifecycleListener, be sure to register your extending class in META-INF/weblogic-application.xml. The sample socket transport provides the following entry for its ApplicationListener class in OSB_ORACLE_HOME/samples/servicebus/sample-transport/META-INF/weblogic-application.xml:

<weblogic-application>
  <listener>
    <!-- This class gives callbacks for the deployment lifecycle and socket
    transport is registered with ALSB whenever the application is started.
    -->
    <listener-class>com.bea.alsb.transports.sock.ApplicationListener
    </listener-class>
  </listener>
</weblogic-application>

42.5 Undeploying a Transport Provider

Once a transport provider has been registered with Service Bus, the undeployment or unregistration of the transport provider is not supported.

42.6 Deploying to a Cluster

Your transport provider must be deployed on all the servers and clusters where Service Bus is deployed. This means that if Service Bus is deployed only on the Admin Server (which it always is), you must deploy the transport provider on the Admin Server. If Service Bus is deployed in an admin + Managed Server topology, you must deploy the transport provider on the Admin Server and that particular Managed Server. If Service Bus is deployed in a cluster, you must deploy your transport provider on the Admin Server and the cluster. Note that Service Bus is always deployed on the Admin Server regardless of the domain topology.

The application code inside your transport provider EAR file needs to be aware dynamically of where the transport is being deployed (such as the Admin Server or a Managed Server) and exhibit only configuration behavior on the Admin Server and only runtime behavior on the Managed Server.

For example, in the initialization pseudo code in some_transport.ear, you can use this logic to decide whether or not to activate the configuration or runtime portion of the provider:

protected SomeTransportProvider() throws TransportException {
    . . . some other initialization code . . .
    if (!isRuntimeEnabled)
        _engine = new RuntimeEngine(. . .);
}

In this case, creating an instance of the RuntimeEngine class is runtime behavior and only needs to happen on a managed node in a multi-server domain or on the administration node in a single server domain.

Furthermore, in a cluster environment, TransportProvider.createEndPoint() and deleteEndPoint() are called on an Admin Server as well as Managed Servers in the cluster (with the exception of WLS HTTP router/front-end host). Some transport providers can choose not to do anything other than registering the fact that there is an endpoint with the given configuration, such as HTTP. In general the transport provider needs to examine whether createEndPoint() or deleteEndPoint() is called on the administration or Managed Server to decide the appropriate behavior.