Package com.peterphi.std.util.jaxb

Class JAXBSerialiser

java.lang.Object
com.peterphi.std.util.jaxb.JAXBSerialiser
public class JAXBSerialiser extends Object
A thread-safe, caching JAXB helper type. This wraps a JAXBContext and its Marshallers and Unmarshallers, allowing their concurrent use
This helper also translates the exceptions that can be thrown during a JAXB serialise/deserialise operation in a JAXBRuntimeException

  • Method Details

    • getContext

      public javax.xml.bind.JAXBContext getContext()
      Retrieve the inner JAXBContext
      NOTE: use of this method is strongly discouraged!
      Returns:

    • setSchema

      public JAXBSerialiser setSchema(Schema schema)
      Optionally specify the schema to use for all future serialisation/deserialisation methods

      Note that if this serializer is returned from and cached by a JAXBSerialiserFactory then use of this method could result in unintended side effects for other classes sharing the JAXBSerialiserFactory

      Parameters:
      schema -
      Returns:
      this for method chaining

    • setPrettyOutput

      public JAXBSerialiser setPrettyOutput(boolean pretty)
      Enable/Disable pretty printing
      Parameters:
      pretty -
      Returns:
      this for method chaining

    • setEncoding

      public JAXBSerialiser setEncoding(String encoding)
      Specify an output encoding to use when marshalling the XML data. The default is UTF-8

      Note that if this serializer is returned from and cached by a JAXBSerialiserFactory then use of this method could result in unintended side effects for other classes sharing the JAXBSerialiserFactory

      Parameters:
      encoding -
      Returns:
      this for method chaining

    • setSchemaLocation

      public JAXBSerialiser setSchemaLocation(String schemaLocation)
      Specify an xsi:schemaLocation attribute in the generated XML

      Note that if this serializer is returned from and cached by a JAXBSerialiserFactory then use of this method could result in unintended side effects for other classes sharing the JAXBSerialiserFactory

      Parameters:
      schemaLocation -
      Returns:
      this for method chaining

    • setNoNamespaceSchemaLocation

      public JAXBSerialiser setNoNamespaceSchemaLocation(String noNamespaceSchemaLocation)
      Specify an xsi:noNamespaceSchemaLocation in the generated XML

      Note that if this serializer is returned from and cached by a JAXBSerialiserFactory then use of this method could result in unintended side effects for other classes sharing the JAXBSerialiserFactory

      Parameters:
      noNamespaceSchemaLocation -
      Returns:
      this for method chaining

    • setFragment

      public JAXBSerialiser setFragment(boolean fragment)
      Specify the value of jaxb.fragment used by the underlying marshaller

      Note that if this serializer is returned from and cached by a JAXBSerialiserFactory then use of this method could result in unintended side effects for other classes sharing the JAXBSerialiserFactory

      Parameters:
      fragment -
      Returns:
      this for method chaining
      See Also:
      • Marshaller

    • deserialise

      public Object deserialise(String xml)
      Deserialise a String of XML to an Object (or JAXBElement)
      Parameters:
      xml -
      Returns:

    • deserialise

      public Object deserialise(InputStream is)
      Deserialise a stream of XML to an Object (or JAXBElement)
      Parameters:
      is -
      Returns:

    • deserialise

      public <T> T deserialise(Class<T> clazz, InputSource source)
      Deserialise an input and cast to a particular type
      Parameters:
      clazz -
      source -
      Returns:

    • deserialise

      public <T> T deserialise(Class<T> clazz, String xml)
      Deserialise and cast to a particular type
      Parameters:
      clazz -
      xml - a String of XML
      Returns:

    • deserialise

      public <T> T deserialise(Class<T> clazz, Element xml)
      Deserialise and cast to a particular type
      Parameters:
      clazz -
      xml - an XML element
      Returns:

    • deserialise

      public Object deserialise(File file)
      Deserialise a File of XML to an Object (or JAXBElement)
      Parameters:
      file -
      Returns:

    • deserialise

      public Object deserialise(InputSource source)

    • deserialise

      public Object deserialise(XMLStreamReader reader)
      Deserialise an XMLStreamReader to an Object (or JAXBElement)
      Parameters:
      reader -
      Returns:

    • deserialise

      public Object deserialise(Node node)
      Deserialise a DOM Node to an Object (or JAXBElement)
      Parameters:
      node -
      Returns:

    • serialiseToDocument

      public Document serialiseToDocument(Object obj)
      Helper method to serialise an Object to an org.w3c.dom.Document
      Parameters:
      obj - the object to serialise
      Returns:
      a new Document containing the serialised form of the provided Object

    • serialise

      public String serialise(Object obj)

    • serialise

      public void serialise(Object obj, Writer writer)

    • serialise

      public void serialise(Object obj, OutputStream os)

    • serialise

      public void serialise(Object obj, File file)

    • serialiseWithDirectWriter

      public void serialiseWithDirectWriter(Object obj, XMLStreamWriter writer)
      Marshals the provided type directly to the provided XMLStreamWriter. This is provided to allow callers to bypass the EclipseLink MOXy mitigation against XmlAnyElements which contain xmlns=""
      Parameters:
      obj -
      writer -

    • serialise

      public void serialise(Object obj, XMLStreamWriter writer)
      Marshals the provided type to the given XMLStreamWriter, filtering the XML stream to remove duplicate xmlns="" events if present. This is to work around an EclipseLink MOXy issue whereby XmlAnyElements which contain xmlns="" get that namespace definition duplicated via STaX
      Parameters:
      obj -
      writer -

    • print

      public static void print(Object obj)
      Helper method to print a serialised object to stdout (for dev/debugging use)
      Parameters:
      obj -

    • serialise

      public void serialise(Object obj, Node node)

    • getInstance

      public static JAXBSerialiser getInstance(javax.xml.bind.JAXBContext context)
      Helper method to get a JAXBSerialiser from an existing JAXBContext.
      This is an expensive operation and so the result should ideally be cached
      Parameters:
      context - an existing JAXBContext
      Returns:

    • getInstance

      public static JAXBSerialiser getInstance(Class<?>... classes)
      Helper method to get a JAXBSerialiser for a set of classes with the underlying JAXB implementation picked using the default rules for JAXB acquisition
      This is an expensive operation and so the result should ideally be cached
      Parameters:
      classes -
      Returns:

    • getInstance

      public static JAXBSerialiser getInstance(String contextPath)
      Helper method to get a JAXBSerialiser from a JAXB Context Path (i.e. a package name or colon-delimited list of package names) with the underlying JAXB implementation picked using the default rules for JAXB acquisition
      This is an expensive operation and so the result should ideally be cached
      Parameters:
      contextPath - a package name or colon-delimited list of package names
      Returns:

    • getMoxy

      public static JAXBSerialiser getMoxy(String contextPath)
      Helper method to get a JAXBSerialiser that uses EclipseLink MOXy for all operations
      Parameters:
      contextPath -
      Returns:

    • getMoxy

      public static JAXBSerialiser getMoxy(Class<?>... classes)
      Helper method to get a JAXBSerialiser that uses EclipseLink MOXy for all operations
      Parameters:
      classes -
      Returns: