Programming WebLogic JMS

Using JMS Helper to Manage Applications

The weblogic.jms.extensions.JMSHelper class contains APIs that you can use to programmatically create and manage JMS resources.

Configuring JMS Resources Using JMSHelper

JMSHelper provides the following API signatures to manage JMS resources, such as queues and topics:

Create a resource
Delete a resource
Find resource

You must specify the JNDI initial context, name of the JMS server to be associated with the destination, name of the destination (queue or topic), and name used to look up the destination within the JNDI namespace.

Each method updates the following:

Configuration file associated with the specified domain to include the dynamically created destination
JNDI namespace to advertise the destination

For more information on JMS servers, see "JMS: Configuring.

JMSHelper Sample Code

This section provides sample code to create and delete a JMS resource.

Creating a JMS Resource

The following code creates a JMS topic.

Listing 7-1 Create a JMS Topic

package examples.jms.topic;

import java.util.*;
import javax.jms.*;
import javax.naming.*;
import weblogic.management.WebLogicMBean;
import weblogic.management.MBeanHome;
import weblogic.management.runtime.*;
import weblogic.management.configuration.*;
import weblogic.jms.extensions.JMSHelper;
import weblogic.jndi.Environment;

public class MBeanConfig
{
   public MBeanConfig() {
   }

public static void main(String[] args) throws Exception {

   String url, username, password;
   if (args.length != 0 && args.length != 3) {
   System.out.println("Usage: MBeanConfig <url> <username> <password>");
   System.exit(1);
   }

   if (args.length == 0) {
      url = new String("t3://localhost:7001");
      username = "weblogic";
      password = "weblogic";
   } else {
      url = args[0];
      username = args[1];
      password = args[2];
   }
   Context ctx = getInitialContext(url, username, password);
   MBeanConfig mbt = new MBeanConfig();

   createJMSUsingJMSHelper(ctx);
}

   private static void createJMSUsingJMSHelper(
      Context ctx
   ){
   System.out.println("\n\n.... Configure a JMS Topic ....\n\n"); 
   try {
      MBeanHome mbeanHome = 
      (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
      DomainMBean domainMBean = mbeanHome.getActiveDomain();
      String domainMBeanName = domainMBean.getName();
      ServerMBean[] servers = domainMBean.getServers();

/** 
  * create a topic
  */
      String jmsServerName = "examplesJMSServer";
      String topicName = "exampleTopic";
      String topicjndiName = "weblogic.examples.jms.exampleTopic"; 
      JMSHelper.createPermanentTopicAsync(
         ctx,
         jmsServerName,
         topicName, 
         topicjndiName);
 System.out.println("Created Topic " + JMSHelper.getJMSTopicConfigMBean(
            ctx,
            jmsServerName,
            topicName
            ));
         } catch (Exception e) {
   System.out.println("Example configuration failed :" + e.getMessage());
      e.printStackTrace();
      } 
   }

private static Context getInitialContext(
   String url,
   String username,
   String password
   ) throws Exception {
      Environment env = new Environment();
      env.setProviderUrl(url);
      env.setSecurityPrincipal(username);
      env.setSecurityCredentials(password);
      Context c = env.getInitialContext();
      return c;
   }
}

Deleting a JMS Resource

The following code removes JMS topic.

Listing 7-2 Delete a JMS Topic

package examples.jms.topic;

import java.util.*;
import javax.jms.*;
import javax.naming.*;

import weblogic.management.WebLogicMBean;
import weblogic.management.MBeanHome;
import weblogic.management.runtime.*;
import weblogic.management.configuration.*;

import weblogic.jms.extensions.JMSHelper;
import weblogic.jndi.Environment;

public class MBeanClean
{
   public MBeanClean() {
}


public static void main(String[] args) throws Exception {

   String url, username, password;

   if (args.length != 0 && args.length != 3) {
      System.out.println("Usage: MBeanClean <url> <username> <password>");
      System.exit(1);
}

if (args.length == 0) {
   url = new String("t3://localhost:7001");
   username = "system";
   password = "gumby1234";
   } else {

      url = args[0];
      username = args[1];
      password = args[2];
   }

   Context ctx = getInitialContext(url, username, password);
   MBeanClean mbt = new MBeanClean();
   deleteJMSUsingJMSHelper(ctx); 
}

private static void deleteJMSUsingJMSHelper(
   Context ctx
   ) {
   System.out.println("\n\n.... Remove a JMS Topic ....\n\n"); 
   try {
      MBeanHome mbeanHome = 
         (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
         DomainMBean domainMBean = mbeanHome.getActiveDomain();
         String domainMBeanName = domainMBean.getName();
         ServerMBean[] servers = domainMBean.getServers();

   String jmsServerName = "examplesJMSServer";

/** 
 * delete a topic
 */
   String topicName = "exampleTopic";
   JMSHelper.deletePermanentTopic(
      ctx,
      jmsServerName,
      topicName
      );
      } catch (Exception e) {
  System.out.println("Example configuration failed :" + e.getMessage());
  e.printStackTrace();
  } 
}

private static Context getInitialContext(
   String url,
   String username,
   String password
   ) throws Exception {
      Environment env = new Environment();
      env.setProviderUrl(url);
      env.setSecurityPrincipal(username);
      env.setSecurityCredentials(password);
      Context c = env.getInitialContext();
      return c;
   }
}

Best Practices when Using JMSHelper

This section provides best practices information when using JMSHelper to configure JMS servers and resources:

Trap for Null MBean objects (such as servers, JMS servers, modules) before trying to manipulate the MBean object.
A create or delete method call can fail without throwing an exception. In addition, a thrown exception does not necessarily indicate that the method call failed.
The time required to create the destination on the JMS server and propagate the information to the JNDI namespace can be significant. The propagation delay increases if the environment contains multiple servers. It is recommended that you test for the existence of the queue or topic, respectively, using the session createQueue() or createTopic() method, rather than perform a JNDI lookup. By doing so, you can avoid some of the propagation-specific delay.

For example, the following method, findQueue(), attempts to access a dynamically created queue, and if unsuccessful, sleeps for a specified interval before retrying. A maximum retry count is established to prevent an infinite loop.

private static Queue findQueue (
  QueueSession queueSession,
  String jmsServerName, 
  String queueName, 
  int retryCount,
  long retryInterval
) throws JMSException
{
   String wlsQueueName = jmsServerName + "/" + queueName;
   String command = "QueueSession.createQueue(" + 
	wlsQueueName + ")";
   long startTimeMillis = System.currentTimeMillis();
   for (int i=retryCount; i>=0; i--) {
	try {
	  System.out.println("Trying " + command);
	  Queue queue = queueSession.createQueue(wlsQueueName);
	  System.out.println(command + "succeeded after " +
	  	(retryCount - i + 1) + " tries in " +
	  	(System.currentTimeMillis() - startTimeMillis) + 
	  	" millis.");
	  return queue;
	} catch (JMSException je) {
	  if (retryCount == 0) throw je;
	}
	try {
	  System.out.println(command + "> failed, pausing " +
	  	retryInterval + " millis.");
	  Thread.sleep(retryInterval);
	} catch (InterruptedException ignore) {}

   }
   throw new JMSException("out of retries");
}

You can then call the findQueue() method after the JMSHelper class method call to retrieve the dynamically created queue once it becomes available. For example:

JMSHelper.createPermanentQueueAsync(ctx, domain, jmsServerName,  
  queueName, jndiName);
Queue queue = findQueue(qsess, jmsServerName, queueName,
  retry_count, retry_interval);

For more information on the JMSHelper class, refer to the weblogic.jms.extensions.JMSHelper Javadoc.