Code that uses the JmsTemplate only needs to implement callback interfaces giving them a clearly defined contract. The IMessageCreator callback interface creates a message given a Session provided by the calling code in JmsTemplate. In order to allow for more complex usage of the JMS API, the callback ISessionCallback provides the user with the JMS session and the callback IProducerCallback exposes a Session and MessageProducer pair.

The JMS API exposes two types of send methods, one that takes delivery mode, priority, and time-to-live as quality of service (QOS) parameters and one that takes no QOS parameters which uses default values. Since there are many send methods in JmsTemplate, the setting of the QOS parameters have been exposed as bean properties to avoid duplication in the number of send methods. Similarly, the timeout value for synchronous receive calls is set using the property ReceiveTimeout.

The JmsTemplate requires a reference to a ConnectionFactory. The ConnectionFactory is part of the JMS specification and serves as the entry point for working with JMS. It is used by the client application as a factory to create connections with the JMS provider and encapsulates various configuration parameters, many of which are vendor specific such as SSL configuration options.

Note: The TIBCO implementation is not interface based and its methods are not virtual so no additional functionality that may otherewise be part of a ConnectionFactory 'Wrapper' are provided. This type of functionality wil be available when Spring.NET uses the implementation neutral NMS AP(s.

In Java implementations of JMS, Connections and Destinations are 'administered objects' accessible though JNDI. In .NET each vendor has selected a different approach, generally JNDI inspired, to retrieve Connections and Destinations that were configured administratively. You can use these vendor specific APIs to perform dependency injection on references to JMS Destination objects in Sprng's XML configuration file by creating am implementation of IObjectFactory.

However, this approach of administerd objects can be quite cumbersome if there are a large number of destinations in the application or if there are advanced destination management features unique to the JMS provider. Examples of such advanced destination management would be the creation of dynamic destinations or support for a hierarchical namespace of destinations. The JmsTemplate delegates the resolution of a destination name to a JMS destination object to an implementation of the interface IDestinationResolver. DynamicDestinationResolver is the default implementation used by JmsTemplate and accommodates resolving dynamic destinations. A JndiDestinationResolver is also provided that acts as a service locator for destinations contained in JNDI and optionally falls back to the behavior contained in DynamicDestinationResolver.

Quite often the destinations used in a JMS application are only known at runtime and therefore cannot be administratively created when the application is deployed. This is often because there is shared application logic between interacting system components that create destinations at runtime according to a well-known naming convention. Even though the creation of dynamic destinations are not part of the JMS specification, most vendors have provided this functionality. Dynamic destinations are created with a name defined by the user which differentiates them from temporary destinations and are often not registered in a JNDI-like directory.. The API used to create dynamic destinations varies from provider to provider since the properties associated with the destination are vendor specific. However, a simple implementation choice that is sometimes made by vendors is to disregard the warnings in the JMS specification and to use the TopicSession method createTopic(String topicName) or the QueueSession method createQueue(String queueName) to create a new destination with default destination properties. Depending on the vendor implementation, DynamicDestinationResolver may then also create a physical destination instead of only resolving one.

The boolean property PubSubDomain determines the behavior of dynamic destination resolution via implementations of the DestinationResolver interface.

You can also configure the JmsTemplate with a default destination via the property defaultDestination. The default destination will be used with send and receive operations that do not refer to a specific destination.

One of the most common uses of JMS is to concurrently process messages delivered asynchronously.

A subclass of AbstractMessageListenerContainer is used to receive messages from JMS and drive the Message-Driven POCOs (MDPs) that are injected into it. The AbstractMessageListenerContainer is responsible for all threading of message reception and dispatch into the MDPs for processing. A message listener container is the intermediary between an MDP and a messaging provider, and takes care of registering to receive messages, participating in transactions, resource acquisition and release, exception conversion and suchlike. This allows you as an application developer to write the (posssibly complex) business logic associated with receiving a message (and possibly responding to it), and delegates boilerplate JMS infrastructure concerns to the framework. There are one subclasses of AbstractMessageListenerContainer packaged with Spring - SimpleMessageListenerContainer.

SimpleMessageListenerContainer creates a fixed number of JMS sessions at startup and uses them throughout the lifespan of the container. This subclass doesn't allow for dynamic adaption to runtime demands or participate in transactional reception of messages.

Spring.Java provides two other subclasses, one to support distributed transactions and the other to provide a dynamic session management to optimize concurrent processing. Distributed transaction support is not provided by .NET C# vendors (AFAIK) and neither is the dynamic session management support which is based on the ServerSessionPool SPI - an optional part of the JMS specification.

TBD. This relates to integration with Spring's transaction management features, the ability to have transacted JMS sessions is supported.

In order to facilitate the sending of domain model objects, the JmsTemplate has various send methods that take a .NET object as an argument for a message's data content. The overloaded methods ConvertAndSend and ReceiveAndConvert in JmsTemplate delegate the conversion process to an instance of the MessageConverter interface. This interface defines a simple contract to convert between .NET objects and JMS messages. The default implementation SimpleMessageConverter supports conversion between String and TextMessage, byte[] and BytesMesssage, and System.Collections.IDictionary and MapMessage. By using the converter, you and your application code can focus on the business object that is being sent or received via JMS and not be concerned with the details of how it is represented as a JMS message.

The family of ConvertAndSend messages are similar to that of the Send method with the additional argument of type IMessagePostProcessor. These methods are listed below.

In the previous example the message priority was set inside the callback. Generally speaking, converters should not be responsible for setting Quality of Service parameters since they are not aware of the context in which they are being called. The following code show this in action.

public void PublishUsingDict(string ticker, double price)
{
  IDictionary marketData = new Hashtable();
  marketData.Add("TICKER", ticker);
  marketData.Add("PRICE", price);
  template.ConvertAndSend("APP.STOCK", marketData);
}

A reflection based converter that can converter arbitrary objects is available as a seperate project.

While JMS is typically associated with asynchronous processing, it is possible to consume messages synchronously. The overloaded Receive(..) methods provide this functionality. During a synchronous receive, the calling thread blocks until a message becomes available. This can be a dangerous operation since the calling thread can potentially be blocked indefinitely. The property ReceiveTimeout specifies how long the receiver should wait before giving up waiting for a message.

The Receive methods are listed below

The Recieve method without arguments used the DefaultDestination. The RecieveSelected methods apply the provided JMS message selector string to the MessageConsumer that is created.

The ReceiveAndConvert methods apply the templates message converter when receiving a message. These methods are listed below.

You can register a class that implements the IMessageListener interface. In the case of TIBCO EMS this interface is defined as

public interface IMessageListener
{
      void OnMessage(Message message);
}

Other vendors may provide a delegate based version of this interface.

You register you listener with a message listener container that specifies JMS configuration parameters and the number of concurrent consumers to create. There is an abstract base class for message listener containers, AbstractMessageListenerContainer, and one concrete implementation, SimpleMessageListenerContainer. SimpleMessageListenerContainer creates a fixed number of JMS Sessions/MessageConsumer pairs as set by the property ConcurrentConsumers. Here is a sample configuration

      <object id="connectionFactory" type="TIBCO.EMS.ConnectionFactory, TIBCO.EMS">
        <constructor-arg index="0" value="tcp://localhost:7222"/>
      </object>

      <object id="messageListener" type="MyApp.MyMessageListener, MyApp"/>

      <object id="jmsContainer" type="Spring.Messaging.Tibco.Ems.Listener.SimpleMessageListenerContainer, Spring.Messaging.Tibco.Ems">
        <property name="ConnectionFactory" ref="connectionFactory"/>
        <property name="DestinationName" value="APP.REQUEST"/>
        <property name="ConcurrentConsumers" value="10"/>
        <property name="MessageListener" ref="messageListener"/>
      </object>

The property PubSubDomain is by defalt false, meaning point-to-point/Queue delivery semantics. The above configuration will create 10 threads that process messages off of the queue named "APP.REQUEST". The threads are those owned by the JMS provider as a result of creating a JMS MessageConsumer. Other important properties are ClientID, used to set the ClientID of the JMS Connection and MessageSelector to specify the JMS 'sql-like' message selector string. Durable subscriptions are supported via the properties SubscriptionDurable and DurableSubscriptionName. You may also register a listener using the property ExceptionListener.

public class SimpleMessageHandler
{
    public void HandleObject(IDictionary dict)
    {
       ...
    }

    public void HandleObject(string text)
    {
      ...
    }

    public void HandleObject(byte[] data)
    {
      ...
    }
     
}

      <object name="simpleMessageHandler, type="MyApp.SimpleMessageHandler, MyApp"/>
   
      <object name="simpleMessageConverter" 
              type="Spring.Messaging.Tibco.Ems.Support.Converter.SimpleMessageConverter, Spring.Messaging.Tibco.Ems"/>

      <object id="messageListenerAdapter" type="Spring.Messaging.Tibco.Ems.Listener.Adapter.MessageListenerAdapter, ">
        <property name="DelegateObject" ref="simpleMessageHandler"/>
        <property name="DefaultListenerMethod" value="HandleObject"/>
        <property name="MessageConverter" ref="simpleMessageConverter"/>
      </object>


      <object id="connectionFactory" type="TIBCO.EMS.ConnectionFactory, TIBCO.EMS">
        <constructor-arg index="0" value="tcp://localhost:7222"/>
      </object>

      <object id="jmsContainer" type="Spring.Messaging.Tibco.Ems.Listener.SimpleMessageListenerContainer, Spring.Messaging.Tibco.Ems">
        <property name="ConnectionFactory" ref="connectionFactory"/>
        <property name="DestinationName" value="APP.REQUEST"/>
        <property name="ConcurrentConsumers" value="10"/>
        <property name="MessageListener" ref="messageListener"/>
      </object>