BEA Systems, Inc.
WebLogic Server 8.1 API Reference

weblogic.jms.extensions
Class JMSHelper

java.lang.Object
  |
  +--weblogic.jms.extensions.JMSHelper
public final class JMSHelper
extends java.lang.Object

This class contains JMS helper methods for locating JMS runtime (i.e., monitoring) and configuration JMX MBeans. It also contains helper methods for dynamically creating and deleting standalone JMS destinations (queues and topics), as well as for dynamically creating and deleting distributed destinations (DD). The DD methods will also create or delete a DD's queue or topic members on each specified JMS server instance, as well as a JMS template that will be used as the template for all the member destinations.

Note: BEA recommends that the use of the create queue/topic methods and create distributed queue/distributed topic methods be strictly limited, as they directly modify the configuration (config.xml) file and provide minimal feedback for detecting success or failure.

Author:
Copyright © 2004 BEA Systems, Inc. All Rights Reserved.

Constructor Summary
JMSHelper()
           
 
Method Summary
static void createDistributedQueueAsync(javax.naming.Context ctx, java.lang.String distributedQName, java.lang.String jndiName, java.lang.String[] jmsServerNames)
          Create a distributed queue and its members on the specified JMS server instances.
static void createDistributedTopicAsync(javax.naming.Context ctx, java.lang.String distributedTName, java.lang.String jndiName, java.lang.String[] jmsServerNames)
          Create a distributed topic and its members on the specified JMS server instances.
static void createPermanentQueueAsync(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String queueName, java.lang.String jndiName)
          Submit an asynchronous request to create a permanent JMS queue.
static void createPermanentTopicAsync(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String topicName, java.lang.String jndiName)
          Submit an asynchronous request to create a permanent JMS topic.
static void deleteDistributedQueue(javax.naming.Context ctx, java.lang.String distributedQName)
          Delete a distributed queue and all its members.
static void deleteDistributedTopic(javax.naming.Context ctx, java.lang.String distributedQName)
          Delete a distributed topic and all its members.
static void deletePermanentQueue(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String queueName)
          Submit a synchronous request to delete a permanent JMS queue.
static void deletePermanentTopic(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String topicName)
          Submit a synchronous request to delete a permanent JMS topic.
static JMSConnectionRuntimeMBean getJMSConnectionRuntimeMBean(javax.naming.Context ctx, javax.jms.Connection connection)
          Retrieve the JMS connection runtime MBean for the associated JMS connection.
static JMSDestinationRuntimeMBean getJMSDestinationRuntimeMBean(javax.naming.Context ctx, javax.jms.Destination destination)
          Retrieve the JMS destination runtime MBean for the associated JMS destination.
static JMSDestinationRuntimeMBean getJMSDestinationRuntimeMBean(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String destinationName)
          Retrieve the JMS destination runtime MBean for the specified JMS destination name on the specified JMS server.
static JMSConsumerRuntimeMBean getJMSMessageConsumerRuntimeMBean(javax.naming.Context ctx, javax.jms.MessageConsumer messageConsumer)
          Retrieve the JMS consumer runtime MBean for the associated JMS message consumer.
static JMSProducerRuntimeMBean getJMSMessageProducerRuntimeMBean(javax.naming.Context ctx, javax.jms.MessageProducer messageProducer)
          Retrieve the JMS producer runtime MBean for the associated JMS message producer.
static JMSQueueMBean getJMSQueueConfigMBean(javax.naming.Context ctx, javax.jms.Queue jmsQueue)
          Retrieve the JMS queue configuration MBean for the associated JMS queue.
static JMSQueueMBean getJMSQueueConfigMBean(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String queueName)
          Retrieve the JMS queue configuration MBean for the specified JMS queue name on the specified JMS server.
static JMSServerMBean getJMSServerConfigMBean(javax.naming.Context ctx, java.lang.String jmsServerName)
          Retrieve the JMS server configuration MBean for the specified JMS server name.
static JMSServerRuntimeMBean getJMSServerRuntimeMBean(javax.naming.Context ctx, javax.jms.Destination destination)
          Retrieve the JMS server runtime MBean hosting the associated JMS destination.
static JMSServerRuntimeMBean getJMSServerRuntimeMBean(javax.naming.Context ctx, java.lang.String mbeanName)
          Retrieve the JMS server runtime MBean for the specified JMS server name.
static JMSSessionRuntimeMBean getJMSSessionRuntimeMBean(javax.naming.Context ctx, javax.jms.Session session)
          Retrieve the JMS session runtime MBean for the associated JMS session.
static JMSTemplateMBean getJMSTemplateConfigMBean(javax.naming.Context ctx, java.lang.String template)
          Retrieve the JMS template configuration MBean for the specified JMS template name.
static JMSTopicMBean getJMSTopicConfigMBean(javax.naming.Context ctx, java.lang.String jmsServerName, java.lang.String topicName)
          Retrieve the JMS topic configuration MBean for the specified JMS topic name on the specified JMS server.
static JMSTopicMBean getJMSTopicConfigMBean(javax.naming.Context ctx, javax.jms.Topic jmsTopic)
          Retrieve the JMS topic configuration MBean for the associated JMS topic.
 java.lang.String newJMSMessageIDToOld(java.lang.String messageId)
          Convert WebLogic JMS 6.0 JMSMessageID format to the pre-6.0 format.
 java.lang.String oldJMSMessageIDToNew(java.lang.String messageId, long timeStamp)
          Convert WebLogic JMS pre-6.0 JMSMessageID format into the 6.0 format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JMSHelper

public JMSHelper()
Method Detail

createPermanentQueueAsync

public static void createPermanentQueueAsync(javax.naming.Context ctx,
                                             java.lang.String jmsServerName,
                                             java.lang.String queueName,
                                             java.lang.String jndiName)
                                      throws javax.jms.JMSException
Submit an asynchronous request to create a permanent JMS queue. This method updates the following:

Note: The createPermanentQueueAsync() 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 on 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 using the session createQueue() method, rather than performing a JNDI lookup. By doing so, you can avoid some of the propagation-specific delays.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
queueName - name of the JMS queue
jndiName - name used to lookup the destination within the JNDI namespace.
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
createPermanentTopicAsync(javax.naming.Context, java.lang.String, java.lang.String, java.lang.String), QueueSession.createQueue(java.lang.String)

createPermanentTopicAsync

public static void createPermanentTopicAsync(javax.naming.Context ctx,
                                             java.lang.String jmsServerName,
                                             java.lang.String topicName,
                                             java.lang.String jndiName)
                                      throws javax.jms.JMSException
Submit an asynchronous request to create a permanent JMS topic. This method is similar to the createPermanentQueueAsync() method, except that it creates topics rather than queues. Once the topic is created, you can test for its existence using the session createTopic() method, rather than performing a JNDI lookup, to avoid some of the propagation-specific delays.

Note: Like the createPermanentQueueAsync() method, the createPermanentTopicAsync() method call can fail without throwing an exception. In addition, a thrown exception does not necessarily indicate that the method call failed.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
topicName - name of the JMS topic
jndiName - name used to lookup the destination within the JNDI namespace.
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
createPermanentQueueAsync(javax.naming.Context, java.lang.String, java.lang.String, java.lang.String), TopicSession.createTopic(java.lang.String)

deletePermanentQueue

public static void deletePermanentQueue(javax.naming.Context ctx,
                                        java.lang.String jmsServerName,
                                        java.lang.String queueName)
                                 throws weblogic.jms.common.ConfigurationException
Submit a synchronous request to delete a permanent JMS queue. This method updates the specified domain's configuration file to remove the queue entry.

A thrown exception does not necessarily indicate that the method call failed.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
queueName - name of the JMS queue
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
weblogic.jms.extensions.JMSHelper#deletePermanentTopicAsync

deletePermanentTopic

public static void deletePermanentTopic(javax.naming.Context ctx,
                                        java.lang.String jmsServerName,
                                        java.lang.String topicName)
                                 throws weblogic.jms.common.ConfigurationException
Submit a synchronous request to delete a permanent JMS topic. This method is similar to the deletePermanentQueue() method, except that it deletes topics rather than queues.

A thrown exception does not necessarily indicate that the method call failed.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
topicName - name of the JMS topic
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
weblogic.jms.extensions.JMSHelper#deletePermanentQueueAsync, TopicSession.createTopic(java.lang.String)

createDistributedQueueAsync

public static void createDistributedQueueAsync(javax.naming.Context ctx,
                                               java.lang.String distributedQName,
                                               java.lang.String jndiName,
                                               java.lang.String[] jmsServerNames)
                                        throws javax.jms.JMSException
Create a distributed queue and its members on the specified JMS server instances. A member queue will be created on each of the JMS servers specified, and the name given to each member will be a combination of the name of the distributed destination and the name of the JMS server where it is created.

A JMS template will also be created for the distributed destination with the same name as the destination, and this template will be used as the template for all of the member destinations.

Parameters:
ctx - the JNDI context to use to access the admin server
distributedQName - the name of the distributed queue to create
jndiName - the name to give the distributed queue in JNDI
jmsServerNames - a list of the names of the JMS server where distributed queue members should be created. This parameter must not be null.

createDistributedTopicAsync

public static void createDistributedTopicAsync(javax.naming.Context ctx,
                                               java.lang.String distributedTName,
                                               java.lang.String jndiName,
                                               java.lang.String[] jmsServerNames)
                                        throws javax.jms.JMSException
Create a distributed topic and its members on the specified JMS server instances. A member topic will be created on each of the JMS servers specified, and the name given to each member will be a combination of the name of the distributed destination and the name of the JMS server where it is created.

A JMS template will also be created for the distributed destination with the same name as the destination, and this template will be used as the template for all of the member destinations.

Parameters:
ctx - the JNDI context to use to access the admin server
distributedTName - the name of the distributed topic to create
jndiName - the name to give the distributed topic in JNDI
jmsServerNames - a list of the names of the JMS server where distributed topic members should be created. This parameter must not be null.

deleteDistributedQueue

public static void deleteDistributedQueue(javax.naming.Context ctx,
                                          java.lang.String distributedQName)
                                   throws javax.jms.JMSException
Delete a distributed queue and all its members. This method will iterate through all the members, and delete the member queues as well as the distributed queue itself. In addition, the default JMS template -- which has the same name as the distributed queue itself -- will be deleted.

deleteDistributedTopic

public static void deleteDistributedTopic(javax.naming.Context ctx,
                                          java.lang.String distributedQName)
                                   throws javax.jms.JMSException
Delete a distributed topic and all its members. This method will iterate through all the members, and delete the member topics as well as the distributed topic itself. In addition, the default JMS template -- which has the same name as the distributed topic itself -- will be deleted.

getJMSTemplateConfigMBean

public static JMSTemplateMBean getJMSTemplateConfigMBean(javax.naming.Context ctx,
                                                         java.lang.String template)
                                                  throws javax.jms.JMSException
Retrieve the JMS template configuration MBean for the specified JMS template name.

Parameters:
ctx - JNDI initial context.
template - name of the JMS Template
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSTemplateMBean

getJMSTopicConfigMBean

public static JMSTopicMBean getJMSTopicConfigMBean(javax.naming.Context ctx,
                                                   javax.jms.Topic jmsTopic)
                                            throws javax.jms.JMSException
Retrieve the JMS topic configuration MBean for the associated JMS topic.

Parameters:
ctx - JNDI initial context.
jmsTopic - javax.jms.Topic
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSTopicMBean

getJMSTopicConfigMBean

public static JMSTopicMBean getJMSTopicConfigMBean(javax.naming.Context ctx,
                                                   java.lang.String jmsServerName,
                                                   java.lang.String topicName)
                                            throws javax.jms.JMSException
Retrieve the JMS topic configuration MBean for the specified JMS topic name on the specified JMS server.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
topicName - name of the JMS topic
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSTopicMBean

getJMSQueueConfigMBean

public static JMSQueueMBean getJMSQueueConfigMBean(javax.naming.Context ctx,
                                                   javax.jms.Queue jmsQueue)
                                            throws javax.jms.JMSException
Retrieve the JMS queue configuration MBean for the associated JMS queue.

Parameters:
ctx - JNDI initial context.
jmsQueue - javax.jms.Queue
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSQueueMBean

getJMSQueueConfigMBean

public static JMSQueueMBean getJMSQueueConfigMBean(javax.naming.Context ctx,
                                                   java.lang.String jmsServerName,
                                                   java.lang.String queueName)
                                            throws javax.jms.JMSException
Retrieve the JMS queue configuration MBean for the specified JMS queue name on the specified JMS server.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
jmsQueue - name of the JMS queue
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSQueueMBean

getJMSServerConfigMBean

public static JMSServerMBean getJMSServerConfigMBean(javax.naming.Context ctx,
                                                     java.lang.String jmsServerName)
                                              throws javax.jms.JMSException
Retrieve the JMS server configuration MBean for the specified JMS server name.

Parameters:
ctx - JNDI initial context.
jmsServerName - name of the JMS server
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSServerMBean

getJMSConnectionRuntimeMBean

public static JMSConnectionRuntimeMBean getJMSConnectionRuntimeMBean(javax.naming.Context ctx,
                                                                     javax.jms.Connection connection)
                                                              throws javax.jms.JMSException
Retrieve the JMS connection runtime MBean for the associated JMS connection.

Parameters:
ctx - JNDI initial context.
connection - javax.jms.Connection
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSConnectionRuntimeMBean

getJMSMessageProducerRuntimeMBean

public static JMSProducerRuntimeMBean getJMSMessageProducerRuntimeMBean(javax.naming.Context ctx,
                                                                        javax.jms.MessageProducer messageProducer)
                                                                 throws javax.jms.JMSException
Retrieve the JMS producer runtime MBean for the associated JMS message producer.

Parameters:
ctx - JNDI initial context.
messageProducer - javax.jms.MessageProducer
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSProducerRuntimeMBean

getJMSMessageConsumerRuntimeMBean

public static JMSConsumerRuntimeMBean getJMSMessageConsumerRuntimeMBean(javax.naming.Context ctx,
                                                                        javax.jms.MessageConsumer messageConsumer)
                                                                 throws javax.jms.JMSException
Retrieve the JMS consumer runtime MBean for the associated JMS message consumer.

Parameters:
ctx - JNDI initial context.
messageConsumer - javax.jms.MessageConsumer
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSConsumerRuntimeMBean

getJMSSessionRuntimeMBean

public static JMSSessionRuntimeMBean getJMSSessionRuntimeMBean(javax.naming.Context ctx,
                                                               javax.jms.Session session)
                                                        throws javax.jms.JMSException
Retrieve the JMS session runtime MBean for the associated JMS session.

Parameters:
ctx - JNDI initial context
session - javax.jms.Session
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSSessionRuntimeMBean

getJMSServerRuntimeMBean

public static JMSServerRuntimeMBean getJMSServerRuntimeMBean(javax.naming.Context ctx,
                                                             javax.jms.Destination destination)
                                                      throws javax.jms.JMSException
Retrieve the JMS server runtime MBean hosting the associated JMS destination.

Parameters:
ctx - JNDI initial context
destination - javax.jms.Destination
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSServerRuntimeMBean

getJMSDestinationRuntimeMBean

public static JMSDestinationRuntimeMBean getJMSDestinationRuntimeMBean(javax.naming.Context ctx,
                                                                       java.lang.String jmsServerName,
                                                                       java.lang.String destinationName)
                                                                throws javax.jms.JMSException
Retrieve the JMS destination runtime MBean for the specified JMS destination name on the specified JMS server.

Parameters:
ctx - JNDI initial context
jmsServerName - name of the JMS server
destinationName - name of the JMS destination
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSDestinationRuntimeMBean

getJMSDestinationRuntimeMBean

public static JMSDestinationRuntimeMBean getJMSDestinationRuntimeMBean(javax.naming.Context ctx,
                                                                       javax.jms.Destination destination)
                                                                throws javax.jms.JMSException
Retrieve the JMS destination runtime MBean for the associated JMS destination.

Parameters:
ctx - JNDI initial context
destination - javax.jms.Destination
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSDestinationRuntimeMBean

getJMSServerRuntimeMBean

public static JMSServerRuntimeMBean getJMSServerRuntimeMBean(javax.naming.Context ctx,
                                                             java.lang.String mbeanName)
                                                      throws javax.jms.JMSException
Retrieve the JMS server runtime MBean for the specified JMS server name.

Parameters:
ctx - JNDI initial context
mbeanName - name of the JMS server
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
JMSServerRuntimeMBean

oldJMSMessageIDToNew

public java.lang.String oldJMSMessageIDToNew(java.lang.String messageId,
                                             long timeStamp)
                                      throws javax.jms.JMSException
Convert WebLogic JMS pre-6.0 JMSMessageID format into the 6.0 format.

Parameters:
messageId - old JMSMessageID.
timestamp - timestamp of message.
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
newJMSMessageIDToOld(java.lang.String)

newJMSMessageIDToOld

public java.lang.String newJMSMessageIDToOld(java.lang.String messageId)
                                      throws javax.jms.JMSException
Convert WebLogic JMS 6.0 JMSMessageID format to the pre-6.0 format.

Parameters:
messageId - old JMSMessageID.
Throws:
javax.jms.JMSException - if a JMS error occurs
See Also:
oldJMSMessageIDToNew(java.lang.String, long)
Documentation is available at
http://e-docs.bea.com/wls/docs81