org.openeai.config
Class ProducerConfig

java.lang.Object
  org.openeai.OpenEaiObject
      org.openeai.config.EnterpriseConfigurationObjectImpl
          org.openeai.config.ProducerConfig

All Implemented Interfaces:

EnterpriseConfigurationObject

public class ProducerConfig
extends EnterpriseConfigurationObjectImpl
implements EnterpriseConfigurationObject

A ProducerConfig is a wrapper class that takes information stored in an OpenEAI Deployment document (ProducerConfig Element) and stores it in a Java object. Then the configuration object is passed to the constructor of the OpenEAI MessageProducers (PointToPointProducer and PubSubProducer) and they are able to configure themselves with the information found in the config object.

Both PubSub and PointToPoint Producers use the same configuration information to initialize themselves. However, some items listed in a ProducerConfig Element are only used by PubSubProducers and some are only used by PointToPointProducers. Where this is the case, it is noted.

Configuration Parameters:

These are the configuration parameters specified by the ProducerConfig Element in the Deployment document. NOTE: Like all other OpenEAI configuration objects, there is a "container" level associated to ProducerConfig objects. Many Elements and attributes are required at that level and may be optionally overridden at this level. This is to avoid having to enter redundant information in the Deployment document if all (or most) Producers being configured should use the same configuration information. Therefore, many of the Producer configuration parameters are optional at this level but required at the "container" level. Where this is the case, it will be indicated by an "*".

Many of the parameters specified for a producer are simply JMS parameters required by the JMS Specification.

Name	Required	Description
name	yes	Name of the Producer. This will be used in many logged messages and is the name by which a producer is stored in AppConfig. A Producer name should be unique within an application. If the 'numberOfProducers' attribute is specified this name will be the name of the ProducerPool object which is stored in AppConfig and is a collection of initialized producer objects.
numberOfProducers	no (default is 1)	This parameter indicates how many producers of this type should be initialized with the configuration information listed and stored in a ProducerPool object. The ProducerPool is then stored in AppConfig and can be retrieved just like any other object housed by AppConfig. If the numberOfProducers attribute is specified, a ProducerPool will be created with that number of producers in it. If numberOfProducers is not specified only the Producer being configured will be stored in AppConfig. It is recommended that most applications utilize a ProducerPool even if the number of producers in the pool is only 1. This gives the application flexibility to increase this number at a later time and potentially improve the application's performance by increasing the number of producers in the pool. This would be determined after a period of time depending on how much load the application is under on a regular basis. By increasing this number, performance is generally improved in a multi-threaded application because of Thread synchronization that must occur when only one producer is used across threads. Generally, this is only used for PointToPoint producers but it can be used for PubSubProducers as well. Generally, PointToPoint production is most critical when it comes to performance.
tempPoolSize	no (default is 5)	This parameter indicates how many TemporaryQueues and QueueReceivers on those TemporaryQueues will be initialized when the Producer is first started. During message production, TempoaryQueues and QueueRecievers will be dynamically created when necessary. This is another performance enhancement that reduces the overhead associated to PointToPoint message production and response consumption. The OpenEAI PointToPoint producers use TemporaryQueues to send messages. However, since the producers must be thread safe, they cannot use the same temporary queue when a message is produced. If they did, producers being used by two threads concurrently, would potentially step on each other when a response was returned by the consumer of the request produced. There are two ways to avoid this situation: One is to create a new TemporaryQueue and QueueReciever each time the producer produces a Request. This is expensive. The second alternative is to create a "pool" of TempoaryQueues and QueueReceivers upon initialization and restrict access to those resources when messages are produced and only create a new TemporaryQueue/QueueReceiver if an available resource cannot be obtained from the pool. Any TempoaryQueue/QueueReceiver that must be created because the pool is busy, is cleaned up when the request has been completed. By monitoring how many TempoaryQueues are being created dynamically for an application and setting this number higher, one can affect the performance of Point-To-Point messaging significantly because fewer resources have to be allocated each time a request is produced. This is only relevant to PointToPointProducers.
startOnInitialization	no*	This parameter tells the Producer whether or not it should start (be ready to produce/publish messages) upon initialization. If the flag is set to true, the Producer will initialize itself and then actually create the connection to the broker. If this flag is false, the Producer will initialize itself so that it is ready to be started but it won't actually create the connection to the broker. Therefore, before a producer that hasn't been started can actually produce/publish messages, it must be started explicitly by the application using it.
acknowledgementMode	no	JMS parameter
transacted	no	JMS parameter
deliveryMode	no	JMS parameter
LoggingProducer	no	This is a PubSubProducer object configured to publish PubSubMessages to a "logging" destination as they are published by the PubSubProducer being configured. Therefore, when a PubSubProducer publishes a message via the publishMessage method, that message will potentially be published to the logging destination by the LoggingProducer as well. This is a feature that allows an organization to specifically track every PubSub message published within their organization. Because PubSub messages are not used for "synchronous" messaging as specified by the OpenEAI Message Protocol they are typically published and processed by messaging applications and gateways when no one is watching. Therefore, it is useful to be able to keep track of all messages that are published incase an emergency occurs where a message needs to be resubmitted etc. OpenEAI provides one logging gateway as a reference implementation to demonstrate the usefulness of this.
ConnectionFactoryName	no*	The name of the JMS Administered object (TopicConnectionFactory or QueueConnectionFactory) that this Producer will use to initialize itself from a JMS perspective. To maintain broker independance, this adminstered object should be stored in a Directory server.
DestinationName	yes	The name of the JMS Administered object (Topic or Queue) that this Producer will produce/publish messages to. To maintain broker independance, this administered object should be stored in a Directory server.
InitialContextFactory	no*	The name of the JNDI context factory that will be used to retrieve the JMS administered objects from a Directory Server or wherever the administered objects are stored.
ProviderURL	no*	Location where the administered objects can be retrieved from. To maintain broker independance, this should reference a location in a Directory server.
SecurityPrincipal	no*	The user with which to create the InitialContext when retrieving the Administered objects.
SecurityCredentials	no*	The credentials associated to the user with which to create the InitialContext when retrieving the Administered objects.
Username	no*	Broker user with which to connect to the broker as. Generally, this is stored within the ConnectionFactory administered object so it is not needed here. However, if it isn't stored or you wish to override what's stored in the AO, you can specify that here.
Password	no*	Password associated to the broker user with which to connect to the broker as. Generally, this is stored within the ConnectionFactory administered object so it is not needed here. However, if it isn't stored or you wish to override what's stored in the AO, you can specify that here.
ProducerIdURL	no*	URL used to generate a unique Producer Id for this producer. Generally, this is a URL that resolves to the OpenEAI UuidGen servlet which generates a unique UUID and returns it to the caller. If this URL is "localhost" the id will be generated locally and will be unique for the machine running the application. This ProducerId will become part of all messages using the OpenEAI foundation that are produced with this producer.
ConfigClass	no*	Name of the configuration class that wraps the config Element (this class)
ObjectClass	yes	Name of the Java object that will be instantiated with this Config class (PointToPointProducer or PubSubProducer)
DefaultCommandName	no	Used by the LoggingProducer when it publishes messages to set the COMMAND_NAME JMS Property on the Message that it publises to the "logging" destination. Generally, this is not needed because the EnterpriseLoggingService should generally execute only one Command (absolute command).

Version:

3.0 - 28 January 2003

Author:

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

See Also:

PointToPointProducer, PubSubProducer, ProducerPool, TempQueuePool, ConsumerConfig

Field Summary

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

ProducerConfig()
This is the constructor used by AppConfig to instantiate the config object.

ProducerConfig(org.jdom.Element configElement)

ProducerConfig(java.lang.String configDocUrl, java.lang.String producerName)

Method Summary

PubSubProducer	getLoggingProducer() This method returns the logging producer that will be associated to an OpenEAI PubSubProducer.
void	init(org.jdom.Element configElement) Implements the init(Element) method that all EnterpriseConfiguration objects must implement.
void	setLoggingProducer(PubSubProducer producer) This method sets the logging producer that will be associated to an OpenEAI PubSubProducer.

Methods inherited from class org.openeai.config.EnterpriseConfigurationObjectImpl

addProperty, getAppName, getConfigDoc, getConfigElementByAttributeValue, getElementByAttributeValue, getName, getType, getValidation, refresh, setAppName, setConfigDoc, setName, setRefresh, setType, setValidation

Methods inherited from class org.openeai.OpenEaiObject

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.openeai.config.EnterpriseConfigurationObject

getAppName, getProperties, refresh, setAppName

Constructor Detail

ProducerConfig

public ProducerConfig()

This is the constructor used by AppConfig to instantiate the config object. Then, AppConfig calls this object's init(Element) method passing the configuration element it retrieved from the XML configuration document which this object uses to configure itself. After this object has initialized itself, it will be used to instantiate and initialize the framework object (MessageObject, Producers, Consumers etc.) with the properties it's been initialized with.

ProducerConfig

public ProducerConfig(java.lang.String configDocUrl,
                      java.lang.String producerName)
               throws EnterpriseConfigurationObjectException

Throws:

EnterpriseConfigurationObjectException

ProducerConfig

public ProducerConfig(org.jdom.Element configElement)
               throws EnterpriseConfigurationObjectException

Throws:

EnterpriseConfigurationObjectException

Method Detail

setLoggingProducer

public void setLoggingProducer(PubSubProducer producer)

This method sets the logging producer that will be associated to an OpenEAI PubSubProducer.

All OpenEAI PubSubProducers have a LoggingProducer associated to them. This is just another PubSubProducer that is configured to publish messages to a "logging topic". This event occurs when a message is published by the publisher if the logging producer exists and is started. So, the end result is that messages published by PubSubProducers may get published twice. Once to the intended destination as specified in the PubSubProducer's configuration and once to the destination associated to the PubSubProducer's LoggingProducer. These "logged" messages serve as a tracking mechanism so that every message published by a message aware application can be persisted in a repository.

Parameters:

producer - PubSubProducer the configured and potentially started "logging producer"

See Also:

PubSubProducer

getLoggingProducer

public PubSubProducer getLoggingProducer()

This method returns the logging producer that will be associated to an OpenEAI PubSubProducer.

Returns:

PubSubProducer

See Also:

PubSubProducer

init

public void init(org.jdom.Element configElement)
          throws EnterpriseConfigurationObjectException

Implements the init(Element) method that all EnterpriseConfiguration objects must implement. This init method takes the Configuration element passed in and pulls out configuration information specific to the Producer (PubSub or PointToPoint) being initialized. Then it sets various instance variables and properties on itself which will be used by the Producer when AppConfig instantiates it passing this configuration object. The Producer will then use the configuration java object to initialize itself.

Specified by:

init in interface EnterpriseConfigurationObject

Overrides:

init in class EnterpriseConfigurationObjectImpl

Parameters:

configElement - Element the configuration element that AppConfig has pulled from the configuration document relevant to the Producer being configured. Or, the element that was found in the init() method.

Throws:

EnterpriseConfigurationObjectException - if errors occur processing the configuration Element.