This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git


The following commit(s) were added to refs/heads/master by this push:
     new 1e3e4f0  Warn when a site or skin descriptor declares a newer model
1e3e4f0 is described below

commit 1e3e4f03b90e4be96b0a966963ba948db975d241
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 3 02:03:41 2026 +0000

    Warn when a site or skin descriptor declares a newer model
    
    The generated readers do not check the namespace version, so a site.xml or 
skin.xml written for a newer
    model fails with errors about unknown elements, which point nowhere near 
the cause. Sitetools now logs a
    warning naming the declared and the supported model version before reading 
the descriptor. Tests pin the
    supported versions to the ones the Modello readers are generated at.
    
    Closes #644
---
 .../apache/maven/doxia/tools/DefaultSiteTool.java  | 11 +++
 .../apache/maven/doxia/site/ModelNamespace.java    | 85 +++++++++++++++++++++
 .../maven/doxia/site/ModelNamespaceTest.java       | 88 ++++++++++++++++++++++
 .../doxia/siterenderer/DefaultSiteRenderer.java    | 15 +++-
 4 files changed, 198 insertions(+), 1 deletion(-)

diff --git 
a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/DefaultSiteTool.java
 
b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/DefaultSiteTool.java
index c24080c..85b8ea4 100644
--- 
a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/DefaultSiteTool.java
+++ 
b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/DefaultSiteTool.java
@@ -51,6 +51,7 @@ import org.apache.maven.doxia.site.LinkItem;
 import org.apache.maven.doxia.site.Logo;
 import org.apache.maven.doxia.site.Menu;
 import org.apache.maven.doxia.site.MenuItem;
+import org.apache.maven.doxia.site.ModelNamespace;
 import org.apache.maven.doxia.site.PublishDate;
 import org.apache.maven.doxia.site.SiteModel;
 import org.apache.maven.doxia.site.Skin;
@@ -1148,6 +1149,16 @@ public class DefaultSiteTool implements SiteTool {
                 return convertOldToNewSiteModel(
                         new DecorationXpp3Reader().read(new 
StringReader(siteDescriptorContent)));
             } else {
+                if (ModelNamespace.isNewerThan(siteDescriptorContent, "SITE", 
ModelNamespace.SITE_MODEL_VERSION)) {
+                    LOGGER.warn("Site descriptor" + (project == null ? "" : " 
of '" + project.getId() + "'")
+                            + " declares the site model "
+                            + 
ModelNamespace.declaredVersion(siteDescriptorContent, "SITE")
+                            + ", but this Doxia Sitetools reads the site model 
up to "
+                            + ModelNamespace.SITE_MODEL_VERSION
+                            + ": elements of the newer model are reported as 
unknown. Use a maven-site-plugin "
+                            + "with a newer Doxia Sitetools, or declare the "
+                            + ModelNamespace.SITE_MODEL_VERSION + " 
namespace.");
+                }
                 return new SiteXpp3Reader().read(new 
StringReader(siteDescriptorContent));
             }
         } catch (XmlPullParserException e) {
diff --git 
a/doxia-site-model/src/main/java/org/apache/maven/doxia/site/ModelNamespace.java
 
b/doxia-site-model/src/main/java/org/apache/maven/doxia/site/ModelNamespace.java
new file mode 100644
index 0000000..22ab119
--- /dev/null
+++ 
b/doxia-site-model/src/main/java/org/apache/maven/doxia/site/ModelNamespace.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.doxia.site;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Checks the namespace version of a site or skin descriptor against the model 
version this Doxia Sitetools reads.
+ * The generated readers do not check it, so a descriptor written for a newer 
model fails with errors about unknown
+ * elements instead of saying that the model is too new.
+ *
+ * @since 2.2.0
+ */
+public final class ModelNamespace {
+    /** The newest site descriptor model this version reads, as in {@code 
http://maven.apache.org/SITE/2.1.0}. */
+    public static final String SITE_MODEL_VERSION = "2.1.0";
+
+    /** The newest skin descriptor model this version reads, as in {@code 
http://maven.apache.org/SKIN/2.1.0}. */
+    public static final String SKIN_MODEL_VERSION = "2.1.0";
+
+    private static final Pattern NAMESPACE_VERSION =
+            
Pattern.compile("xmlns\\s*=\\s*[\"']http://maven\\.apache\\.org/(SITE|SKIN)/([0-9][0-9.]*)[\"']");
+
+    private ModelNamespace() {}
+
+    /**
+     * Returns the model version of the descriptor's {@code SITE} or {@code 
SKIN} namespace, if it declares one.
+     *
+     * @param descriptorContent the descriptor XML
+     * @param model {@code "SITE"} or {@code "SKIN"}
+     * @return the version, for example {@code "2.1.0"}, or {@code null} 
without such a namespace
+     */
+    public static String declaredVersion(String descriptorContent, String 
model) {
+        Matcher matcher = NAMESPACE_VERSION.matcher(descriptorContent);
+        while (matcher.find()) {
+            if (matcher.group(1).equals(model)) {
+                return matcher.group(2);
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Returns whether the descriptor declares a namespace for a newer model 
than {@code supportedVersion}.
+     *
+     * @param descriptorContent the descriptor XML
+     * @param model {@code "SITE"} or {@code "SKIN"}
+     * @param supportedVersion the newest model version that can be read
+     * @return {@code true} if the declared namespace version is newer than 
the supported one
+     */
+    public static boolean isNewerThan(String descriptorContent, String model, 
String supportedVersion) {
+        String declared = declaredVersion(descriptorContent, model);
+        return declared != null && compare(declared, supportedVersion) > 0;
+    }
+
+    private static int compare(String a, String b) {
+        String[] left = a.split("\\.");
+        String[] right = b.split("\\.");
+        for (int i = 0; i < Math.max(left.length, right.length); i++) {
+            int l = i < left.length && !left[i].isEmpty() ? 
Integer.parseInt(left[i]) : 0;
+            int r = i < right.length && !right[i].isEmpty() ? 
Integer.parseInt(right[i]) : 0;
+            if (l != r) {
+                return Integer.compare(l, r);
+            }
+        }
+        return 0;
+    }
+}
diff --git 
a/doxia-site-model/src/test/java/org/apache/maven/doxia/site/ModelNamespaceTest.java
 
b/doxia-site-model/src/test/java/org/apache/maven/doxia/site/ModelNamespaceTest.java
new file mode 100644
index 0000000..7ff6b19
--- /dev/null
+++ 
b/doxia-site-model/src/test/java/org/apache/maven/doxia/site/ModelNamespaceTest.java
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.doxia.site;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ModelNamespaceTest {
+
+    private static String site(String version) {
+        return "<site xmlns=\"http://maven.apache.org/SITE/"; + version + "\"\n"
+                + "  
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\";><body/></site>";
+    }
+
+    @Test
+    void declaredVersion() {
+        assertEquals("2.0.0", ModelNamespace.declaredVersion(site("2.0.0"), 
"SITE"));
+        assertEquals(
+                "2.1.0", ModelNamespace.declaredVersion("<skin 
xmlns='http://maven.apache.org/SKIN/2.1.0'/>", "SKIN"));
+        assertNull(ModelNamespace.declaredVersion(site("2.0.0"), "SKIN"));
+        assertNull(ModelNamespace.declaredVersion("<site><body/></site>", 
"SITE"));
+    }
+
+    @Test
+    void onlyANewerModelIsReported() {
+        assertFalse(ModelNamespace.isNewerThan(site("2.0.0"), "SITE", 
"2.1.0"));
+        assertFalse(ModelNamespace.isNewerThan(site("2.1.0"), "SITE", 
"2.1.0"));
+        assertTrue(ModelNamespace.isNewerThan(site("2.1.1"), "SITE", "2.1.0"));
+        assertTrue(ModelNamespace.isNewerThan(site("2.2.0"), "SITE", "2.1.0"));
+        assertTrue(ModelNamespace.isNewerThan(site("2.10"), "SITE", "2.1.0"));
+        // no namespace, or the 1.x decoration model: nothing to report
+        assertFalse(ModelNamespace.isNewerThan("<site><body/></site>", "SITE", 
"2.1.0"));
+        assertFalse(ModelNamespace.isNewerThan(
+                "<project 
xmlns=\"http://maven.apache.org/DECORATION/1.8.0\"/>", "SITE", "2.1.0"));
+    }
+
+    @Test
+    void supportedVersionsMatchTheModelsBuiltByModello() throws Exception {
+        // doxia-site-model/pom.xml generates site.mdo and skin.mdo readers at 
this version
+        String pom = new String(Files.readAllBytes(new 
File("pom.xml").toPath()), StandardCharsets.UTF_8);
+        Matcher matcher = Pattern.compile(
+                        
"<model>src/main/mdo/site\\.mdo</model>\\s*</models>\\s*(?:<!--.*?-->\\s*)?"
+                                + "<version>([^<]+)</version>",
+                        Pattern.DOTALL)
+                .matcher(pom);
+        assertTrue(matcher.find(), "site.mdo version in pom.xml");
+        assertEquals(matcher.group(1), ModelNamespace.SITE_MODEL_VERSION);
+    }
+
+    @Test
+    void supportedSkinVersionMatchesTheSkinModel() throws Exception {
+        // doxia-skin-model/pom.xml, next to this module, generates the 
skin.mdo reader at this version
+        String pom = new String(
+                Files.readAllBytes(new 
File("../doxia-skin-model/pom.xml").toPath()), StandardCharsets.UTF_8);
+        Matcher matcher = Pattern.compile(
+                        
"<model>src/main/mdo/skin\\.mdo</model>\\s*</models>\\s*(?:<!--.*?-->\\s*)?<version>([^<]+)</version>",
+                        Pattern.DOTALL)
+                .matcher(pom);
+        assertTrue(matcher.find(), "skin.mdo version in 
doxia-skin-model/pom.xml");
+        assertEquals(matcher.group(1), ModelNamespace.SKIN_MODEL_VERSION);
+    }
+}
diff --git 
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
 
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
index 1da9522..efc7203 100644
--- 
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
+++ 
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
@@ -23,6 +23,7 @@ import javax.inject.Named;
 import javax.inject.Singleton;
 
 import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
@@ -66,6 +67,7 @@ import 
org.apache.maven.doxia.parser.manager.ParserNotFoundException;
 import org.apache.maven.doxia.parser.module.ParserModule;
 import org.apache.maven.doxia.parser.module.ParserModuleManager;
 import org.apache.maven.doxia.site.LinkItem;
+import org.apache.maven.doxia.site.ModelNamespace;
 import org.apache.maven.doxia.site.SiteModel;
 import org.apache.maven.doxia.site.skin.ResourceCondition;
 import org.apache.maven.doxia.site.skin.SkinModel;
@@ -834,8 +836,19 @@ public class DefaultSiteRenderer implements Renderer {
             ZipEntry skinDescriptorEntry = 
zipFile.getEntry(SkinModel.SKIN_DESCRIPTOR_LOCATION);
             if (skinDescriptorEntry != null) {
                 in = zipFile.getInputStream(skinDescriptorEntry);
+                byte[] skinDescriptor = IOUtil.toByteArray(in);
+                String skinDescriptorContent =
+                        IOUtil.toString(new XmlStreamReader(new 
ByteArrayInputStream(skinDescriptor)));
+                if (ModelNamespace.isNewerThan(skinDescriptorContent, "SKIN", 
ModelNamespace.SKIN_MODEL_VERSION)) {
+                    LOGGER.warn("Skin " + skinId + " declares the skin model "
+                            + 
ModelNamespace.declaredVersion(skinDescriptorContent, "SKIN")
+                            + ", but this Doxia Sitetools reads the skin model 
up to "
+                            + ModelNamespace.SKIN_MODEL_VERSION
+                            + ": elements of the newer model are reported as 
unknown. Use a maven-site-plugin "
+                            + "with a newer Doxia Sitetools, or a skin version 
made for this one.");
+                }
 
-                SkinModel skinModel = new SkinXpp3Reader().read(in);
+                SkinModel skinModel = new SkinXpp3Reader().read(new 
ByteArrayInputStream(skinDescriptor));
                 context.setSkinModel(skinModel);
 
                 String toolsPrerequisite = skinModel.getPrerequisites() == null

Reply via email to