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