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

org.springframework.web.servlet.view.xslt

## Class XsltView

- java.lang.Object
- - org.springframework.context.support.ApplicationObjectSupport
  - - org.springframework.web.context.support.WebApplicationObjectSupport
    - - org.springframework.web.servlet.view.AbstractView
      - - org.springframework.web.servlet.view.AbstractUrlBasedView
        - - org.springframework.web.servlet.view.xslt.XsltView

- All Implemented Interfaces:
    Aware, BeanNameAware, InitializingBean, ApplicationContextAware, ServletContextAware, View

      public class XsltView
      extends AbstractUrlBasedView

  XSLT-driven View that allows for response context to be rendered as the result of an XSLT transformation.

  The XSLT Source object is supplied as a parameter in the model and then `detected` during response rendering. Users can either specify a specific entry in the model via the `sourceKey` property or have Spring locate the Source object. This class also provides basic conversion of objects into Source implementations. See `here` for more details.

  All model parameters are passed to the XSLT Transformer as parameters. In addition the user can configure `output properties` to be passed to the Transformer.

  Since:
    2.0
  Author:
    Rob Harrop, Juergen Hoeller

- - ### Field Summary

    - ### Fields inherited from class org.springframework.web.servlet.view.AbstractView

      `DEFAULT_CONTENT_TYPE`

    - ### Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

      `logger`

    - ### Fields inherited from interface org.springframework.web.servlet.View

      `PATH_VARIABLES, RESPONSE_STATUS_ATTRIBUTE, SELECTED_CONTENT_TYPE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XsltView()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `configureIndentation(Transformer transformer)` Configure the indentation settings for the supplied `Transformer`.
    `protected void` | `configureResponse(Map<String,Object> model, HttpServletResponse response, Transformer transformer)` Configure the supplied `HttpServletResponse`.
    `protected void` | `configureTransformer(Map<String,Object> model, HttpServletResponse response, Transformer transformer)` Configure the supplied `Transformer` instance.
    `protected Source` | `convertSource(Object source)` Convert the supplied `Object` into an XSLT `Source` if the `Object` type is `supported`.
    `protected void` | `copyModelParameters(Map<String,Object> model, Transformer transformer)` Copy all entries from the supplied Map into the `parameter set` of the supplied `Transformer`.
    `protected void` | `copyOutputProperties(Transformer transformer)` Copy the configured output `Properties`, if any, into the `output property set` of the supplied `Transformer`.
    `protected Result` | `createResult(HttpServletResponse response)` Create the XSLT `Result` used to render the result of the transformation.
    `protected Transformer` | `createTransformer(Templates templates)` Create the `Transformer` instance used to prefer the XSLT transformation.
    `protected Class[]` | `getSourceTypes()` Return the array of `Classes` that are supported when converting to an XSLT `Source`.
    `protected Source` | `getStylesheetSource()` Get the XSLT `Source` for the XSLT template under the `configured URL`.
    `protected TransformerFactory` | `getTransformerFactory()` Return the TransformerFactory that this XsltView uses.
    `protected void` | `initApplicationContext()` Initialize this XsltView's TransformerFactory.
    `protected Source` | `locateSource(Map<String,Object> model)` Locate the `Source` object in the supplied model, converting objects as required.
    `protected TransformerFactory` | `newTransformerFactory(Class transformerFactoryClass)` Instantiate a new TransformerFactory for this view.
    `protected void` | `renderMergedOutputModel(Map<String,Object> model, HttpServletRequest request, HttpServletResponse response)` Subclasses must implement this method to actually render the view.
    `void` | `setCacheTemplates(boolean cacheTemplates)` Turn on/off the caching of the XSLT `Templates` instance.
    `void` | `setErrorListener(ErrorListener errorListener)` Set an implementation of the `ErrorListener` interface for custom handling of transformation errors and warnings.
    `void` | `setIndent(boolean indent)` Set whether the XSLT transformer may add additional whitespace when outputting the result tree.
    `void` | `setOutputProperties(Properties outputProperties)` Set arbitrary transformer output properties to be applied to the stylesheet.
    `void` | `setSourceKey(String sourceKey)` Set the name of the model attribute that represents the XSLT Source.
    `void` | `setTransformerFactoryClass(Class transformerFactoryClass)` Specify the XSLT TransformerFactory class to use.
    `void` | `setUriResolver(URIResolver uriResolver)` Set the URIResolver used in the transform.

    - ### Methods inherited from class org.springframework.web.servlet.view.AbstractUrlBasedView

      `afterPropertiesSet, checkResource, getUrl, isUrlRequired, setUrl, toString`

    - ### Methods inherited from class org.springframework.web.servlet.view.AbstractView

      `addStaticAttribute, createMergedOutputModel, createRequestContext, createTemporaryOutputStream, exposeModelAsRequestAttributes, generatesDownloadContent, getAttributesMap, getBeanName, getContentType, getRequestContextAttribute, getStaticAttributes, isExposePathVariables, prepareResponse, render, setAttributes, setAttributesCSV, setAttributesMap, setBeanName, setContentType, setExposePathVariables, setRequestContextAttribute, setResponseContentType, writeToResponse`

    - ### Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

      `getApplicationContext, getMessageSourceAccessor, requiredContextClass, setApplicationContext`

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

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

- - ### Constructor Detail

    - #### XsltView

          public XsltView()

  - ### Method Detail

    - #### setTransformerFactoryClass

          public void setTransformerFactoryClass(Class transformerFactoryClass)

      Specify the XSLT TransformerFactory class to use.

      The default constructor of the specified class will be called to build the TransformerFactory for this view.

    - #### setSourceKey

          public void setSourceKey(String sourceKey)

      Set the name of the model attribute that represents the XSLT Source. If not specified, the model map will be searched for a matching value type.

      The following source types are supported out of the box: `Source`, `Document`, `Node`, `Reader`, `InputStream` and `Resource`.

      See Also:
        `getSourceTypes()`, `convertSource(java.lang.Object)`

    - #### setUriResolver

          public void setUriResolver(URIResolver uriResolver)

      Set the URIResolver used in the transform.

      The URIResolver handles calls to the XSLT `document()` function.

    - #### setErrorListener

          public void setErrorListener(ErrorListener errorListener)

      Set an implementation of the `ErrorListener` interface for custom handling of transformation errors and warnings.

      If not set, a default `SimpleTransformErrorListener` is used that simply logs warnings using the logger instance of the view class, and rethrows errors to discontinue the XML transformation.

      See Also:
        `SimpleTransformErrorListener`

    - #### setIndent

          public void setIndent(boolean indent)

      Set whether the XSLT transformer may add additional whitespace when outputting the result tree.

      Default is `true` (on); set this to `false` (off) to not specify an "indent" key, leaving the choice up to the stylesheet.

      See Also:
        `OutputKeys.INDENT`

    - #### setOutputProperties

          public void setOutputProperties(Properties outputProperties)

      Set arbitrary transformer output properties to be applied to the stylesheet.

      Any values specified here will override defaults that this view sets programmatically.

      See Also:
        `Transformer.setOutputProperty(java.lang.String, java.lang.String)`

    - #### setCacheTemplates

          public void setCacheTemplates(boolean cacheTemplates)

      Turn on/off the caching of the XSLT `Templates` instance.

      The default value is "true". Only set this to "false" in development, where caching does not seriously impact performance.

    - #### initApplicationContext

          protected void initApplicationContext()
                                         throws BeansException

      Initialize this XsltView's TransformerFactory.
      Overrides:
        `initApplicationContext` in class `ApplicationObjectSupport`
      Throws:
        `ApplicationContextException` - in case of initialization errors
        `BeansException` - if thrown by ApplicationContext methods
      See Also:
        `ApplicationObjectSupport.setApplicationContext(org.springframework.context.ApplicationContext)`

    - #### newTransformerFactory

          protected TransformerFactory newTransformerFactory(Class transformerFactoryClass)

      Instantiate a new TransformerFactory for this view.

      The default implementation simply calls `TransformerFactory.newInstance()`. If a `"transformerFactoryClass"` has been specified explicitly, the default constructor of the specified class will be called instead.

      Can be overridden in subclasses.

      Parameters:
        `transformerFactoryClass` - the specified factory class (if any)
      Returns:
        the new TransactionFactory instance
      See Also:
        `setTransformerFactoryClass(java.lang.Class)`, `getTransformerFactory()`

    - #### getTransformerFactory

          protected final TransformerFactory getTransformerFactory()

      Return the TransformerFactory that this XsltView uses.
      Returns:
        the TransformerFactory (never `null`)

    - #### renderMergedOutputModel

          protected void renderMergedOutputModel(Map<String,Object> model,
                                     HttpServletRequest request,
                                     HttpServletResponse response)
                                          throws Exception

      Description copied from class: `AbstractView`
      Subclasses must implement this method to actually render the view.

      The first step will be preparing the request: In the JSP case, this would mean setting model objects as request attributes. The second step will be the actual rendering of the view, for example including the JSP via a RequestDispatcher.

      Specified by:
        `renderMergedOutputModel` in class `AbstractView`
      Parameters:
        `model` - combined output Map (never `null`), with dynamic values taking precedence over static attributes
        `request` - current HTTP request
        `response` - current HTTP response
      Throws:
        `Exception` - if rendering failed

    - #### createResult

          protected Result createResult(HttpServletResponse response)
                                 throws Exception

      Create the XSLT `Result` used to render the result of the transformation.

      The default implementation creates a `StreamResult` wrapping the supplied HttpServletResponse's `OutputStream`.

      Parameters:
        `response` - current HTTP response
      Returns:
        the XSLT Result to use
      Throws:
        `Exception` - if the Result cannot be built

    - #### locateSource

          protected Source locateSource(Map<String,Object> model)
                                 throws Exception

      Locate the `Source` object in the supplied model, converting objects as required. The default implementation first attempts to look under the configured `source key`, if any, before attempting to locate an object of `supported type`.

      Parameters:
        `model` - the merged model Map
      Returns:
        the XSLT Source object (or `null` if none found)
      Throws:
        `Exception` - if an error occured during locating the source
      See Also:
        `setSourceKey(java.lang.String)`, `convertSource(java.lang.Object)`

    - #### getSourceTypes

          protected Class[] getSourceTypes()

      Return the array of `Classes` that are supported when converting to an XSLT `Source`.

      Currently supports `Source`, `Document`, `Node`, `Reader`, `InputStream` and `Resource`.

      Returns:
        the supported source types

    - #### convertSource

          protected Source convertSource(Object source)
                                  throws Exception

      Convert the supplied `Object` into an XSLT `Source` if the `Object` type is `supported`.
      Parameters:
        `source` - the original source object
      Returns:
        the adapted XSLT Source
      Throws:
        `IllegalArgumentException` - if the given Object is not of a supported type
        `Exception`

    - #### configureTransformer

          protected void configureTransformer(Map<String,Object> model,
                                  HttpServletResponse response,
                                  Transformer transformer)

      Configure the supplied `Transformer` instance.

      The default implementation copies parameters from the model into the Transformer's `parameter set`. This implementation also copies the `output properties` into the `Transformer` `output properties`. Indentation properties are set as well.

      Parameters:
        `model` - merged output Map (never `null`)
        `response` - current HTTP response
        `transformer` - the target transformer
      See Also:
        `copyModelParameters(Map, Transformer)`, `copyOutputProperties(Transformer)`, `configureIndentation(Transformer)`

    - #### configureIndentation

          protected final void configureIndentation(Transformer transformer)

      Configure the indentation settings for the supplied `Transformer`.
      Parameters:
        `transformer` - the target transformer
      See Also:
        `TransformerUtils.enableIndenting(javax.xml.transform.Transformer)`, `TransformerUtils.disableIndenting(javax.xml.transform.Transformer)`

    - #### copyOutputProperties

          protected final void copyOutputProperties(Transformer transformer)

      Copy the configured output `Properties`, if any, into the `output property set` of the supplied `Transformer`.
      Parameters:
        `transformer` - the target transformer

    - #### copyModelParameters

          protected final void copyModelParameters(Map<String,Object> model,
                                 Transformer transformer)

      Copy all entries from the supplied Map into the `parameter set` of the supplied `Transformer`.
      Parameters:
        `model` - merged output Map (never `null`)
        `transformer` - the target transformer

    - #### configureResponse

          protected void configureResponse(Map<String,Object> model,
                               HttpServletResponse response,
                               Transformer transformer)

      Configure the supplied `HttpServletResponse`.

      The default implementation of this method sets the `content type` and `encoding` from the "media-type" and "encoding" output properties specified in the `Transformer`.

      Parameters:
        `model` - merged output Map (never `null`)
        `response` - current HTTP response
        `transformer` - the target transformer

    - #### createTransformer

          protected Transformer createTransformer(Templates templates)
                                           throws TransformerConfigurationException

      Create the `Transformer` instance used to prefer the XSLT transformation.

      The default implementation simply calls `Templates.newTransformer()`, and configures the `Transformer` with the custom `URIResolver` if specified.

      Parameters:
        `templates` - the XSLT Templates instance to create a Transformer for
      Returns:
        the Transformer object
      Throws:
        `TransformerConfigurationException` - in case of creation failure

    - #### getStylesheetSource

          protected Source getStylesheetSource()

      Get the XSLT `Source` for the XSLT template under the `configured URL`.
      Returns:
        the Source object