7 Using JMS Module Helper to Manage Applications

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 Basic JMS System Resources" in the Oracle WebLogic Server Administration Console 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

• Undeploy 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 Basic JMS System Resources" in the Oracle WebLogic Server Administration Console Help.

• "Understanding the Store-and-Forward Service" in the Oracle WebLogic Server Administration Console Help.

JMSModuleHelper Sample Code

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

.
.
.
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();
     } 
}
.
.
.

.
.
.
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);