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

org.springframework.http.converter.xml

## Class Jaxb2CollectionHttpMessageConverter<T extends Collection>

- java.lang.Object
- - org.springframework.http.converter.AbstractHttpMessageConverter<T>
  - - org.springframework.http.converter.xml.AbstractXmlHttpMessageConverter<T>
    - - org.springframework.http.converter.xml.AbstractJaxb2HttpMessageConverter<T>
      - - org.springframework.http.converter.xml.Jaxb2CollectionHttpMessageConverter<T>

- All Implemented Interfaces:
    GenericHttpMessageConverter<T>, HttpMessageConverter<T>

      public class Jaxb2CollectionHttpMessageConverter<T extends Collection>
      extends AbstractJaxb2HttpMessageConverter<T>
      implements GenericHttpMessageConverter<T>

  An `HttpMessageConverter` that can read XML collections using JAXB2.

  This converter can read collections that contain classes annotated with `XmlRootElement` and `XmlType`. Note that this converter does not support writing.

  Since:
    3.2
  Author:
    Arjen Poutsma

- - ### Field Summary

    - ### Fields inherited from class org.springframework.http.converter.AbstractHttpMessageConverter

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Jaxb2CollectionHttpMessageConverter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canRead(Class<?> clazz, MediaType mediaType)` Always returns `false` since Jaxb2CollectionHttpMessageConverter required generic type information in order to read a Collection.
    `boolean` | `canRead(Type type, Class<?> contextClass, MediaType mediaType)` Indicates whether the given type can be read by this converter.
    `boolean` | `canWrite(Class<?> clazz, MediaType mediaType)` Always returns `false` since Jaxb2CollectionHttpMessageConverter does not convert collections to XML.
    `protected T` | `createCollection(Class<?> collectionClass)` Create a Collection of the given type, with the given initial capacity (if supported by the Collection type).
    `protected XMLInputFactory` | `createXmlInputFactory()` Create a `XMLInputFactory` that this converter will use to create `XMLStreamReader` and `XMLEventReader` objects.
    `T` | `read(Type type, Class<?> contextClass, HttpInputMessage inputMessage)` Read an object of the given type form the given input message, and returns it.
    `protected T` | `readFromSource(Class<? extends T> clazz, HttpHeaders headers, Source source)` Abstract template method called from `AbstractHttpMessageConverter.read(Class, HttpInputMessage)`.
    `protected boolean` | `supports(Class<?> clazz)` Indicates whether the given class is supported by this converter.
    `protected void` | `writeToResult(T t, HttpHeaders headers, Result result)` Abstract template method called from `AbstractXmlHttpMessageConverter.writeInternal(Object, HttpOutputMessage)`.

    - ### Methods inherited from class org.springframework.http.converter.xml.AbstractJaxb2HttpMessageConverter

      `createMarshaller, createUnmarshaller, getJaxbContext`

    - ### Methods inherited from class org.springframework.http.converter.xml.AbstractXmlHttpMessageConverter

      `readInternal, transform, writeInternal`

    - ### Methods inherited from class org.springframework.http.converter.AbstractHttpMessageConverter

      `canRead, canWrite, getContentLength, getDefaultContentType, getSupportedMediaTypes, read, setSupportedMediaTypes, write`

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

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

    - ### Methods inherited from interface org.springframework.http.converter.HttpMessageConverter

      `getSupportedMediaTypes, read, write`

- - ### Constructor Detail

    - #### Jaxb2CollectionHttpMessageConverter

          public Jaxb2CollectionHttpMessageConverter()

  - ### Method Detail

    - #### canRead

          public boolean canRead(Class<?> clazz,
                        MediaType mediaType)

      Always returns `false` since Jaxb2CollectionHttpMessageConverter required generic type information in order to read a Collection.
      Specified by:
        `canRead` in interface `HttpMessageConverter<T extends Collection>`
      Overrides:
        `canRead` in class `AbstractHttpMessageConverter<T extends Collection>`
      Parameters:
        `clazz` - the class to test for readability
        `mediaType` - the media type to read, can be `null` if not specified. Typically the value of a `Content-Type` header.
      Returns:
        `true` if readable; `false` otherwise

    - #### canRead

          public boolean canRead(Type type,
                        Class<?> contextClass,
                        MediaType mediaType)

      Indicates whether the given type can be read by this converter.

      Jaxb2CollectionHttpMessageConverter can read a generic `Collection` where the generic type is a JAXB type annotated with `XmlRootElement` or `XmlType`.

      Specified by:
        `canRead` in interface `GenericHttpMessageConverter<T extends Collection>`
      Parameters:
        `type` - the type to test for readability
        `contextClass` - a context class for the target type, for example a class in which the target type appears in a method signature, can be `null`
        `mediaType` - the media type to read, can be `null` if not specified. Typically the value of a `Content-Type` header.
      Returns:
        `true` if readable; `false` otherwise

    - #### canWrite

          public boolean canWrite(Class<?> clazz,
                         MediaType mediaType)

      Always returns `false` since Jaxb2CollectionHttpMessageConverter does not convert collections to XML.
      Specified by:
        `canWrite` in interface `HttpMessageConverter<T extends Collection>`
      Overrides:
        `canWrite` in class `AbstractHttpMessageConverter<T extends Collection>`
      Parameters:
        `clazz` - the class to test for writability
        `mediaType` - the media type to write, can be `null` if not specified. Typically the value of an `Accept` header.
      Returns:
        `true` if writable; `false` otherwise

    - #### supports

          protected boolean supports(Class<?> clazz)

      Description copied from class: `AbstractHttpMessageConverter`
      Indicates whether the given class is supported by this converter.
      Specified by:
        `supports` in class `AbstractHttpMessageConverter<T extends Collection>`
      Parameters:
        `clazz` - the class to test for support
      Returns:
        `true` if supported; `false` otherwise

    - #### readFromSource

          protected T readFromSource(Class<? extends T> clazz,
                         HttpHeaders headers,
                         Source source)
                                                 throws IOException

      Description copied from class: `AbstractXmlHttpMessageConverter`
      Abstract template method called from `AbstractHttpMessageConverter.read(Class, HttpInputMessage)`.
      Specified by:
        `readFromSource` in class `AbstractXmlHttpMessageConverter<T extends Collection>`
      Parameters:
        `clazz` - the type of object to return
        `headers` - the HTTP input headers
        `source` - the HTTP input body
      Returns:
        the converted object
      Throws:
        `IOException` - in case of I/O errors

    - #### read

          public T read(Type type,
               Class<?> contextClass,
               HttpInputMessage inputMessage)
                                    throws IOException,
                                           HttpMessageNotReadableException

      Description copied from interface: `GenericHttpMessageConverter`
      Read an object of the given type form the given input message, and returns it.
      Specified by:
        `read` in interface `GenericHttpMessageConverter<T extends Collection>`
      Parameters:
        `type` - the type of object to return. This type must have previously been passed to the `canRead` method of this interface, which must have returned `true`.
        `contextClass` - a context class for the target type, for example a class in which the target type appears in a method signature, can be `null`
        `inputMessage` - the HTTP input message to read from
      Returns:
        the converted object
      Throws:
        `IOException` - in case of I/O errors
        `HttpMessageNotReadableException` - in case of conversion errors

    - #### createCollection

          protected T createCollection(Class<?> collectionClass)

      Create a Collection of the given type, with the given initial capacity (if supported by the Collection type).
      Parameters:
        `collectionClass` - the type of Collection to instantiate
      Returns:
        the created Collection instance

    - #### writeToResult

          protected void writeToResult(T t,
                           HttpHeaders headers,
                           Result result)
                                throws IOException

      Description copied from class: `AbstractXmlHttpMessageConverter`
      Abstract template method called from `AbstractXmlHttpMessageConverter.writeInternal(Object, HttpOutputMessage)`.
      Specified by:
        `writeToResult` in class `AbstractXmlHttpMessageConverter<T extends Collection>`
      Parameters:
        `t` - the object to write to the output message
        `headers` - the HTTP output headers
        `result` - the HTTP output body
      Throws:
        `IOException` - in case of I/O errors

    - #### createXmlInputFactory

          protected XMLInputFactory createXmlInputFactory()

      Create a `XMLInputFactory` that this converter will use to create `XMLStreamReader` and `XMLEventReader` objects.

      Can be overridden in subclasses, adding further initialization of the factory. The resulting factory is cached, so this method will only be called once.
      Returns:
        the created factory