Package org.springframework.oxm.jaxb

Class Jaxb2Marshaller

java.lang.Object
org.springframework.oxm.jaxb.Jaxb2Marshaller
All Implemented Interfaces:
Aware, BeanClassLoaderAware, InitializingBean, GenericMarshaller, GenericUnmarshaller, Marshaller, MimeMarshaller, MimeUnmarshaller, Unmarshaller
public class Jaxb2Marshaller extends Object implements MimeMarshaller, MimeUnmarshaller, GenericMarshaller, GenericUnmarshaller, BeanClassLoaderAware, InitializingBean
Implementation of the GenericMarshaller interface for JAXB 2.2.

The typical usage will be to set either the "contextPath" or the "classesToBeBound" property on this bean, possibly customize the marshaller and unmarshaller by setting properties, schemas, adapters, and listeners, and to refer to it.

Since:
3.0
Author:
Arjen Poutsma, Juergen Hoeller, Rossen Stoyanchev, Sam Brannen
See Also:

  • Field Details

    • logger

      protected final org.apache.commons.logging.Log logger
      Logger available to subclasses.

  • Constructor Details

    • Jaxb2Marshaller

      public Jaxb2Marshaller()

  • Method Details

    • setContextPaths

      public void setContextPaths(String... contextPaths)
      Set multiple JAXB context paths. The given array of context paths gets converted to a colon-delimited string, as supported by JAXB.

    • setContextPath

      public void setContextPath(@Nullable String contextPath)
      Set a JAXB context path.

      Setting either this property, "classesToBeBound" or "packagesToScan" is required.

    • getContextPath

      public @Nullable String getContextPath()
      Return the JAXB context path.

    • setClassesToBeBound

      public void setClassesToBeBound(Class<?> @Nullable ... classesToBeBound)
      Set the list of Java classes to be recognized by a newly created JAXBContext.

      Setting either this property, "contextPath" or "packagesToScan" is required.

    • getClassesToBeBound

      public Class<?> @Nullable [] getClassesToBeBound()
      Return the list of Java classes to be recognized by a newly created JAXBContext.

    • setPackagesToScan

      public void setPackagesToScan(String @Nullable ... packagesToScan)
      Set the packages to search for classes with JAXB2 annotations in the classpath. This is using a Spring-bases search and therefore analogous to Spring's component-scan feature (ClassPathBeanDefinitionScanner).

      Setting either this property, "contextPath" or "classesToBeBound" is required.

    • getPackagesToScan

      public String @Nullable [] getPackagesToScan()
      Return the packages to search for JAXB2 annotations.

    • setJaxbContextProperties

      public void setJaxbContextProperties(Map<String,?> jaxbContextProperties)
      Set the JAXBContext properties. These implementation-specific properties will be set on the underlying JAXBContext.

    • setMarshallerProperties

      public void setMarshallerProperties(Map<String,?> properties)
      Set the JAXB Marshaller properties.

      These properties will be set on the underlying JAXB Marshaller, and allow for features such as indentation.

      Parameters:
      properties - the properties
      See Also:
      • Marshaller.setProperty(String, Object)
      • Marshaller.JAXB_ENCODING
      • Marshaller.JAXB_FORMATTED_OUTPUT
      • Marshaller.JAXB_NO_NAMESPACE_SCHEMA_LOCATION
      • Marshaller.JAXB_SCHEMA_LOCATION

    • setUnmarshallerProperties

      public void setUnmarshallerProperties(Map<String,?> properties)
      Set the JAXB Unmarshaller properties.

      These properties will be set on the underlying JAXB Unmarshaller.

      Parameters:
      properties - the properties
      See Also:
      • Unmarshaller.setProperty(String, Object)

    • setMarshallerListener

      public void setMarshallerListener(jakarta.xml.bind.Marshaller.Listener marshallerListener)
      Specify the Marshaller.Listener to be registered with the JAXB Marshaller.

    • setUnmarshallerListener

      public void setUnmarshallerListener(jakarta.xml.bind.Unmarshaller.Listener unmarshallerListener)
      Set the Unmarshaller.Listener to be registered with the JAXB Unmarshaller.

    • setValidationEventHandler

      public void setValidationEventHandler(jakarta.xml.bind.ValidationEventHandler validationEventHandler)
      Set the JAXB validation event handler. This event handler will be called by JAXB if any validation errors are encountered during calls to any of the marshal APIs.

    • setAdapters

      public void setAdapters(jakarta.xml.bind.annotation.adapters.XmlAdapter<?,?>... adapters)
      Specify the XmlAdapters to be registered with the JAXB Marshaller and Unmarshaller.

    • setSchema

      public void setSchema(Resource schemaResource)
      Set the schema resource to use for validation.

    • setSchemas

      public void setSchemas(Resource... schemaResources)
      Set the schema resources to use for validation.

    • setSchemaLanguage

      public void setSchemaLanguage(String schemaLanguage)
      Set the schema language. Default is the W3C XML Schema: http://www.w3.org/2001/XMLSchema".
      See Also:

    • setSchemaResourceResolver

      public void setSchemaResourceResolver(LSResourceResolver schemaResourceResolver)
      Set the resource resolver, as used to load the schema resources.
      See Also:

    • setLazyInit

      public void setLazyInit(boolean lazyInit)
      Set whether to lazily initialize the JAXBContext for this marshaller. Default is false to initialize on startup; can be switched to true.

      Early initialization just applies if afterPropertiesSet() is called.

    • setMtomEnabled

      public void setMtomEnabled(boolean mtomEnabled)
      Specify whether MTOM support should be enabled or not. Default is false: marshalling using XOP/MTOM not being enabled.

    • setSupportJaxbElementClass

      public void setSupportJaxbElementClass(boolean supportJaxbElementClass)
      Specify whether the supports(Class) returns true for the JAXBElement class.

      Default is false, meaning that supports(Class) always returns false for JAXBElement classes (though supports(Type) can return true, since it can obtain the type parameters of JAXBElement).

      This property is typically enabled in combination with usage of classes like MarshallingView, since the ModelAndView does not offer type parameter information at runtime.

      See Also:

    • setCheckForXmlRootElement

      public void setCheckForXmlRootElement(boolean checkForXmlRootElement)
      Specify whether the supports(Class) should check for @XmlRootElement annotations.

      Default is true, meaning that supports(Class) will check for this annotation. However, some JAXB implementations (i.e. EclipseLink MOXy) allow for defining the bindings in an external definition file, thus keeping the classes annotations free. Setting this property to false supports these JAXB implementations.

      See Also:

    • setMappedClass

      public void setMappedClass(Class<?> mappedClass)
      Specify a JAXB mapped class for partial unmarshalling.
      See Also:
      • Unmarshaller.unmarshal(javax.xml.transform.Source, Class)

    • setSupportDtd

      public void setSupportDtd(boolean supportDtd)
      Indicate whether DTD parsing should be supported.

      Default is false meaning that DTD is disabled.

    • isSupportDtd

      public boolean isSupportDtd()
      Return whether DTD parsing is supported.

    • setProcessExternalEntities

      public void setProcessExternalEntities(boolean processExternalEntities)
      Indicate whether external XML entities are processed when unmarshalling.

      Default is false, meaning that external entities are not resolved. Note that processing of external entities will only be enabled/disabled when the Source passed to unmarshal(Source) is a SAXSource or StreamSource. It has no effect for DOMSource or StAXSource instances.

      Note: setting this option to true also automatically sets setSupportDtd(boolean) to true.

    • isProcessExternalEntities

      public boolean isProcessExternalEntities()
      Return whether XML external entities are allowed.

    • setBeanClassLoader

      public void setBeanClassLoader(ClassLoader classLoader)
      Description copied from interface: BeanClassLoaderAware
      Callback that supplies the bean class loader to a bean instance.

      Invoked after the population of normal bean properties but before an initialization callback such as InitializingBean's InitializingBean.afterPropertiesSet() method or a custom init-method.

      Specified by:
      setBeanClassLoader in interface BeanClassLoaderAware
      Parameters:
      classLoader - the owning class loader

    • afterPropertiesSet

      public void afterPropertiesSet() throws Exception
      Description copied from interface: InitializingBean
      Invoked by the containing BeanFactory after it has set all bean properties and satisfied BeanFactoryAware, ApplicationContextAware etc.

      This method allows the bean instance to perform validation of its overall configuration and final initialization when all bean properties have been set.

      Specified by:
      afterPropertiesSet in interface InitializingBean
      Throws:
      Exception - in the event of misconfiguration (such as failure to set an essential property) or if initialization fails for any other reason

    • getJaxbContext

      public jakarta.xml.bind.JAXBContext getJaxbContext()
      Return the JAXBContext used by this marshaller, lazily building it if necessary.

    • supports

      public boolean supports(Class<?> clazz)
      Description copied from interface: Marshaller
      Indicate whether this marshaller can marshal instances of the supplied type.
      Specified by:
      supports in interface Marshaller
      Specified by:
      supports in interface Unmarshaller
      Parameters:
      clazz - the class that this marshaller is being asked if it can marshal
      Returns:
      true if this marshaller can indeed marshal instances of the supplied class; false otherwise

    • supports

      public boolean supports(Type genericType)
      Description copied from interface: GenericMarshaller
      Indicates whether this marshaller can marshal instances of the supplied generic type.
      Specified by:
      supports in interface GenericMarshaller
      Specified by:
      supports in interface GenericUnmarshaller
      Parameters:
      genericType - the type that this marshaller is being asked if it can marshal
      Returns:
      true if this marshaller can indeed marshal instances of the supplied type; false otherwise

    • marshal

      public void marshal(Object graph, Result result) throws XmlMappingException
      Description copied from interface: Marshaller
      Marshal the object graph with the given root into the provided Result.
      Specified by:
      marshal in interface Marshaller
      Parameters:
      graph - the root of the object graph to marshal
      result - the result to marshal to
      Throws:
      XmlMappingException - if the given object cannot be marshalled to the result

    • marshal

      public void marshal(Object graph, Result result, @Nullable MimeContainer mimeContainer) throws XmlMappingException
      Description copied from interface: MimeMarshaller
      Marshals the object graph with the given root into the provided Result, writing binary data to a MimeContainer.
      Specified by:
      marshal in interface MimeMarshaller
      Parameters:
      graph - the root of the object graph to marshal
      result - the result to marshal to
      mimeContainer - the MIME container to write extracted binary content to
      Throws:
      XmlMappingException - if the given object cannot be marshalled to the result

    • createMarshaller

      public jakarta.xml.bind.Marshaller createMarshaller()
      Return a newly created JAXB marshaller.

      Note: JAXB marshallers are not necessarily thread-safe. This method is public as of 5.2.

      Since:
      5.2
      See Also:

    • initJaxbMarshaller

      protected void initJaxbMarshaller(jakarta.xml.bind.Marshaller marshaller) throws jakarta.xml.bind.JAXBException
      Template method that can be overridden by concrete JAXB marshallers for custom initialization behavior. Gets called after creation of JAXB Marshaller, and after the respective properties have been set.

      The default implementation sets the defined properties, the validation event handler, the schemas, listener, and adapters.

      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshal

      public Object unmarshal(Source source) throws XmlMappingException
      Description copied from interface: Unmarshaller
      Unmarshal the given Source into an object graph.
      Specified by:
      unmarshal in interface Unmarshaller
      Parameters:
      source - the source to marshal from
      Returns:
      the object graph
      Throws:
      XmlMappingException - if the given source cannot be mapped to an object

    • unmarshal

      public Object unmarshal(Source source, @Nullable MimeContainer mimeContainer) throws XmlMappingException
      Description copied from interface: MimeUnmarshaller
      Unmarshals the given provided Source into an object graph, reading binary attachments from a MimeContainer.
      Specified by:
      unmarshal in interface MimeUnmarshaller
      Parameters:
      source - the source to marshal from
      mimeContainer - the MIME container to read extracted binary content from
      Returns:
      the object graph
      Throws:
      XmlMappingException - if the given source cannot be mapped to an object

    • createUnmarshaller

      public jakarta.xml.bind.Unmarshaller createUnmarshaller()
      Return a newly created JAXB unmarshaller.

      Note: JAXB unmarshallers are not necessarily thread-safe. This method is public as of 5.2.

      Since:
      5.2
      See Also:

    • unmarshalStaxSource

      protected Object unmarshalStaxSource(jakarta.xml.bind.Unmarshaller jaxbUnmarshaller, Source staxSource) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • initJaxbUnmarshaller

      protected void initJaxbUnmarshaller(jakarta.xml.bind.Unmarshaller unmarshaller) throws jakarta.xml.bind.JAXBException
      Template method that can be overridden by concrete JAXB marshallers for custom initialization behavior. Gets called after creation of JAXB Marshaller, and after the respective properties have been set.

      The default implementation sets the defined properties, the validation event handler, the schemas, listener, and adapters.

      Throws:
      jakarta.xml.bind.JAXBException

    • convertJaxbException

      protected XmlMappingException convertJaxbException(jakarta.xml.bind.JAXBException ex)
      Convert the given JAXBException to an appropriate exception from the org.springframework.oxm hierarchy.
      Parameters:
      ex - JAXBException that occurred
      Returns:
      the corresponding XmlMappingException