The goals of Spring's MSMQ 3.0 messaging support is to raise the level of abstraction when writing MSMQ applications. The System.Messaging API is a low-level API that provides the basis for creating a messaging application. However, 'Out-of-the-box', System.Messaging leaves the act of creating sophisticated multi-threaded messaging servers and clients as an infrastructure activity for the developer. Spring fills this gap by proving easy to use helper classes that makes creating an enterprise messaging application easy. These helper classes take into account the nuances of the System.Messaging API, such as its lack of thread-safety in many cases, the handling of so-called 'poison messages' (messages that are endlessly redelivered due to an unrecoverable exception during message processing), and combining database transactions with message transactions. Other goals of Spring's MSMQ messaging support are to support messaging best practices, in particular encouraging a clean architectural layering that separates the messaging middleware specifics from the core business processing.

Spring's approach to distributed computing has always been to promote a plain old CLR object approach or a POCO programming model. In this approach plain CLR objects are those that are devoid of any reference to a particular middleware technology. Spring provides the 'adapter' classes that converts between the middleware world, in this case MSMQ, and the oo-world of your business processing. This is done through the use of Spring's MessageListenerAdapter class and IMessageConverters.

The namespace Spring.Messaging provides the core functionality for messaging. It contains the class MessageQueueTemplate that simplifies the use of System.Messaging.MessageQueue by handling the lack of thread-safety in most of System.Messaging.MessageQueue's methods (for example Send). A single instance of MessageQueueTemplate can be used throughout your application and Spring will ensure that a different instance of a MessageQueue class is used per thread when using MessageQueueTemplate's methods. This per-thread instance of a System.Messaging.MessageQueue is also available via its property MessageQueue. The MessageQueueTemplate class is also aware of the presence of either an 'ambient' System.Transaction's transaction or a local System.Messaging.MessageQueueTransaction. As such if you use MessageQueueTemplate's send and receive methods, unlike with plain use of System.Messaging.MessageQueue, you do not need to keep track of this information yourself and call the correct overloaded System.Messaging.MessageQueue method for a specific transaction environment. When using a System.Messaging.MessageQueueTransaction this would usually require you as a developer to come up with your own mechanism for passing around a MessageQueueTransaction to multiple classes and layers in your application. MessageQueueTemplate manages this for you, so you don't have to do so yourself. These resource management and transaction features of MessageQueueTemplate are quite analogous to the transactional features of Spring's AdoTemplate in case you are already familiar with that functionality.

For asynchronous reception Spring provides several multi-threaded message listener containers. You can pick and configure the container that matches your message transactional processing needs and configure poison-message handling policies. The message listener container leverages Spring's support for managing transactions. Both DTC, local messaging transactions, and local database transactions are supported. In particular, you can easily coordinate the commit and rollback of a local MessageQueueTransaction and a local database transaction when they are used together.

From a programming perspective, Spring's MSMQ support involves you configuring message listener containers and writing a callback function for message processing. On the sending side, it involves you learning how to use MessageQueueTemplate. In both cases you will quite likely want to take advantage of using MessageListenerConverters so you can better structure the translation from the System.Messaging.Message data structure to your business objects. After the initial learning hurdle, you should find that you will be much more productive leveraging Spring's helper classes to write enterprise MSMQ applications than rolling your own infrastructure. Feedback and new feature requests are always welcome.

The Spring.MsmqQuickstart application located in the examples directory of the distribution shows this functionality in action.

Here is a quick example of how to use Spring's MSMQ support to create a client that sends a message and a multi-threaded server application that receives the message. (The client code could also be used as-is in a multi-threaded environment but this is not demonstrated).

On the client side you create an instance of the MessageQueueTemplate class and configure it to use a MessageQueue. This can be done programmatically but it is common to use dependency injection and Spring's XML configuration file to configure your client class as shown below.

  <object id='questionTxQueue' type='Spring.Messaging.Support.MessageQueueFactoryObject, Spring.Messaging'>
    <property name='Path' value='.\Private$\questionTxQueue'/>
    <property name='MessageReadPropertyFilterSetAll' value='true'/>
  </object>

  <object id="messageQueueTemplate" type="Spring.Messaging.Core.MessageQueueTemplate, Spring.Messaging">
    <property name="MessageQueueObjectName" value="questionTxQueue"/>
  </object>

  <!-- Class you write -->
  <object id="questionService" type="MyNamespace.QuestionService, MyAssembly">
    <property name="MessageQueueTemplate" ref="messageQueueTemplate"/>
  <object>

The MessageQueue object is created via an instance of MessageQueueFactoryObject and the MessageQueueTemplate refers to this factory object by name and not by reference. The SimpleSender class looks like this

public class QuestionService : IQuestionService
{
  private MessageQueueTemplate messageQueueTemplate;

  public MessageQueueTemplate { 
    get { return messageQueueTemplate; }
    set { messageQueueTemplate = value; }
  }

  public void SendQuestion(string question)
  {
    MessageQueueTemplate.ConvertAndSend(question);
  }
}

This class can be shared across multiple threads and the MessageQueueTemplate will take care of managing thread local access to a System.Messaging.MessageQueue as well as any System.Messaging.IMessageFormatter instances.

Furthermore, since this is a transactional queue (only the name gives it away), the message will be sent using a single local messaging transaction. The conversion from the string to the underling message is managed by an instance of the IMessageConverter class. By default an implementation that uses an XmlMessageFormatter with a TargetType of System.String is used. You can configure the MessageQueueTemplate to use other IMessageConveter implementations that do conversions above and beyond what the 'stock' IMessageFormatters do. See the section on MessageConverters for more details.

On the receiving side we would like to consume the messages transactionally from the queue. Since no other database operations are being performed in our server side processing, we select the TransactionMessageListenerContainer and configure it to use the MessageQueueTransactionManager. The MessageQueueTransactionManager an implementation of Spring's IPlatformTransactionManager abstraction that provides a uniform API on top of various transaction manager (ADO.NET,NHibernate, MSMQ, etc). Spring's MessageQueueTransactionManager is responsible for createing, committing, and rolling back a MSMQ MessageQueueTransaction.

While you can create the message listener container programmatically, we will show the declarative configuration approach below

  <!-- Queue to receive from -->
  <object id='questionTxQueue' type='Spring.Messaging.Support.MessageQueueFactoryObject, Spring.Messaging'>
    <property name='Path' value='.\Private$\questionTxQueue'/>
    <property name='MessageReadPropertyFilterSetAll' value='true'/>
  </object>

  <!-- MSMQ Transaction Manager -->
  <object id="messageQueueTransactionManager" type="Spring.Messaging.Core.MessageQueueTransactionManager, Spring.Messaging"/>

  <!-- Message Listener Container that uses MSMQ transactional for receives -->
  <object id="transactionalMessageListenerContainer" type="Spring.Messaging.Listener.TransactionalMessageListenerContainer, Spring.Messaging">
    <property name="MessageQueueObjectName" value="questionTxQueue"/>
    <property name="PlatformTransactionManager" ref="messageQueueTransactionManager"/>
    <property name="MaxConcurrentListeners" value="10"/>
    <property name="MessageListener" ref="messageListenerAdapter"/>
  </object>
 
  <!-- Adapter to call a POCO as a messaging callback -->
  <object id="messageListenerAdapter" type="Spring.Messaging.Listener.MessageListenerAdapter, Spring.Messaging">
    <property name="HandlerObject" ref="questionHandler"/>
  </object>

  <!-- The POCO class that you write -->
  <object id="questionHandler" type="MyNamespace.QuestionHandler, MyAssembly"/>
  

We have specified the queue to listen, that we want to consume the messages transactionally, process messages from the queue using 10 threads, and that our plain object that will handle the business processing is of the type QuestionHandler. The only class you need to write, QuestionHandler, looks like

public class QuestionHandler : IQuestionHandler
{
  public void HandleObject(string question)
  {
     // perform message processing here

     Console.WriteLine("Received question: " + question);

     // use an instance of MessageQueueTemplate and have other MSQM send operations
     // partake in the same local message transaction used to receive
  }

}

That is general idea. You write the sender class using MessageQueueTemplate and the consumer class which does not refer to any messaging specific class. The rest is configuration of Spring provided helper classes.

Note that if the HandleObject method has returned a string value a reply message would be sent to a response queue. The response queue would be taken from the Message's own ResponseQueue property or can be specified explicitly using MessageListenerAdapter's DefaultResponseQueueName property.

If an exception is thrown inside the QuestionHandler, then the MSMQ transaction is rolled back, putting the message back on the queue for redelivery. If the exception is not due to a transient error in the system, but a logical processing exception, then one would get endless redelivery of the message - clearly not a desirable situation. These messages are so called 'poison messages' and a strategy needs to be developed to deal with them. This is left as a development task if you when using the System.Messaging APIs but Spring provides a strategy for handling poison messages, both for DTC based message reception as well as for local messaging transactions.

In the last part this 'quick tour' we will configure the message listener container to handle poison messages. This is done by creating an instance of SendToQueueExceptionHandler and setting the property MaxRetry to be the number of exceptions or retry attempts we are willing to tolerate before taking corrective actions. In this case, the corrective action is to send the message to another queue. We can then create other message listener containers to read from those queues and handle the messages appropriately or perhaps you will avoid automated processing of these messages and take manual corrective actions.

  <!-- The 'error' queue to send poison messages -->
  <object id='errorQuestionTxQueue' type='Spring.Messaging.Support.MessageQueueFactoryObject, Spring.Messaging'>
    <property name='Path' value='.\Private$\errorQuestionTxQueue'/>
    <property name='MessageReadPropertyFilterSetAll' value='true'/>
  </object>

  <!-- Message Listener Container that uses MSMQ transactional for receives -->
  <object id="transactionalMessageListenerContainer" type="Spring.Messaging.Listener.TransactionalMessageListenerContainer, Spring.Messaging">

    <!-- as before but adding -->
    <property name="MessageTransactionExceptionHandler" ref="messageTransactionExceptionHandler"/>
  </object>

  <!-- Poison message handling policy -->
  <object id="messageTransactionExceptionHandler" type="Spring.Messaging.Listener.SendToQueueExceptionHandler, Spring.Messaging">
    <property name="MaxRetry" value="5"/>
    <property name="MessageQueueObjectName" value="errorQuestionTxQueue"/>
  </object>

In the event of an exception while processing the message, the message transaction will be rolled back (putting the message back on the queue questionTxQueue for redelivery). If the same message causes an exception in processing 5 times ,then it will be sent transactionally to the errorQuestionTxQueue and the message transaction will commit (removing it from the queue questionTxQueue). You can also specify that certain exceptions should commit the transaction (remove from the queue) but this is not shown here ,see below for more informatio non this functionality The SendToQueueExceptionHandler implements the interface IMessageTransactionExceptionHandler (discussed below) so you can write your own implementations should the provided ones not meet your needs.

That's the quick tour folks. Hopefully you got a general feel for how things work, what requires configuration, and what is the code you need to write. The following sections describe each of Spring's helper classes in more detail. The sample application that ships with Spring is also a good place to get started.

The goals of Spring's MSMQ messaging support are quite similar to those of WCF with its MSMQ related bindings, in as much as a WCF service contract is a POCO (minus the attributes if you really picky about what you call a POCO). Spring's messaging support can give you the programming convenience of dealing with POCO contracts for message receiving but does not (at the moment) provide a similar POCO contract for sending, instead relying on explicit use of the MessageQueueTemplate class. This feature exists - some question whether it should for messaging - in the Java version of the Spring framework, see JmsInvokerServiceExporter and JmsInvokerProxyFactoryBean.

The good news is that if and when it comes time to move from a Spring MSMQ solution to WCF, you will be in a great position as the POCO interface used for business processing when receiving in a Spring based MSMQ application can easily be adapted to a WCF environment. There may also be some features unique to MSMQ and/or Spring's MSMQ support that you may find appealing over WCF. Many messaging applications still need to be 'closer to the metal' and this is not possible using the WCF bindings, for example Peeking and Label, AppSpecific properties, multicast.. An interesting recent quote by Yoel Arnon (MSMQ guru) "With all the respect to WCF, System.Messaging is still the major programming model for MSMQ programmers, and is probably going to remain significant for the foreseeable future. The message-oriented programming model is different from the service-oriented model of WCF, and many real-world solutions would always prefer it."