Implement #849: allow adding comments in doc prolog

Author: cowtowncoder

release-notes/VERSION

@@ -119,6 +119,8 @@ Version: 3.x (for earlier see VERSION-2.x)
  (fix by @cowtowncoder, w/ Claude code)
 #845: Implement `JsonGenerator` methods `writeComment()` and `canWriteComments()`
  (implemented by @cowtowncoder, w/ Claude code)
+#849: Allow writing Comments in Document Prolog (before root element)
+ (implemented by @cowtowncoder)
 
 3.1.2 (11-Apr-2026)
 3.1.1 (27-Mar-2026)

src/main/java/tools/jackson/dataformat/xml/ser/Comment.java

@@ -0,0 +1,29 @@
+package tools.jackson.dataformat.xml.ser;
+
+import javax.xml.stream.XMLStreamException;
+
+import org.codehaus.stax2.XMLStreamWriter2;
+
+import tools.jackson.dataformat.xml.util.ArgUtil;
+
+/**
+ * Value container to represent XML Comment within "prolog"
+ * part of the Document (before XML Root element, after XML
+ * declaration if one written),
+ * to be written using {@link XmlGeneratorInitializer}.
+ *
+ * @since 3.2
+ */
+public record Comment(String content)
+    implements XmlPrologDirective
+{
+    public Comment {
+        content = ArgUtil.nullToEmpty(content);
+    }
+
+    @Override
+    public void write(ToXmlGenerator xmlGen, XMLStreamWriter2 sw) throws XMLStreamException {
+        sw.writeComment(content);
+    }
+    
+}

src/main/java/tools/jackson/dataformat/xml/ser/DTD.java

@@ -4,6 +4,8 @@
 
 import org.codehaus.stax2.XMLStreamWriter2;
 
+import tools.jackson.dataformat.xml.util.ArgUtil;
+
 /**
  * Value container to represent XML Document Type Declaration,
  * to be written using {@link XmlGeneratorInitializer}.
@@ -16,22 +18,10 @@ public record DTD(String rootName,
     implements XmlPrologDirective
 {
     public DTD {
-        rootName = _nonEmptyNonNull("rootName", rootName);
-        systemId = _emptyToNull(systemId);
-        publicId = _emptyToNull(publicId);
-        internalSubset = _emptyToNull(internalSubset);
-    }
-
-    static String _emptyToNull(String str) {
-        return "".equals(str) ? null : str;
-    }
-
-    static String _nonEmptyNonNull(String prop, String str) {
-        if (str == null || str.isEmpty()) {
-            throw new IllegalArgumentException("Illegal argument for '%s': must be non-empty String"
-                    .formatted(prop));
-        }
-        return str;
+        rootName = ArgUtil.nonEmptyNonNull("rootName", rootName);
+        systemId = ArgUtil.emptyToNull(systemId);
+        publicId = ArgUtil.emptyToNull(publicId);
+        internalSubset = ArgUtil.emptyToNull(internalSubset);
     }
 
     @Override

src/main/java/tools/jackson/dataformat/xml/ser/ToXmlGenerator.java

@@ -249,11 +249,8 @@ public void initGenerator() throws JacksonException
             }
 
             // as per [dataformat-xml#172], try adding indentation
-            if (xmlDeclWritten && (_xmlPrettyPrinter != null)) {
-                // ... but only if it is likely to succeed:
-                if (!_stax2Emulation) {
-                    _xmlPrettyPrinter.writePrologLinefeed(_xmlWriter);
-                }
+            if (xmlDeclWritten) {
+                _prologLinefeed();
             }
             if (XmlWriteFeature.AUTO_DETECT_XSI_TYPE.enabledIn(_formatFeatures)) {
                 _xmlWriter.setPrefix("xsi", XMLConstants.W3C_XML_SCHEMA_INSTANCE_NS_URI);
@@ -263,6 +260,8 @@ public void initGenerator() throws JacksonException
             if (_prologDirectives != null) {
                 for (XmlPrologDirective d : _prologDirectives) {
                     d.write(this, _xmlWriter);
+                    // Add linefeed separators b/w directives
+                    _prologLinefeed();
                 }
             }
 
@@ -271,6 +270,18 @@ public void initGenerator() throws JacksonException
         }
     }
 
+    // @since 3.2
+    private void _prologLinefeed() throws XMLStreamException
+    {
+        if (!_stax2Emulation) {
+            if (_xmlPrettyPrinter != null) {
+                _xmlPrettyPrinter.writePrologLinefeed(_xmlWriter);
+            } else {
+                _xmlWriter.writeSpace("\n");
+            }
+        }
+    }
+    
     /**
      * Method called by {@link XmlGeneratorInitializer} to inject
      * necessary configuration.

src/main/java/tools/jackson/dataformat/xml/ser/XmlGeneratorInitializer.java

@@ -38,6 +38,20 @@ public void initialize(SerializationConfig config, JsonGenerator g) throws Jacks
         }
     }
 
+    /**
+     * Method for adding XML comment; to be written in position added
+     * with respective to other directives
+     * (but always after XML Declaration which most come before any other output;
+     * and before Document Root element)
+     *
+     * @param commentContent (option) Comment content to include
+     *
+     * @return This initializer for call chaining
+     */
+    public XmlGeneratorInitializer addComment(String commentContent) {
+        return _add(new Comment(commentContent));
+    }
+
     /**
      * Convenience method that constructs {@link DTD} out of arguments
      * and calls {@link #addDTD(DTD)}.
@@ -57,10 +71,10 @@ public XmlGeneratorInitializer addDTD(String rootName,
     }
 
     /**
-     * Method for adding Document Type Declaration (DTD) directive; to write
-     * in order added with respective to other directives (but always after
-     * XML Declaration which most come before any other output; and before
-     * Document Root element)
+     * Method for adding Document Type Declaration (DTD) directive; to
+     * be written in position added with respective to other directives
+     * (but always after XML Declaration which most come before any other output;
+     * and before Document Root element)
      *
      * @param dtd DTD to write
      *

src/main/java/tools/jackson/dataformat/xml/util/ArgUtil.java

@@ -0,0 +1,20 @@
+package tools.jackson.dataformat.xml.util;
+
+public abstract class ArgUtil
+{
+    public static String emptyToNull(String str) {
+        return "".equals(str) ? null : str;
+    }
+
+    public static String nullToEmpty(String str) {
+        return (str == null) ? "" : str;
+    }
+
+    public static String nonEmptyNonNull(String prop, String str) {
+        if (str == null || str.isEmpty()) {
+            throw new IllegalArgumentException("Illegal argument for '%s': must be non-empty String"
+                    .formatted(prop));
+        }
+        return str;
+    }
+}

src/test/java/tools/jackson/dataformat/xml/ser/XmlGeneratorInitializerTest.java

@@ -14,14 +14,15 @@ public class XmlGeneratorInitializerTest extends XmlTestUtil
 {
     private final XmlMapper MAPPER = newMapper();
 
-    // [dataformat-xml#150]: DTD writing -- ok cases
+    // // [dataformat-xml#150]: DTD writing -- ok cases
+
     @Test
     public void testDTDWithOnlyRootElement() throws Exception
     {
         ObjectWriter w = MAPPER.writer().with(
                 new XmlGeneratorInitializer()
                         .addDTD("StringBean", null, null, null));
-        assertEquals(a2q("<!DOCTYPE StringBean>"
+        assertEquals(a2q("<!DOCTYPE StringBean>\n"
                 +"<StringBean><text>test</text></StringBean>"),
                 w.writeValueAsString(new StringBean("test")));
     }
@@ -32,7 +33,7 @@ public void testDTDWithPublicId() throws Exception
         ObjectWriter w = MAPPER.writer().with(
                 new XmlGeneratorInitializer()
                         .addDTD("StringBean", "system", "http://foo.bar", ""));
-        assertEquals(a2q("<!DOCTYPE StringBean PUBLIC 'http://foo.bar' 'system'>"
+        assertEquals(a2q("<!DOCTYPE StringBean PUBLIC 'http://foo.bar' 'system'>\n"
                 +"<StringBean><text>test</text></StringBean>"),
                 w.writeValueAsString(new StringBean("test")));
     }
@@ -43,7 +44,7 @@ public void testDTDWithSystemIdOnly() throws Exception
         ObjectWriter w = MAPPER.writer().with(
                 new XmlGeneratorInitializer()
                         .addDTD("StringBean", "system", "", null));
-        assertEquals(a2q("<!DOCTYPE StringBean SYSTEM 'system'>"
+        assertEquals(a2q("<!DOCTYPE StringBean SYSTEM 'system'>\n"
                 +"<StringBean><text>test</text></StringBean>"),
                 w.writeValueAsString(new StringBean("test")));
     }
@@ -55,7 +56,7 @@ public void testDTDWithInternalSubset() throws Exception
                 new XmlGeneratorInitializer()
                         .addDTD("StringBean", "system", "http://foo.bar", "<!ELEMENT root (#PCDATA)>"));
         assertEquals(a2q("<!DOCTYPE StringBean PUBLIC 'http://foo.bar' 'system' "
-                +"[<!ELEMENT root (#PCDATA)>]>"
+                +"[<!ELEMENT root (#PCDATA)>]>\n"
                 +"<StringBean><text>test</text></StringBean>"),
                 w.writeValueAsString(new StringBean("test")));
     }
@@ -72,13 +73,13 @@ public void testDTDWithXmlDeclaration() throws Exception
                         .addDTD("StringBean", "system", "http://foo.bar", null));
         // XML declaration is emitted with single quotes, DOCTYPE with double quotes,
         // so cannot use a2q() on the whole string here.
-        assertEquals("<?xml version='1.0' encoding='UTF-8'?>"
-                +"<!DOCTYPE StringBean PUBLIC \"http://foo.bar\" \"system\">"
+        assertEquals("<?xml version='1.0' encoding='UTF-8'?>\n"
+                +"<!DOCTYPE StringBean PUBLIC \"http://foo.bar\" \"system\">\n"
                 +"<StringBean><text>test</text></StringBean>",
                 w.writeValueAsString(new StringBean("test")));
     }
 
-    // [dataformat-xml#150]: DTD writing -- failing cases
+    // // [dataformat-xml#150]: DTD writing -- failing cases
     @Test
     public void testDTDInvalidNoRoot() throws Exception
     {
@@ -92,5 +93,18 @@ public void testDTDInvalidNoRoot() throws Exception
         }
     }
 
-    // Other tests
+    // // [dataformat-xml#849]: Comment writing -- ok cases
+
+    @Test
+    public void testSimpleComment() throws Exception
+    {
+        ObjectWriter w = MAPPER.writer().with(
+                new XmlGeneratorInitializer()
+                        .addComment("Comment content!"));
+        assertEquals(a2q("<!--Comment content!-->\n"
+                +"<StringBean><text>test</text></StringBean>"),
+                w.writeValueAsString(new StringBean("test")));
+    }
+
+    // // Other tests
 }