org.pricingnexus.tools
Class JmsWrapper

java.lang.Object
  |
  +--org.pricingnexus.tools.JmsWrapper

public class JmsWrapper

extends java.lang.Object

This object is the result of some frustrating weeks of work with JMS ,-)) Ok, joking off... Although JMS is probably straight forward it's sometims a little ugly to use. I.e. you have a hierachy of elements that start from Destination and goes down to the individual message. But e.g. for creating a message producer or consumer (low hierachy object which can be used for individual threads) you need a reference to the applying destination object. You even need the destination to create a message! Therefore you need to pass a lot of information from a master to a client thread, code can get really ugly. An alternative approach is to use a thread-safe wrapper than contains all necessary information and to pass just this object. It's considered to be lightweigt as it just encapsulates all neccessary JMS calls and stores refrences. As this object is not a general purpose wrapper to JMS but specifically designed for the use in Pricing-Nexus you'll also note that a lot of very specific JMS features are missing. E.g. it supports currently only text messages and no other types. $Header$

Field Summary

static java.lang.String	QCF_NAME Provider specific name for a JMS "QueueConnectionFactory".
static java.lang.String	TCF_NAME Provider specific name for a JMS "TopicConnectionFactory".

Constructor Summary

JmsWrapper(java.lang.String icfClassName, java.lang.String providerURL, int retries)
Standard constructor of class.

Method Summary

void	close() Closes a connection.
void	connect(java.lang.String destinationName) Creates JMS on the named queue or topic connection.
javax.jms.QueueReceiver	createQueueReceiver(int sessionID) Creates a QueueSender for given session identifier and returns a reference to it.
javax.jms.QueueSender	createQueueSender(int sessionID) Creates a QueueSender for given session identifier and returns a reference to it.
org.pricingnexus.tools.Session	createSession(int sessionID, boolean transacted) A new session is created and returned.
javax.jms.TextMessage	createTextMessage(int sessionID) Creates a TextMessage and returns a reference to it.
org.pricingnexus.tools.TopicPublisher	createTopicPublisher(int sessionID) Creates a TopicPublisher for given session identifier and returns a reference to it.
org.pricingnexus.tools.TopicSubscriber	createTopicSubscriber(int sessionID) Creates a TopicSubscriber for given session identifier and returns a reference to it.
org.pricingnexus.tools.QueueSession	getQueueSession(int sessionID) Returns a reference to a previously created QueueSession.
org.pricingnexus.tools.Session	getSession(int sessionID) Returns a reference to a previously created JMS-session.
org.pricingnexus.tools.TopicSession	getTopicSession(int sessionID) Returns a reference to a previously created TopicSession.
boolean	setIsQueue() Corresponding to setIsTopic this method declares the obejct to be used in a queue context.
boolean	setIsTopic() As our object does support Topics as well as Queues the calling context first needs to decice if an instance of this object needs to handle Topics or Queues.
void	startConnection() Very simple: Starts the "stored" connection
void	stopConnection() Stops the "stored" connection

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

QCF_NAME

public static java.lang.String QCF_NAME

Provider specific name for a JMS "QueueConnectionFactory". Probably has to be changed depending on the JMS provider.

TCF_NAME

public static java.lang.String TCF_NAME

Provider specific name for a JMS "TopicConnectionFactory". Probably has to be changed depending on the JMS provider.

Constructor Detail

JmsWrapper

public JmsWrapper(java.lang.String icfClassName,
                  java.lang.String providerURL,
                  int retries)

Standard constructor of class. Just puts parameters on internal data fields, nothing else.

Parameters:

icfClassName - name of the initial context factory class (ini-Name "JMS_ICF_CLASS") providerURL provider URL to connect to (ini-Name "JMS_URL") numRetries Number of retries for various actions if anything does not work correctly

Method Detail

setIsTopic

public boolean setIsTopic()

As our object does support Topics as well as Queues the calling context first needs to decice if an instance of this object needs to handle Topics or Queues. This must be done directly after creation of an instance of this object. Normally "true" should be returned.

Returns:

boolean should normally be true; only false if set method has been called already before

setIsQueue

public boolean setIsQueue()

Corresponding to setIsTopic this method declares the obejct to be used in a queue context.

Returns:

boolean should normally be true; only false if set method has been called already before

connect

public void connect(java.lang.String destinationName)
             throws javax.jms.JMSException,
                    javax.naming.NamingException

Creates JMS on the named queue or topic connection. Before this we must also create a destination, and a Connection Factory. Because a Connection object is multithreaded in the context of PricingNexus there's no need to create more than one Connection per Destination, as there will be normally only one message producer or consumer per destination. XX2: Please note that currently there's no error checking if e.g. the object has been correctly initialized, i.e. set to either topic or queue. Also there's no check if already a connection has been made. This needs to be enhanced in the future.

Parameters:

destinationName - Name of queue or topic to connect to

Throws:

JMSException, - NamingException

startConnection

public void startConnection()
                     throws javax.jms.JMSException

Very simple: Starts the "stored" connection

Throws:

javax.jms.JMSException -

stopConnection

public void stopConnection()
                    throws javax.jms.JMSException

Stops the "stored" connection

close

public void close()
           throws javax.jms.JMSException

Closes a connection. This should release resources at the JMS provider as well as at the client. Should be called as GC is not always the best way to do this job...-))

createSession

public org.pricingnexus.tools.Session createSession(int sessionID,
                                                    boolean transacted)
                                             throws javax.jms.JMSException

A new session is created and returned. It is also stored in the local "session-store" which is in fact just a simple Hashtable. Please note: This method can be called more than once (e.g. if you need more than one session for multiple threads) but there's no check if already a session exists with this ID and is valid!

Parameters:

sessionID - A simple number [0..n] as unique identification of a session transacted "true" or "false"; corresponds with the transacted flag when creating a JMS session

Returns:

Session reference to the created session; can be used directly if necessary

Throws:

javax.jms.JMSException -

getSession

public org.pricingnexus.tools.Session getSession(int sessionID)

Returns a reference to a previously created JMS-session. If no session with this ID exists, a null reference is returned. Easy thing: The get-method of the Hashtable object does return null itself if no entry with the used key is in it.

Parameters:

sessionID - number of the session to be returned; must have been created previously

Returns:

Session reference to session

getTopicSession

public org.pricingnexus.tools.TopicSession getTopicSession(int sessionID)

Returns a reference to a previously created TopicSession. If no session with this ID exists, a null reference is returned.

Parameters:

sessionID - number of the session to be returned; must have been created previously

Returns:

Session reference to session

getQueueSession

public org.pricingnexus.tools.QueueSession getQueueSession(int sessionID)

Returns a reference to a previously created QueueSession. If no session with this ID exists, a null reference is returned.

Parameters:

sessionID - number of the session to be returned; must have been created previously

Returns:

Session reference to session

createQueueSender

public javax.jms.QueueSender createQueueSender(int sessionID)
                                        throws javax.jms.JMSException

Creates a QueueSender for given session identifier and returns a reference to it. As with JMS a Destination must be given to create a QueueSender we use the one, we've created at the very beginning.
The reason to have an individual class for each topic and queue MessageProducer/Consumer is a small performance gain: By using the interface classes "MessageProducer"/"MessageConsumer" instead of the topic/queue specific ones one had to cast every time, a producer/consumer is needed. This is something that can be avoided easily in the wrapper class by providing just all kind of creation methods.

Parameters:

sessionRef - reference to existing session. If a session with the appropriate identifier cannot be return value will be null.

Throws:

javax.jms.JMSException -

createQueueReceiver

public javax.jms.QueueReceiver createQueueReceiver(int sessionID)
                                            throws javax.jms.JMSException

Creates a QueueSender for given session identifier and returns a reference to it.

Parameters:

sessionRef - reference to existing session. If a session with the appropriate identifier cannot be return value will be null.

Throws:

javax.jms.JMSException -

createTopicPublisher

public org.pricingnexus.tools.TopicPublisher createTopicPublisher(int sessionID)
                                                           throws javax.jms.JMSException

Creates a TopicPublisher for given session identifier and returns a reference to it.

Parameters:

sessionRef - reference to existing session. If a session with the appropriate identifier cannot be return value will be null.

Throws:

javax.jms.JMSException -

createTopicSubscriber

public org.pricingnexus.tools.TopicSubscriber createTopicSubscriber(int sessionID)
                                                             throws javax.jms.JMSException

Creates a TopicSubscriber for given session identifier and returns a reference to it.

Parameters:

sessionRef - reference to existing session. If a session with the appropriate identifier cannot be return value will be null.

Throws:

javax.jms.JMSException -

createTextMessage

public javax.jms.TextMessage createTextMessage(int sessionID)
                                        throws javax.jms.JMSException

Creates a TextMessage and returns a reference to it.

Parameters:

sessionRef - reference to existing session. If a session with the appropriate identifier cannot be return value will be null.

Throws:

javax.jms.JMSException -