log4j-docgen: Support attributes as a union of strict type and String

This update enhances the generated XML schema by allowing each attribute to accept either its strict, expected type or a `${...}` expression. This accommodates use cases where property substitution is used, but at the same time allows IDE auto-completions.

> [!WARNING]
> This PR depends on #190 and should not be reviewed until that is merged.

Closes #136

Author: ppkarwasz

log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/generator/SchemaGenerator.java

@@ -32,6 +32,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.TreeSet;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import javax.inject.Named;
@@ -67,6 +68,24 @@ public final class SchemaGenerator {
 
     private static final String CHARSET_NAME = "UTF-8";
 
+    private static final String PROPERTY_SUBSTITUTION_TYPE = "property-substitution";
+    private static final String BOOLEAN_TYPE = "boolean";
+    private static final String STRING_TYPE = "string";
+    private static final ScalarType BOOLEAN_SCALAR_TYPE = new ScalarType();
+
+    static {
+        BOOLEAN_SCALAR_TYPE.setClassName(BOOLEAN_TYPE);
+        final Description description = new Description();
+        description.setText(
+                "A custom boolean type that allows `true`, `false`, or a property substitution expression.");
+        BOOLEAN_SCALAR_TYPE.setDescription(description);
+        for (final Boolean value : new Boolean[] {true, false}) {
+            final ScalarValue scalarValue = new ScalarValue();
+            scalarValue.setName(value.toString());
+            BOOLEAN_SCALAR_TYPE.addValue(scalarValue);
+        }
+    }
+
     private static final Map<String, String> XML_BUILTIN_TYPES = Map.ofEntries(
             entry(BigDecimal.class.getName(), "decimal"),
             entry(BigInteger.class.getName(), "integer"),
@@ -138,6 +157,12 @@ private static void writeSchema(final String version, final TypeLookup lookup, f
     }
 
     private static void writeTypes(final TypeLookup lookup, final XMLStreamWriter writer) throws XMLStreamException {
+        writePropertySubstitutionType(writer);
+        // A union with member types `xsd:boolean` and `log4j:property-substitution` does not allow auto-completion
+        // in IDEs. This is why we define a `log4j:boolean` type from scratch.
+        writeScalarType(BOOLEAN_SCALAR_TYPE, writer);
+        writeUnionBuiltinTypes(writer);
+
         for (final ArtifactSourcedType sourcedType : lookup.values()) {
             final Type type = sourcedType.type;
             if (isBuiltinXmlType(type.getClassName())) {
@@ -167,12 +192,66 @@ private static boolean isBuiltinXmlType(final String className) {
         return XML_BUILTIN_TYPES.containsKey(className);
     }
 
+    /**
+     * A restriction of {@code string} that requires at least one property substitution expression {@code ${...}}.
+     */
+    private static void writePropertySubstitutionType(final XMLStreamWriter writer) throws XMLStreamException {
+        writer.writeStartElement(XSD_NAMESPACE, "simpleType");
+        writer.writeAttribute("name", PROPERTY_SUBSTITUTION_TYPE);
+
+        writeDocumentation("A string with a property substitution expression.", writer);
+
+        writer.writeStartElement(XSD_NAMESPACE, "restriction");
+        writer.writeAttribute("base", "string");
+
+        writer.writeEmptyElement(XSD_NAMESPACE, "pattern");
+        writer.writeAttribute("value", ".*\\$\\{.*\\}.*");
+
+        writer.writeEndElement();
+        writer.writeEndElement();
+    }
+
+    /**
+     * Define types that are the union of a builtin type and {@value PROPERTY_SUBSTITUTION_TYPE}.
+     * <p>
+     *     IDEs don't propose auto-completion for these types.
+     * </p>
+     */
+    private static void writeUnionBuiltinTypes(final XMLStreamWriter writer) throws XMLStreamException {
+        final Collection<String> types = new TreeSet<>(XML_BUILTIN_TYPES.values());
+        // `xsd:string` is a superset of PROPERTY_SUBSTITUTION_TYPE, so no union is needed.
+        types.remove(STRING_TYPE);
+        // The union of `xsd:boolean` with PROPERTY_SUBSTITUTION_TYPE does not show auto-completion in IDEs.
+        // `log4j:boolean` will be generated from an _ad-hoc_ ScalarType definition in `base-log4j-types.xml`.
+        types.remove(BOOLEAN_TYPE);
+        for (final String type : types) {
+            writeUnionBuiltinType(type, writer);
+        }
+    }
+
+    private static void writeUnionBuiltinType(final String type, final XMLStreamWriter writer)
+            throws XMLStreamException {
+        writer.writeStartElement(XSD_NAMESPACE, "simpleType");
+        writer.writeAttribute("name", type);
+
+        writeDocumentation("Union of `xsd:" + type + "` and ` " + PROPERTY_SUBSTITUTION_TYPE + "`.", writer);
+
+        writer.writeEmptyElement(XSD_NAMESPACE, "union");
+        writer.writeAttribute("memberTypes", type + " log4j:" + PROPERTY_SUBSTITUTION_TYPE);
+
+        writer.writeEndElement();
+    }
+
     private static void writeScalarType(final ScalarType type, final XMLStreamWriter writer) throws XMLStreamException {
         writer.writeStartElement(XSD_NAMESPACE, "simpleType");
         writer.writeAttribute("name", type.getClassName());
 
         writeDocumentation(type.getDescription(), writer);
 
+        writer.writeStartElement(XSD_NAMESPACE, "union");
+        writer.writeAttribute("memberTypes", "log4j:" + PROPERTY_SUBSTITUTION_TYPE);
+        writer.writeStartElement(XSD_NAMESPACE, "simpleType");
+
         writer.writeStartElement(XSD_NAMESPACE, "restriction");
         writer.writeAttribute("base", "string");
 
@@ -182,6 +261,8 @@ private static void writeScalarType(final ScalarType type, final XMLStreamWriter
 
         writer.writeEndElement();
         writer.writeEndElement();
+        writer.writeEndElement();
+        writer.writeEndElement();
     }
 
     private static void writePluginType(
@@ -240,22 +321,30 @@ private static void writeAbstractType(
     private static void writeDocumentation(@Nullable final Description description, final XMLStreamWriter writer)
             throws XMLStreamException {
         if (description != null) {
-            writer.writeStartElement(XSD_NAMESPACE, "annotation");
-            writer.writeStartElement(XSD_NAMESPACE, "documentation");
-            writer.writeCharacters(description.getText());
-            writer.writeEndElement();
-            writer.writeEndElement();
+            writeDocumentation(description.getText(), writer);
         }
     }
 
+    private static void writeDocumentation(final String text, final XMLStreamWriter writer) throws XMLStreamException {
+        writer.writeStartElement(XSD_NAMESPACE, "annotation");
+        writer.writeStartElement(XSD_NAMESPACE, "documentation");
+        writer.writeCharacters(text);
+        writer.writeEndElement();
+        writer.writeEndElement();
+    }
+
     private static void writeScalarValue(final ScalarValue value, final XMLStreamWriter writer)
             throws XMLStreamException {
-        writer.writeStartElement(XSD_NAMESPACE, "enumeration");
-        writer.writeAttribute("value", value.getName());
-
-        writeDocumentation(value.getDescription(), writer);
-
-        writer.writeEndElement();
+        final Description description = value.getDescription();
+        if (description != null) {
+            writer.writeStartElement(XSD_NAMESPACE, "enumeration");
+            writer.writeAttribute("value", value.getName());
+            writeDocumentation(value.getDescription(), writer);
+            writer.writeEndElement();
+        } else {
+            writer.writeEmptyElement(XSD_NAMESPACE, "enumeration");
+            writer.writeAttribute("value", value.getName());
+        }
     }
 
     private static void writePluginElement(
@@ -303,25 +392,28 @@ private static void writePluginElement(
     private static void writePluginAttribute(
             final TypeLookup lookup, final PluginAttribute attribute, final XMLStreamWriter writer)
             throws XMLStreamException {
-        @Nullable final String xmlType = getXmlType(lookup, attribute.getType());
-        if (xmlType == null) {
-            return;
+        final String xmlType = getXmlType(lookup, attribute.getType());
+        final Description description = attribute.getDescription();
+        if (description != null) {
+            writer.writeStartElement(XSD_NAMESPACE, "attribute");
+        } else {
+            writer.writeEmptyElement(XSD_NAMESPACE, "attribute");
         }
-        writer.writeStartElement(XSD_NAMESPACE, "attribute");
         writer.writeAttribute("name", attribute.getName());
-        writer.writeAttribute("type", xmlType);
-        final Description description = attribute.getDescription();
+        // If the type is unknown, use `string`
+        writer.writeAttribute("type", xmlType != null ? xmlType : "string");
         if (description != null) {
             writeDocumentation(description, writer);
+            writer.writeEndElement();
         }
-        writer.writeEndElement();
     }
 
     @Nullable
     private static String getXmlType(final TypeLookup lookup, final String className) {
         final String builtinType = XML_BUILTIN_TYPES.get(className);
         if (builtinType != null) {
-            return builtinType;
+            // Use the union types for all built-in types, except `string`.
+            return STRING_TYPE.equals(builtinType) ? STRING_TYPE : LOG4J_PREFIX + ":" + builtinType;
         }
         final ArtifactSourcedType type = lookup.get(className);
         return type != null ? LOG4J_PREFIX + ":" + className : null;