Brett Lomas' Blog

I had to do some work around Store-and-Forward (SAF) using the WebLogic JMS C API for a customer recently. I found some of the C API documentation and examples have disappeared during the migration of BEA to Oracle (or perhaps this is a reflection of my lacking search skills, or indeed my persistence with search results) so this blog details my results in the hope it might be useful to someone else.

Assumptions
This blog entry assumes the following
1. You have a proficiency in WebLogic Server and JMS
2. You know about Java and C coding

Notes
While this blog reflects work done using WebLogic Server 10gR3, it should work with all WebLogic Server version 9 and above (for SAF).

Introduction
The JMS C API uses JNI to access the standard WebLogic JMS Libraries. The API follows the same flow as the Java equivalent (funnily enough) where a context is used to look up the connection factory and destination and the connection factory creates the connection etc etc.

Setting up your Environment
To use the C JMS API you need to set up your environment, this blog assumes Unix/Linux but the same principles apply for Windows users.
1. Set up the CLASSPATH to include, the weblogic.jar file (found in /wlserver_10.3/server/lib - the path will change depending on the version you're using) or you can use the wlsjmsclient.jar instead of the full jar file if you wish.
2. Set up the library path so your executable knows where to find the jvm and jni shared libraries. This equates to setting the LD_LIBRARY_PATH to something like /wlserver_10.3/server/native/linux/i686:/jdk160_05/jre/lib/i386/server/.

The C Code
Once you have done this you're ready to work on the code. The follow code 'skeleton' shows how to publish a message to a JMS Queue.
1. Get the context using JmsContextCreate
2. Use the context to get the connection factory using JmsContextCreateConnectionFactory and the destination (the queue) using JmsDestinationCreate
3. Get the connection to the JMS Server using JmsConnectionFactoryCreateConnection
4. Create the session using JmsConnectionCreateSession
5. Create the producer (or consumer) using JmsSessionCreateProducer (or check me)
6.Create the message (in this case a Text Message) using JmsSessionTestMessageCreate
7. Send the message using JmsProducerSend

When using the C API it is critical all handles returned from the API functions are closed or destroyed correctly using the appropriate -Destroy or -Close functions, failing to do so could cause memory leaks (don't depend on GC, especially when using the C API).

Compiling
When compiling you need to make sure you
1. Include the WebLogic C API header files (located in /wlserver_10.3/server/include)
2. Link the libjmsc.so, libjvm.so, and libpthread.so with your code.

Here is an example command (using gcc):
gcc -I/usr/local/bea/WLS103/wlserver_10.3/server/include -L/usr/local/bea/WLS103/wlserver_10.3/server/native/linux/i686/ -L/usr/local/bea/WLS103/jdk160_05/jre/lib/i386/server -ljmsc -ljvm -lpthread -o JMSClient JMSClient.c

You could use make to automate a lot of this.

Running the Binary
Run the binary as you would any other linux/unix binary, while making sure the library path and classpath is set correctly

Configuring the Store-and-Forward
Once you have the simple producer working and publishing messages to a queue or topic you are ready to setup the SAF.

You need to export the SAF Context file as per the SAF documentation. Once you have done this you need to make sure you use weblogic.jms.safclient.jndi.InitialContextFactoryImpl as the JNDI provider (passed as a parameter to the JmsContextCreate function and the URI (or connection string) needs to be the location of the SAF Context you exported. Make sure you have either weblogic.jar or wlssafclient.jar in the classpath.

Because the SAF Sending Agent runs in a separate thread to your main thread there can be some latency between your producing the first message and it getting to the destination. This thread also means you need to make sure you don't exit the program too quickly, otherwise nothing will be sent (you keep exiting before the SAF Sending Agent can initialise)!

Download Example

You can download an example I have created here, this is only meant as an example and there is no warranty, use it at your own risk.

References
1. WebLogic JMS C Documentation
  a) JMS C Documentation
  b) The WebLogic Server 10gR3 JMS C API
2. WebLogic Store-and-Forward Client Documentation