com.waveset.util.jms
Class JmsUtil

java.lang.Object
  extended bycom.waveset.util.jms.JmsUtil

public class JmsUtil
extends java.lang.Object

Various low-level convenience methods for interacting with JMS queues and topics.

The class is a thin wrapper around the JMS API. The order in which you can use the methods here is rather strict. The methods are all public static so that they can be easily called via the IdM <invoke> script tag.

Below is a pseudo-code sample of how you might use JmsUtil to send a single message to a queue.

And below is a pseudo-code sample of how you might use JmsUtil to publish a single message to a topic.

If you want to use an easier, higher-level (but less powerful) JMS abstraction, see JmsWriter.


Method Summary
static void closeConnection(javax.jms.Connection connection)
          Inform the system that no more messaging will occur on the Connection.
static void commitSession(javax.jms.Session session)
          Commit all messaging done in the specified Session, and release any locks currently held.
static javax.jms.BytesMessage createBytesMessage(javax.jms.Session session)
           
static javax.jms.MapMessage createMapMessage(javax.jms.Session session)
           
static javax.jms.ObjectMessage createObjectMessage(javax.jms.Session session)
           
static javax.jms.Queue createQueue(javax.naming.Context context, java.lang.String destinationName)
          Create a new Queue
static javax.jms.QueueConnection createQueueConnection(javax.naming.Context context, java.lang.String factoryName, java.lang.String userName, java.lang.Object password)
          Create a new QueueConnection from the specified queue connection factory
static javax.jms.QueueSender createQueueSender(javax.jms.QueueSession queueSession, javax.jms.Queue queue)
          Create a QueueSender to send messages to the specified queue.
static javax.jms.QueueSession createQueueSession(javax.jms.QueueConnection queueConnection, java.lang.String reliabilityMode)
          Create a new QueueSession from the given QueueConnection
static javax.jms.StreamMessage createStreamMessage(javax.jms.Session session)
           
static javax.jms.TextMessage createTextMessage(javax.jms.Session session)
           
static javax.jms.TextMessage createTextMessage(javax.jms.Session session, java.lang.String text)
           
static javax.jms.Topic createTopic(javax.naming.Context context, java.lang.String destinationName)
          Create a new Topic
static javax.jms.TopicConnection createTopicConnection(javax.naming.Context context, java.lang.String factoryName, java.lang.String userName, java.lang.Object password)
          Create a new TopicConnection from the specified topic connection factory
static javax.jms.TopicPublisher createTopicPublisher(javax.jms.TopicSession topicSession, javax.jms.Topic topic)
          Create a Publisher for the specified topic.
static javax.jms.TopicSession createTopicSession(javax.jms.TopicConnection topicConnection, java.lang.String reliabilityMode)
          Create a new TopicSession from the given TopicConnection
static javax.naming.Context getInitialContext(java.util.List jndiPropertiesList)
          Uses the JNDI naming service properties to get an initial context for JNDI lookups.
static javax.naming.Context getInitialContext(java.util.Map jndiPropertiesMap)
          Uses the JNDI naming service properties to get an initial context for JNDI lookups.
static java.lang.String getMessageDetails(javax.jms.Connection conn, javax.jms.Message msg)
          Generate a String with detailed info about the Message.
static void populateMapMessage(javax.jms.MapMessage message, java.util.Map srcMap)
          Populate a MapMessage with a given Map
static void publish(javax.jms.TopicPublisher topicPublisher, javax.jms.Message message, java.util.Map deliveryOptionsMap)
          Publish a message to a topic.
static void rollbackSession(javax.jms.Session session)
          Rollback all messaging done in the specified Session, and release any locks currently held.
static void send(javax.jms.QueueSender queueSender, javax.jms.Message message, java.util.Map deliveryOptionsMap)
          Send a message to a queue.
static java.util.Map stringListToMap(java.util.List stringList)
          Convert a list of assignment strings to a Map
static java.lang.String stringListToString(java.util.List stringList)
          Convert a list of strings to a single string, each separated by "\n"
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInitialContext

public static javax.naming.Context getInitialContext(java.util.Map jndiPropertiesMap)
                                              throws javax.naming.NamingException
Uses the JNDI naming service properties to get an initial context for JNDI lookups.

Parameters:
jndiPropertiesMap - a Map of JNDI properties/values. Common keys for the Map include java.naming.factory.initial and java.naming.provider.url.
Returns:
an initial Context
Throws:
javax.naming.NamingException - if a naming exception is encountered

getInitialContext

public static javax.naming.Context getInitialContext(java.util.List jndiPropertiesList)
                                              throws javax.naming.NamingException,
                                                     WavesetException
Uses the JNDI naming service properties to get an initial context for JNDI lookups.

Parameters:
jndiPropertiesList - a List of JNDI property assignment strings. Each String in the List must be of the format <key>=<value>. Most common <key> entries include java.naming.factory.initial and java.naming.provider.url
Returns:
an initial Context
Throws:
WavesetException - if the property assignment strings contain invalid syntax
javax.naming.NamingException - if a naming exception is encountered

stringListToMap

public static java.util.Map stringListToMap(java.util.List stringList)
                                     throws WavesetException
Convert a list of assignment strings to a Map

Parameters:
stringList - a List of assignment strings. Each String in the List must be of the format <key>=<value>.
Returns:
a Map which represents the stringList
Throws:
WavesetException

stringListToString

public static java.lang.String stringListToString(java.util.List stringList)
Convert a list of strings to a single string, each separated by "\n"

Parameters:
stringList - a list of strings
Returns:
a single String concatenation (with line separators) from the list of Strings

populateMapMessage

public static void populateMapMessage(javax.jms.MapMessage message,
                                      java.util.Map srcMap)
                               throws javax.jms.JMSException
Populate a MapMessage with a given Map

Parameters:
message - the MapMessage to populate
srcMap - the Map of values to add to the MapMessage
Throws:
javax.jms.JMSException

createQueueConnection

public static javax.jms.QueueConnection createQueueConnection(javax.naming.Context context,
                                                              java.lang.String factoryName,
                                                              java.lang.String userName,
                                                              java.lang.Object password)
                                                       throws javax.naming.NamingException,
                                                              javax.jms.JMSException
Create a new QueueConnection from the specified queue connection factory

Parameters:
context - the Context to use to perform the lookup of the queue connection factory
factoryName - the JNDI name of the queue connection factory to use to return the QueueConnection
userName - if userName is present, then an authenticated connection will be performed using the userName and password provided. If null, the default identity configured for the factory will be used.
password - used along with userName to perform an authenticated connection. This is expected to be either an EncryptedData or String instance.
Returns:
a newly created queue connection
Throws:
javax.naming.NamingException - a naming exception occurred looking up the queue connection factory
javax.jms.JMSException - if JMS Provider fails to create Queue Connection due to some internal error.

createTopicConnection

public static javax.jms.TopicConnection createTopicConnection(javax.naming.Context context,
                                                              java.lang.String factoryName,
                                                              java.lang.String userName,
                                                              java.lang.Object password)
                                                       throws javax.naming.NamingException,
                                                              javax.jms.JMSException
Create a new TopicConnection from the specified topic connection factory

Parameters:
context - the Context to use to perform the lookup of the topic connection factory
factoryName - the JNDI name of the topic connection factory to use to return the TopicConnection // * @param connOptions an optional Map containing userName and password keys.
userName - If username is supplied, then an authenticated connection will be performed using the userName and password supplied. Otherwise, the default identity configured for the factory will be used.
password - If username is supplied, then an authenticated connection will be performed using the userName and password supplied. Otherwise, the default identity configured for the factory will be used.
Returns:
a newly created topic connection
Throws:
javax.naming.NamingException - a naming exception occurred looking up the topic connection factory
javax.jms.JMSException - if JMS Provider fails to create Topic Connection due to some internal error.

closeConnection

public static void closeConnection(javax.jms.Connection connection)
Inform the system that no more messaging will occur on the Connection. All resources used by the Connection will be freed. Any transacted sessions will be rolled back.

Any errors which occur during the close are ignored.

Parameters:
connection - the QueueConnection or TopicConnection to close.

commitSession

public static void commitSession(javax.jms.Session session)
                          throws javax.jms.JMSException
Commit all messaging done in the specified Session, and release any locks currently held. The commit will be performed only if the session is transacted.

Parameters:
session - the Session to commit
Throws:
javax.jms.JMSException - if JMS fails to commit the session due to some internal error.

rollbackSession

public static void rollbackSession(javax.jms.Session session)
                            throws javax.jms.JMSException
Rollback all messaging done in the specified Session, and release any locks currently held. The rollback will be performed only if the session is transacted.

Parameters:
session - the Session to rollback
Throws:
javax.jms.JMSException - if JMS fails to rollback the session due to some internal error.

createQueueSession

public static javax.jms.QueueSession createQueueSession(javax.jms.QueueConnection queueConnection,
                                                        java.lang.String reliabilityMode)
                                                 throws javax.jms.JMSException,
                                                        WavesetException
Create a new QueueSession from the given QueueConnection

Parameters:
queueConnection - the QueueConnection from which the new QueueSession is to be created
reliabilityMode - specifies the mechanism used to ensure reliable messaging. The valid values are "LOCAL", "AUTO", "DUPS_OK", and "CLIENT".


    "LOCAL" specifies that a local session transaction will be used.

    "AUTO" specifies that the AUTO_ACK acknowledgment mode is used instead of a transaction.

    "DUPS_OK" specifies that the DUPS_OK_ACK acknowledgment mode is used instead of a transaction.

    "CLIENT" specifies that the CLIENT_ACK acknowledgment mode is used instead of a transaction.
Returns:
a newly created QueueSession
Throws:
javax.jms.JMSException - if JMS Connection fails to create a session due to some internal error or lack of support for specific transaction and acknowledgement mode.
WavesetException - if reliabilityMode contains an invalid value

createTopicSession

public static javax.jms.TopicSession createTopicSession(javax.jms.TopicConnection topicConnection,
                                                        java.lang.String reliabilityMode)
                                                 throws javax.jms.JMSException,
                                                        WavesetException
Create a new TopicSession from the given TopicConnection

Parameters:
topicConnection - the TopicConnection from which the new TopicSession is to be created
reliabilityMode - specifies the mechanism used to ensure reliable messaging. The valid values are "LOCAL", "AUTO", "DUPS_OK", and "CLIENT".


    "LOCAL" specifies that a local session transaction will be used.

    "AUTO" specifies that the AUTO_ACK acknowledgment mode is used instead of a transaction.

    "DUPS_OK" specifies that the DUPS_OK_ACK acknowledgment mode is used instead of a transaction.

    "CLIENT" specifies that the CLIENT_ACK acknowledgment mode is used instead of a transaction.
Returns:
a newly created TopicSession
Throws:
javax.jms.JMSException - if JMS Connection fails to create a session due to some internal error or lack of support for specific transaction and acknowledgement mode.
WavesetException - if reliabilityMode contains an invalid value

createQueue

public static javax.jms.Queue createQueue(javax.naming.Context context,
                                          java.lang.String destinationName)
                                   throws WavesetException
Create a new Queue

Parameters:
context - the Context to use to perform the lookup of the queue
destinationName - the JNDI lookup name of the desired queue
Returns:
a newly created Queue
Throws:
WavesetException - if a naming exception is encountered, or the JNDI lookup does not return a javax.jms.Queue object

createTopic

public static javax.jms.Topic createTopic(javax.naming.Context context,
                                          java.lang.String destinationName)
                                   throws WavesetException
Create a new Topic

Parameters:
context - the Context to use to perform the lookup of the topic
destinationName - the JNDI lookup name of the desired Topic
Returns:
a newly created Topic
Throws:
WavesetException - if a naming exception is encountered, or the JNDI lookup does not return a javax.jms.Topic object

createQueueSender

public static javax.jms.QueueSender createQueueSender(javax.jms.QueueSession queueSession,
                                                      javax.jms.Queue queue)
                                               throws javax.jms.JMSException
Create a QueueSender to send messages to the specified queue.

Parameters:
queueSession - the session under which messages will be sent
queue - the queue to send to
Returns:
the newly created QueueSender
Throws:
javax.jms.JMSException - if a session fails to create a sender due to some JMS error

send

public static void send(javax.jms.QueueSender queueSender,
                        javax.jms.Message message,
                        java.util.Map deliveryOptionsMap)
                 throws javax.jms.JMSException,
                        WavesetException
Send a message to a queue.

Parameters:
queueSender - the QueueSender which will send the message
message - the message to be sent
deliveryOptionsMap - Specify a non-null map if you need to specify delivery mode, priority and time to live options.

The table below describes each expected key for the deliveryOptionsMap, and the significance of each key's value.

KeyValue typeReqd?UsageDefault
"deliveryMode" java.lang.String no Valid values are "PERSISTENT" and "NON_PERSISTENT" "PERSISTENT"
"priority" java.lang.String or java.lang.Integer no The message priority for this message. Priority must be a value between 0 and 9.

JMS defines a 10 level priority value with 0 as the lowest and 9 as the highest. Clients should consider 0-4 as gradients of normal priority and 5-9 as gradients of expedited priority. Priority is set to 4, by default.

4
"timeToLive" java.lang.String or java.lang.Integer no The length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. zero is unlimited. 0
Throws:
WavesetException - if illegal values are found in deliveryOptionsMap map
javax.jms.JMSException - if JMS fails to send the message due to some internal error

createTopicPublisher

public static javax.jms.TopicPublisher createTopicPublisher(javax.jms.TopicSession topicSession,
                                                            javax.jms.Topic topic)
                                                     throws javax.jms.JMSException
Create a Publisher for the specified topic.

Parameters:
topicSession - the session under which messages will be published
topic - the topic to publish to
Returns:
the newly created TopicPublisher
Throws:
javax.jms.JMSException - if a session fails to create a publisher due to some JMS error

publish

public static void publish(javax.jms.TopicPublisher topicPublisher,
                           javax.jms.Message message,
                           java.util.Map deliveryOptionsMap)
                    throws javax.jms.JMSException,
                           WavesetException
Publish a message to a topic.

Parameters:
topicPublisher - the TopicPublisher which will publish the message
message - the message to be published
deliveryOptionsMap - same as described in send
Throws:
WavesetException - if illegal values are found in deliveryOptionsMap map
javax.jms.JMSException - if JMS fails to send the message due to some internal error

createTextMessage

public static javax.jms.TextMessage createTextMessage(javax.jms.Session session)
                                               throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
Returns:
an un-initialized TextMessage. A TextMessage is used to send a message containing a String.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error

createTextMessage

public static javax.jms.TextMessage createTextMessage(javax.jms.Session session,
                                                      java.lang.String text)
                                               throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
text - the string used to initialize this message
Returns:
an initialized TextMessage. A TextMessage is used to send a message containing a String.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createMapMessage

public static javax.jms.MapMessage createMapMessage(javax.jms.Session session)
                                             throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
Returns:
a MapMessage. A MapMessage is used to send a self-defining set of name-value pairs where names are Strings and values are Java primitive types.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createBytesMessage

public static javax.jms.BytesMessage createBytesMessage(javax.jms.Session session)
                                                 throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
Returns:
a BytesMessage. A BytesMessage is used to send a message containing a stream of uninterpreted bytes.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createObjectMessage

public static javax.jms.ObjectMessage createObjectMessage(javax.jms.Session session)
                                                   throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
Returns:
an initialized ObjectMessage. An ObjectMessage is used to send a message that containing a serializable Java object.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createStreamMessage

public static javax.jms.StreamMessage createStreamMessage(javax.jms.Session session)
                                                   throws javax.jms.JMSException
Parameters:
session - the Session from which to create the Message
Returns:
a StreamMessage. A StreamMessage is used to send a self-defining stream of Java primitives.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

getMessageDetails

public static java.lang.String getMessageDetails(javax.jms.Connection conn,
                                                 javax.jms.Message msg)
Generate a String with detailed info about the Message. Useful for debugging.

Parameters:
conn - specify a non-null Connection if you wish to also view the standard properties exposed by the Connection meta-data
msg - the Message to detail
Returns:
the formatted details String