MarshallingMessageConverter (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jms.support.converter

## Class MarshallingMessageConverter

- java.lang.Object
- - org.springframework.jms.support.converter.MarshallingMessageConverter

- All Implemented Interfaces:
    InitializingBean, MessageConverter

      public class MarshallingMessageConverter
      extends Object
      implements MessageConverter, InitializingBean

  Spring JMS `MessageConverter` that uses a `Marshaller` and `Unmarshaller`. Marshals an object to a `BytesMessage`, or to a `TextMessage` if the `targetType` is set to `MessageType.TEXT`. Unmarshals from a `TextMessage` or `BytesMessage` to an object.
  Since:
    3.0
  Author:
    Arjen Poutsma, Juergen Hoeller
  See Also:
    `JmsTemplate.convertAndSend(java.lang.Object)`, `JmsTemplate.receiveAndConvert()`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MarshallingMessageConverter()` Construct a new `MarshallingMessageConverter` with no `Marshaller` or `Unmarshaller` set.
    `MarshallingMessageConverter(Marshaller marshaller)` Construct a new `MarshallingMessageConverter` with the given `Marshaller` set.
    `MarshallingMessageConverter(Marshaller marshaller, Unmarshaller unmarshaller)` Construct a new `MarshallingMessageConverter` with the given Marshaller and Unmarshaller.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `Object` | `fromMessage(Message message)` This implementation unmarshals the given `Message` into an object.
    `protected BytesMessage` | `marshalToBytesMessage(Object object, Session session, Marshaller marshaller)` Marshal the given object to a `BytesMessage`.
    `protected Message` | `marshalToMessage(Object object, Session session, Marshaller marshaller, MessageType targetType)` Template method that allows for custom message marshalling.
    `protected TextMessage` | `marshalToTextMessage(Object object, Session session, Marshaller marshaller)` Marshal the given object to a `TextMessage`.
    `void` | `setMarshaller(Marshaller marshaller)` Set the `Marshaller` to be used by this message converter.
    `void` | `setTargetType(MessageType targetType)` Specify whether `toMessage(Object, Session)` should marshal to a `BytesMessage` or a `TextMessage`.
    `void` | `setUnmarshaller(Unmarshaller unmarshaller)` Set the `Unmarshaller` to be used by this message converter.
    `Message` | `toMessage(Object object, Session session)` This implementation marshals the given object to a `TextMessage` or `BytesMessage`.
    `protected Object` | `unmarshalFromBytesMessage(BytesMessage message, Unmarshaller unmarshaller)` Unmarshal the given `BytesMessage` into an object.
    `protected Object` | `unmarshalFromMessage(Message message, Unmarshaller unmarshaller)` Template method that allows for custom message unmarshalling.
    `protected Object` | `unmarshalFromTextMessage(TextMessage message, Unmarshaller unmarshaller)` Unmarshal the given `TextMessage` into an object.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MarshallingMessageConverter

          public MarshallingMessageConverter()

      Construct a new `MarshallingMessageConverter` with no `Marshaller` or `Unmarshaller` set. The marshaller must be set after construction by invoking `setMarshaller(Marshaller)` and `setUnmarshaller(Unmarshaller)` .

    - #### MarshallingMessageConverter

          public MarshallingMessageConverter(Marshaller marshaller)

      Construct a new `MarshallingMessageConverter` with the given `Marshaller` set.

      If the given `Marshaller` also implements the `Unmarshaller` interface, it is used for both marshalling and unmarshalling. Otherwise, an exception is thrown.

      Note that all `Marshaller` implementations in Spring also implement the `Unmarshaller` interface, so that you can safely use this constructor.

      Parameters:
        `marshaller` - object used as marshaller and unmarshaller
      Throws:
        `IllegalArgumentException` - when `marshaller` does not implement the `Unmarshaller` interface as well

    - #### MarshallingMessageConverter

          public MarshallingMessageConverter(Marshaller marshaller,
                                     Unmarshaller unmarshaller)

      Construct a new `MarshallingMessageConverter` with the given Marshaller and Unmarshaller.
      Parameters:
        `marshaller` - the Marshaller to use
        `unmarshaller` - the Unmarshaller to use

  - ### Method Detail

    - #### setMarshaller

          public void setMarshaller(Marshaller marshaller)

      Set the `Marshaller` to be used by this message converter.

    - #### setUnmarshaller

          public void setUnmarshaller(Unmarshaller unmarshaller)

      Set the `Unmarshaller` to be used by this message converter.

    - #### setTargetType

          public void setTargetType(MessageType targetType)

      Specify whether `toMessage(Object, Session)` should marshal to a `BytesMessage` or a `TextMessage`.

      The default is `MessageType.BYTES`, i.e. this converter marshals to a `BytesMessage`. Note that the default version of this converter supports `MessageType.BYTES` and `MessageType.TEXT` only.

      See Also:
        `MessageType.BYTES`, `MessageType.TEXT`

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Description copied from interface: `InitializingBean`
      Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

      This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### toMessage

          public Message toMessage(Object object,
                          Session session)
                            throws JMSException,
                                   MessageConversionException

      This implementation marshals the given object to a `TextMessage` or `BytesMessage`. The desired message type can be defined by setting the `"marshalTo"` property.
      Specified by:
        `toMessage` in interface `MessageConverter`
      Parameters:
        `object` - the object to convert
        `session` - the Session to use for creating a JMS Message
      Returns:
        the JMS Message
      Throws:
        `JMSException` - if thrown by JMS API methods
        `MessageConversionException` - in case of conversion failure
      See Also:
        `marshalToTextMessage(java.lang.Object, javax.jms.Session, org.springframework.oxm.Marshaller)`, `marshalToBytesMessage(java.lang.Object, javax.jms.Session, org.springframework.oxm.Marshaller)`

    - #### fromMessage

          public Object fromMessage(Message message)
                             throws JMSException,
                                    MessageConversionException

      This implementation unmarshals the given `Message` into an object.
      Specified by:
        `fromMessage` in interface `MessageConverter`
      Parameters:
        `message` - the message to convert
      Returns:
        the converted Java object
      Throws:
        `JMSException` - if thrown by JMS API methods
        `MessageConversionException` - in case of conversion failure
      See Also:
        `unmarshalFromTextMessage(javax.jms.TextMessage, org.springframework.oxm.Unmarshaller)`, `unmarshalFromBytesMessage(javax.jms.BytesMessage, org.springframework.oxm.Unmarshaller)`

    - #### marshalToTextMessage

          protected TextMessage marshalToTextMessage(Object object,
                                         Session session,
                                         Marshaller marshaller)
                                              throws JMSException,
                                                     IOException,
                                                     XmlMappingException

      Marshal the given object to a `TextMessage`.
      Parameters:
        `object` - the object to be marshalled
        `session` - current JMS session
        `marshaller` - the marshaller to use
      Returns:
        the resulting message
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors
      See Also:
        `Session.createTextMessage()`, `Marshaller.marshal(Object, Result)`

    - #### marshalToBytesMessage

          protected BytesMessage marshalToBytesMessage(Object object,
                                           Session session,
                                           Marshaller marshaller)
                                                throws JMSException,
                                                       IOException,
                                                       XmlMappingException

      Marshal the given object to a `BytesMessage`.
      Parameters:
        `object` - the object to be marshalled
        `session` - current JMS session
        `marshaller` - the marshaller to use
      Returns:
        the resulting message
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors
      See Also:
        `Session.createBytesMessage()`, `Marshaller.marshal(Object, Result)`

    - #### marshalToMessage

          protected Message marshalToMessage(Object object,
                                 Session session,
                                 Marshaller marshaller,
                                 MessageType targetType)
                                      throws JMSException,
                                             IOException,
                                             XmlMappingException

      Template method that allows for custom message marshalling. Invoked when `setTargetType(org.springframework.jms.support.converter.MessageType)` is not `MessageType.TEXT` or `MessageType.BYTES`.

      The default implementation throws an `IllegalArgumentException`.

      Parameters:
        `object` - the object to marshal
        `session` - the JMS session
        `marshaller` - the marshaller to use
        `targetType` - the target message type (other than TEXT or BYTES)
      Returns:
        the resulting message
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors

    - #### unmarshalFromTextMessage

          protected Object unmarshalFromTextMessage(TextMessage message,
                                        Unmarshaller unmarshaller)
                                             throws JMSException,
                                                    IOException,
                                                    XmlMappingException

      Unmarshal the given `TextMessage` into an object.
      Parameters:
        `message` - the message
        `unmarshaller` - the unmarshaller to use
      Returns:
        the unmarshalled object
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors
      See Also:
        `Unmarshaller.unmarshal(Source)`

    - #### unmarshalFromBytesMessage

          protected Object unmarshalFromBytesMessage(BytesMessage message,
                                         Unmarshaller unmarshaller)
                                              throws JMSException,
                                                     IOException,
                                                     XmlMappingException

      Unmarshal the given `BytesMessage` into an object.
      Parameters:
        `message` - the message
        `unmarshaller` - the unmarshaller to use
      Returns:
        the unmarshalled object
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors
      See Also:
        `Unmarshaller.unmarshal(Source)`

    - #### unmarshalFromMessage

          protected Object unmarshalFromMessage(Message message,
                                    Unmarshaller unmarshaller)
                                         throws JMSException,
                                                IOException,
                                                XmlMappingException

      Template method that allows for custom message unmarshalling. Invoked when `fromMessage(Message)` is invoked with a message that is not a `TextMessage` or `BytesMessage`.

      The default implementation throws an `IllegalArgumentException`.

      Parameters:
        `message` - the message
        `unmarshaller` - the unmarshaller to use
      Returns:
        the unmarshalled object
      Throws:
        `JMSException` - if thrown by JMS methods
        `IOException` - in case of I/O errors
        `XmlMappingException` - in case of OXM mapping errors