org.openeai.jms.producer
Class ProducerPool

java.lang.Object
  org.openeai.OpenEaiObject
      org.openeai.jms.producer.ProducerPool

public class ProducerPool
extends OpenEaiObject

The ProducerPool is a class that contains a list of producers for use by an application or command. It is very similar to a Database Connection pool in that it is filled with pre-configured and started producers when the application starts up. This is to allow developers to affect the performance of an application by adding producers to a pool relative to the amount of processing and number of threads present in the application. Since OpenEAI producers are by default thread safe, it does not do anything to limit the number of threads accessing a producer at the same time. It simply makes the number of producers producing to the same queue higher so their will be a smaller number of synchronizations occurring within the producers (when a message is produced and Session synchronization occurrs).

Version:

3.0 - 28 January 2003

Author:

Tod Jackson (tod@openeai.org), Steve Wheat (steve@openeai.org)

See Also:

ProducerConfig

Field Summary

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

ProducerPool()
Constructor

ProducerPool(java.util.List vProducers)

Method Summary

MessageProducer	getExclusiveProducer() Returns an EXCLUSIVE producer from the pool.
MessageProducer	getProducer() Returns the next producer from the pool.
java.util.List	getProducers() Returns the list of OpenEAI producers associated to this pool.
void	releaseProducer(MessageProducer producer) Release a previously retrieved Exclusive producer to the pool.
void	setProducers(java.util.List vProducers) Sets the list of OpenEAI producers to what's passed in.
int	size() Returns the size of the pool.

Methods inherited from class org.openeai.OpenEaiObject

getAppName, getDebug, getFromAddr, getMailHost, getMailService, getProperties, getToAddr, initializeLog4j, initializeLog4j, initializeLog4j, setAppName, setDebug, setFromAddr, setMailHost, setMailService, setProperties, setToAddr

Methods inherited from class java.lang.Object

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

Constructor Detail

ProducerPool

public ProducerPool()

Constructor

ProducerPool

public ProducerPool(java.util.List vProducers)

Method Detail

setProducers

public final void setProducers(java.util.List vProducers)

Sets the list of OpenEAI producers to what's passed in.

Parameters:

vProducers - java.util.List

getProducers

public final java.util.List getProducers()

Returns the list of OpenEAI producers associated to this pool.

Returns:

java.util.List

size

public final int size()

Returns the size of the pool.

Returns:

int the size of the pool.

getProducer

public final MessageProducer getProducer()
                                  throws javax.jms.JMSException

Returns the next producer from the pool. This is determined simply by maintaining and counter indicating the last producer returned. Since producers are thread safe it does not attempt to ensure that only one request is using a given producer at a time.

If a producer is not started, it will not be returned.

Returns:

MessageProducer either a PointToPoint or PubSubProducer

Throws:

javax.jms.JMSException - if no started producers can be found in the pool.

getExclusiveProducer

public final MessageProducer getExclusiveProducer()
                                           throws javax.jms.JMSException

Returns an EXCLUSIVE producer from the pool. This is most often required when a high-volume gateway or application needs to use a producer pool filled with PubSubProducers that will be transacted. In this situation, you want to make sure you've got an exclusive hold on the producer you're using to publish the message with because when you perform a "commit" on the producer, you'll be committing everything published with that producer. If you have multiple threads using that producer who have all published messages but not committed them, they will all be committed when any of those threads performs a commit on the producer (much like a database connection).

By obtaining an exclusive producer, you're ensuring that the thread requesting the producer from the pool is the only thread that should be using that producer at that time and therefore anything committed on that producer will be related to the messages published by that thread only.

Generally, this method SHOULD NOT be called if the pool contains PointToPointProducers because there is no need to obtain an exclusive producer in that case.

When the getExclusiveProducer method is called, a flag is set so that any subsequent retrievals from the pool will not return the same producer until the producer has been released back to the pool via the releaseProducer(MessageProducer) method.

This method DOES NOT attempt to create a new producer if there are none available in the pool. Instead, it "blocks" until one becomes available. Because of this, it is critical that if using this method, you promptly release the producer back to the pool when you're done with it. Otherwise, all producers will become unavailable and it will be impossible to retrieve any producers from this particular pool resulting in an endless loop.

NOTE: Applications using the getExclusiveProducer method on a ProducerPool should NOT use the getProducerMethod on that same pool. This will confuse things and may result in un-expected behavior since the getProducer method doesn't care about multiple threads accessing the same producer.

Returns:

MessageProducer either a PointToPoint or PubSubProducer

Throws:

javax.jms.JMSException - if no started producers can be found in the pool.

See Also:

releaseProducer(MessageProducer), getProducer()

releaseProducer

public final void releaseProducer(MessageProducer producer)

Release a previously retrieved Exclusive producer to the pool. This method should be called promptly after you're finished with the exclusive producer you previously rertrieved (via the getExclusiveProducer method). If you fail to release the producer, all producers in this pool will become unavailable and your application will find itself in an endless "hung" situation once all producers have been retrieved exclusively.

Parameters:

producer - the MessageProducer to release back to the pool.