View Javadoc
1   /*
2    * Copyright (c) 2002-2026 Gargoyle Software Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * https://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  package org.htmlunit.html.serializer;
16  
17  import static org.htmlunit.BrowserVersionFeatures.JS_INNER_HTML_XHTML_BOOLEAN_ATTRIBUTE_VALUE;
18  import static org.htmlunit.BrowserVersionFeatures.JS_INNER_HTML_XHTML_HEX_LINE_BREAK;
19  import static org.htmlunit.BrowserVersionFeatures.JS_INNER_HTML_XHTML_NS_DECLARATION_AFTER_ATTRIBUTE;
20  
21  import java.util.Collection;
22  import java.util.HashMap;
23  import java.util.Map;
24  import java.util.Objects;
25  import java.util.Set;
26  
27  import javax.xml.XMLConstants;
28  
29  import org.htmlunit.BrowserVersion;
30  import org.htmlunit.html.DomAttr;
31  import org.htmlunit.html.DomCDataSection;
32  import org.htmlunit.html.DomComment;
33  import org.htmlunit.html.DomDocumentFragment;
34  import org.htmlunit.html.DomElement;
35  import org.htmlunit.html.DomNode;
36  import org.htmlunit.html.DomProcessingInstruction;
37  import org.htmlunit.html.DomText;
38  import org.htmlunit.html.Html;
39  import org.htmlunit.html.HtmlElement;
40  import org.htmlunit.html.HtmlTemplate;
41  import org.htmlunit.util.StringUtils;
42  import org.htmlunit.util.XmlUtils;
43  
44  /**
45   * The XML serialization used by innerHTML/outerHTML for XHTML and XML documents.
46   * <p>This is a simplified implementation of the algorithm described in
47   * <a href="https://w3c.github.io/DOM-Parsing/#xml-serialization">DOM Parsing and Serialization -
48   * XML serialization</a>: namespace declarations are added if the namespace of an element
49   * (or the prefix of an attribute) is not declared by the context; elements without children
50   * are written as empty elements.</p>
51   *
52   * @author Ronald Brill
53   */
54  public final class XmlMarkupSerializer {
55  
56      /** Boolean attributes written as name="name" if the value is empty (Firefox). */
57      private static final Set<String> BOOLEAN_ATTRIBUTES = Set.of(
58              "checked", "compact", "declare", "defer", "disabled", "ismap", "multiple",
59              "nohref", "noresize", "noshade", "nowrap", "readonly", "selected");
60  
61      /** The start of the name of a prefix declaration attribute (xmlns:foo). */
62      private static final String XMLNS_PREFIX = XMLConstants.XMLNS_ATTRIBUTE + ":";
63  
64      private final boolean booleanAttributeValue_;
65      private final boolean hexLineBreak_;
66      private final boolean declarationAfterAttribute_;
67  
68      /**
69       * Ctor.
70       *
71       * @param browserVersion the browser version used to determine the browser specific details
72       */
73      private XmlMarkupSerializer(final BrowserVersion browserVersion) {
74          booleanAttributeValue_ = browserVersion.hasFeature(JS_INNER_HTML_XHTML_BOOLEAN_ATTRIBUTE_VALUE);
75          hexLineBreak_ = browserVersion.hasFeature(JS_INNER_HTML_XHTML_HEX_LINE_BREAK);
76          declarationAfterAttribute_ = browserVersion.hasFeature(JS_INNER_HTML_XHTML_NS_DECLARATION_AFTER_ATTRIBUTE);
77      }
78  
79      /**
80       * Serializes the children of the given node (the innerHTML).
81       *
82       * @param node the node whose children are serialized
83       * @param browserVersion the browser version used to determine the browser specific details
84       * @return the serialized children
85       */
86      public static String serializeChildren(final DomNode node, final BrowserVersion browserVersion) {
87          final StringBuilder builder = new StringBuilder();
88          new XmlMarkupSerializer(browserVersion).appendChildren(builder, node, null, newPrefixMap());
89          return builder.toString();
90      }
91  
92      /**
93       * Serializes the given node including the node itself (the outerHTML).
94       *
95       * @param node the node to serialize
96       * @param browserVersion the browser version used to determine the browser specific details
97       * @return the serialized node
98       */
99      public static String serialize(final DomNode node, final BrowserVersion browserVersion) {
100         final StringBuilder builder = new StringBuilder();
101         new XmlMarkupSerializer(browserVersion).appendNode(builder, node, null, newPrefixMap());
102         return builder.toString();
103     }
104 
105     /**
106      * Creates the initial prefix map; only the xml prefix is declared.
107      *
108      * @return the prefix map (prefix to namespace)
109      */
110     private static Map<String, String> newPrefixMap() {
111         final Map<String, String> prefixMap = new HashMap<>();
112         prefixMap.put(XMLConstants.XML_NS_PREFIX, XMLConstants.XML_NS_URI);
113         return prefixMap;
114     }
115 
116     /**
117      * Serializes all children of the given node; the children of a template
118      * are the children of the template content.
119      *
120      * @param builder the builder to write to
121      * @param node the parent node
122      * @param contextNamespace the default namespace of the context
123      * @param prefixMap the prefixes declared by the context (prefix to namespace)
124      */
125     private void appendChildren(final StringBuilder builder, final DomNode node,
126             final String contextNamespace, final Map<String, String> prefixMap) {
127         final DomNode parent = node instanceof HtmlTemplate template ? template.getContent() : node;
128         for (final DomNode child : parent.getChildren()) {
129             appendNode(builder, child, contextNamespace, prefixMap);
130         }
131     }
132 
133     /**
134      * Serializes a single node.
135      *
136      * @param builder the builder to write to
137      * @param node the node
138      * @param contextNamespace the default namespace of the context
139      * @param prefixMap the prefixes declared by the context (prefix to namespace)
140      */
141     private void appendNode(final StringBuilder builder, final DomNode node,
142             final String contextNamespace, final Map<String, String> prefixMap) {
143         if (node instanceof DomElement element) {
144             appendElement(builder, element, contextNamespace, prefixMap);
145         }
146         else if (node instanceof DomCDataSection) {
147             builder.append("<![CDATA[").append(node.getNodeValue()).append("]]>");
148         }
149         else if (node instanceof DomComment) {
150             builder.append("<!--").append(node.getNodeValue()).append("-->");
151         }
152         else if (node instanceof DomText) {
153             builder.append(StringUtils.escapeXmlChars(node.getNodeValue()));
154         }
155         else if (node instanceof DomProcessingInstruction pi) {
156             builder.append("<?").append(pi.getTarget());
157             final String data = pi.getData();
158             if (!StringUtils.isEmptyOrNull(data)) {
159                 builder.append(' ').append(data);
160             }
161             builder.append("?>");
162         }
163         else if (node instanceof DomDocumentFragment) {
164             appendChildren(builder, node, contextNamespace, prefixMap);
165         }
166     }
167 
168     /**
169      * Serializes an element.
170      *
171      * @param builder the builder to write to
172      * @param element the element
173      * @param contextNamespace the default namespace of the context
174      * @param contextPrefixMap the prefixes declared by the context (prefix to namespace)
175      */
176     private void appendElement(final StringBuilder builder, final DomElement element,
177             final String contextNamespace, final Map<String, String> contextPrefixMap) {
178         final String namespace = namespaceOf(element);
179         final String prefix = element.getPrefix();
180         final Collection<DomAttr> attributes = element.getAttributesMap().values();
181 
182         // copy on write: most elements do not declare a prefix, therefore
183         // the map of the context is shared until the first change
184         Map<String, String> prefixMap = contextPrefixMap;
185 
186         // namespace declarations of the element itself (xmlns and xmlns:foo attributes)
187         String localDefaultNamespace = null;
188         boolean hasDefaultNamespaceAttribute = false;
189         for (final DomAttr attr : attributes) {
190             final String name = attr.getName();
191             if (XMLConstants.XMLNS_ATTRIBUTE.equals(name)) {
192                 hasDefaultNamespaceAttribute = true;
193                 localDefaultNamespace = StringUtils.isEmptyOrNull(attr.getValue()) ? null : attr.getValue();
194             }
195             else if (name.startsWith(XMLNS_PREFIX)) {
196                 prefixMap = writablePrefixMap(prefixMap, contextPrefixMap);
197                 prefixMap.put(name.substring(XMLNS_PREFIX.length()), attr.getValue());
198             }
199         }
200 
201         final String qualifiedName = prefix == null ? element.getLocalName() : prefix + ":" + element.getLocalName();
202         builder.append('<').append(qualifiedName);
203 
204         String childNamespace = contextNamespace;
205         if (prefix != null) {
206             if (!Objects.equals(prefixMap.get(prefix), namespace)) {
207                 appendDeclaration(builder, prefix, namespace);
208                 prefixMap = writablePrefixMap(prefixMap, contextPrefixMap);
209                 prefixMap.put(prefix, namespace);
210             }
211         }
212         else if (hasDefaultNamespaceAttribute) {
213             childNamespace = localDefaultNamespace;
214         }
215         else {
216             if (!Objects.equals(namespace, contextNamespace)) {
217                 appendDeclaration(builder, null, namespace);
218             }
219             childNamespace = namespace;
220         }
221 
222         // prefixes used by the attributes; written in front of all attributes
223         // or (Firefox) after the attribute
224         if (!declarationAfterAttribute_) {
225             for (final DomAttr attr : attributes) {
226                 if (isUndeclaredAttributePrefix(attr, prefixMap)) {
227                     appendDeclaration(builder, attr.getPrefix(), attr.getNamespaceURI());
228                     prefixMap = writablePrefixMap(prefixMap, contextPrefixMap);
229                     prefixMap.put(attr.getPrefix(), attr.getNamespaceURI());
230                 }
231             }
232         }
233 
234         for (final DomAttr attr : attributes) {
235             final boolean declare = declarationAfterAttribute_ && isUndeclaredAttributePrefix(attr, prefixMap);
236             if (attr.getSpecified()) {
237                 builder.append(' ').append(attr.getName()).append("=\"")
238                     .append(attributeValue(attr, namespace)).append('"');
239                 if (declare) {
240                     appendDeclaration(builder, attr.getPrefix(), attr.getNamespaceURI());
241                 }
242             }
243             if (declare) {
244                 prefixMap = writablePrefixMap(prefixMap, contextPrefixMap);
245                 prefixMap.put(attr.getPrefix(), attr.getNamespaceURI());
246             }
247         }
248 
249         final DomNode contentParent = element instanceof HtmlTemplate template ? template.getContent() : element;
250         if (contentParent.getFirstChild() == null) {
251             if (Html.XHTML_NAMESPACE.equals(namespace)) {
252                 // the void elements are written as <br /> in the XHTML namespace
253                 if (HtmlElement.isVoidElement(element.getLocalName())) {
254                     builder.append(" />");
255                     return;
256                 }
257                 builder.append("></").append(qualifiedName).append('>');
258                 return;
259             }
260             builder.append("/>");
261             return;
262         }
263 
264         builder.append('>');
265         appendChildren(builder, element, childNamespace, prefixMap);
266         builder.append("</").append(qualifiedName).append('>');
267     }
268 
269     /**
270      * Returns a prefix map that can be modified; the map of the context
271      * is copied on the first change.
272      *
273      * @param prefixMap the current prefix map of the element
274      * @param contextPrefixMap the prefix map of the context (never modified)
275      * @return a prefix map that can be modified
276      */
277     private static Map<String, String> writablePrefixMap(final Map<String, String> prefixMap,
278             final Map<String, String> contextPrefixMap) {
279         if (prefixMap == contextPrefixMap) {
280             return new HashMap<>(contextPrefixMap);
281         }
282         return prefixMap;
283     }
284 
285     /**
286      * Checks if the prefix of the given attribute requires a namespace declaration;
287      * this is the case if the prefix is not (or differently) declared by the context.
288      *
289      * @param attr the attribute
290      * @param prefixMap the prefixes declared so far (prefix to namespace)
291      * @return true if a namespace declaration is required
292      */
293     private static boolean isUndeclaredAttributePrefix(final DomAttr attr, final Map<String, String> prefixMap) {
294         final String attrNamespace = attr.getNamespaceURI();
295         final String attrPrefix = attr.getPrefix();
296         return attrNamespace != null && attrPrefix != null
297                 && !XMLConstants.XML_NS_URI.equals(attrNamespace)
298                 && !XMLConstants.XMLNS_ATTRIBUTE_NS_URI.equals(attrNamespace)
299                 && !XMLConstants.XMLNS_ATTRIBUTE.equals(attrPrefix)
300                 && !attrNamespace.equals(prefixMap.get(attrPrefix));
301     }
302 
303     /**
304      * Returns the escaped value of the attribute.
305      *
306      * @param attr the attribute
307      * @param elementNamespace the namespace of the element
308      * @return the escaped value
309      */
310     private String attributeValue(final DomAttr attr, final String elementNamespace) {
311         String value = attr.getValue();
312         if (booleanAttributeValue_
313                 && StringUtils.isEmptyOrNull(value)
314                 && attr.getPrefix() == null
315                 && Html.XHTML_NAMESPACE.equals(elementNamespace)
316                 && BOOLEAN_ATTRIBUTES.contains(attr.getName())) {
317             value = attr.getName();
318         }
319 
320         value = XmlUtils.escapeXmlAttributeValue(value);
321         if (hexLineBreak_) {
322             value = value.replace("&#10;", "&#xA;").replace("&#13;", "&#xD;");
323         }
324         return value;
325     }
326 
327     /**
328      * Appends a namespace declaration.
329      *
330      * @param builder the builder to write to
331      * @param prefix the prefix or {@code null} for the default namespace
332      * @param namespace the namespace or {@code null}
333      */
334     private static void appendDeclaration(final StringBuilder builder, final String prefix, final String namespace) {
335         builder.append(' ').append(XMLConstants.XMLNS_ATTRIBUTE);
336         if (prefix != null) {
337             builder.append(':').append(prefix);
338         }
339         builder.append("=\"");
340         if (namespace != null) {
341             builder.append(XmlUtils.escapeXmlAttributeValue(namespace));
342         }
343         builder.append('"');
344     }
345 
346     /**
347      * Returns the namespace of the element; HTML elements without namespace
348      * are in the XHTML namespace.
349      *
350      * @param element the element
351      * @return the namespace or {@code null}
352      */
353     private static String namespaceOf(final DomElement element) {
354         final String namespace = element.getNamespaceURI();
355         if (StringUtils.isEmptyOrNull(namespace)) {
356             return element instanceof HtmlElement ? Html.XHTML_NAMESPACE : null;
357         }
358         return namespace;
359     }
360 }