Class Serializer

java.lang.Object
eu.maveniverse.domtrip.Serializer
public class Serializer extends Object
Serializes XML node trees back to XML string format with configurable formatting options and lossless preservation for unmodified content.

The Serializer class is responsible for converting DomTrip's internal XML node tree back into XML text format. It provides intelligent formatting preservation that maintains the original formatting for unchanged content while applying new formatting rules to modified sections.

Serialization Features:

  • Selective Preservation - Preserves formatting only for unmodified content
  • Pretty Printing - Configurable indentation and formatting
  • Raw Mode - Completely unformatted output (no line breaks or indentation)
  • Automatic Detection - Intelligently detects and preserves existing formatting patterns
  • Attribute Formatting - Preserves quote styles and attribute order
  • Namespace Handling - Serialization of namespace declarations

Serialization Modes:

  • Preservation Mode (prettyPrint = false, default) - Maintains original formatting for unchanged content. Automatically detects formatting patterns in existing XML and preserves them when adding new content.
  • Pretty Print Mode (prettyPrint = true) - Applies consistent indentation and formatting using configured settings. When lineEnding = "" and indentString = "", produces raw mode output.

Raw Mode:

Raw mode produces XML with no line breaks or indentation, resulting in a single continuous line. This is useful for minimizing file size or when formatting is not desired. Raw mode can be achieved by setting both lineEnding and indentString to empty strings, or by using DomTripConfig.raw().

Automatic Formatting Detection:

When parsing existing XML documents, the system automatically detects the formatting style:

  • Raw formatting - XML with no line breaks or custom spacing is detected and preserved when adding new content
  • Pretty formatting - XML with consistent indentation is detected and preserved
  • Custom formatting - XML with custom spacing patterns is detected and preserved

Usage Examples:

// Basic serialization with preservation (default)
Serializer serializer = new Serializer();
String xml = serializer.serialize(document);

// Pretty printing with custom indentation
Serializer prettySerializer = new Serializer();
prettySerializer.setPrettyPrint(true);
prettySerializer.setIndentString("    "); // 4 spaces
prettySerializer.setLineEnding("\n");
String prettyXml = prettySerializer.serialize(document);

// Raw mode (no formatting)
Serializer rawSerializer = new Serializer(DomTripConfig.raw());
String rawXml = rawSerializer.serialize(document);
// Result: <root><child>content</child></root>

// Manual raw mode configuration
Serializer manualRaw = new Serializer();
manualRaw.setPrettyPrint(true);
manualRaw.setIndentString(""); // No indentation
manualRaw.setLineEnding("");   // No line endings

// Serialize to OutputStream with encoding
OutputStream outputStream = new FileOutputStream("output.xml");
serializer.serialize(document, outputStream);

// Using configuration
DomTripConfig config = DomTripConfig.prettyPrint()
    .withIndentString("\t")
    .withLineEnding("\r\n");
Serializer configSerializer = new Serializer(config);

Performance Considerations:

The Serializer is optimized for performance:

  • Uses StringBuilder for efficient string building
  • Avoids re-serializing unmodified content when possible
  • Provides both string and StringBuilder output methods
See Also:

  • Constructor Details

    • Serializer

      public Serializer()
      Creates a new Serializer with default settings.

      Default settings include two-space indentation, pretty printing disabled (which preserves original formatting), and standard line endings.

    • Serializer

      public Serializer(DomTripConfig config)
      Creates a new Serializer with the specified configuration.
      Parameters:
      config - the DomTripConfig to use for serialization settings

  • Method Details

    • indentString

      public String indentString()
      Gets the indentation string used for pretty printing.
      Returns:
      the indentation string

    • getIndentString

      @Deprecated public String getIndentString()
      Deprecated.
      Use indentString() instead.
      Gets the indentation string used for pretty printing.
      Returns:
      the indentation string

    • setIndentString

      public void setIndentString(String indentString)
      Sets the indentation string for pretty printing.
      Parameters:
      indentString - the indentation string, or null for default

    • isPrettyPrint

      public boolean isPrettyPrint()
      Checks if pretty printing is enabled.
      Returns:
      true if pretty printing is enabled, false otherwise

    • setPrettyPrint

      public void setPrettyPrint(boolean prettyPrint)
      Sets whether to enable pretty printing.
      Parameters:
      prettyPrint - true to enable pretty printing, false otherwise

    • lineEnding

      public String lineEnding()
      Gets the line ending string used for pretty printing.
      Returns:
      the line ending string

    • getLineEnding

      @Deprecated public String getLineEnding()
      Deprecated.
      Use lineEnding() instead.
      Gets the line ending string used for pretty printing.
      Returns:
      the line ending string

    • setLineEnding

      public void setLineEnding(String lineEnding)
      Sets the line ending string for pretty printing.
      Parameters:
      lineEnding - the line ending string, or null for default

    • emptyElementStyle

      public EmptyElementStyle emptyElementStyle()
      Gets the empty element style used for serialization.
      Returns:
      the empty element style

    • getEmptyElementStyle

      @Deprecated public EmptyElementStyle getEmptyElementStyle()
      Deprecated.
      Use emptyElementStyle() instead.
      Gets the empty element style used for serialization.
      Returns:
      the empty element style

    • setEmptyElementStyle

      public void setEmptyElementStyle(EmptyElementStyle emptyElementStyle)
      Sets the empty element style for serialization.
      Parameters:
      emptyElementStyle - the empty element style, or null for default

    • serialize

      public String serialize(Document document, DomTripConfig config)
      Serializes an XML document to string with custom configuration.

      Creates a temporary serializer with the specified configuration and uses it to serialize the document. This allows one-time use of different serialization settings without modifying this serializer.

      Parameters:
      document - the document to serialize
      config - the configuration to use for serialization
      Returns:
      the serialized XML string, or empty string if document is null

    • serialize

      public String serialize(Document document)
      Serializes an XML document to string using this serializer's configuration.

      If pretty printing is disabled and the document is unmodified, the original formatting will be preserved. Otherwise, the document will be serialized according to this serializer's configuration.

      Parameters:
      document - the document to serialize
      Returns:
      the serialized XML string, or empty string if document is null

    • serialize

      public void serialize(Document document, OutputStream outputStream) throws DomTripException
      Serializes an XML document to an OutputStream using the document's encoding.

      This method uses the document's encoding property to determine the character encoding for the output stream. If the document has no encoding specified, UTF-8 is used as the default.

      Parameters:
      document - the document to serialize
      outputStream - the OutputStream to write to
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public void serialize(Document document, OutputStream outputStream, Charset charset) throws DomTripException
      Serializes an XML document to an OutputStream using the specified charset.

      This method allows explicit control over the character encoding used for serialization, regardless of the document's encoding property.

      Parameters:
      document - the document to serialize
      outputStream - the OutputStream to write to
      charset - the character encoding to use
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public void serialize(Document document, OutputStream outputStream, String encoding) throws DomTripException
      Serializes an XML document to an OutputStream using the specified encoding.

      This method allows explicit control over the character encoding used for serialization, regardless of the document's encoding property.

      Parameters:
      document - the document to serialize
      outputStream - the OutputStream to write to
      encoding - the character encoding name to use
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public void serialize(Node node, OutputStream outputStream) throws DomTripException
      Serializes a single node to an OutputStream using UTF-8 encoding.
      Parameters:
      node - the node to serialize
      outputStream - the OutputStream to write to
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public void serialize(Node node, OutputStream outputStream, Charset charset) throws DomTripException
      Serializes a single node to an OutputStream using the specified charset.
      Parameters:
      node - the node to serialize
      outputStream - the OutputStream to write to
      charset - the character encoding to use
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public void serialize(Node node, OutputStream outputStream, String encoding) throws DomTripException
      Serializes a single node to an OutputStream using the specified encoding.
      Parameters:
      node - the node to serialize
      outputStream - the OutputStream to write to
      encoding - the character encoding name to use
      Throws:
      DomTripException - if serialization fails or I/O errors occur

    • serialize

      public String serialize(Node node)
      Serializes a single node to string.

      If pretty printing is disabled and the node is unmodified, the original formatting will be preserved. Otherwise, the node will be serialized according to this serializer's configuration.

      Parameters:
      node - the node to serialize
      Returns:
      the serialized XML string, or empty string if node is null