Implement #90: allow adding attributes to root element (#859)

Author: cowtowncoder

release-notes/VERSION

@@ -12,6 +12,8 @@ Version: 3.x (for earlier see VERSION-2.x)
 #27: `@JacksonXmlElementWrapper` conflicting getter/setter definitions for property
  (reported by @n00bman)
  (fix by @cowtowncoder, w/ Claude code)
+#90: Add support for adding attributes to output for root element
+ (fix by @cowtowncoder, w/ Claude code)
 #149: `@JacksonXmlElementWrapper` as a `@JsonCreator parameter` not working
  (reported by Dai M)
  (fix by Christopher M))

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

@@ -0,0 +1,49 @@
+package tools.jackson.dataformat.xml.ser;
+
+import java.util.Objects;
+
+import javax.xml.namespace.QName;
+import javax.xml.stream.XMLStreamException;
+
+import org.codehaus.stax2.XMLStreamWriter2;
+
+import tools.jackson.dataformat.xml.util.ArgUtil;
+
+/**
+ * Value container to represent an attribute to add to the root XML element
+ * being written, to be registered via
+ * {@link XmlGeneratorInitializer#addRootAttribute(QName, String)}
+ * (or its String-name overload).
+ *<p>
+ * Typical use case is adding XML Schema instance attributes such as
+ * {@code xsi:schemaLocation} or {@code xsi:noNamespaceSchemaLocation},
+ * but any attribute can be added.
+ *<p>
+ * NOTE: root attributes are only emitted when the root value being serialized
+ * produces a structured (object) start element; scalar root values (e.g.
+ * a bare {@code String}) do not currently get root attributes attached.
+ *
+ * @since 3.2
+ */
+public record RootAttribute(QName name, String value)
+    implements XmlGeneratorWritable
+{
+    public RootAttribute {
+        Objects.requireNonNull(name, "name");
+        ArgUtil.nonEmptyNonNull("name.localPart", name.getLocalPart());
+        value = ArgUtil.nullToEmpty(value);
+    }
+
+    @Override
+    public void write(ToXmlGenerator xmlGen, XMLStreamWriter2 sw) throws XMLStreamException {
+        final String ns = name.getNamespaceURI();
+        if (ns == null || ns.isEmpty()) {
+            sw.writeAttribute(name.getLocalPart(), value);
+        } else {
+            // Use prefix from QName if present; Stax will fall back to a bound
+            // prefix when prefix is empty but namespace URI is registered
+            // (e.g. via XmlGeneratorInitializer.addNamespace("xsi", ...)).
+            sw.writeAttribute(name.getPrefix(), ns, name.getLocalPart(), value);
+        }
+    }
+}

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

@@ -120,6 +120,13 @@ public class ToXmlGenerator
      */
     protected List<PrologDirective> _prologDirectives;
 
+    /**
+     * Attributes to add to the root element, if any.
+     *
+     * @since 3.2
+     */
+    protected List<RootAttribute> _rootAttributes;
+
     /**
      * Whether linefeed ("pretty-printing") enabled between directives
      * in Document prolog.
@@ -250,7 +257,8 @@ public ToXmlGenerator(ObjectWriteContext writeCtxt, IOContext ioCtxt,
     public void initDocument(XmlDeclaration xmlDeclaration,
             boolean lfBetweenPrologDirectives,
             List<PrologDirective> directives,
-            List<NamespaceBinding> nsBindings)
+            List<NamespaceBinding> nsBindings,
+            List<RootAttribute> rootAttributes)
     {
         if (_initialized) { // sanity check
             _reportError("Internal error: cannot call `initDocument()` after generator already initialized");
@@ -259,6 +267,7 @@ public void initDocument(XmlDeclaration xmlDeclaration,
         _namespaceBindings = nsBindings;
         _lfBetweenPrologDirectives = lfBetweenPrologDirectives;
         _prologDirectives = directives;
+        _rootAttributes = rootAttributes;
     }
 
     /**
@@ -775,8 +784,13 @@ public final void _handleStartObject() throws JacksonException
 
     // @since 3.2
     protected void _handleStartRootObject(QName rootElemName) throws XMLStreamException {
-        // !!! TODO: special handling
-        _xmlWriter.writeStartElement(_nextName.getNamespaceURI(), _nextName.getLocalPart());
+        _xmlWriter.writeStartElement(rootElemName.getNamespaceURI(), rootElemName.getLocalPart());
+        // [dataformat-xml#90]: emit caller-registered root attributes (e.g. xsi:schemaLocation)
+        if (_rootAttributes != null) {
+            for (RootAttribute attr : _rootAttributes) {
+                attr.write(this, _xmlWriter);
+            }
+        }
     }
 
     // note: public just because pretty printer needs to make a callback

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

@@ -3,6 +3,8 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import javax.xml.namespace.QName;
+
 import tools.jackson.core.JacksonException;
 import tools.jackson.core.JsonGenerator;
 import tools.jackson.core.exc.StreamWriteException;
@@ -47,6 +49,13 @@ public class XmlGeneratorInitializer
      */
     protected List<NamespaceBinding> _namespaceBindings;
 
+    /**
+     * Attributes to add to root element (if any).
+     *
+     * @since 3.2
+     */
+    protected List<RootAttribute> _rootAttributes;
+
     /**
      * Custom XML declaration to write.
      */
@@ -61,7 +70,7 @@ public void initialize(SerializationConfig config, JsonGenerator g) throws Jacks
         if (g instanceof ToXmlGenerator xg) {
             xg.initDocument(_xmlDeclaration,
                     _addLfBetweenPrologDirectives, _directives,
-                    _namespaceBindings);
+                    _namespaceBindings, _rootAttributes);
         }
     }
 
@@ -178,6 +187,50 @@ public XmlGeneratorInitializer addNamespace(String prefix, String namespaceURI)
         return this;
     }
 
+    /**
+     * 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.
+     *<p>
+     * Typical use case is adding XML Schema instance attributes such as
+     * {@code xsi:schemaLocation} or {@code xsi:noNamespaceSchemaLocation}.
+     *<p>
+     * 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.
+     *
+     * @param name Attribute name (with optional namespace and prefix)
+     * @param value Attribute value (null is coerced to empty String)
+     *
+     * @return This initializer for call chaining
+     *
+     * @since 3.2
+     */
+    public XmlGeneratorInitializer addRootAttribute(QName name, String value) {
+        if (_rootAttributes == null) {
+            _rootAttributes = new ArrayList<>();
+        }
+        _rootAttributes.add(new RootAttribute(name, value));
+        return this;
+    }
+
+    /**
+     * Convenience overload of {@link #addRootAttribute(QName, String)} for
+     * adding non-namespaced attribute by local name.
+     *
+     * @param localName Attribute local name (must be non-empty) in default
+     *   namespace (one with URI of "")
+     * @param value Attribute value (if {@code null}, coerced to empty String)
+     *
+     * @return This initializer for call chaining
+     *
+     * @since 3.2
+     */
+    public XmlGeneratorInitializer addRootAttribute(String localName, String value) {
+        return addRootAttribute(new QName(localName), value);
+    }
+
     /**
      * Method for specifying custom XML declaration to write.
      *<p>