Oracle RIB (Retail Information Bus) is a message-based integration platform peaked for retail outlets. The messaging layer is Java Message Service, and the messaging provider is Oracle AQ. One of the enterprise solutions that’s frequently integrated with Oracle RIB is Microsoft’s BizTalk Server. While the JNBridge JMS Adapter for BizTalk is a key component enabling this integration, Oracle RIB presents an integration challenge for stand-alone JMS clients like the adapter. This blog entry will discuss how to integrate Oracle RIB to BizTalk Server using the JMS adapter, but first it might be worthwhile to understand the particular problems with integrating stand-alone JMS clients.
Stand-alone JMS clients
JMS clients usually execute in a Java EE container within an application server, for example a Message Driven Bean. The container provides services to the client including transaction enlistment and implicit naming environments. A generic stand-alone JMS client does not execute in a container and must explicitly use the Java Naming and Directory Interface (JNDI) to acquire connection factories and destinations. Because of this, stand-alone JMS clients often require special libraries—the JAR files in the classpath—and configuration properties that are different from those used for a MDB. Some vendors, like IBM, and some products, like WebLogic, provide special thin-client JAR files. For other vendors, it is necessary to choose a subset of JAR files from the Java EE server implementation, copying them to the JMS client machine. Most times, the vendor will actually publish the required JAR files for each version, other times it is necessary to build the class path one ClassNotFoundException at a time.
Depending on the implementation of the JMS server, a stand-alone client may not have access to a JNDI service. Some JMS implementations don’t provide JNDI, relying instead on the host Java EE application server to provide naming and directory services. If the JMS implementation is not integrated into an application server, but is running as a stand-alone broker, all clients must access connection factories and destinations through proprietary APIs. That’s fine, but it isn’t portable, which is the whole idea behind the JMS specification.
Oracle AQ is an example of a JMS implementation that can run as a stand-alone broker or run in a Java EE application server like Oracle WebLogic. This blog will address both scenarios: a stand-alone JMS client, in this case the JNBridge JMS Adapter for BizTalk Server, connecting to Oracle AQ as a stand-alone broker and as a JMS service provider within WebLogic. As we’ll see, both scenarios require some extra work to support a stand-alone JMS client.
Oracle AQ configured as a Foreign Server within WebLogic
Generally speaking, the JMS specification was intended as an API that provides a generic surface on proprietary messaging middleware. The JMS surface is provided by a Java EE application server which also provides JNDI, another generic API for obtaining connection factories and destinations. Usually, the integration of the messaging provider to JMS and JNDI within the application server is accomplished by a Java Connection Architecture resource adapter. However, the preferred method required by Oracle RIB for integrating Oracle AQ to WebLogic is to configure the message provider as a foreign server.
Oracle AQ uses an Oracle Database as its message store, mapping destinations to tables. Because of the transactional nature of the DB, a Java Data Source is used in the foreign server configuration. A data source automatically handles DB transactions by enlisting in a transaction handled by the Java EE transaction manager, a service provided by WebLogic. This works well when the JMS client is executing in a Java EE container because the data source provides the transactional support. However, a stand-alone client is unable to use a data source because there’s no transaction manager available—it’s executing outside the transactional scope. While a JMS client can use local transactions, either explicitly calling commit or rollback, it cannot participate in a distributed transaction.
Foreign Server using a Data Source
Using WebLogic 10.3 and Oracle AQ 11.2, the configuration as a foreign server starts with configuring the data source. A data source for an Oracle DB is a transaction aware wrapper around the database connection URL. This screen shot shows the data source configuration within WebLogic. Note the standard Oracle connection URL at the top with the default SID, orcl.
Here’s a screen shot of the foreign server configuration using the above data source which has been mapped to the JNDI name, jms/oracleDS.
This foreign server configuration will work fine for JMS clients executing inside containers in WebLogic. However, if a stand-alone JMS client attempts to connect to WebLogic, this exception is thrown.
cannot assign instance of weblogic.jdbc.common.internal.RmiDataSource_1033_WLStub to field oracle.jms.AQjmsConnectionFactory.data_source of type javax.sql.DataSource in instance of oracle.jms.AQjmsXATopicConnectionFactory
Foreign Server using a Connection URL
The problem is the data source. If the foreign server configuration does not use a data source, but instead uses the connection URL, then the stand-alone JMS client will be able to connect. The following screen shot shows the foreign server configuration using a connection URL instead of a data source.
Mutually Exclusive: Requires Two Foreign Servers
Now, a stand-alone JMS client can connect to WebLogic and access Oracle AQ queues and topics. However, a JMS client running inside a container in WebLogic cannot use this foreign server configuration. The internal JMS client requires a data source to provide transaction enlistment. The solution is to configure two foreign servers, one using a data source for the WebLogic JMS clients, the other using a connection URL for the external stand-alone JMS clients. Each foreign server configuration will have its own connection factory with a unique JNDI name. Each foreign server will also point to the same Oracle AQ queues or topics, but will use unique JNDI names.
The configuration for the JNBridge JMS Adapter for BizTalk when using Oracle AQ configured as a WebLogic Foreign Server can be found here.
Oracle AQ as a stand-alone broker.
The JMS specification is a generic interface, but there is no specified mechanism for obtaining connection factories or destinations. Generic access is usually provided by JNDI, however the specification does not preclude a non-JNDI mechanism, i.e. a proprietary extension. Oracle AQ is an example of a JMS implementation that doesn’t require JNDI if it is running as a stand-alone broker. However, because the API for creating connection factories and accessing destinations is proprietary, the JNBridge JMS Adapter for BizTalk can only support stand-alone Oracle AQ if there is a JNDI service available.
One way to get around this problem is to write a Java wrapper that mimics JNDI, but uses the Oracle AQ API to create and return connection factories and destinations. JNDI requires the implementation of two Java naming interfaces, InitialContextFactory and Context. When a Java EE client requires remote access to objects in the JNDI repository, it creates an InitialContext from the InitialContextFactory. The client then uses the InitialContext to look-up connection factories and destinations. The InitialContextFactory must implement the method getInitialContext(). Here’s the Java code for that method.
This method simply parses the Hashtable object, environment, that’s an argument to the InitialContext constructor. The JMS Adapter for BizTalk constructs the Hashtable object, populating it with connection values, passing it as an argument to the InitialContext constructor in the factory class where the method getInitialContext() is invoked. The method then creates an instance of OAQContext passing in the connection properties, where they’re stored in instance variables, and returns it. The OAQContext object is an implementation of the Context interface and therefore must implement the lookup() method.
Here’s the implementation for lookup(), notice the casts of the interface javax.jms.Session to the subclass AQjmsSession. This allows the code to invoke the proprietary methods getQueue() and getTopic().
rtn = q;
The private method getCF() creates a ConnectionFactory object using the Oracle AQ API. If the name of the object to look-up matches the the name “QueueConnectionFactory” or “TopicConnactionFactory”, then the appropriate connection factory is returned. In the lookup() method, if a queue or topic name is the target of the look-up, then the connection factory is used to create a connection followed by a session. This is the private method getCF().
The two classes, com.jnbridge.adapters.oaq.InitialContextFactory and com.jnbridge.adapters.oaq.OAQContext must be archived in a JAR file and added to the class path property in the BizTalk transport handlers. In order to correctly build the connection URL for the Oracle Database behind AQ, the Oracle SID must be used. For example, this connection URL,
has a SID name of etude. While the other values in the connection URL can be obtained from the InitialContext constructor argument, the SID name must use a system property. System properties can be defined and set using arguments to the Java Virtual Machine. For that reason, when configuring the JMS Adapter in BizTalk, the JVM Arguments property in the BTS transport handlers must supply this argument:
For more information on configuring the JNBridge JMS Adapter for BizTalk using the JNDI wrapper, please go here.
To download the source for the JNDI wrapper, please go here.
For more information on configuring Oracle AQ as a foreign server in Oracle WebLogic (albeit using a data source), please go here.
The latest 3.0.1 versions of the JMS Adapter for .NET and for BizTalk Server now support Oracle AQ. You can download them here, or take a look at the documentation for using the JNBridge JMS Adapter for BizTalk Server (pdf) or for .NET (pdf) with Oracle AQ.
Past versions of the adapters didn’t support Oracle AQ, as they relied on the standard JMS 1.1 specification, including JNDI. Instead of JNDI, Oracle AQ uses its own proprietary API. The adapters now include a JNDI scaffold, which is basically and implementation of JNDI on top of the proprietary Oracle AQ JMS calls. Also included are guidelines for configuring WebLogic.
This effort grew out of some specific requests to support the Oracle Retail Integration Bus (RIB) with .NET and BizTalk Server. Try it out for yourself, and let us know what you think!
We’ve just released version 2.1 of the JMS Adapter for BizTalk Server and the JMS Adapter for .NET.
Version 2.1 of the JMS Adapter for BizTalk Server adds:
- Fault-tolerant connections for JMS Server shutdown scenarios. This feature provides the ability to configure specific behaviors for send and receive locations when the JMS server is explicitly brought down. Locations can be configured to either disable or periodically attempt to reconnect to the JMS server.
- Support for ISO 8859-15 encoding. Used almost exclusively in Europe, ISO 8895-15 is a single byte encoding that includes the Euro currency character.
- Ability to add a unique identifier to a receive location. This allows multiple receive locations to access the same JMS queue or topic providing a mechanism to support concurrent message consumption using JMS message selectors.
- New configuration documents for SonicMQ and GlassFish/OpenMQ.
- Improved logging and error reporting.
Version 2.1 of the JMS Adapter for .NET adds:
- Support for .NET 4.0.
- Support for version 2.0 of Microsoft’s WCF Line-of-Business adapter framework providing support for Visual Studio 2010.
- Support for Microsoft’s Azure AppFabric API, allowing .NET client endpoints running in the cloud to consume and produce JMS messages from JMS servers on the ground.
- Extended configuration and tuning documentation.
Both adapters are now:
- Built on top of JNBridgePro 5.1, which adds support for .NET Framework 4 and Visual Studio 2010.
We’ve published a new case study on how Graebel Companies, Inc., used the JNBridge JMS Adapter for .NET to leverage existing business logic and easily integrate JMS messaging with their .NET-based SOA framework.
We’ve posted a new case study featuring Benefitfocus and our JMS Adapter for BizTalk Server.
How to streamline incoming carrier data from JMS (Java Message Service) with a BizTalk enterprise application integration infrastructure — and do it within a two-month software development window.
Use an off-the-shelf BizTalk adapter — the JNBridge JMS Adapter for BizTalk Server — to integrate applications into the enterprise infrastructure without the cost, risk, and time-to-deploy associated with an open source or internally developed solution.
Version 1.2 of the JMS Adapter for .NET supports distributed transactions with full rollback capability
Boulder, Colorado, June 1, 2009 (JavaOne Booth #208)
JNBridge, www.jnbridge.com, the award-winning provider of Java and .NET interoperability tools, today announced the release of version 1.2 of its JMS Adapter for .NET. The adapter provides a single-step integration between JMS (Java Messaging Service) capabilities and .NET Framework-based applications. This new version adds interoperability between .NET distributed transactions and local JMS transactions, thereby allowing JMS to fully participate in .NET transactions.
“We use JNBridge’s core product, JNBridgePro, to rapidly integrate our .NET-based Enterprise Service Bus with our JMS broker,” said Don Taylor, CTO for Benefitfocus. “The ability to combine .NET and JMS transactions will allow us to extend our use of JNBridge interoperability technology to additional business-critical applications where preserving the integrity of data is paramount.”
The JNBridge JMS Adapter for .NET integrates any vendor’s JMS implementation directly with a .NET Framework-based application. Customers can quickly and easily create custom .NET applications that send messages to, and receive messages from, an existing JMS infrastructure. In the new version of the adapter, if a .NET-side operation fails inside a transaction, and the transaction must be rolled back, JMS messages that are consumed as part of the transaction will be placed back on the JMS queue, ensuring that no data is lost. When the .NET side resumes its activity, the messages are still on the JMS queue, and will be read when the .NET operations resume.
“JNBridge’s technologies provide seamless integration between both the Java and .NET frameworks, which allows our organization to meet customer demand regardless of platform,” said Michael Petersen, President at TechPath, a systems integration company. “We’ve successfully and easily integrated Microsoft’s products with our customers’ existing JMS systems, including enterprise systems that require 99.999 percent uptime. This new ability to support distributed transactions across platforms will be crucial for certain architectures in financial services and other transaction processing systems.”
“Transactions are critical to many applications, especially in financial services,” said Wayne Citrin, CTO of JNBridge. “A transaction needs to succeed or fail in its entirety, especially where money is involved. Current solutions that support distributed transactions do not guarantee their success across platforms. With version 1.2 of the adapter, this process is completely transparent for the user, and works regardless of the JMS vendor.”
“With the increased adoption of financial systems that integrate both .NET and JEE technologies, true cross-platform transactions are a necessity that current web service-based interoperability standards fail to adequately meet,” said Mark Driver vice president of research at Gartner. “Bridging technologies offer an alternative that is both fine-grained and tightly coupled-a fundamental requirement of any robust transaction processing implementation.”
Pricing and Availability
The JNBridge JMS Adapter for .NET is available for immediate download from www.jnbridge.com, and can be purchased directly from JNBridge.
JNBridge connects Java and .NET-Framework based components and applications together with tools and adapters that are fast, simple to use and remove the complexities of cross-platform interoperability. JNBridge is a privately-held company based in Boulder, Colorado. Founded in 2001, JNBridge has more than 350 unique customers in 40 countries that use JNBridge’s solutions in a wide variety of applications in financial services, insurance, media, manufacturing and other industries. Please visit www.jnbridge.com for more information.
Hello all! The beta program for the JNBridge JMS Adapter is under way. Those of you who’ve already registered for the Beta Partner Program will receive an e-mail linking you to the download page for Beta1. If you haven’t registered, go to www.jnbridge.com/adapter and I’ll follow up with the link.
I’m Bill Heinzman. I will be the main contact for the beta program. Direct all your questions to email@example.com. I’ll be providing all technical support, receiving and replying to your questions and feedback. I know you’re all busy, so if you run into a problem, or don’t understand the documentation—don’t waste your time, send me an e-mail and I’ll remedy the problem ASAP.
I’ll be blogging several times a week providing technical articles on the capabilities of the JNBridge JMS Adapter in combination with WCF, .Net and Visual Studio. I’ll start out each week with a summary of things learned (and the resulting new feature) , things fixed and directions to the latest documentation, patch or beta bits.
For those of you new to JNBridge’s technology and the JMS Adapter, here’s the synopsis:
The JNBridge WCF Adapter for JMS™ is a Windows Communication Foundation implementation that encapsulates Java Message Service client capabilities into a standard WCF Line of Business Adapter. The JNBridge JMS Adapter integrates JMS into into any .Net solution using Visual Studio 2005.
The JNBridge JMS Adapter exposes a simple, yet dynamic interface for producing and consuming JMS messages to and from queues and topics without requiring knowledge of JMS classes, architecture—or even Java, for that matter. During the installation of the JNBridge JMS Adapter, a new plug-in is added to Visual Studio that provides design time integration in .Net applications. By using the new Add Adapter Service Reference plug-in, a developer can create a .Net C# WCF client proxy for integration into a .Net assembly, form or application. The developer can browse specific send and receive operations particular to the queues and topics discovered on any JMS implementation including OpenJMS, JBoss, Websphere, Tibco EMS and WebLogic.
This support for any vendor’s JMS implementation is accomplished through the JNBridge .Net-to-Java interoperability product, JNBridgePro. For more information on JNBridgePro, visit www.jnbridge.com.