Spring.Messaging A implementation that caches MessageQueue and IMessageConverter instances. The MessageQueue objects are created by retrieving them by-name from the ApplicationContext. Mark Pollack An interface for creating MessageQueue and IMessageConverter objects from object definitions defined in the application context. MessageQueue and IMessageConverter objects have methods that are generally not thread safe, (IMessageConverter classes rely on IMessageFormatter objects that are not thread safe). As such, a major reason to for this interface is to provide thread-local instances such that appliation code need not be concerned with these resource management issues. Mark Pollack Registers the message queue, its creation specified via the factory method MessageQueueCreatorDelegate, with the provided name in the application context Name of the message queue object. The message queue creator delegate. Creates the message queue given its name in the application context. Name of the message queue object. A MessageQueue instance configured via the application context Determines whether the application context contains the message queue object definition. Name of the message queue object. true if the application context contains the specified message queue object name; otherwise, false. Registers the message converter, its creation specified via the factory method MessageConverterCreatorDelegate, with the provided name in the application context. Name of the message converter. The message converter creator delegate. Creates the message converter given its name in the application context. Name of the message converter object. A IMessageConverter instance configured via the application context Determines whether the application context contains the message queue object definition. Name of the message converter object. true if the application context contains the specified message message converter object name; otherwise, false. The instance for this class. Registers the message queue, its creation specified via the factory method MessageQueueCreatorDelegate, with the provided name in the application context Name of the message queue object. The message queue creator delegate. Creates the message queue given its name in the application context. Name of the message queue object. A MessageQueue instance configured via the application context Determines whether the application context contains the message queue object definition. Name of the message queue object. true if the application context contains the specified message queue object name; otherwise, false. Registers the message converter. Name of the message converter. The message converter creator delegate. Creates the message converter given its name in the application context. Name of the message converter object. A IMessageConverter instance configured via the application context Determines whether the application context contains the message queue object definition. Name of the message converter object. true if the application context contains the specified message message converter object name; otherwise, false. Gets or sets the that this object runs in.

Normally this call will be used to initialize the object.

Invoked after population of normal object properties but before an init callback such as 's or a custom init-method. Invoked after the setting of any 's property.

In the case of application context initialization errors. If thrown by any application context methods. Specifies a basic set of helper MSMQ opertions. Implemented by . Not often used but a useful option to enhance testability, as it can easily be mocked or stubbed. Provides MessageQueueTemplate's Send(..) and receive(..) methods that mirror various MSMQ MessageQueue API methods. Mark Pollack Send the given object to the default destination, converting the object to a MSMQ message with a configured IMessageConverter. This will only work with a default destination queue specified! The obj. Send the given object to the default destination, converting the object to a MSMQ message with a configured IMessageConverter. The IMessagePostProcessor callback allows for modification of the message after conversion.

This will only work with a default destination specified!

 the object to convert to a message the callback to modify the message if thrown by MSMQ API methods Send the given object to the specified destination, converting the object to a MSMQ message with a configured and resolving the destination name to a using a the name of the destination queue to send this message to (to be resolved to an actual MessageQueue by a IMessageQueueFactory) the object to convert to a message NMSException if there is any problem Send the given object to the specified destination, converting the object to a MSMQ message with a configured and resolving the destination name to a with an The callback allows for modification of the message after conversion. the name of the destination queue to send this message to (to be resolved to an actual MessageQueue by a IMessageQueueFactory) the object to convert to a message the callback to modify the message if thrown by MSMQ API methods Receive and convert a message synchronously from the default message queue. The converted object if thrown by MSMQ API methods. Note an exception will be thrown if the timeout of the syncrhonous recieve operation expires. Receives and convert a message synchronously from the specified message queue. Name of the message queue object. the converted object if thrown by MSMQ API methods. Note an exception will be thrown if the timeout of the syncrhonous recieve operation expires. Receives a message on the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. A message. Receives a message on the specified queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. Name of the message queue object. Sends the specified message to the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. The message to send Sends the specified message to the message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. Name of the message queue object. The message. Sends the specified message on the provided MessageQueue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. Note that it is the callers responsibility to ensure that the MessageQueue instance passed into this not being access simultaneously by other threads. A transactional send (either local or DTC transaction) will be attempted for a transacitonal queue, falling back to a single-transaction send to a transactional queue if there is not ambient Spring managed transaction. The DefaultMessageQueue to send a message to. The message to send MessageQueueResourceHolder marker subclass that indicates local exposure, i.e. that does not indicate an externally managed transaction. Mark Pollack MessageQueue resource holder, wrapping a MessageQueueTransaction. MessageQueueTransactionManager binds instances of this class to the thread. This is an SPI class, not intended to be used by applications. Mark Pollack Initializes a new instance of the class. The message queue transaction. Gets or sets the message queue transaction. The message queue transaction. Initializes a new instance of the class. The message queue transaction. To be used with MessageQueueTemplate's send method that convert an object to a message. It allows for further modification of the message after it has been processed by the converter. This is useful for setting of Message properties (e.g. CorrelationId, AppSpecific, TimeToReachQueue). Mark Pollack Convenient super class for application classes that need MSMQ access. Override the InitGateway method to perform custom startup tasks. Mark Pollack Subclasses can override this for custom initialization behavior. Gets called after population of this instance's properties. Gets or sets the message queue template. . The message queue template. Gets the message queue factory, a convenience method. The message queue factory. Encapsulates additional metadata information about the MessageQueue that can not be easily obtained from the MessageQueue itself. Initializes a new instance of the class. if set to true [remote queue]. if set to true [remote queue is transactional]. Gets or sets a value indicating whether the queue is a remote queue. The operations that one can perform on the MessageQueue depend on if it is local or remote, for example checking if it is transactional. This is very difficult to determine programmatically. The property was made virtual so it can be overridden to take into account custom heuristics you may want to use to determine this programmatically. true if remote queue; otherwise, false. Gets or sets a value indicating whether the remote queue is transactional. true if the remote queue is transactional; otherwise, false. Retrieves MessageQueueMetadata from the cache. The queue path. Item for the specified , or null. Removes the specified queue path from the cache The queue path. Removes collection of MessageQueueMetaCache from the cache. Array of MessageQueue paths to remove. Removes all MessageQueueMetadata from the cache. Gets the number of items in the cache. Gets a collection of all cache queue paths. Helper class that simplifies MSMQ access code. Using the System.Messaging.MessageQueue class directly in application code has a number of shortcomings, namely that most operations are not thread safe (in particular Send) and IMessageFormatter classes are not thread safe either. The MessageQueueTemplate class overcomes these limitations letting you use a single instance of MessageQueueTemplate across multiple threads to perform standard MessageQueue opertations. Classes that are not thread safe are obtained and cached in thread local storage via an implementation of the interface, specifically . You can access the thread local instance of the MessageQueue associated with this template via the Property DefaultMessageQueue. The template's Send methods will select an appropriate transaction delivery settings so calling code does not need to explicitly manage this responsibility themselves and thus allowing for greater portability of code across different, but common, transactional usage scenarios. A transactional send (either local or DTC transaction) will be attempted for a transacitonal queue, falling back to a single-transaction send to a transactional queue if there is not ambient Spring managed transaction. The overloaded ConvertAndSend and ReceiveAndConvert methods inherit the transactional semantics of the previously described Send method but more importantly, they help to ensure that thread safe access to instances are used as well as providing additional central location to put programmic logic that translates between the MSMQ Message object and the your business objects. This for example is useful if you need to perform additional translation operations after calling a IMessageFormatter instance or want to directly extract and process the Message body contents. Initializes a new instance of the class. Initializes a new instance of the class. Name of the message queue as registered in the Spring container. Invoked by an after it has injected all of an object's dependencies. Ensure that the DefaultMessageQueueObjectName property is set, creates a default implementation of the interface () that retrieves instances on a per-thread basis, and registers in the Spring container a default implementation of () with a simple System.String as its TargetType. Send the given object to the default destination, converting the object to a MSMQ message with a configured IMessageConverter. The obj. This will only work with a default destination queue specified! Send the given object to the default destination, converting the object to a MSMQ message with a configured IMessageConverter. The IMessagePostProcessor callback allows for modification of the message after conversion.

This will only work with a default destination specified!

 the object to convert to a message the callback to modify the message if thrown by MSMQ API methods Send the given object to the specified destination, converting the object to a MSMQ message with a configured and resolving the destination name to a using a the name of the destination queue to send this message to (to be resolved to an actual MessageQueue by a IMessageQueueFactory) the object to convert to a message NMSException if there is any problem Send the given object to the specified destination, converting the object to a MSMQ message with a configured and resolving the destination name to a with an The callback allows for modification of the message after conversion. the name of the destination queue to send this message to (to be resolved to an actual MessageQueue by a IMessageQueueFactory) the object to convert to a message the callback to modify the message if thrown by MSMQ API methods Receive and convert a message synchronously from the default message queue. The converted object if thrown by MSMQ API methods. Note an exception will be thrown if the timeout of the syncrhonous recieve operation expires. Receives and convert a message synchronously from the specified message queue. Name of the message queue object. the converted object if thrown by MSMQ API methods. Note an exception will be thrown if the timeout of the syncrhonous recieve operation expires. Receives a message on the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. A message. Receives a message on the specified queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. Name of the message queue object. Sends the specified message to the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. The message to send Sends the specified message to the message queue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. Name of the message queue object. The message. Sends the specified message on the provided MessageQueue using the transactional settings as dicted by MessageQueue's Transactional property and the current Spring managed ambient transaction. The DefaultMessageQueue to send a message to. The message to send Note that it is the callers responsibility to ensure that the MessageQueue instance passed into this not being access simultaneously by other threads. A transactional send (either local or DTC transaction) will be attempted for a transacitonal queue, falling back to a single-transaction send to a transactional queue if there is not ambient Spring managed transaction. Sends the message to the given message queue. If System.Transactions.Transaction.Current is null, then send based on the transaction semantics of the queue definition. See The message queue. The message. Send the message queue selecting the appropriate transactional delivery options. If the message queue is transactional and there is an ambient MessageQueueTransaction in thread local storage (put there via the use of Spring's MessageQueueTransactionManager or TransactionalMessageListenerContainer), the message will be sent transactionally using the MessageQueueTransaction object in thread local storage. This lets you group together multiple messaging operations within the same transaction without having to explicitly pass around the MessageQueueTransaction object. If the message queue is transactional but there is no ambient MessageQueueTransaction, then a single message transaction is created on each messaging operation. (MessageQueueTransactionType = Single). If there is an ambient System.Transactions transaction then that transaction will be used (MessageQueueTransactionType = Automatic). If the queue is not transactional, then a non-transactional send (MessageQueueTransactionType = None) is used. The mq. The MSG. Does the send message transaction. The mq. The transaction to use. The MSG. Does the send message queue non transactional. The mq. The transaction to use. The MSG. Sends using MessageQueueTransactionType.Automatic transaction type The message queue. The message. Template method to convert the message if it is not null. The message. The converted message ,or null if no message converter is set. Checks if the default message queue if defined. Gets or sets the message queue factory to use for creating MessageQueue and IMessageConverters. Default value is one that support thread local instances. The message queue factory. Gets or sets the name of the default message queue as identified in the Spring container. The name of the message queue as identified in the Spring container. Gets or sets the name of the message converter object. The name will be passed to the class to resolve it to an actual MessageQueue instance. The default name is internally generated and will register an XmlMessageConverter that uses an and a simple System.String as its TargetType. The name of the message converter object. Gets the default message queue to be used on send/receive operations that do not have a destination parameter. The MessageQueue instance is resolved using the template's , the default implementaion will return an unique instance per thread. The default message queue. Gets the message converter to use for this template. Used to resolve object parameters to ConvertAndSend methods and object results from ReceiveAndConvert methods. The default The message converter. Gets or sets the receive timeout to be used on recieve operations. Default value is MessageQueue.InfiniteTimeout (which is actually ~3 months). The receive timeout. Gets or sets the metadata cache. The metadata cache. Gets or sets the that this object runs in.

Normally this call will be used to initialize the object.

Invoked after population of normal object properties but before an init callback such as 's or a custom init-method. Invoked after the setting of any 's property.

In the case of application context initialization errors. If thrown by any application context methods. implementation for MSMQ. Binds a MessageQueueTransaction to the thread. This local strategy is an alternative to executing MSMQ operations within DTC transactions. Its advantage is that multiple MSMQ operations can easily participate within the same local MessagingTransaction transparently when using the class for send and recieve operations and not pay the overhead of a DTC transaction. Transaction synchronization is turned off by default, as this manager might be used alongside a IDbProvider-based Spring transaction manager such as the ADO.NET . which has stronger needs for synchronization. Mark Pollack Location where the message transaction is stored in thread local storage. Initializes a new instance of the class. Turns off transaction synchronization by default, as this manager might be used alongside a DbProvider-based Spring transaction manager like AdoPlatformTransactionManager, which has stronger needs for synchronization. Only one manager is allowed to drive synchronization at any point of time. Return the current transaction object. The current transaction object. If transaction support is not available. In the case of lookup or system errors. Check if the given transaction object indicates an existing transaction (that is, a transaction which has already started). MessageQueueTransactionObject object returned by . True if there is an existing transaction. Begin a new transaction with the given transaction definition. Transaction object returned by . instance, describing propagation behavior, isolation level, timeout etc. In the case of creation or system errors. Suspend the resources of the current transaction. Transaction object returned by . An object that holds suspended resources (will be kept unexamined for passing it into .) Resume the resources of the current transaction. Transaction object returned by . The object that holds suspended resources as returned by . Perform an actual commit on the given transaction. The status representation of the transaction.

An implementation does not need to check the rollback-only flag.

Perform an actual rollback on the given transaction, calls Transaction.Abort(). The status representation of the transaction. An implementation does not need to check the new transaction flag. Set the given transaction rollback-only. Only called on rollback if the current transaction takes part in an existing one. The status representation of the transaction. Default implementation throws an IllegalTransactionStateException, assuming that participating in existing transactions is generally not supported. Subclasses are of course encouraged to provide such support. In the case of system errors. Cleanup resources after transaction completion. Transaction object returned by . Called after and execution on any outcome. Utility methods to support Spring's MSMQ functionality Registers the default message converter with the application context. The application context. The name of the message converter to use for lookups with . Gets the message queue transaction from thread local storage The resource factory. null if not found in thread local storage Callback interface for resource creation. Serving as argument for the GetMessageQueueTransaction method. Return whether to allow for a local transaction that is synchronized with a Spring-managed transaction (where the main transaction might be a ADO.NET-based one for a specific IDbProvider, for example), with the MSMQ transaction committing right after the main transaction. Returns whether to allow for synchronizing a local MSMQ transaction Provides basic lifecyle management methods for implementing a message listener container. This base class does not assume any specific listener programming model or listener invoker mechanism. It just provides the general runtime lifecycle management needed for any kind of message-based listening mechanism. For a concrete listener programming model, check out the subclass. For a concrete listener invoker mechanism, check out the , , or classes. Mark Pollack Delegates to and Calls when the application context destroys the container instance. Validates the configuration of this container The default implementation is empty. To be overridden in subclasses. Initializes this container. Calls the abstract method to initialize the listening infrastructure (i.e. subclasses will typically resolve a MessageQueue instance from a MessageQueueObjectName) and then calls the abstract method DoStart if the property is set to true, Sets the container state to inactive and not running, calls template method Starts this container. Sets the state to running, can be overridden in subclasses. Stops this instance. Template method suitable for overriding that stops the container. Check whether this container's listeners are generally allowed to run. This implementation always returns true; the default 'running' state is purely determined by and Subclasses may override this method to check against temporary conditions that prevent listeners from actually running. In other words, they may apply further restrictions to the 'running' state, returning false if such a restriction prevents listeners from running. false if such a restriction prevents listeners from running. Subclasses need to implement this method for their specific listener management process. Subclasses need to implement this method for their specific listener management process. Sets a value indicating whether to automatically start the container after initialization. Default is "true"; set this to "false" to allow for manual startup though the method. true if autostartup; otherwise, false. Gets a value indicating whether this Container is active, that is, whether it has been set up but not shut down yet. true if active; otherwise, false. Gets a value indicating whether this Container is running, that is whether it has been started and not stopped yet. true if running; otherwise, false. Return the object name that this listener container has been assigned in its containing object factory, if any. Defines a minimal programming model for message listener containers. They are expected to invoke a upon asynchronous receives of a MSMQ message. Access to obtain MessageQueue and instances is available through the property, the default implementation provides per-thread instances of these classes. Mark Pollack Most operations within the MessageListener container hierarchy use methods on the MessageQueue instance which are thread safe (BeginPeek, BeginReceive, EndPeek, EndReceive, GetAllMessages, Peek, and Receive). When using another method on the shared MessageQueue instance, wrap calls with a lock on this object. Validates that the is not null. If is null, a is created. Can be be overridden in subclasses. Template method that execute listener with the provided message if is true. Subclasses will call this method at the appropriate point in their processing lifecycle, for example committing or rolling back a transaction if needed. Calls the template method The message. Invokes the listener if it is not null. Invokes the method . Can be overridden in subclasses. The message. Invokes the listener. Can be overriden in subclasses. The listener. The message. Closes the queue handle. Cancel pending receive operation by closing the queue handle To properly dispose of the queue handle, ensure that EnableConnectionCache=false on the MessageQueue that this listener is configured to use. Gets or sets the message queue factory. The message queue factory. Gets or sets the name of the message queue object, as refered to in the Spring configuration, that will be used to create a DefaultMessageQueue instance for consuming messages in the container. The name of the message queue object. Gets or sets the message listener. The message listener. Gets or sets the recovery time span, how long to sleep after an exception in processing occured to avoid excessive redelivery attempts. Default value is 1 second. The recovery time span. Gets or sets the that this object runs in.

Normally this call will be used to initialize the object.

Invoked after population of normal object properties but before an init callback such as 's or a custom init-method. Invoked after the setting of any 's property.

In the case of application context initialization errors. If thrown by any application context methods. Base class for listener container implementations which are based on Peeking for messages on a MessageQueue. Peeking is the only resource efficient approach that can be used in order to have MessageQueue receipt in conjunction with transactions, either local MSMQ transactions, local ADO.NET based transactions, or DTC transactions. See SimpleMessageListenerContainer for an implementation based on a synchronous receives and you do not require transactional support. The number of threads that will be created for processing messages after the Peek occurs is set via the property MaxConcurrentListeners. Each processing thread will continue to listen for messages up until the the timeout value specified by ListenerTimeLimit or until there are no more messages on the queue (which ver comes first). The default value of ListenerTimeLimit is TimeSpan.Zero, meaning that only one attempt to recieve a message from the queue will be performed by each listener thread. The current implementation uses the standard .NET thread pool. Future implementations will use a custom (and pluggable) thread pool. Retrieves a MessageQueue instance given the MessageQueueObjectName Wait for all listener threads to exit and closes the DefaultMessageQueue. Starts peeking on the DefaultMessageQueue. Stops peeking on the message queue. Starts peeking on the DefaultMessageQueue. This is the method that must be called again at the end of message procesing to continue the peeking process. The callback when the peek has completed. Schedule up to the maximum number of concurrent listeners to receive messages off the queue. Delegates to the abstract method DoReceiveAndExecute so that subclasses may customize the receiving process, for example to surround the receive operation with transactional semantics. The async result. Execute the listener for a message received from the given queue wrapping the entire operation in an external transaction if demanded. The DefaultMessageQueue upon which the call to receive should be called. Subclasses perform a receive opertion on the message queue and execute the message listener The DefaultMessageQueue. true if received a message, false otherwise Waits for listener threads to exit. Configures the initial peek thread, setting it to be a background thread. Can be overridden in subclasses. The peek thread. Template method that gets called right when a new message has been received, before attempting to process it. Allows subclasses to react to the event of an actual incoming message, for example adapting their consumer count. The message. Template method that gets called right before a new message is received, i.e. messageQueue.Receive(). It allows subclasses to modify the state of the MessageQueue before receiving which maybe required when using remote queues Gets or sets the listener time limit to continuously receive messages. The value is specified in milliseconds. The default value is TimeSpan.Zero, indicating to only perform one Receive operation per Peek trigger. The listener time limit in millis. Gets or sets the max concurrent listeners to receive messages. The max concurrent listeners. Gets or sets the message queue used for Peeking. The message queue. Provides common functionality to exception handlers that will send the exceptional message to another queue. Allows for setting of MaxRetry limit and contains an internal dictionary to keep track of the Message Ids of messages. Mark Pollack Synchronization object for access to messageMap protected variable In-memory storage to keep track of Message Ids that have been already processed. Ensure that the MessageQueueObject name is set and creates a if no is specified. Will attempt to create an instance of the DefaultMessageQueue to detect early any configuraiton errors. In the event of misconfiguration (such as the failure to set a required property) or if initialization fails. Gets or sets the maximum retry count to reattempt processing of a message that has thrown an exception The max retry count. Gets or sets the message queue factory. The message queue factory. Gets or sets the name of the message queue object to send the message that cannot be processed successfully after MaxRetry delivery attempts. The name of the message queue object. Gets or sets the that this object runs in.

Normally this call will be used to initialize the object.

Invoked after population of normal object properties but before an init callback such as 's or a custom init-method. Invoked after the setting of any 's property.

In the case of application context initialization errors. If thrown by any application context methods. An implementation of a Peeking based MessageListener container that starts a transaction before recieving a message. The implementation determines the type of transaction that will be started. An exception while processing the message will result in a rollback, otherwise a transaction commit will be performed. The type of transaction that can be started can either be local transaction, (e.g. , a local messaging transaction (e.g. or a DTC based transaction, (eg. . Transaction properties can be set using the property and the transaction timeout via the property . Subclasses perform a receive opertion on the message queue and execute the message listener The DefaultMessageQueue. true if received a message, false otherwise Does the receive and execute using platform transaction manager. The message queue. The transactional status. true if should continue peeking, false otherwise. Rollback the transaction on exception. The transactional status. The exception. Gets or sets the platform transaction manager. The platform transaction manager. Gets or sets the transaction definition. The transaction definition. Sets the transaction timeout to use for transactional wrapping, in seconds. Default is none, using the transaction manager's default timeout. The transaction timeout. A MessageListenerContainer that uses distributed (DTC) based transactions. Exceptions are handled by instances of . Starts a DTC based transaction before receiving the message. The transaction is automaticaly promoted to 2PC to avoid the default behaivor of transactional promotion. Database and messaging operations will commit or rollback together. If you only want local message based transactions use the . With some simple programming you may also achieve 'exactly once' processing using the . Poison messages can be detected and sent to another queue using Spring's . Set the transaction name to be the spring object name. Call base class Initialize() functionality. Does the receive and execute using TxPlatformTransactionManager. Starts a distributed transaction before calling Receive. The message queue. The transactional status. true if should continue peeking, false otherwise. Handles the distributed transaction listener exception by calling the if not null. The exception. The message. Gets or sets the distributed transaction exception handler. The distributed transaction exception handler. Exception handler for use with DTC based message listener container. such as . See for an implementation that detects poison messages and send them to another queue. Determines whether the incoming message is a poison message. This method is called before the is invoked. The will call if this method returns true and will then commit the distibuted transaction (removing the message from the queue). The incoming message. true if it is a poison message; otherwise, false. Handles the poison message. Typical implementations will move the message to another queue. The will call this method while still within a DTC-based transaction. The poison message. Called when an exception is thrown in listener processing. The exception. The message. Exception handler called when an exception occurs during non-transactional receive processing. A non-transactional receive will remove the message from the queue. Non-transactional receivers do not suffer from poison messages since there is no redelivery by MSMQ. Typical actions to perform are to log the message or place it in another queue. If placed in another queue, another message listener container can be used to process the message later, assuming the root cause of the original exception is transient in nature. Called when an exception is thrown in listener processing. The exception. The message. The callback invoked when a message is received. Mark Pollack Called when message is received. The message. The exception handler within a transactional context. The return value indicates to the invoker (typically a ) whether the MessageTransaction that is associated with the delivery of this message should be rolled back (placing the message back on the transactional queue for redelivery) or commited (removing the message from the transactional queue) Mark Pollack Called when an exception is thrown during listener processing under the scope of a . The exception. The message. The message queue transaction. An action indicating if the caller should commit or rollback the Exception to be thrown when the execution of a listener method failed. Juergen Hoeller Mark Pollack (.NET) Base exception class for exceptions thrown by Spring in Spring.Messaging Mark Pollack Creates a new instance of the MessagingException class. Creates a new instance of the MessagingException class. with the specified message. A message about the exception. Creates a new instance of the MessagingException class with the specified message and root cause. A message about the exception. The root exception that is being wrapped. Creates a new instance of the MessagingException class. The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class, with the specified message The message. Initializes a new instance of the class, with the specified message and root cause exception The message. The inner exception. Message listener adapter that delegates the handling of messages to target listener methods via reflection , with flexible message type conversion. Allows listener methods to operate on message content types, completely independent from the MSMQ API. By default, the content of incoming MSMQ messages gets extracted before being passed into the target handler method, to let the target method operate on message content types such as String or business object instead of . Message type conversion is delegated to a Spring By default, an with TargetType set to System.String is used. If you do not want such automatic message conversion taking place, then be sure to set the MessageConverter property to null. If a target handler method returns a non-null object (for example, with a message content type such as String), it will get wrapped in a MSMQ Message and sent to the response destination (either using the MSMQ Message.ResponseQueue property or ) specified default response queue destination). Find below some examples of method signatures compliant with this adapter class. This first example uses the default that can marhsall/unmarshall string values from the MSMQ Message. public interface IMyHandler { void HandleMessage(string text); } The next example indicates a similar method signature but the name of the handler method name has been changed to "DoWork", using the property public interface IMyHandler { void DoWork(string text); } If your implementation will return multiple object types, overloading the handler method is perfectly acceptible, the most specific matching method will be used. A method with an object signature would be consider a 'catch-all' method public interface IMyHandler { void DoWork(string text); void DoWork(OrderRequest orderRequest); void DoWork(InvoiceRequest invoiceRequest); void DoWork(object obj); } The last example shows how to send a message to the ResponseQueue for those methods that do not return void. public interface MyHandler { string DoWork(string text); OrderResponse DoWork(OrderRequest orderRequest); InvoiceResponse DoWork(InvoiceRequest invoiceRequest); void DoWork(object obj); } Mark Pollack Out-of-the-box value for the default listener method: "HandleMessage" Initializes a new instance of the class. Initializes a new instance of the class. The handler object. Invoked by an after it has injected all of an object's dependencies.

This method allows the object instance to perform the kind of initialization only possible when all of it's dependencies have been injected (set), and to throw an appropriate exception in the event of misconfiguration.

Please do consult the class level documentation for the interface for a description of exactly when this method is invoked. In particular, it is worth noting that the and callbacks will have been invoked prior to this method being called.

In the event of misconfiguration (such as the failure to set a required property) or if initialization fails. Called when message is received. The message. Gets the name of the handler method. The original message. The extracted message. The name of the handler method. Builds an array of arguments to be passed into the taret listener method. Allows for multiple method arguments to be built from a single message object.

The default implementation builds an array with the given message object as sole element. This means that the extracted message will always be passed into a single method argument, even if it is an array, with the target method having a corresponding single argument of the array's type declared.

This can be overridden to treat special message content such as arrays differently, for example passing in each element of the message array as distinct method argument.

 The converted message. the array of arguments to be passed into the listener method (each element of the array corresponding to a distinct method argument) Invokes the specified listener method. This default implementation can only handle invoking a single argument method. Name of the listener method. The arguments to be passed in. Only the first argument in the list is currently supported in this implementation. The result returned from the listener method Initialize the default implementations for the adapter's strategies. Extracts the message body from the given message. The message. the content of the message, to be passed into the listener method as argument Sends the given response message to the given destination. The destination to send to. The outgoing message about to be sent. Builds a MSMQ message to be sent as response based on the given result object. The result. the MSMQ Message (never null) If no messgae converter is specified. Post-process the given response message before it will be sent. The default implementation sets the response's correlation id to the request message's correlation id. The original incoming message. The outgoing MSMQ message about to be sent. Determine a response destination for the given message. The default implementation first checks the MSMQ ResponseQueue of the supplied request; if that is not null it is returned; if it is null, then the configured default response destination} is returned; if this too is null, then an is thrown. The request. The response. Gets or sets the handler object to delegate message listening to. Specified listener methods have to be present on this target object. If no explicit handler object has been specified, listener methods are expected to present on this adapter instance, that is, on a custom subclass of this adapter, defining listener methods. The handler object. Gets or sets the default handler method to delegate to, for the case where no specific listener method has been determined. Out-of-the-box value is "HandleMessage". The default handler method. Gets or sets the processing expression for use in custom subclasses The processing expression. Gets or sets the that this object runs in.

Normally this call will be used to initialize the object.

Invoked after population of normal object properties but before an init callback such as 's or a custom init-method. Invoked after the setting of any 's property.

In the case of application context initialization errors. If thrown by any application context methods. Gets or sets the message queue factory. The message queue factory. Sets the name of the default response queue to send response messages to. This will be applied in case of a request message that does not carry a "ResponseQueue" value. Alternatively, specify a response queue via the property . The name of the default response destination queue. Sets the default destination to send response messages to. This will be applied in case of a request message that does not carry a "ResponseQueue" property Response destinations are only relevant for listener methods that return result objects, which will be wrapped in a response message and sent to a response destination. Alternatively, specify a "DefaultResponseQueueName" to be dynamically resolved via the MessageQueueFactory. The default response destination. Gets or sets the name of the message converter object used to resolved a instance. The name of the message converter object. Gets message converter that will convert incoming MSMQ messages to listener method arguments, and objects returned from listener methods back to MSMQ messages. The converter used is the one returned by CreateMessageConverter on MessageQueueFactory. The message converter. Sets the message queue template. If not set, will create one for it own internal use whne MessageListenerAdapter is constructed. It maybe useful to share an existing instance if you have an extensively configured MessageQueueTemplate. The message queue template. An implementation of a Peeking based MessageListener container that does not surround the receive operation with a transaction. Exceptions that occur during message processing are handled by an instance of . Mark Pollack Handles the listener exception. The exception. The message delivered that resultd in an processing exception. Perform a receive opertion on the message queue and execute the message listener The MessageQueue. true if received a message, false otherwise Gets or sets the exception handler. The exception handler. detects poison messages by tracking the Message Id property in memory with a count of how many times an exception has occurred. If that count is greater than the handler's MaxRetry count it will be sent to another queue. The queue to send the message to is specified via the property M essageQueueObjectName. Exception handler when using DistributedTxMessageListenerContainer Determines whether the incoming message is a poison message. This method is called before the is invoked. The incoming message. true if it is a poison message; otherwise, false. The will call if this method returns true and will then commit the distibuted transaction (removing the message from the queue). Handles the poison message. The message. Called when an exception is thrown in listener processing. The exception. The message. Sends the message to queue. The message. Keeps track of the Message's Id property in memory with a count of how many times an exception has occurred. If that count is greater than the handler's MaxRetry count it will be sent to another queue using the provided MessageQueueTransaction. The queue to send the message to is specified via the property MessageQueueObjectName. Called when an exception is thrown during listener processing under the scope of a . The exception. The message. The message queue transaction. An action indicating if the caller should commit or rollback the Determines whether this exception was already processed. The exception. true if the exception was already processed; otherwise, false. Sends the message to queue. The message. The message queue transaction. TransactionAction.Commit Template method called before the message that caused the exception is send to another queue. The default behavior is to set the CorrelationId to the current message's Id value for tracking purposes. Subclasses can use other means, perhaps using the AppSpecific field or modifying the body of the message to a known shared format that keeps track of the full 'lifecycle' of the message as it goes from queue-to-queue. The message. Gets or sets the exception anmes that indicate the message has already been processed. If the exception thrown matches one of these names then the returned TransactionAction is Commit to remove it from the queue. The name test is thrownException.GetType().Name.IndexOf(exceptionName) >= 0 The message already processed exception types. Action to perform on the MessageQueueTransaction when handling message listener exceptions. Rollback the MessageQueueTransaction, returning the recieved message back onto the queue. Commit the MessageQueueTransaction, removing the message from the queue. A MessageListenerContainer that uses local (non-DTC) based transactions. Exceptions are handled by instances of . This container distinguishes between two types of implementations. If you specify a then a MSMQ will be started before receiving the message and used as part of the container's recieve operation. The binds the to thread local storage and as such will implicitly be used by send and receive operations to a transactional queue. Service layer operations that are called inside the message listener will typically be transactional based on using standard Spring declarative transaction management functionality. In case of exceptions in the service layer, the database operation will have been rolled back and the that is later invoked should decide to either commit the surrounding local MSMQ based transaction (removing the message from the queue) or to rollback (placing the message back on the queue for redelivery). The use of a transactional service layer in combination with a container managed is a powerful combination that can be used to achieve "exactly one" transaction message processing with database operations that are commonly associated with using transactional messaging and distributed transactions (i.e. both the messaging and database operation commit or rollback together). The additional programming logic needed to achieve this is to keep track of the Message.Id that has been processed successfully within the transactional service layer. This is needed as there may be a system failure (e.g. power goes off) between the 'inner' database commit and the 'outer' messaging commit, resulting in message redelivery. The transactional service layer needs logic to detect if incoming message was processed successfully. It can do this by checking the database for an indication of successfull processing, perhaps by recording the Message.Id itself in a status table. If the transactional service layer determines that the message has already been processed, it can throw a specific exception for thise case. The container's exception handler will recognize this exception type and vote to commit (remove from the queue) the 'outer' messaging transaction. Spring provides an exception handler with this functionality, see for more information. If you specify an implementation of (e.g. or HibernateTransactionManager) then an local database transaction will be started before receiving the message. By default, the container will also start a local after the local database transaction has started, but before the receiving the message. The will be used to receive the message. If you do not want his behavior set to false. Also by default, the will be bound to thread local storage such that any send or recieve operations will participate transparently in the same . If you do not want this behavior set the property to false. In case of exceptions during processing when using an implementation of (e.g. and starting a container managed ) the container's will determine if the should commit (removing it from the queue) or rollback (placing it back on the queue for redelivery). The listener exception will always trigger a rollback in the 'outer' (e.g. or HibernateTransactionManager) based transaction. PoisonMessage handing, that is endless redelivery of a message due to exceptions during processing, can be detected using implementatons of the interface. A specific implementation is provided that will move the poison message to another queue after a maximum number of redelivery attempts. See for more information. Determine if the container should create its own MessageQueueTransaction when a IResourceTransactionManager is specified. Set the transaction name to the name of the spring object. Call base class Initialize() funtionality Does the receive and execute using platform transaction manager. The message queue. The transactional status. true if should continue peeking, false otherwise. Does the recieve and execute using message queue transaction manager. The message queue. The transactional status. true if should continue peeking, false otherise Does the recieve and execute using a local MessageQueueTransaction. The mqessage queue. The transactional status. true if should continue peeking, false otherwise. Handles the transactional listener exception. The exception thrown while processing the message. The message. The message queue transaction. The TransactionAction retruned by the TransactionalExceptionListener Invokes the transactional exception listener. The exception thrown during message processing. The message. The message queue transaction. TransactionAction.Rollback if no exception handler is defined, otherwise the TransactionAction returned by the exception handler Gets or sets a value indicating whether the MessageListenerContainer should be responsible for creating a MessageQueueTransaction when receiving a message. Creating MessageQueueTransactions is usually the responsibility of the IPlatformTransactionManager, e.g. TxScopePlatformTransactionManager (when using DTC) or MessageQueueTransactionManager (when using local messaging transactions). For all other IPlatformTransactionManager implementations, including when none is specified, the MessageListenerContainer will itself create a MessageQueueTransaction (assuming the container is consuming from a transactional queue). Set the ExposeContainerManagedMessageQueueTransaction property to true if you want the MessageQueueTransaction to be exposed to Spring's MessageQueueTemplate class true to use a container managed MessageQueueTransaction; otherwise, false. Gets or sets a value indicating whether expose the container managed to thread local storage where it will be automatically used by send and receive operations. Using an will always exposes a to thread local storage. This property only has effect when using a non-DTC based true if [expose container managed message queue transaction]; otherwise, false. Gets or sets the message transaction exception handler. The message transaction exception handler. An implementation that delegates to an instance of to convert messages. Mark Pollack An interface specifying the contract to convert to and from objects. Convert the given object to a Message. The object to send. Message to send Convert the given message to a object. The message. the object Initializes a new instance of the class. Initializes a new instance of the class. The message formatter. Convert the given object to a Message. The object to send. Message to send Convert the given message to a object. The message. the object Creates a new object that is a copy of the current instance. A new object that is a copy of this instance. An implementation that delegates to an instance of to convert messages. Mark Pollack Initializes a new instance of the class. Initializes a new instance of the class. The binary message formatter. Convert the given object to a Message using the The object to send. Message to send Convert the given message to a object using the The message. the object Creates a new object that is a copy of the current instance. A new object that is a copy of this instance. Gets or sets the type format used in the The type format. Gets or sets the top object format used in the The top object format. Delegate for creating IMessageConverter instance. Used by to register a creation function with a given name. Internal class to that users can specify a delegate function to register with the application context that will create a IMessageConverter instance easily at runtime. Mark Pollack Gets the template object definition that should be used to configure the instance of the object managed by this factory. The object definition to configure the factory's product Converts an to a Message and vice-versa by using the message's body stream. Mark Pollack Convert the given object to a Message. The object to send. Message to send Convert the given message to a object. The message. the object Creates a new object that is a copy of the current instance. A new object that is a copy of this instance. An implementation that delegates to an instance of to convert messages. Mark Pollack Initializes a new instance of the class. Initializes a new instance of the class. The message formatter. Convert the given object to a Message. The object to send. Message to send Convert the given message to a object. The message. the object Creates a new object that is a copy of the current instance. A new object that is a copy of this instance. Gets or sets the target types used by the The target types. Gets or sets the target type names used by the The target type names. Delegate for creating MessageQueue instance. Used by to register a creation function with a given name. Factory for creating MessageQueues. This factory will create prototype instances, i.e. every call to GetObject will return a new MessageQueue object. All MessageQueue constructor arguments are exposed as properties of the factory object. As this is a use the PropertyTemplate property to specify additional configuration of the MessageQueue. Mark Pollack Retrun a configured MessageQueue object. A newly configured MessageQueue object Gets or sets an instance of the MessageQueueCreator delegate that will be used to create the MessageQueue object, instead of using the various public properties on this class such as Path, AccessMode, etc. Not intended for end-users but rather as a means to help register MessageQueueFactoryObject at runtime using convenience method on the IMessageQueueFactory. Can also be specifed using an instance of MessageCreatorDelegate. If both are specifed, the Interface implementation has priority. The function that is responsbile for creating a message queue. Gets or sets the path used to create a MessageQueue instance. The location of the queue. Gets or sets a value indicating whether to create the MessageQueue instance with exclusive read access to the first application that accesses the queue true to grant exclusive read access to the first application that accesses the queue; otherwise, false. Gets or sets the queue access mode. The queue access mode. Gets or sets a value indicating whether [enable cache]. true to create and use a connection cache; otherwise false. Sets a value indicating whether to enable connection cache. The default is false, which is different than the default value when creating a System.Messaging.MessageQueue object. true if enable connection cache; otherwise, false. Sets a value indicating whether to retrieve all message properties when receiving a message. true if should etrieve all message properties when receiving a message; otherwise, false. Sets a value indicating whether to set the filter values of common Message Queuing properties to true and the integer-valued properties to their default values.. true if should set the filter values of common Message Queuing properties; otherwise, false. Gets or sets a value indicating whether the queue is a remote queue. The operations that one can perform on the MessageQueue depend on if it is local or remote, for example checking if it is transactional. This is very difficult to determine programmatically. The property was made virtual so it can be overridden to take into account custom heuristics you may want to use to determine this programmatically. true if remote queue; otherwise, false. Gets or sets a value indicating whether the remote queue is transactional. true if the remote queue is transactional; otherwise, false. Return the of object that this creates, or if not known in advance. The type System.Messaging.MessageQueue Is the object managed by this factory a singleton or a prototype? return false, a new object will be created for each request of the object Gets the template object definition that should be used to configure the instance of the object managed by this factory. The object definition to configure the factory's product Set the name of the object in the object factory that created this object. The name of the object in the factory.

Invoked after population of normal object properties but before an init callback like 's method or a custom init-method.