Module tools.jackson.dataformat.xml
Package tools.jackson.dataformat.xml.ser

Class XmlGeneratorInitializer

java.lang.Object
tools.jackson.dataformat.xml.ser.XmlGeneratorInitializer
All Implemented Interfaces:
tools.jackson.databind.cfg.GeneratorInitializer
public class XmlGeneratorInitializer extends Object implements tools.jackson.databind.cfg.GeneratorInitializer
Default GeneratorInitializer implementation to use with ToXmlGenerator, registered via ObjectWriter.with(GeneratorInitializer). It allows output of various document-level things such as
  • Document Type Declarations (DTD); that is "<!DOCTYPE>" directive
  • Comments (in Document prolog, before the root element)
  • Namespace bindings (prefix to URI mappings)
  • Processing Instructions (PIs; in Document prolog, before the root element)
  • XML Declaration (with custom version, encoding and/or standalone value)

NOTE: instances are mutable, not thread-safe.

Since:
3.2

  • Field Details

    • _directives

      protected List<PrologDirective> _directives
      Prolog Directives to pass for generator to write.

    • _namespaceBindings

      protected List<NamespaceBinding> _namespaceBindings
      Namespace bindings (prefix to URI) to register with generator.

    • _rootAttributes

      protected List<RootAttribute> _rootAttributes
      Attributes to add to root element (if any).
      Since:
      3.2

    • _xmlDeclaration

      protected XmlDeclaration _xmlDeclaration
      Custom XML declaration to write.

    • _addLfBetweenPrologDirectives

      protected boolean _addLfBetweenPrologDirectives

    • _hasDTD

      protected boolean _hasDTD

  • Constructor Details

    • XmlGeneratorInitializer

      public XmlGeneratorInitializer()

  • Method Details

    • initialize

      public void initialize(tools.jackson.databind.SerializationConfig config, tools.jackson.core.JsonGenerator g) throws tools.jackson.core.JacksonException
      Specified by:
      initialize in interface tools.jackson.databind.cfg.GeneratorInitializer
      Throws:
      tools.jackson.core.JacksonException

    • linefeedsBetweenPrologDirectives

      public XmlGeneratorInitializer linefeedsBetweenPrologDirectives(boolean addLFs)
      Method to change whether line-feeds are to be added between Prolog directives or not: default being they are (enabled).
      Parameters:
      addLFs - Whether line-feeds are to be added or not (default: true)
      Returns:
      This initializer for call chaining

    • addComment

      public XmlGeneratorInitializer addComment(String commentContent)
      Method for adding XML comment; to be written at position added relative to other directives (but always after XML Declaration which must come before any other output; and before Document Root element)
      Parameters:
      commentContent - (optional) Comment content to include
      Returns:
      This initializer for call chaining

    • addDTD

      public XmlGeneratorInitializer addDTD(String rootName, String systemId, String publicId, String internalSubset)
      Convenience method that constructs DTD out of arguments and calls addDTD(DTD).
      Parameters:
      rootName - (required) Root name for DTD
      systemId - (optional) System Id for DTD
      publicId - (optional) Public Id for DTD
      internalSubset - (optional) Internal subset for DTD (not including surrounding brackets
      Returns:
      This initializer for call chaining

    • addDTD

      public XmlGeneratorInitializer addDTD(DTD dtd)
      Method for adding Document Type Declaration (DTD) directive; to be written at position added relative to other directives (but always after XML Declaration which must come before any other output; and before Document Root element)
      Parameters:
      dtd - DTD to write
      Returns:
      This initializer for call chaining

    • addPI

      public XmlGeneratorInitializer addPI(String target, String data)
      Method for adding XML Processing Instruction (PI); to be written at position added relative to other directives (but always after XML Declaration which must come before any other output; and before Document Root element)
      Parameters:
      target - Processing Instruction target: must not be null or empty String
      data - (optional) Processing Instruction data part, if any, separated by a space from target (if not null)
      Returns:
      This initializer for call chaining

    • addDefaultNamespace

      public XmlGeneratorInitializer addDefaultNamespace(String namespaceURI)
      Method for specifying namespace URI to preferentially bind to the "default namespace" (one used when element has no prefix). This will guide underlying generator to add necessary declarations when actually writing elements with matching namespace URI.
      Parameters:
      namespaceURI - URI of the default namespace
      Returns:
      This initializer for call chaining

    • addNamespace

      public XmlGeneratorInitializer addNamespace(String prefix, String namespaceURI)
      Method for adding a mapping (binding) between given prefix and matching namespace URI. This will guide underlying generator to add necessary declarations when actually writing namespaced attributes and elements.
      Parameters:
      prefix - Prefix to use for namespace
      namespaceURI - URI of the namespace
      Returns:
      This initializer for call chaining

    • addRootAttribute

      public XmlGeneratorInitializer addRootAttribute(QName name, String value)
      Method for adding an attribute to be written on the root element of the output document. Attributes are emitted in the order added, after the root element's start tag is written and before any content from the value being serialized.

      Typical use case is adding XML Schema instance attributes such as xsi:schemaLocation or xsi:noNamespaceSchemaLocation.

      NOTE: root attributes are only emitted when the root value being serialized produces a structured (object) start element; scalar root values do not currently get root attributes attached.

      Parameters:
      name - Attribute name (with optional namespace and prefix)
      value - Attribute value (null is coerced to empty String)
      Returns:
      This initializer for call chaining
      Since:
      3.2

    • addRootAttribute

      public XmlGeneratorInitializer addRootAttribute(String localName, String value)
      Convenience overload of addRootAttribute(QName, String) for adding non-namespaced attribute by local name.
      Parameters:
      localName - Attribute local name (must be non-empty) in default namespace (one with URI of "")
      value - Attribute value (if null, coerced to empty String)
      Returns:
      This initializer for call chaining
      Since:
      3.2

    • addXmlDeclaration

      public XmlGeneratorInitializer addXmlDeclaration(String version, String encoding)
      Method for specifying custom XML declaration to write.

      When a custom XML declaration is registered it fully replaces output that would otherwise be produced by XmlWriteFeature.WRITE_XML_DECLARATION, XmlWriteFeature.WRITE_XML_1_1 and XmlWriteFeature.WRITE_STANDALONE_YES_TO_XML_DECLARATION: those format features are ignored. Note that caller is responsible for ensuring the declared encoding matches the encoding the underlying Writer or OutputStream actually uses.

      Parameters:
      version - XML version: either "1.0" or "1.1"
      encoding - encoding content will be encoded in: usually "UTF-8"
      Returns:
      This initializer for call chaining

    • addXmlDeclaration

      public XmlGeneratorInitializer addXmlDeclaration(String version, String encoding, boolean standalone)
      Method for specifying custom XML declaration to write.

      See addXmlDeclaration(String, String) for details on how this interacts with XmlWriteFeature flags.

      Parameters:
      version - XML version: either "1.0" or "1.1"
      encoding - encoding content will be encoded in: usually "UTF-8"
      standalone - standalone pseudo-attribute value to write
      Returns:
      This initializer for call chaining

    • addXmlDeclaration

      public XmlGeneratorInitializer addXmlDeclaration(XmlDeclaration xmlDeclaration)
      Method for specifying custom XML declaration to write.

      See addXmlDeclaration(String, String) for details on how this interacts with XmlWriteFeature flags.

      Parameters:
      xmlDeclaration - declaration to write
      Returns:
      This initializer for call chaining

    • _add

      protected XmlGeneratorInitializer _add(PrologDirective d)