Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic JMS

# Using JMS Module Helper to Manage Applications

The weblogic.jms.extensions.JMSModuleHelper class contains APIs that you can use to programmatically create and manage JMS servers, Store-and-Forward Agents, and JMS system resources.

- Configuring JMS System Resources Using JMSModuleHelper
- Configuring JMS Servers and Store-and-Forward Agents
- JMSModuleHelper Sample Code
- Best Practices when Using JMSModuleHelper

# Configuring JMS System Resources Using JMSModuleHelper

JMSModuleHelper provides the following API signatures to manage a system module and JMS resources, such as queues and topics:

- Create a resource
- Create and modify resource
- Delete a resource
- Find and modify a resource
- Find using a template

You can manage a system module, including the JMS resources it contains by providing the domain MBean or by providing the initial context to the administration server in the API signature. For more information on JMS system resources, see "Configuring JMS System Resources" in the Administration Console Online Help.

# Configuring JMS Servers and Store-and-Forward Agents

JMSModuleHelper provides the following method APIs to manage JMS servers and Store-and-Forward Agents:

- Create JMS servers and Store-and-Forward Agents
- Delete JMS servers and Store-and-Forward Agents
- Deploy JMS servers and Store-and-Forward Agents
- Undelploy JMS servers and Store-and-Forward Agents

You can manage JMS servers and Store-and-Forward Agents by providing the domain MBean or by providing the initial context to the administration server in the API signature. For more information, see:

- "Configuring JMS System Resources".
- "Understanding the Store-and-Forward Service".

# JMSModuleHelper Sample Code

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

## Creating a JMS System Resource

The module contains a connection factory and a topic.

Listing 6-1 Create JMS System Resources

>     .
>     .
>     .
>     private static void createJMSUsingJMSModuleHelper(Context ctx){
>     System.out.println(
>          "\n\n.... Configure JMS Resource for C API Topic Example ....\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";

>     //
>     // create a JMSSystemResource "CapiTopic-jms"
>     //
>          String resourceName = "CapiTopic-jms";
>          JMSModuleHelper.createJMSSystemResource(
>             ctx,
>              resourceName,
>              servers[0].getName());
>              JMSSystemResourceMBean jmsSR =
>                   JMSModuleHelper.findJMSSystemResource(
>                         ctx,
>                         resourceName);
>               JMSBean jmsBean = jmsSR.getJMSResource();
>          System.out.println("Created JMSSystemResource " + resourceName);

>     //
>     // create a JMSConnectionFactory "CConFac"
>     //
>          String factoryName = "CConFac";
>          String jndiName = "CConFac";
>          JMSModuleHelper.createConnectionFactory(
>             ctx,
>             resourceName,
>              factoryName,
>              jndiName,
>               servers[0].getName());
>          JMSConnectionFactoryBean factory =           jmsBean.lookupConnectionFactory(factoryName);
>          System.out.println("Created Factory " + factory.getName());

>     //
>     // create a topic "CTopic"
>     //
>          String topicName = "CTopic";
>          String topicjndiName = "CTopic";
>          JMSModuleHelper.createTopic(
>             ctx,
>             resourceName,
>             jmsServerName,
>             topicName,
>             topicjndiName);

>          TopicBean topic = jmsBean.lookupTopic(topicName);
>          System.out.println("Created Topic " + topic.getName());
>          } catch (Exception e) {
>              System.out.println("Example configuration failed :" + e.getMessage());
>             e.printStackTrace();
>          }
>     }
>     .
>     .
>     .

## Deleting a JMS System Resource

The following code removes JMS system resources.

Listing 6-2 Delete JMS System Resources

>     .
>     .
>     .
>     private static void deleteJMSUsingJMSModuleHelper(Context ctx ) {

>          System.out.println("\n\n.... Remove JMS System Resource for C API Topic Example ....\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 JMSSystemResource "CapiTopic-jms"
>     //
>          String resourceName = "CapiTopic-jms";
>          JMSModuleHelper.deleteJMSSystemResource(
>             ctx,
>             resourceName
>              );
>          } catch (Exception e) {
>             System.out.println("Example configuration failed :" + e.getMessage());
>             e.printStackTrace();
>          }
>     }
>     .
>     .
>     .

# Best Practices when Using JMSModuleHelper

This section provides best practices information when using JMSModuleHelper 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 `JMSModuleHelper` class method call to retrieve the dynamically created queue once it becomes available. For example:

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