Using Foreign JMS Providers with WebLogic...

Using Foreign JMS Providers with WebLogic Server

May 2002

Copyright © 2002 BEA Systems, Inc.

BEA Systems, Inc.

Font for text in the document is Arial Narrow. Is this some template that you got from someone ? Why not Times New Roman ?


1 INTRODUCTION ......................................................................................................... 3 1.1 WHY USE A FOREIGN JMS PROVIDER?................................................................... 3 1.2 WHY USE WEBLOGIC JMS INSTEAD....................................................................... 3 1.3 NEW FEATURES IN WEBLOGIC SERVER 7.0 ............................................................ 4

2 CONFIGURING JMS USING JNDI........................................................................... 4 2.1 USING WEBLOGIC JNDI.......................................................................................... 6 2.2 USING THE JNDI FILESYSTEM PROVIDER ............................................................... 7 2.3 USING THE JNDI LDAP PROVIDER......................................................................... 7 2.4 USING THE JNDI PROVIDER IN FIORANO FIORANOMQ .......................................... 8 2.5 USING THE JNDI PROVIDER IN IBUS MESSAGESERVER ......................................... 9 2.6 CREATING FOREIGN JNDI OBJECTS IN A STARTUP CLASS ..................................... 9 2.7 COPYING FOREIGN JNDI OBJECTS TO WEBLOGIC SERVER.................................. 10 2.8 SUMMARY.............................................................................................................. 11

3 CONFIGURING JMS PROVIDERS ........................................................................ 11 3.1 MQSERIES ............................................................................................................. 11 3.2 SONICMQ .............................................................................................................. 15 3.3 TALARIAN SMARTSOCKETS................................................................................... 16 3.4 FIORANOMQ.......................................................................................................... 17 3.5 IBUS MESSAGESERVER ......................................................................................... 18 3.6 SUMMARY.............................................................................................................. 20

4 JMS FEATURES IN WEBLOGIC SERVER........................................................... 20 4.1 MESSAGING BRIDGE.............................................................................................. 20 4.2 MESSAGE-DRIVEN BEANS ..................................................................................... 22

5 SAMPLE CODE.......................................................................................................... 24 5.1 BASIC DEMONSTRATION PROGRAM ...................................................................... 24 5.2 SIMPLEMDB.......................................................................................................... 30 5.3 MQ-SPECIFIC WEBLOGIC STARTUP CLASS........................................................... 34

May, 2002 Using Foreign JMS Providers with WebLogic Server Page 2


1 Introduction This document describes ways to integrate WebLogic Server with JMS providers from other vendors. It includes information about using a foreign JMS provider with a message-driven bean, as part of the WebLogic Messaging Bridge, and in a stand-alone client program. This document discusses five foreign JMS providers:

MQSeries from IBM SonicMQ from Progress Software SmartSockets from Talarian FioranoMQ from Fiorano IBus MessageServer from SoftWired

1.1 Why Use a Foreign JMS Provider? Customers sometimes need to use a different JMS provider from WebLogic JMS. Some of the reasons for doing this are:

Legacy system access. It may be necessary to use a foreign JMS provider because only that software provides access to a particular legacy system, because only that software connects to a platform where WebLogic Server is not available.

Message forwarding. Some customers may need to forward messages between a foreign JMS provider and WebLogic JMS, or even between two foreign JMS providers. In WebLogic Server 6.1 SP3 and 7.0, this can be accomplished without programming by using the Web-Logic Messaging Bridge. In addition, this document describes some ways to do this without using the bridge. Some customers may want to use two-phase commit when they do this in order to eliminate the possibility of losing or duplicating a message.

Driving message-driven beans. Some customers, especially those who need to access messages from legacy systems, may need to use a foreign JMS provider to supply messages to a message-driven bean.

1.2 Why Use WebLogic JMS Instead Thanks to the standards of Java 2 Enterprise Edition (J2EE), WebLogic Server provides flexible out-of-the-box support for foreign JMS providers. But for most applications, the JMS support built in to WebLogic Server is easier to use, configure, and monitor, and it provides performance and features that meet or exceed those of competing JMS vendors. Some reasons to use We-bLogic JMS are:

WebLogic JMS runs as an integral part of WebLogic Server. On the other hand, a foreign JMS provider must be configured, started, stopped, and monitored using a totally separate set of tools.

WebLogic JMS is integrated with the built-in JNDI and clustering support of WebLogic Server. There is no need to configure and manage a separate JNDI infrastructure, whether it is a collection of files or an LDAP server.

WebLogic JMS provides strict conformance with the JMS specification, so applications may be written in a portable way.



WebLogic JMS provides excellent performance and scalability. WebLogic JMS provides more efficient transaction management for JMS. When a foreign

JMS provider is used, both WebLogic and the foreign provider must undergo the extra over-head of two-phase commit between WebLogic Server and the JMS provider.

1.3 New Features in WebLogic Server 7.0 Version 7.0 of WebLogic Server provides several features that make it easier to integrate with foreign JMS providers.

1.3.1 WebLogic Messaging Bridge

The WebLogic Messaging Bridge is a part of WebLogic Server that forwards messages from a “source” destination to a “target” destination. Out-of-the-box adapters are provided so that the source and/or target may be a JMS destination. Either end can be a JMS topic or queue, and could be a server running WebLogic Server 5.1 or higher, or a foreign JMS provider. The WebLogic Messaging Bridge also provides interoperability between different versions of WebLogic Server.

The WebLogic Messaging Bridge supports two-phase commit transactions using XA for JMS providers that support it, and one-phase commit transactions for providers that do not. Section 4.1 describes how to use the bridge in more detail, and also discusses how some versions of We-bLogic Server other than 7.0 can support the bridge.

1.3.2 Container-Managed Transactions for Message-Driven Beans

A message-driven bean (MDB) is a special type of Enterprise Java Bean (EJB) that pulls mes-sages from a JMS queue or topic. The EJB container (WebLogic Server) is responsible for connecting to the JMS provider, receiving messages, and passing them to the MDB in the proper transaction context. This allows asynchronous events to be processed by a J2EE-based applica-tion, which was not possible in a standard way before MDBs..

WebLogic Server has supported MDBs since WebLogic Server 6.0. Version 6.0 SP1 of the server added support for foreign JMS providers. However, container-managed transactions could only be used with WebLogic JMS, so a foreign JMS provider could not participate in the WebLogic transaction.

WebLogic Server 7.0 allows foreign JMS providers to participate in a WebLogic transaction. If the MDB is set up to support container-managed transactions, and if the JMS provider is config-ured to support XA, then WebLogic Server will use XA to include the JMS provider in the overall WebLogic transaction. This way, it is possible to deploy an MDB that supports “Exactly-once” transactional guarantees, thereby ensuring that each message will be processed once and only once.

Section 4.2 describes how to use container-managed transactions and foreign JMS providers in more detail.

2 Configuring JMS Using JNDI A program written against the JMS API can work with any vendor’s implementation of JMS, as long as it complies with the JMS specification. This is possible when the JMS client program uses



JNDI (the Java Naming and Directory Interface) to look up the initial “Connection Factory” object. Once this object has been looked up from the directory, it is used to create the “Connec-tion” object, then the “Session” object, and so on until all the necessary objects are created. Since all these objects implement the standard JMS interfaces, any program that uses only the standard interfaces can interoperate with any compliant JMS provider. Plus, since the connection factory is stored in JNDI by the provider itself, it provides a place for the provider to put its own configura-tion information, such as the location of the server, or any special options it may implement.

Destination objects – queues and topics – can also be stored in JNDI. This gives each provider a way to associate special configuration parameters with each destination that may not be a part of the standard JMS interface.

JNDI is also a standard Java interface. Therefore, a client written to this standard API can look up information from any type of directory that implements the standard Java interfaces.

WebLogic Server uses JMS and JNDI when it interfaces with JMS inside the WebLogic Messag-ing Bridge, or when receiving messages for a message-driven bean. Stand-alone JMS clients, session beans, and servlets can also use JNDI to get access to a JMS provider.

Since WebLogic Server uses JNDI to look up the connection factory and destination objects, it can be configured to work with any JMS provider that properly implements the JMS and JNDI specifications.

In order for WebLogic Server to look up the JMS connection factory from JNDI, four pieces of information are needed. These are described below, and examples are provided later in this document:

Initial context factory. This is the name of the JNDI class that will be created to perform the lookup. This class may be part of the JDK, it may be provided by Sun Microsystems, or it may be provided by the JMS vendor itself.

Provider URL. This URL is used to tell the initial context factory where to find the directory information. It may refer to a server using a protocol like LDAP, or it may refer to a file in the filesystem, or something else.

Connection factory JNDI name. This is the name of the connection factory object that is stored in JNDI. Each JMS provider creates its own tool to create this object and store it in JNDI. Once it is stored there, any JMS client program (including WebLogic Server) can look up the object.

Destination JNDI name. This is the object that represents a JMS destination – a queue or a topic – as stored in JNDI. Like the connection factory, each JMS provider will provide its own tool to create the object and place it in JNDI.

When setting up WebLogic Server to access a foreign JMS provider, these four parameters must be specified. The remaining topics in this section of this document describe how to use various JNDI providers. After that, section 3 describes the various JMS providers. You will need information from both sections to set up a particular interaction between JMS and WebLogic Server. In this section, there is information about a few basic types of JNDI providers.

General-purpose JNDI providers. The filesystem and LDAP providers are examples of general-purpose JNDI providers. They may be used to store various types of Java objects on behalf of many different types of servers. Normally, once an object is stored in a general-



purpose JNDI provider, it remains there in persistent form and may be looked up at a later time after a server restart. MQSeries and SonicMQ are examples of JMS providers that rely on a general-purpose JNDI provider in order to provide interoperability with WebLogic Server.

Vendor-specific JNDI providers. Some JMS providers, such as FioranoMQ and IBus MessageServer, provide a JNDI interface of their own. JMS connection factory and destina-tion objects may be looked up using this provider, usually without any additional configura-tion required on the client or on the server. However, these providers only allow JNDI access to their own objects, and cannot be used to store additional information.

WebLogic JNDI. A JNDI provider is built in to WebLogic Server. It combines some aspects of a general-purpose JNDI provider with those of a vendor-specific provider. Like a general-purpose JNDI provider, it can be used to store all kinds of objects, and users can use it to store their own objects as well. And like a vendor-specific provider, it is built in to WebLogic Server and requires no additional configuration. JNDI objects that are created by the server itself, such as WebLogic Server JMS connection factory and destination objects, are auto-matically re-created when the server starts up. However, other objects that users store in JNDI are not automatically re-created, and must be inserted into JNDI every time the server starts up using a mechanism such as a WebLogic “startup class”.

2.1 Using WebLogic JNDI As described above, the JNDI provider built in to WebLogic combines aspects of a general-purpose and a vendor-specific JNDI provider. When using the JMS server built in to WebLogic Server, this is the JNDI provider that you will use. The WebLogic JNDI provider is included as part of a standard client or server installation, so there is nothing to install or configure.

There are various options for connecting to the provider, and covering all of them is beyond the scope of this document. You will find more information in the “Programming with WebLogic JNDI” document at the following URL:

http://e-docs.bea.com/wls/docs70/jndi/jndi.html

JMS providers such as MQSeries that do not include a vendor-specific JNDI provider cannot directly use WebLogic JNDI because objects stored there by a third party are not persistent. However, there are two ways to place these vendor’s JMS information into WebLogic JNDI that may be of interest. These methods may involve more steps then using a general-purpose JNDI provider such as LDAP or the filesystem provider, but they do provide some advantages.

The first method is to use a WebLogic “startup class” to create objects in JNDI every time WebLogic Server is started. This is possible because in addition to JNDI, each JMS provider makes it possible to create connection factory and destination objects using their proprietary JMS classes. (For instance, in MQSeries it is possible to do this using the “com.ibm.mq.jms.MQQueueConnectionFactory” class.) This technique is described in more detail in section 2.6, and an example can be found in section 5.3.

The second method is to first create the objects in a general-purpose JNDI provider, and then to copy them into WebLogic JNDI, again using a startup class. This technique is useful be-cause while simple JNDI providers such as the filesystem provider are confined to a single machine, objects stored in WebLogic JNDI can be automatically replicated to all the servers in a WebLogic cluster. This method is described in section 2.7.




2.1.1 Using the WebLogic Provider

Initial context factory: Set to “weblogic.jndi.WLInitialContextFactory”.

URL: When using WebLogic JNDI from inside WebLogic Server – such as inside a session bean or entity bean – you should create an “InitialContext” object with no arguments. Similarly, when using a message-driven bean or the WebLogic Messaging Bridge, you do not usually specify a URL. Otherwise, see the “Programming with WebLogic JNDI” document at the following URL:


2.2 Using the JNDI Filesystem Provider The “filesystem provider” is the simplest general-purpose JNDI provider. This implementation of JNDI simply stores objects in a set of specially-formatted files on the disk. This method may not scale to the needs of a giant corporation, but it is very useful in smaller environments or in development.

2.2.1 Acquiring the Filesystem Provider

The filesystem provider (which Sun sometimes calls the “FS Context”) is not shipped with the Java Development Kit (JDK). Instead, it must be downloaded from Sun from the following URL:

http://java.sun.com/products/jndi/

2.2.2 Installing and Configuring the Filesystem Provider

To install the provider, extract the JAR files from the ZIP file. You must place two files in your CLASSPATH: “fscontext.jar” and “providerutil.jar”.

To configure the provider, simply create a directory. You will refer to the directory in the URL, and the provider will create any files that are necessary. To make the objects available on differ-ent systems, either copy the files or mount them using a network file system.

2.2.3 Using the Filesystem Provider

Initial context factory: Set this to “com.sun.jndi.fscontext.RefFSContextFactory”.

Provider URL: Set this to “file:/directory/”, where “directory” is the name of the directory that you created to store the JNDI information. For instance “file:/D:/JNDI/”.

2.3 Using the JNDI LDAP Provider The LDAP provider is a generic JNDI provider that allows Java objects to be stored in a LDAP server. LDAP servers are available from a number of vendors, and open-source implementations are also available. LDAP servers generally use some sort of database to store directory informa-tion, and may provide features such as security and replication. They are designed to store thousands of directory entries, and are certainly up to the task of handling a few Java objects for JMS.





LDAP servers do not allow clients to store arbitrary kinds of information in them out of the box. Instead, they must be explicitly configured to support different kinds of data. In order to store Java objects in LDAP, a standard LDAP schema was defined. This schema must be installed on your LDAP server before you can use it to store JMS objects. The schema, and an associated “readme” file that describes how to set it up, are included in the LDAP provider download from Sun. In addition, some LDAP servers, such as OpenLDAP, include this schema as part of their supplied configuration files.

2.3.1 Acquiring the LDAP Provider

Parts of the LDAP provider are shipped with certain versions of the Java Development Kit (JDK). However, it is a good idea to download the latest provider from Sun to avoid any possible inconsistencies. The provider can be downloaded from the following URL:


2.3.2 Installing and Configuring the LDAP Provider

Before you can use the Java classes, you must install, configure, and start an LDAP server. That is beyond the scope of this document. If your LDAP provider does not include the proper schema for storing Java objects, use the tools provided in the “schema” subdirectory of the provider .zip or .tar file that you downloaded from Sun to set it up.

Once the server is installed, you must place two files in your CLASSPATH: “ldap.jar” and “providerutil.jar”.

2.3.3 Using the LDAP Provider

Initial context factory: Set this to “com.sun.jndi.ldap.LdapCtxFactory”.

Provider URL: Set this to “ldap://host:port/dn-prefix”. If not specified, “port” defaults to 389. The setting of “dn-prefix” will depend on the way the LDAP server was set up. All JNDI lookups will start at the point denoted by this prefix. For instance, if the URL is: ldap://testhost/ou=Testing,o=TestCo,c=US

then a lookup of the object named: cn=TestJMSServer

will result in a lookup of following distinguished name, using the LDAP server running on port 389 of “testhost”: cn=TestJMSServer,ou=Testing,o=TestCo,c=US

2.4 Using the JNDI Provider in Fiorano FioranoMQ FioranoMQ is a JMS provider that includes a vendor-specific JNDI provider. This provider may only be used to look up objects that are automatically defined by the FioranoMQ server itself. It cannot used to store other Java objects.

Fiorano also allows FioranoMQ objects to be stored in an LDAP server. Consult the Fiorano documentation if you want to do this, and then use the settings in section 2.3 to enable WebLogic Server to access LDAP.




2.4.1 Using the Fiorano Provider

Initial context factory. Set this to “fiorano.jms.rtl.FioranoInitialContextFactory”.

URL: Set this to “http://host:port/”.

2.5 Using the JNDI Provider in IBus MessageServer IBus MessageServer is another JMS provider that includes a vendor-specific JNDI provider. This JNDI provider can only be used to look up objects that already exist inside the IBus server – it may not be used to store any other objects.

The IBus JNDI provider is provided as part of the standard IBus installation. No additional JAR files need to be configured.

2.5.1 Using the IBUS Provider

Initial context factory. Set this to either:

“ch.softwired.jms.naming.IBusQueueContextFactory”, or “ch.softwired.jms.naming.IBusTopicContextFactory”.

This is necessary because IBus JNDI does not necessarily return the correct type of destination object (Queue or Topic) when a client does a JNDI lookup. Instead, it tries to guess. You must explicitly specify either the “QueueContextFactory” or the “TopicContextFactory” object for each message-driven bean or Messaging Bridge instance that uses IBus in order to get the right type of destination objects back.

URL: When using this provider, the IBus client does not use this parameter, but instead reads a configuration file to determine the configuration of the server. However, the WebLogic Messag-ing Bridge requires that this parameter be set. We recommend setting this parameter to a value like “ibus:///” to avoid configuration errors.

2.6 Creating Foreign JNDI Objects in a Startup Class In addition to the other topics described in this document, it is possible to add objects to JNDI inside a startup class – a special class that runs inside WebLogic Server when the server is first started. Inside this startup class, use the vendor’s proprietary API to create connection factory and destination objects as necessary, and store them in WebLogic JNDI using the “InitialContext” class.

Unlike other approaches described in this document, this technique requires that you write code to a specific vendor’s JMS classes, rather than only writing code to the standard “javax.jms” interfaces. However, by using this technique you can avoid setting up JNDI, and you can also avoid using some of the vendor-specific JNDI configuration utilities described in section 3. Also, once the object is registered in JNDI by the startup class, it can be made available to all the nodes in the cluster, whereas a simple JNDI provider such as the filesystem provider is usually only available to one node at a time. (A LDAP server, of course, can be made available to many machines on the network.)



An example startup class that implements this technique can be found in section 5.3. This section also describes how to configure the class.

For more information on how to implement a startup class, see the WebLogic Server Javadoc, which can be found at the following URL:

http://e-docs.bea.com/wls/docs70/javadocs/index.html

For advanced information on WebLogic JNDI, including information on how to ensure that foreign JMS objects stored within WebLogic JNDI are replicated (or how to insure that they are not), see the “Programming WebLogic JNDI” document, available at the following URL:


2.7 Copying Foreign JNDI Objects to WebLogic Server Another way to get foreign JMS objects into WebLogic JNDI is to copy them from a general-purpose JNDI provider into WebLogic JNDI in a startup class. This technique allows vendor-specific tools to be used to create the objects in the provider’s JNDI, but then the objects can be stored in WebLogic JNDI and replicated throughout the cluster.

This technique consists of three steps:

1. Configure a general-purpose JNDI provider, such as the filesystem provider, as described in section 2.2, or configure a provider-specific JNDI provider, depending on which JMS pro-vider you are using.

2. Configure your JMS provider as described in the appropriate part of section 3. 3. Install the wrappers as a startup class. When WebLogic Server is started, the wrappers will

read objects from the provider’s JNDI provider and insert them into WebLogic JMS.

For details of this technique, and a set of Java classes that can be used to implement it, look on http://dev2dev.bea.com under “Code Library...alpha code”, and then click on “WebLogic Server”. The item is called “WebLogic MQSeries JMS Support”. It can also be found at the following URL:

ftp://edownload:[email protected]/pub/downloads/wlsmqseries.zip




http://dev2dev.bea.com/



2.8 Summary Table 1: Configuration parameters for JNDI providers

Provider JAR Files Context Factory URL

WebLogic Server

provided in standard WLS JAR files

weblogic.jndi. WLInitialContextFactory

none for server use, or see WebLogic Server documentation

Filesystem fscontext.jar providerutil.jar

com.sun.jndi.fscontext. RefFSContextFactory

file://directory/

LDAP ldap.jar providerutil.jar

com.sun.jndi.ldap. LdapCtxFactory

ldap://host:port/prefix

Fiorano FioranoMQ

provided in standard Fiorano JAR files

fiorano.jms.rtl. FioranoInitialContextFactory

http://host:port/

IBus MessageServer

provided in standard IBus JAR files

ch.softwired.jms.naming. IBusQueueContextFactory or ch.softwired.jms.naming. IBusTopicContextFactory

not required (but see note in section 2.5.1)

3 Configuring JMS Providers This section describes how to configure the following JMS providers with WebLogic Server:

IBM MQSeries Progress Software’s SonicMQ Talarian SmartSockets Fiorano FioranoMQ IBus MessageServer

In order for these JMS providers to interoperate with WebLogic Server, JNDI must be used, so this section will also refer to the information about JNDI that was covered in section 2.

3.1 MQSeries

3.1.1 Basic MQSeries Concepts

Like other client-server systems, MQSeries consists of two major components: a server (called the “queue manager”) and a client. The queue manager consists of a number of processes that use shared memory to communicate with each other. It is responsible for storing messages either in memory or on the disk (in the case of persistent messages). A third component, the pub-lish/subscribe broker, is a separate application that uses the MQSeries API to forward pub-lish/subscribe messages. It must be installed and started separately if publish/subscribe is to be used.

The MQ client API has two separate implementations:

The classic MQ API, referred to as “bindings mode,” uses shared memory to communicate with a queue manager running on the came machine as the client application.



The other implementation is referred to as “client mode,” and uses a TCP/IP socket to communicate with a special process that runs as part of the queue manager called the “lis-tener.”

There is very little difference between the two implementations of the MQSeries API. However, one item is important: in order to use MQSeries as an XA resource manager, the “bindings” mode must be used. XA is an optional feature in JMS that allows a transaction manager (such as WebLogic Server) to control a resource manager (such as MQSeries) and provide two-phase commit support for transactional integrity. In order to run the WebLogic Messaging Bridge in “Exactly-once” delivery mode, or to use a message-driven bean with container-managed transac-tions, XA is required. These topics will be explored in more detail in section 4.

In order to set up MQSeries for use with JMS, it is necessary to configure MQSeries on two levels:

The first level is the standard MQSeries level. Here you create the necessary servers, queues, and channels necessary for your application.

The second level is the JNDI level. A special JNDI administration tool, which is provided by IBM, must be used to create various objects in JNDI before you can use MQSeries JMS.

3.1.2 Installing MQSeries Components

On a Windows NT/2000 system, MQSeries is normally installed in C:/Program Files/MQSeries. However, you may want to install it in C:/Program Files/IBM/MQSeries for consistency with the MQSeries Java “SupportPac”, as you’ll see below.

In order to use MQSeries JMS, you must install the MQSeries Java support. If this is not avail-able as part of the MQSeries software you received from IBM, it can be downloaded for free from the IBM MQSeries web site. Look for SupportPac “MA88”. You can find this feature at: http://www-3.ibm.com/software/ts/mqseries/txppacs/txpm2.html, but be aware that URLs change often.

In addition, if you want to use the publish/subscribe features of JMS, you must also install the publish/subscribe support for MQ. This is available from the same web site listed above as SupportPac “MA0C”. (However, if you will only use MQSeries and JMS for point-to-point message queuing, and not for publish/subscribe, then you do not need to install this SupportPac.)

To start MQSeries on Windows, right-click the “IBM MQSeries” icon in the system tray in the lower right corner of your screen and select “Start IBM MQSeries”. On Windows and Unix platforms, you can also use the “strmqm” command.

In order to run publish/subscribe applications with JMS, you must also start the publish/subscribe broker that you installed from SupportPac “MA0C”. To start the broker, use the “strmqbrk” command. If you do not start the broker, then MQSeries JMS will return an error message when you attempt to create a TopicConnection object.


http://www-3.ibm.com/software/ts/mqseries/txppacs/txpm2.html


3.1.3 Setting Environment Variables

You must add the following JAR files to your CLASSPATH in order to use MQSeries. We recommend setting these environment variables in the shell or script that you will use to run “java weblogic.Server”.

On Windows NT/2000, the following JAR files are required for all MQSeries JMS installations: C:/Program Files/IBM/MQSeries/Java/lib/com.ibm.mq.jar C:/Program Files/IBM/MQSeries/Java/lib/com.ibm.mqjms.jar C:/Program Files/IBM/MQSeries/Java/lib

(Note that you should include the “lib” directory in your CLASSPATH in addition to the JAR files so that MQSeries JMS can find its message catalogs. Otherwise, MQSeries will print a warning message every time an application is started that uses JMS.)

The following JAR file is required only if you are running MQSeries in “bindings mode”, which is what happens when WebLogic Server runs on the same host as the MQSeries queue manager: C:/Program Files/IBM/MQSeries/Java/lib/com.ibm.mqbind.jar

You must also set CLASSPATH to include the appropriate JNDI provider. See section 2 for more information.

Finally, if you are running MQSeries in “bindings mode”, you must also add the MQSeries shared library directories to your PATH. (Note that these exact directory locations may differ depending on where you install the base MQSeries product:) C:/Program Files/IBM/MQSeries/Java/lib C:/Program Files/IBM/MQSeries/bin

On a platform other than Windows NT/2000, the preceding settings must still be set, but the exact path names will differ. In addition, you will need to use an environment variable such as LD_LIBRARY_PATH or LIBPATH instead of PATH as described above. In all these cases, consult the IBM MQSeries documentation for the most up-to-date information.

3.1.4 Running “JMSAdmin”

JMSAdmin is an IBM-supplied program that manipulates MQSeries configuration information in JNDI. It is located in C:/Program Files/IBM/MQSeries/Java/bin and is driven by a configuration file in the same directory called “JMSAdmin.config”.

You must edit JMSAdmin.config in order to run this program. You may want to edit it in-place or make a copy. If you make a copy, “JMSAdmin” will first access the “JMSAdmin.config” file in your local directory, and then use the copy in the MQSeries installation directory. (For more advanced options, see the MQSeries documentation.)

JMSAdmin.config must be edited for the JNDI provider that you are using. You can select a filesystem provider or an LDAP provider. Use the values specified in Table 1 for the provider that you choose.



For example, for the filesystem provider, you will set the following: INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory PROVIDER_URL=file:<some directory> SECURITY_AUTHENTICATION=none

Once the configuration file is edited, you must set your CLASSPATH environment variable to the proper values, again from Table 1. Once you have done this, you can run “JMSAdmin.bat”.

3.1.5 Adding Entries to JNDI

Before you can use MQSeries with WebLogic Server, you must define at least one connection factory and at least one destination in JNDI.

In MQSeries, like WebLogic JMS, the connection factory defines many parameters that affect how the connection to a server behaves. Unlike WebLogic JMS, the connection factory also specifies the location of the queue manager, either on the same machine as WebLogic Server or elsewhere on the network. The JNDI provider where the connection factory is stored may be a completely different machine from the machine where the MQSeries queue manager runs.

Also unlike WebLogic JMS, the definition of queues and topics in JNDI is totally separate from the creation of these objects on the queue manager. In order to use an MQSeries queue with JMS, you must create it using an MQSeries administration tool such as “runmqsc” or the MQSeries Explorer, and you must also define a “queue” object in JNDI.

On the other hand, MQSeries publish/subscribe does not require that you define topics in ad-vance. So, it is only necessary to create a “topic” object in JNDI, and not to perform any configu-ration of MQSeries itself in order to use publish/subscribe. (However, a publish/subscribe broker must be configured and started, as described briefly in section 3.1.2.)

“JMSAdmin” has a command-line interface, but it can easily be scripted. See the IBM document “MQSeries Using Java” for the complete details. Below are some examples of common com-mands:

Display a summary of everything in JNDI, and to check if you are properly configured: dis ctx

Add a QueueConnectionFactory object called “QCF” for an MQSeries queue manager named “QM1”, which runs on the same host as WebLogic Server: def qcf(QCF) qmanager(QM1)

Add a TopicConnectionFactory object called “TCF” for an MQSeries queue manager named “QM1”, which runs on the same host as WebLogic Server: def tcf(TCF) qmanager(QM1)

Add an XAQueueConnectionFactory object called “XAQCF” for an MQSeries queue manager named “QM1”, which runs on the same host as WebLogic Server: def xaqcf(XAQCF) qmanager(QM1)

Add a QueueConnectionFactory object called “Remote_QCF” for an MQSeries queue manager named “QM2”, which runs on port 1414 of host “remotehost”: def qcf(Remote_QCF) qmanager(QM2)



host(remotehost) port(1414) transport(client)

Add a Queue named “TEST1” on the queue manager named “QM1”: def q(TEST1) queue(TEST1) qmanager(QM1)

(Note: if you do not add the “queue” argument you will not be able to use this queue, even though this parameter seems redundant.)

Add a Topic called “Topic1” on the queue manager named “QM2”: def t(Topic1) topic(Topic1)

(Note: if you do not add the “topic” argument you will not be able to use the topic, even though this parameter seems redundant.)

Finally, there are many other options for the various JNDI objects than the ones described here. Refer to the MQSeries documentation to get all the details.

3.1.6 Limitations

WebLogic Server is able to take advantage of the XA support in MQSeries to provide the “Exactly-once” mode of operation in the WebLogic Messaging Bridge, and also to provide container-managed transactions in message-driven beans. However, since MQSeries only supports XA in “bindings mode”, this support is only available if the WebLogic Server and MQSeries queue manager run on the same machine. If this configuration is not possible, then consider using the “Duplicates-okay” or “Atmost-once” mode in the bridge, or using bean-managed transactions with message-driven beans.

3.2 SonicMQ

3.2.1 Basic SonicMQ Concepts

In SonicMQ, JMS is integrated into the server, rather than being a separate installation as is required by MQSeries. However, SonicMQ does not configure JNDI automatically, so it must still be set up manually before SonicMQ is to be used with WebLogic Server.


You must add the following JAR files to your CLASSPATH in order to use WebLogic Server with SonicMQ. We recommend that you set these environment variables in the shell or script that you will use to run “java weblogic.Server”: C:/Program Files/SonicSoftware/SonicMQ/lib/sonic_Client.jar C:/Program Files/SonicSoftware/SonicMQ/lib/sonic_XA.jar

The second JAR file is only necessary if you are using the XA features of SonicMQ.

(Of course, these JAR files will be in a different directory if you are using a different platform or if you chose to install SonicMQ in a different directory.)



3.2.3 Configuring JNDI

The “Sonic MQ Explorer” GUI tool can be used to insert JMS objects into JNDI. To run this tool, you must ensure that the JNDI JAR files are in your CLASSPATH. One way to do this is to edit the startup script for the “SonicMQ Explorer.” On Windows, this file is usually located in: C:/Program Files/SonicSoftware/SonicMQ/bin/explorer.bat

SonicMQ supports both LDAP and filesystem JNDI providers. Use Table 1 to determine which JAR files to add to your CLASSPATH.

Once you have started SonicMQ explorer, you must type the JNDI provider information into the GUI. Select “JMS Administered Object Stores” from the “navigation tree” window on the left, select “JNDI Naming Service” in the box to the right, and then type the following in the “Proper-ties” text box: java.naming.factory.initial=<initial context name>,

java.naming.provider.url=<provider url>

(In this example, take the values of “initial context name” and “provider url” from Table 1.)

You must type in this information all on one line – it is not possible to do that on this page, so ignore the line breaks shown here and do not replace them with spaces. Also, the two values here must be separated by a comma, without spaces, as shown above.

Once this is accomplished, a line will appear in the tree view window to the left. Select your JNDI provider in this window; you should be able to graphically manipulate the contents of the JNDI tree using the GUI.

(Note that Sonic MQ also makes it possible to store connection factory and destination objects using what it calls the “filesystem”. Although this sounds similar to the “filesystem JNDI pro-vider” that we are talking about in this document, it is not the same. You must use JNDI in order to interoperate between WebLogic Server and SonicMQ.)

3.2.4 Limitations

Sonic MQ version 4.0 implements XA in a non-standard way. WebLogic Server recognizes this for use with message-driven beans, but not with the WebLogic Messaging Bridge. So, it is possible to deploy message-driven beans with container-managed transactions against SonicMQ 4.0.

However, the WebLogic Messaging Bridge does not recognize SonicMQ specifically, and it may not be run in “Exactly-once” mode when SonicMQ is used. You must choose “Duplicates-okay” mode for the bridge instead when using SonicMQ.

3.3 Talarian SmartSockets

3.3.1 Basic Talarian Concepts

Talarian provides a product called “SmartSockets for JMS”. This product includes the Talarian messaging product, which provides publish/subscribe and point-to-point messaging, with a JMS API layer. There are two basic servers you must use: “MQServer” is used for point-to-point



messaging, while “RTServer” does publish/subscribe. It is not necessary to run both servers unless you want to use both styles of messaging.


SmartSockets provides a pre-configured script, called “JMSVAR~1.BAT”, which sets the environment variables required to run a SmartSockets client. On Windows, this script is usually located in: C:\PROGRA~1\Talarian\jms11\bin\i86_w32

We recommend that you run this script before starting “java weblogic.Server”, or that you call it from your regular server startup script.


SmartSockets for JMS provides an administration tool that can update JNDI as queues, topics, and connection factory objects are created. This administration tool uses a file called “jndi.properties” for configuration. On Windows, this file is normally located in: C:/Program Files/Talarian/jms11/lib

There is a setting in this file called “java.naming.provider.url”. This is the same as the “URL” setting in Table 1. The setting of this parameter should match between Talarian and WebLogic Server.

3.3.4 Limitations

Not all versions of SmartSockets support XA. Unless XA is supported, you will not be able to deploy a message-driven bean that supports container-managed transactions, and you will not be able to run the WebLogic Messaging Bridge in “Exactly-once” mode.

3.4 FioranoMQ

3.4.1 Installing FioranoMQ Components

After performing the installation, you will be able to start a FioranoMQ server from the Windows “Start” menu. You will also be able to start an administrative GUI for the server. However, in order to start the GUI, you will need to know two things that are not necessarily easy to find in the installation instructions:

The default URL for the server, which is “http://localhost:1856/” The administration password, which is “passwd”.


The following JAR file must be included in the CLASSPATH of WebLogic Server: C:/Program Files/Fiorano/FioranoMQ/lib/fmprtl.zip




Fiorano has a built-in JNDI provider. A QueueConnectionFactory called “PRIMARYQCF” and a TopicConnectionFactory called “PRIMARYTCF” come as part of the default configuration. In addition, all topics and queues defined using the administration tools are automatically registered in JNDI.

See section 2.4 for information on the proper “initial context factory” and “provider URL” settings for FioranoMQ.

If you want, it is also possible to configure FioranoMQ to store its destination and connection factory objects in an LDAP server. See the Fiorano documentation for more information on this.

3.4.4 Limitations

FioranoMQ does not support XA. This means that the WebLogic Messaging Bridge cannot be used with FioranoMQ in “Exactly-once” mode. You must configure the bridge in “Duplicates-okay” or “Atmost-once” mode instead.

This also means that it is not possible to deploy a message-driven bean that uses container-managed persistence. You must configure the MDB for bean-managed persistence, or set the “trans-attribute” of the bean to “NotSupported”.

3.5 IBus MessageServer

3.5.1 Installing IBus Components

After performing the IBus installation, be sure that the environment variables IBUSSRV_HOME and IBUSSRV_ADMIN_HOME have been set by the installation program. If they were not set (for instance, if you did not install the product as the “Administrator” user), then you must set them before any of the pre-configured administrative tools can work. Assuming that IBus was installed in the C:/Program Files/iBusMessageServer4.5.0LE directory, they should be set as follows: IBUSSRV_HOME = C:/Program Files/iBusMessageServer4.5.0LE/server IBUSSRV_ADMIN_HOME = C:/Program Files/iBusMessageServer4.5.0LE/adminClient

Once IBUSSRV_HOME is set, you can run the IBus “Configuration Wizard” from the Start menu to configure and start the server.


In addition to the IBUSSRV_HOME and IBUSSRV_ADMIN_HOME environment variables, the following JAR file must be included in the CLASSPATH of WebLogic Server: C:/Program Files/iBusMessageServer4.5.0LE/client/lib/msrvClt.jar




IBus comes with a built-in JNDI provider that is already configured and part of the standard client and server installations. This provider was discussed in section 2.4.

When WebLogic JMS goes to look up Queue and Topic objects from IBus JNDI, IBus tries to guess whether it should return a Queue or a Topic object. Unfortunately, it does not always guess correctly. As a result, you may receive an error message from WebLogic Server indicating that the destination cannot be found.

In order to get around this situation, you must choose the correct “initial context factory” setting when performing lookups from JNDI, depending on whether you are looking up a Queue or a Topic. For message-driven beans and Messaging Bridge instances that read from a queue, you must specify: ch.softwired.jms.naming.IBusQueueContextFactory

When reading from a Topic, on the other hand, you must specify: ch.softwired.jms.naming.IBusTopicContextFactory

Finally, you may find that it is more convenient in a large environment to store IBus connection factory and destination objects in an LDAP server. IBus supports this, although you must write a custom Java program to accomplish it. The IBus objects do not implement the Java “Reference-able” interface, so it is not possible to store them in the JNDI filesystem provider.

3.5.4 Limitations

At this time, it is not possible to use the WebLogic Messaging Bridge to forward messages from a WebLogic JMS queue or topic to an IBus queue or topic because IBus throws an exception when WebLogic Server attempts to set the message ID on the message that was forwarded. This issue is being tracked at BEA as CR076239, which will change WebLogic Server to accommodate this behavior. If you want to use the Messaging Bridge in this way, please contact BEA support and mention this CR.

However, it is possible to use the Messaging Bridge to forward messages in the opposite direction – from a IBus queue or topic to a WebLogic JMS queue or topic. Also, it is possible to use IBus as a source for message-driven beans. XA support is provided, and works with WebLogic JMS, so container-managed transactions are also supported.

Also, WebLogic JMS is not able to process JMS “MapMessage” objects that have been received from IBus if they contain a byte array field. This happens because the IBus MapMessage class uses a non-standard data type for byte array fields. As a result, it is not possible at this time to use the Messaging Bridge to receive MapMessage messages from IBus and forward them to a WebLogic JMS destination if they contain a byte array field.


BEA Systems, Inc.

Why?


3.6 Summary Table 2: Configuration parameters for JMS providers

JMS Provider JNDI Provider(s) Supported

CLASSPATH PATH

WebLogic Server

WebLogic Server Installed with WLS none

MQSeries File, LDAP com.ibm.mq.jar com.ibm.mqbind.jar com.ibm.mqjms.jar “lib” directory

C:/Program Files/IBM/MQSeries/Java/lib; C:/Program Files/MQSeries/bin

SonicMQ File, LDAP sonic_Client.jar sonic_XA.jar

none

SmartSockets File, (possibly others)

Set by SmartSockets configuration script

Set by SmartSockets configuration script

Fiorano FioranoMQ

Built-in provider, also LDAP

fmprtl.zip none

IBus MessageServer

Built-in provider; also LDAP

msrvClt.jar none

4 JMS Features in WebLogic Server

4.1 WebLogic Messaging Bridge

The Messaging Bridge, a new feature of WebLogic Server 7.0, can be used to shuttle messages between two JMS destinations, whether these are destinations in WebLogic JMS or another JMS product, and whether these destinations are JMS queues or topics. (The Messaging Bridge also supports a generic adapter framework so that other types of systems will be able to be integrated in the future.) The Messaging Bridge is also available as a fully-supported part of WebLogic Server 6.1 SP3, and in alpha mode for WebLogic Server 6.1 with no service packs.

Note that in addition to offering interoperability between different JMS providers, the bridge also allows interoperability between different versions of WebLogic JMS. Although the bridge itself runs on version 6.1 and greater, the Messaging Bridge can be used to forward messages between destinations running on WebLogic Server 5.1 and greater.

The bridge supports various qualities of service:

“Exactly-once” guarantees that each message is forwarded once and only once regardless of failure

“Duplicates-okay” guarantees that messages will not be lost, but may be forwarded more than once in case of failure

“Atmost-once” provides no guarantees

The bridge can provide “Exactly-once” service only when both JMS providers are configured to use XA. (XA support is built in to WebLogic JMS. However, the bridge does not support XA when working with WebLogic JMS versions 5.1 and 6.0.)



The Messaging Bridge works by receiving messages from a “source” JMS destination, and then passing those same Message objects directly to a “target” destination. In order for this to work, the destination provider must be able to understand a message produced by the source provider. This is required by the JMS specification, but not all vendors implement this functionality completely. See section 3 for information about particular JMS providers.

You may want to verify that you can forward messages between two different JMS providers before running the bridge. The program “TransferMessages.java” can be used to do this. It may be found in section 5.1.

Additional documentation on using the WebLogic Messaging Bridge may be found at the following URL:

http://e-docs.bea.com/wls/docs70/adminguide/msgbridge.html

4.1.1 Messaging Bridge Settings

The WebLogic Messaging Bridge depends on the WebLogic J2EE Connector Architecture in order to interface with JMS. Before you can deploy the Messaging Bridge, the appropriate J2EE connector must be deployed. Refer to the Messaging Bridge documentation in the WebLogic Server Administration Guide for information on how to do this.

In order to use the Messaging Bridge, you must first create a “JMS Bridge Destination” for each JMS queue or topic that you want to use with the bridge. You should set the following parameters when configuring each destination:

Adapter JNDI Name: If using an JMS connection factory that supports XA, use eis.jms.WLSConnectionFactoryJNDIXA. If using a connection factory that does not support XA, use eis.jms.WLSConnectionFactoryJNDINoTX.

Adapter Classpath: Rather than setting this parameter, set the CLASSPATH and PATH environment variables (if necessary) before starting WebLogic Server. See Table 1 and Table 2 for information about how to set these environment variables for the JMS provider you are using.

Initial Context Factory: This is the name of the initial context factory class for your JNDI provider, as described in Table 1.

Connection URL: This is the URL for your JNDI provider, as described in Table 1. If the bridge destination is a WebLogic JMS server that runs on the same server or cluster as the bridge, then leave this parameter blank.

Connection Factory JNDI Name: This is the name of a JMS connection factory object, which you created and stored in JNDI using your JMS provider’s administration tool, such as IBM’s “JMSAdmin” or Sonic’s “Explorer”, or using the WebLogic Server console.

Destination JNDI Name: This is the name of a JMS “queue” or “topic” object, which you created and stored in JNDI using the JMS provider’s administration tool.

Once you have defined the destinations, you can create instances of the bridge. Be aware that if you want to enable “Exactly-once” delivery for the bridge, you must have configured an XA connection factory for your JMS provider and used that XA connection factory when creating your bridge destinations. If you do not configure an XA connection factory, then the bridge will log an error and refuse to start unless you change the “Quality of Service” parameter to “dupli-cates-okay” or “atmost-once”, or set the “QOS Degradation Allowed” parameter of the bridge.




When using WebLogic JMS as the source or target for the Messaging Bridge in “Exactly-once” mode, it is necessary to use a connection factory that supports XA. (This feature is available in WebLogic Server 6.1 and higher.) To configure such a connection factory, you must set the “User Transactions Enabled” and “XA Connection Factory Enabled” options in the console. (If you configure the connection factory using a JMSConnectionFactory element in the config.xml file, then these attributes are called “UserTransactionsEnabled” and “XAConnectionFactoryEnabled”.

4.2 Message-Driven Beans A message-driven bean (MDB) is a new kind of Enterprise JavaBean (EJB) that was introduced in the EJB 2.0 specification to provide for the integration of JMS with EJBs. A message-driven bean’s “onMessage” method is invoked by WebLogic Server whenever a message is received from a JMS Queue or Topic. WebLogic Server automatically creates and removes message-driven bean instances as needed to process incoming messages.

If the MDB is configured to support “container-managed transactions”, then WebLogic Server will also automatically start a transaction and enlist the JMS provider as a participant in the transaction before invoking the MDB’s “onMessage” method. The MDB may then perform other transactional operations, such as updating a XA-enabled relational database. Support for con-tainer-managed transactions with foreign JMS providers is a new feature in WebLogic Server 7.0, and is not available with earlier versions of the product.

MDBs are sensitive to the difference between a queue and a topic. If the same MDB is configured to read messages from a queue, and it is deployed on several servers in a WebLogic Server domain, then each message will be only delivered to one instance of the MDB. However, if that MDB is configured to read messages from a topic, then one copy of the message will be delivered to each MDB in each separate server.

For more information on MDB's, see:

http://edocs.bea.com/wls/docs70/ejb/message_beans.html

There is also a very good article on MDB's called "How to Develop Message-Driven Beans" at:

http://www.sys-con.com/java/article.cfm?id=604

Note that MDBs were first supported in WebLogic Server 6.0. Support for MDBs that use a foreign JMS provider is not available until WLS 6.0 Service Pack 1.

See section 5.2 for a sample message-driven bean, complete with the necessary XML files for deployment.

4.2.1 Container-Managed Transactions and XA

A message-driven bean can be configured to support container-managed transactions. This means that when a message is received from the JMS destination, the server uses a distributed transac-tion so that the JMS server participates in a two-phase commit with any other transactional resource managers, such as databases, that are used by the MDB. For instance, this feature allows an MDB to update a database and ensure that if a server crashes, either the database will be updated or the message will remain on the queue for processing, but not both or neither.


http://edocs.bea.com/wls/docs70/ejb/message_beans.html

http://www.sys-con.com/java/article.cfm?id=604


WebLogic Server uses the Java Transaction API (JTA) and the optional XA extensions to JMS to support distributed transactions if the message-driven bean is configured to use container-managed transactions. Specifically, this means:

The “transaction-type” element in the ejb-jar.xml file is “Container”, and The “trans-attribute” element in the ejb-jar.xml file is “Required”

To use a message-driven bean with container-managed transactions, you must configure it to use a JMS connection factory that supports XA. If the connection factory does not support XA, then the message-driven bean cannot be deployed.

When container-managed transactions are used, then the “onMessage” method on the MDB will be invoked inside a WebLogic Server transaction. Any other transactional resources that the MDB accesses – such as “TxDataSource” objects – will be “infected” with the transaction, so that the JMS server and all those other resources will either all commit or all roll back.

If there is an application error inside the “onMessage” method of a container-managed bean, call “setRollbackOnly” on the MessageDrivenContext object associated with your MDB. This object is provided by the “setMessageDrivenContext” method, which will always be called before your MDB is invoked. If you call “setRollbackOnly”, then the EJB container will roll back the transaction, and all the work done by the transaction will be undone.

(Note that in JMS, an XA transaction is different from the kind of transaction you get by creating a “transacted Session”. In JMS, a transacted session is internal – it only affects one JMS session’s operations. A distributed transaction using XA, on the other hand, may involve many transac-tional resources, such as databases and other JMS servers that also support XA.)

If XA support is not available for your JMS provider, you can deploy the MDB with a “trans-attribute” of “NotSupported”, or with a “transaction-type” of “Bean”. In those cases, WebLogic Server will receive the message using a non-transacted JMS session, and call “acknowledge” on the message once it has been processed. If you want to indicate that the message could not be processed, throw a RuntimeException from inside the message-driven bean’s “onMessage” method. WebLogic Server will handle this exception and call “recover” on the JMS session so that the message can be processed again later.

4.2.2 Message-Driven Bean Settings

To configure a message-driven bean to receive messages from a foreign JMS provider, you must set the following parameters in your “weblogic-ejb-jar.xml” file:

destination-jndi-name: This is the name of a JMS “queue” or “topic” object, which you created and stored in JNDI using the JMS provider’s administration tool.

initial-context-factory: This is the name of the initial context factory class for your JNDI provider, as described in Table 1. (It is not necessary to include this parameter if you are us-ing WebLogic Server JMS.)

provider-url: This is the URL for your JNDI provider, as described in Table 1. (It is not necessary to include this parameter if you are using WebLogic Server JMS and the JMS server is on the same server or in the same cluster as your MDB.)

connection-factory-jndi-name: This is the name of a JMS connection factory object, which you created and stored in JNDI using your JMS provider’s administration tool, such as IBM’s



“JMSAdmin” or Sonic’s “Explorer”. (It is not necessary to include this parameter if you are using WebLogic Server JMS.)

4.2.3 System Properties for Message-Driven Beans

When an MDB is configured with container-managed transactions and a foreign JMS provider, WebLogic Server will attempt to “back off” if there are too many errors while trying to process messages. By default, the container will pause the processing of messages for five seconds after 10 consecutive errors. (It is considered an error if the MDB throws a RuntimeException or if it calls “setRollbackOnly.”

The following system properties can be set on the command line for WebLogic Server in order to control this behavior. They can be replaced by a different configuration mechanism in a future release.

weblogic.ejb20.MaxMDBErrors: This property defines the maximum number of consecu-tive errors that may be raised by an MDB’s “onMessage” routine before processing of the MDB will pause. It is considered an error if the “onMessage” routine throws a RuntimeEx-ception, or if it calls “setRollbackOnly” on the transaction. This property defaults to 10. The counter associated with this parameter is reset every time a message is successfully proc-essed. A separate counter is maintained for every MDB class deployed on the server.

weblogic.ejb20.MDBErrorSleepTime: This property determines how long processing of an MDB will pause after “MaxMDBErrors” is exceeded. The value of this parameter is the sleep time in seconds. This property defaults to 5 (5 seconds).

5 Sample Code

5.1 Basic Demonstration Program The following program cam be used for various purposes. Out of the box, it sends a message to one JMS queue, receives it and sends to another, and then passes the message between the queues two more times.

If left unmodified, the program can be used to test message object interoperability between two different JMS providers. (You will need to change some constants at the top of the file for your particular providers.) This capability is necessary in order for the WebLogic Messaging Bridge to work.

You can also modify this program and use it as the basis for a simple JMS client. For instance, change “main” so instead of calling “JMSSend” and “JMSReceive” repeatedly, it simply calls “JMSSend” once. Then, it can be used to send a message to any JMS provider, or it may be used to drive a message-driven bean.

You can also use this program as the basis for a home grown “messaging bridge” much like the bridge supplied with WebLogic Server 7.0. By receiving a message from one queue and sending it to another queue on a different JMS provider, you have the basics of such a bridge.

In order to run this program, do the following:

Set up your CLASSPATH and PATH environment variables as described in Table 1 and Table 2.



Set up your JMS provider and put its objects into JNDI, as described in section 3. In the source code below, replace the value of “MQqcf” with the name of the JMS queue

connection factory you created for the foreign JMS provider using its native administration tool, as described in section 3.

Replace the value of “MQqname” with the name of the JMS queue that you set up using the provider’s native administration tool.

Replace the value of “WLSqname” with the JNDI name of a queue you created on the WebLogic Server.

Replace the value of “MQurl” with the URL for the JNDI provider that stores the foreign JMS provider’s object, as described in Table 1.

Replace the value of “WLSurl” with the URL for the WebLogic Server that you will use. Replace “MQJNDIfactory” with the name of the appropriate JNDI provider from Table 1.

Compile both “TransferMessages.java” and “ProviderConnection.java” using “javac”, like this: javac TransferMessages.java ProviderConnection.java

Run the test by executing “java TransferMessages”. You may need a period (“.”) in your CLASSPATH in order for this to work.



5.1.1 TransferMessages.java /* * This program defines an object that works for WLS JMS and foreign * provider JMS connection factories and queues. In the sample main, it * generates a foreign provider message, sends and receives it via the * foreign provider JMS, sends and receives it via WLS JMS, then sends * and receives it via the foreign provider’s JMS. * * Usage: java TransferMessages */ import javax.jms.*; import javax.naming.*; import javax.naming.directory.*; import java.util.Hashtable; public class TransferMessages { /* * WebLogic JMS setup. Edit the variables below in order to * specify which WebLogic JMS server and queue this program will use. */ // WLSJNDIfactory: Initial context factory for WebLogic. // There will be no need to change this public static final String WLSJNDIfactory = "weblogic.jndi.WLInitialContextFactory"; // WLSurl: URL for WebLogic Server which hosts connection factory. // Change this if your WLS server is located somewhere else. public static final String WLSurl = "t3://localhost:7001/"; // WLSqcf: JNDI connection factory name for WebLogic. You may change // this if you wish to use a different one, but this default is // always available public static final String WLSqcf = "weblogic.jms.ConnectionFactory"; // WLSqname: Queue name (in JNDI) for WebLogic queue. Change this // to reflect the name of the queue you wish to use in WLS public static final String WLSqname = "TestQueue";



/* * Foreign JMS provider setup. Edit the variables below in order to * specify which foreign JMS server you will connect to and which * queue this program will use. */ // MQJNDIfactory: Initial context factory for foreign provider. // MQurl: URL for JNDI provider // Both values are from Table 1 // -- Filesystem JNDI provider, for MQ, SonicMQ, and so forth public static final String MQJNDIfactory = "com.sun.jndi.fscontext.RefFSContextFactory"; public static final String MQurl = "file:/D:/JNDI/"; // -- Uncomment for LDAP provider for MQ, SonicMQ, etc. // public static final String MQJNDIfactory = // "com.sun.jndi.ldap.LdapCtxFactory"; // public static final String MQurl = "ldap://host:port/"; // -- Uncomment for FioranoMQ JNDI provider // public static final String MQJNDIfactory = // "fiorano.jms.rtl.FioranoInitialContextFactory"; // public static final String MQurl = "http://localhost:1856"; // -- Uncomment for IBus JNDI provider // public static final String MQJNDIfactory = // "ch.softwired.jms.naming.IBusQueueContextFactory"; // public static final String MQurl = "NotUsed"; // MQqcf: The name of the connection factory (in JNDI) for the // foreign JMS provider public static final String MQqcf = "QCF"; // -- Uncomment for IBus. It has hard-coded connection factory names // public static final String MQqcf = "QueueConnectionFactory"; // MQqname: Queue name (in JNDI) for foreign JMS queue public static final String MQqname = "TEST_QUEUE";



public static void main(String[] args) { ProviderConnection MQobject = null; ProviderConnection WLSobject = null; TextMessage msg; Context ctx; try { // Create foreign connection factory, connection, session, queue MQobject = new ProviderConnection(MQurl, MQJNDIfactory, MQqcf, MQqname); // Create the WLS connection factory, connection, session, queue WLSobject = new ProviderConnection(WLSurl, WLSJNDIfactory, WLSqcf, WLSqname); msg = MQobject.createTextMessage("Test String"); MQobject.send(msg); msg = MQobject.receiveTextMessage(); System.out.println("Received message: "+msg); WLSobject.send(msg); msg = WLSobject.receiveTextMessage(); System.out.println("Received message: "+msg); MQobject.send(msg); msg = MQobject.receiveTextMessage(); System.out.println("Received message: "+msg); } catch(JMSException je) { System.out.println("Caught JMSException: "+je); Exception le = je.getLinkedException(); if (le != null) { System.out.println("Linked exception: "+le); } je.printStackTrace(); } catch(Exception e) { e.printStackTrace(); System.out.println("Caught Exception: "+e); } finally { try { if (MQobject != null) { MQobject.cleanup(); } if (WLSobject != null) { WLSobject.cleanup(); } } catch (Exception ignore) {} } } }



5.1.2 ProviderConnection.java import javax.jms.*; import javax.naming.*; import javax.naming.directory.*; import java.util.Hashtable; public class ProviderConnection { private Queue ioQueue; private QueueSession session; private QueueConnection connection; private QueueConnectionFactory factory; private QueueSender queueSender; private QueueReceiver queueReceiver; private InitialContext ctx; public ProviderConnection(String url, String jndi, String qcf, String qname) throws JMSException, NamingException { // Get the initial context Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, jndi); if (url != null) { env.put(Context.PROVIDER_URL, url); } // env.put(Context.REFERRAL, "throw"); ctx = new InitialContext(env); factory = (QueueConnectionFactory)ctx.lookup(qcf); // Create a QueueConnection, QueueSession connection = factory.createQueueConnection(); session = connection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE); ioQueue = (Queue)ctx.lookup(qname); ctx.close(); connection.start(); queueSender = session.createSender(ioQueue); queueReceiver = session.createReceiver(ioQueue); } public TextMessage createTextMessage(String text) throws JMSException { return session.createTextMessage(text); }



public void send(Message msg) throws JMSException { System.out.println("Sending the message on queue " + ioQueue.getQueueName()); // If on WLS 5.0 or 6.0 with no service pack, uncomment the // next three lines // msg.setJMSDestination(null); // code around WLS bug CR042458 // if (msg.getJMSCorrelationID() == null) // msg.setJMSCorrelationID("fix"); // code around WLS bug CR042461 queueSender.send(msg); } public TextMessage receiveTextMessage() throws JMSException { TextMessage msg; System.out.println("Receiving the message on queue " + ioQueue.getQueueName()); msg = (TextMessage)queueReceiver.receive(1000); if (msg == null) throw new JMSException("Failed to receive message"); return(msg); } public void cleanup() throws JMSException { if (session != null) { session.close(); session = null; } if (connection != null) { connection.close(); connection = null; } } }

5.2 SimpleMDB This program is a very simple message-driven bean. It simply prints the JMS message ID of every message that it receives.

As shown, this MDB is configured to receive messages from MQSeries under a container-managed transaction. In this configuration, XA is used to provide two-phase commit between MQSeries and WebLogic Server. You can configure this MDB to receive messages from another JMS provider by editing the “weblogic-ejb-jar.xml” file.



5.2.1 Building the Example

To compile SimpleMDB and package it for deployment to WebLogic Server, follow these steps using the files in the following sections: mkdir weblogic mkdir weblogic/jms mkdir weblogic/jms/whitepaper copy SimpleMDB.java weblogic/jms/whitepaper mkdir build mkdir build\META-INF copy ejb-jar.xml build\META-INF copy weblogic-ejb-jar.xml build\META-INF javac -d build weblogic/jms/whitepaper/SimpleMDB.java cd build jar cvf simplemdb.jar . cd .. java weblogic.ejbc \ -compiler javac \ build\simplemdb.jar simplemdb_compiled.jar

5.2.2 Deploying the Example

Once you have built the “simplemdb_compiled.jar” file, there are several ways to deploy it.

One simple way to deploy the bean is using the Administration Console. Click the “Deploy-ments/EJB” icon on the navigation tree on the left. Next, click the “Configure a new EJB” link in the right pane. Then, select the “simplemdb_compiled.jar” file as the file to deploy, follow the menus, and select a target for your message-driven bean. It will then be deployed.

You can also deploy the message-driven bean using the weblogic.Deployer utility. This method and several others are discussed in the “WebLogic Server Deployment” document, which may be found at the following URL:

http://e-docs.bea.com/wls/docs70/programming/deploying.html

If you are using WebLogic Server 6.0, message-driven beans are not supported out of the box. Before you can run EJB 2.0 with WLS 6.0, you need to download the EJB 2.0 upgrade for WLS at the following URL:

http://commerce.beasys.com/downloads/weblogic_server.jsp - wls

The file “ejb20.zip” contains an “ejb20.jar” file that needs to be extracted and added to the CLASSPATH. You must also edit the configuration file, “config/mydomain/config.xml”, to deploy the EJB by adding the some lines like the following before the final </domain> line: <Application Name="MDB" Path="d:\apps"> <EJBComponent Name="MDB" URI="simplemdb_compiled.jar" Targets="myserver"/> </Application>



http://commerce.beasys.com/downloads/weblogic_server.jsp


5.2.3 SimpleMDB.java package weblogic.jms.whitepaper; import javax.ejb.*; import javax.jms.*; public class SimpleMDB implements MessageDrivenBean, MessageListener { private MessageDrivenContext context; // Required - public constructor with no argument public SimpleMDB() { } // Required - ejbRemove public void ejbRemove() { context = null; } public void setMessageDrivenContext(MessageDrivenContext mycontext) { context = mycontext; } // Required - ejbCreate() with no arguments public void ejbCreate () throws CreateException { } // Implementation of MessageListener - throws no exceptions public void onMessage(Message msg) { try { System.out.println("SimpleMDB got JMS message: " + msg.getJMSMessageID()); } catch(Exception e) { // Catch any exception e.printStackTrace(); } } }



5.2.4 ejb-jar.xml

This file, part of the Enterprise Java Beans standard, describes the message-driven bean. See the Enterprise Java Beans specification at the following URL for more information on this file:

http://java.sun.com/products/ejb/docs.html <?xml version="1.0"?> <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd">  <ejb-jar> <enterprise-beans> <message-driven> <ejb-name>SimpleMDB</ejb-name> <ejb-class>weblogic.jms.whitepaper.SimpleMDB</ejb-class> <transaction-type>Container</transaction-type> <message-driven-destination>  <destination-type>javax.jms.Queue</destination-type> </message-driven-destination> </message-driven> </enterprise-beans> <assembly-descriptor> <container-transaction> <method> <ejb-name>SimpleMDB</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Required</trans-attribute> </container-transaction> </assembly-descriptor> </ejb-jar>


http://java.sun.com/products/ejb/docs.html


5.2.5 weblogic-ejb-jar.xml

This file specifies WebLogic Server-specific parameters for the message-driven bean. See the following URL for more documentation at this URL:

http://edocs.bea.com/wls/docs70/ejb/reference.html - 1061421 <?xml version="1.0"?> <!DOCTYPE weblogic-ejb-jar PUBLIC "-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN" "http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd">  <weblogic-ejb-jar> <weblogic-enterprise-bean> <ejb-name>SimpleMDB</ejb-name> <message-driven-descriptor> <pool> <max-beans-in-free-pool>8</max-beans-in-free-pool> <initial-beans-in-free-pool>1</initial-beans-in-free-pool> </pool> <destination-jndi-name>TEST_QUEUE</destination-jndi-name> <!—- The next three elements are not necessary if the JMS that is driving this message-driven bean is WebLogic Server. --> <initial-context-factory> com.sun.jndi.fscontext.RefFSContextFactory </initial-context-factory> <provider-url>file:/D:/JNDI/</provider-url> <connection-factory-jndi-name> XAQCF </connection-factory-jndi-name> </message-driven-descriptor> </weblogic-enterprise-bean> </weblogic-ejb-jar>

5.3 MQ-Specific WebLogic Startup Class This class implements the technique described in section 2.6 for MQSeries JMS. It is a WebLogic Server startup class, so it can be configured using the config.xml file or the Administration Console so that it is executed when the server starts. When invoked, it creates a QueueConnec-tionFactory object for MQ JMS using the proprietary MQ JMS APIs. It then stores the object in WebLogic JNDI. Because WebLogic JNDI is cluster-aware, the object can then be looked up from any node in the cluster.


http://edocs.bea.com/wls/docs70/ejb/reference.html


To use this class, first modify it for your own use. Then compile it, create a JAR file, and put it in the CLASSPATH of your WebLogic Server.

You can configure this startup class using the Administration Console. On the navigation tree on the left, go to “Deployments... Startup and Shutdown”, and then click on the “Configure a new Startup Class” link. Enter the fully-qualified name of the Java class that you have implemented (such as weblogic.jms.whitepaper.MQJMSStartup in this example). In the “arguments” field, you must enter the parameters for the startup class, in name=value format, separated by a comma. For example: QManager=QM_gbrail2,JNDIName=QM_gbrail2

You should also select the “Run before application deployments” option so that the JMS objects are registered before your EJBs are deployed, as well as the “Failure is fatal” option so that you know whether the class worked or not.

You can also configure this class by editing the config.xml file. The resulting XML element looks like the following: <StartupClass Arguments="QManager=QM_gbrail2,JNDIName=QM_gbrail2" ClassName="weblogic.jms.whitepaper.MQJMSStartup" FailureIsFatal="true" LoadBeforeAppDeployments="true" Name="MQStartup" Targets="MQServer"/>



5.3.1 MQJMSStartup.java package weblogic.jms.whitepaper; import com.ibm.mq.jms.*; import java.util.*; import javax.jms.*; import javax.naming.*; import weblogic.common.*; /** * This startup class simply creates an IBM MQ "QueueConnectionFactory" * object and stores it in WebLogic JNDI. It takes three basic * parameters from the environment and uses them and the proprietary * IBM interfaces to create the appropriate connection factory * object and store it in JNDI. * <p> * Using this class as an example, it should be fairly * straightforward to create MQSeries Queue or Topic objects; * to create additional connection factory objects, such as an * XAConnectionFactory; and to use this method with other JMS * vendors. You will need to use the IBM MQ JMS documentation * on the IBM-specific JMS classes if you need more information. */ public class MQJMSStartup implements T3StartupDef { /** * The name of the queue manager to connect to. The startup class * will throw an exception if this parameter is not set. */ public final static String QM_NAME_PROPERTY = "QManager"; /** * The host name where the queue manager runs. If not set, the * startup class will create a "bindings mode" connection to a * queue manager on the local host. */ public final static String QM_HOST_PROPERTY = "QManagerHost"; /** * The port number where the queue manager listens. If not set, this * defaults to 1414, the default MQSeries port */ public final static String QM_PORT_PROPERTY = "QManagerPort"; /** * The name in JNDI to store this queue manager object under. * If not set, the startup class will throw an exception. */ public static final String JNDI_NAME_PROPERTY = "JNDIName"; // Required public MQJMSStartup() { } // Required, but not needed public void setServices(T3ServicesDef services) { }



/** * This method uses the arguments in "args" to look up the * configuration parameters for this class, using the constants * at the top of this class. It then creates an * MQQueueConnectionFactory object, and stores * it into the JNDI name specified by the "JNDIName" property. */ public String startup(String name, Hashtable args) throws Exception { String qmName = (String)args.get(QM_NAME_PROPERTY); if (qmName == null) { throw new Exception("Startup parameter " + QM_NAME_PROPERTY + " must be set"); } String jndiName = (String)args.get(JNDI_NAME_PROPERTY); if (jndiName == null) { throw new Exception("Startup parameter " + JNDI_NAME_PROPERTY + " must be set"); } String qmHost = (String)args.get(QM_HOST_PROPERTY); String qmPort = (String)args.get(QM_PORT_PROPERTY); MQQueueConnectionFactory factory = new MQQueueConnectionFactory(); factory.setQueueManager(qmName); if (qmHost == null) { factory.setTransportType(JMSC.MQJMS_TP_BINDINGS_MQ); factory.setHostName(qmHost); if (qmPort != null) { try { int portNum = Integer.parseInt(qmPort); factory.setPort(portNum); } catch (NumberFormatException ignore) {} } } else { factory.setTransportType(JMSC.MQJMS_TP_CLIENT_MQ_TCPIP); } InitialContext context = new InitialContext(); context.bind(jndiName, factory); context.close(); StringBuffer buf = new StringBuffer(); buf.append( "A connection factory was created for the MQ Queue Manager "); buf.append(qmName); buf.append(" and stored in JNDI at "); buf.append(jndiName); return buf.toString(); } }



6 Links This section summarizes some of the other on-line documents referenced above.

6.1 WebLogic Server Documentation WebLogic Server 7.0 Documentation Home Page:

http://e-docs.bea.com/wls/docs70/

Programming WebLogic JMS:

http://e-docs.bea.com/wls/docs70/jms/index.html

Managing WebLogic JMS:

http://e-docs.bea.com/wls/docs70/adminguide/jms.html

System Administration Guide:

http://e-docs.bea.com/wls/docs70/adminguide/index.html

Programming Message-Driven Beans:

http://e-docs.bea.com/wls/docs70/ejb/message_beans.html

Using the WebLogic Messaging Bridge:


Programming with WebLogic JNDI:


Javadoc (programming reference) for WebLogic Server:


Wrappers for copying provider JNDI objects to WebLogic JNDI:


WebLogic Server Deployment:



http://e-docs.bea.com/wls/docs70/

http://e-docs.bea.com/wls/docs70/jms/index.html

http://e-docs.bea.com/wls/docs70/adminguide/jms.html

http://e-docs.bea.com/wls/docs70/adminguide/index.html

http://e-docs.bea.com/wls/docs70/ejb/message_beans.html







6.2 Vendor Links Fiorano:

http://www.fiorano.com/

IBM MQSeries:

http://www.ibm.com/software/ts/mqseries/

IBM MQSeries SupportPacs (includes JMS and publish/subscribe):


Progress Software (home of SonicMQ):

http://www.sonicsoftware.com/

Softwired (home of IBus):

http://www.softwired-inc.com/

Sun Microsystems JNDI providers (includes filesystem and LDAP providers):


TIBCO (home of Talarian SmartSockets):

http://www.talarian.com/index2.shtml

6.3 Specifications Enterprise Java Beans:


Java Message Service:

http://java.sun.com/products/jms/docs.html


http://www.fiorano.com/

http://www.ibm.com/software/ts/mqseries/


http://www.sonicsoftware.com/

http://www.softwired-inc.com/


http://www.talarian.com/index2.shtml


http://java.sun.com/products/jms/docs.html

Date post:	30-Aug-2018
Category:	Documents
Upload:	lynga
View:	231 times
Download:	0 times

Using Foreign JMS Providers with WebLogic...

Documents