Oracle Service Bus (or Service Bus for short) provides a very powerful set of APIs that allow experienced Java developers to create custom transport providers. This is called Service Bus Transport SDK. By using this SDK, it is possible to create custom transport providers to handle both inbound and outbound message handling for specific protocols, without having to worry with the internal details of Service Bus.
The objective of this post is not about how the Service Bus Transport SDK works, neither about providing examples about how to use it. This is very detailed in the Service Bus documentation. Instead, we are going to cover the specifics about creating custom transport providers for Service Bus 12.2.1. Thus; this post will walk through the changes and challenges introduced by this new version, which may help people that want to port their custom transports from previous versions of Service Bus to 12.2.1.
Changes in the Classpath
No matter which IDE you commonly use to develop the code for custom transport providers, when you try to open your project you will face some annoying classpath issues. This will happen because the 12.2.1 version of Service Bus changed many of its JAR files, in an attempt to create a more consistent system library classpath. This is also true for some JAR files that belongs to WebLogic, and many others from the Fusion Middleware stack.
Therefore, you will have to adapt your classpath to be able to compile your source-code again, either compiling the code from the IDE or using the Ant javac task. The XML snippet below is an Eclipse user library export with some of the most important JARs that you might need while working with Service Bus 12.2.1.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<eclipse-userlibraries version="2">
<library name="Java EE API" systemlibrary="false">
<archive path="/oracle/mw-home/wlserver/server/lib/javax.javaee-api.jar"/>
</library>
<library name="Service Bus Transport SDK" systemlibrary="false">
<archive path="/oracle/mw-home/wlserver/server/lib/weblogic.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.xml.xmlbeans.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.kernel-api.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.configfwk.jar"/>
<archive path="/oracle/mw-home/osb/lib/transports/main-transport.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.common.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.services.sources.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.services.core.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.platform.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.utils.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.jmspool.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.resources.svcaccount.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.descriptor.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.descriptor.j2ee.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.descriptor.application.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.descriptor.wl.jar"/>
<archive path="/oracle/mw-home/osb/lib/modules/oracle.servicebus.resources.service.jar"/>
<archive path="/oracle/mw-home/wlserver/server/lib/wls-api.jar"/>
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.utils.full.jar"/>
</library>
<library name="WebLogic JMS API" systemlibrary="false">
<archive path="/oracle/mw-home/wlserver/server/lib/wljmsclient.jar"/>
</library>
<library name="WebLogic WorkManager API" systemlibrary="false">
<archive path="/oracle/mw-home/wlserver/modules/com.bea.core.weblogic.workmanager.jar"/>
</library>
</eclipse-userlibraries>
You might need to change your Ant script as well:
Changes in the Kernel API
Although there are minimal, there were changes in the Service Bus Kernel API that can avoid your code to be compiled. Specifically, you will see some compiler errors in the classes that handle the UI part of your custom transport provider. The first change noticed is the removal of the setRequired() method in the com.bea.wli.sb.transports.ui.TransportEditField class. It seems that it vanished in the 12.2.1 version.
Similarly, the Kernel API removed the DISPLAY_LIST constant from the TransportUIFactory.SelectObject inner class:
However, if you try to compile the source-code using the Ant javac task, it works. Moreover; all the missing parts are still available in the 12.2.1 version of Service Bus, and works in runtime after you install the custom transport provider. For this reason, it can be considered safe to ignore those compiler errors.
Targeting to JDK 1.8
Service Bus 12.2.1 is certified to run on top of Fusion Middleware 12.2.1, which in turn is certified to run on top of JDK 1.8. Thus, it might be a good idea to change your compiler settings to generate JDK 1.8 compliant bytecode.
This is not a pre-requirement of course, since the JVM allows the execution of code compiled in earlier versions. But to promote better alignment with the Fusion Middleware certification matrix, that can be considered a best practice. Besides, you might be interested in using some of the JDK 1.8 new features such as lambdas expressions, pipelines & streams and default methods.
Issues with the Service Bus Console
The Service Bus Console had its UI changed in version 12.2.1. Now it uses the Oracle Alta UI, the same look-and-feel found in major Cloud offerings such as the Integration Cloud Service and SOA Cloud Service. While this is good because it provides better experience for users using the Service Bus Console, it brings an additional challenge when you deploy your custom transport provider.
The challenge is that even after having the custom transport provider installed, you will notice that it will not be available in the Service Bus Console. At first, you will think that the custom transport provider was not installed properly, but if you strictly follow the instructions about how to deploy custom transport providers, you can be certain that it will be installed correctly.
The issue here is a bug in the Service Bus Console regarding internationalization. All the transports must have an entry in a property file that maintains the descriptions of the resources created in Service Bus Console. For the transports that come with Service Bus, these entries are set. But for custom transport providers, you will have to manually create these entries in the properties file in order to have your custom transport provider working with the Service Bus Console. The instructions below will help you to solve this issue.
Firstly, locate the following file:
$MW_HOME/osb/lib/osbconsoleEar/webapp/WEB-INF/lib/adflib_osb_folder.jar
Secondly, open this JAR and edit a properties file that is contained inside. The file to be edited is:
/oracle/soa/osb/console/folder/l10n/FolderBundle.properties
This file generically handles internationalized messages when no language is specified in the browser. You might need to change other files to make your custom transport provider available when specific languages (i.e.: Brazilian Portuguese, Spanish, Japanese) have been set.
You will have to create two, maybe three entries in this file. The first entry provides a generic description to your custom transport provider. If your custom transport provider has inbound support, then it must have an entry for the Proxy Service description. If your custom transport provider has outbound support, then it must have an entry for the Business Service description.
The example below shows the entries for a custom transport provider named kafka, that has both inbound and outbound support:
desc.res.gallery.kafka=The Kafka transport allows you to create proxy and business services that communicate with Apache Kafka brokers.
desc.res.gallery.kafka.proxy=The Kafka transport allows you to create proxy services that receive messages from Apache Kafka brokers.
desc.res.gallery.kafka.business=The Kafka transport allows you to create business services that route messages to Apache Kafka brokers.
Save all the changes made in the properties file, and save this file back to the JAR file. You will need to restart Service Bus to check if this change had effect. After restart Service Bus, you will notice that the Service Bus Console now allows your custom transport provider to be used.
The Oracle support and engineering teams are aware about this bug, and hopefully future versions of Service Bus will eliminate the need to manually create these entries. This issue has no impact if you develop Service Bus applications using Fusion Middleware JDeveloper.
All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission