This chapter describes how to package and deploy a custom transport provider for use with Oracle Service Bus.
This chapter includes the following sections:
You must package your custom transport provider as a self-contained EAR file. You can then deploy the EAR with the Oracle Service Bus Kernel EAR and other Oracle Service Bus related applications.
Tip:
The sample socket transport provider example illustrates how a transport provider is organized and deployed. See Section 42, "Sample Socket Transport Provider," for more information.
Each transport provider consists of two distinct parts:
Configuration – The configuration part of a transport provider is used by Oracle Service Bus Administration Console to register endpoints with the transport provider. This configuration behavior is provided by the implementation of the UI interfaces.Section 41.6, "User Interface Configuration."
Runtime – The runtime part of a transport provider implements the business logic of sending and receiving messages.
Tip:
A best practice is to package the transport provider so that the configuration and runtime parts are placed in separate deployment units. This practice makes cluster deployment simpler. See Section 43.4, "Deploying to a Cluster" for more information. See also Section 38.4, "Transport Provider Components."
This section discusses how to deploy a transport provider.
Tip:
For more information on deploying applications to Oracle Service Bus, see the Oracle Fusion Middleware Deployment Guide for Oracle Service Bus.
After you create a deployable EAR file for your transport provider, you need to deploy it to the Oracle Service Bus domain. You can deploy the EAR by whatever method you prefer:
Programmatically (using WebLogic Deployment Manager JSR-88 API)
Using the Oracle WebLogic Server Administration Console
Adding an entry similar to Example 43-1 to the Oracle Service Bus domain config.xml file
Example 43-1 Application Deployment Entry
<app-deployment>
<name>My Transport Provider</name>
<target>AdminServer, myCluster</target>
<module-type>ear</module-type>
<source-path>$USER_INSTALL_DIR$/servicebus/lib/mytransport.ear</source-path>
<deployment-order>1234</deployment-order>
</app-deployment>
Note:
The deployment order of your transport provider EAR file should be high enough so that the entire Oracle Service Bus Kernel EAR is deployed before the transport provider.
On server restart, you want 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().
The sample socket transport has an ApplicationListener class that you can use for reference, located at OSB_ORACLE_HOME/samples/servicebus/socket-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>
Once a transport provider has been registered with Oracle Service Bus, the undeployment or unregistration of the transport provider is not supported.
Your transport provider must be deployed on all the servers/clusters where Oracle Service Bus is deployed. This means that if Oracle Service Bus is deployed only on the Admin Server (which it always is), you must deploy the transport provider on the Admin Server; if Oracle 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; and if Oracle Service Bus is deployed in a cluster, you must deploy your transport provider on the Admin Server and the cluster. Oracle 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, as mentioned previously, 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.