sync(2.0.x): backport 3.0.x optimizations (JDK 17 adaptation)

Port the non-dependency 3.0.x improvements to the 2.0.x line (JDK 17):
- Security: OGNL DefaultMemberAccess(false,false,false), Zip Slip canonical
  path check, strict variable mode (-Deasydoc.variable.strict=true)
- Correctness: font-mapper null-safe putIfAvailable, mergeDocx temp file
  deleted on stream close, try-with-resources IO cleanup (incl.
  ZipFolderHelper), mutable static cleanup (WMLPackageUtils.FACTORY final,
  FontMapperHolder volatile)
- Architecture: AbstractWmlTemplate skeleton + VariableReplacer SPI
  (sealed interface + record strategies, JDK 17) collapsing the 3 docx
  templates; EngineFactory + Renderer separation across 8 engine modules;
  beetl placeholder defaults aligned with test properties; httl/rythm/webit
  @deprecated; XHTMLDocumentHandler file:/jar: URL support; JSP variables
  injected as request attributes (javax.servlet namespace preserved)
- Build: javadoc plugin 3.11.2 -> 3.12.0 with native <doclint>none</doclint>

Full reactor verify on JDK 17 (Corretto 17): BUILD SUCCESS, all modules green
(core 338, xhtml 32, jsp 64, engines 8-20 each).

Author: loong10k

easydoc-beetl/src/main/java/io/github/easy4j/doc/beetl/EngineFactory.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2018, hiwepy (https://github.com/easy-4-java).
+ *
+ * Licensed 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 io.github.easy4j.doc.beetl;
+
+import java.io.IOException;
+import java.util.Map;
+
+import org.beetl.core.Configuration;
+import org.beetl.core.GroupTemplate;
+import org.beetl.core.resource.ClasspathResourceLoader;
+import org.docx4j.Docx4jProperties;
+import io.github.easy4j.doc.Docx4jConstants;
+
+/**
+ * Immutable factory that lazily creates and caches a Beetl {@link GroupTemplate}
+ * instance using double-checked locking.
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ */
+public final class EngineFactory {
+
+    private volatile GroupTemplate engine;
+
+    /**
+     * Returns the shared {@link GroupTemplate} instance, creating it on first access.
+     */
+    public GroupTemplate get() throws IOException {
+        GroupTemplate local = engine;
+        if (local == null) {
+            synchronized (this) {
+                local = engine;
+                if (local == null) {
+                    ClasspathResourceLoader loader = new ClasspathResourceLoader();
+                    Configuration cfg = Configuration.defaultConfiguration();
+                    cfg.setCharset(Docx4jProperties.getProperty("docx4j.beetl.charset", Docx4jConstants.DEFAULT_CHARSETNAME));
+                    cfg.setPlaceholderStart(Docx4jProperties.getProperty("docx4j.beetl.placeholderStart", "${"));
+                    cfg.setPlaceholderEnd(Docx4jProperties.getProperty("docx4j.beetl.placeholderEnd", "}"));
+                    cfg.setStatementStart(Docx4jProperties.getProperty("docx4j.beetl.statementStart", "<%"));
+                    cfg.setStatementEnd(Docx4jProperties.getProperty("docx4j.beetl.statementEnd", "%>"));
+                    cfg.setHtmlTagSupport(Docx4jProperties.getProperty("docx4j.beetl.htmlTagSupport", false));
+                    cfg.setHtmlTagFlag(Docx4jProperties.getProperty("docx4j.beetl.htmlTagFlag", "#"));
+                    cfg.setHtmlTagBindingAttribute(Docx4jProperties.getProperty("docx4j.beetl.htmlTagBindingAttribute", "var"));
+                    cfg.setNativeCall(Docx4jProperties.getProperty("docx4j.beetl.nativeCall", false));
+                    cfg.setDirectByteOutput(Docx4jProperties.getProperty("docx4j.beetl.directByteOutput", true));
+                    cfg.setStrict(Docx4jProperties.getProperty("docx4j.beetl.strict", false));
+                    cfg.setIgnoreClientIOError(Docx4jProperties.getProperty("docx4j.beetl.ignoreClientIOError", true));
+                    cfg.setErrorHandlerClass(Docx4jProperties.getProperty("docx4j.beetl.errorHandlerClass", "org.beetl.core.ConsoleErrorHandler"));
+
+                    Map<String, String> resourceMap = cfg.getResourceMap();
+                    resourceMap.put("root", Docx4jProperties.getProperty("docx4j.beetl.resource.root", "/"));
+                    resourceMap.put("autoCheck", Docx4jProperties.getProperty("docx4j.beetl.resource.autoCheck", "true"));
+                    resourceMap.put("functionRoot", Docx4jProperties.getProperty("docx4j.beetl.resource.functionRoot", "functions"));
+                    resourceMap.put("functionSuffix", Docx4jProperties.getProperty("docx4j.beetl.resource.functionSuffix", "html"));
+                    resourceMap.put("tagRoot", Docx4jProperties.getProperty("docx4j.beetl.resource.tagRoot", "htmltag"));
+                    resourceMap.put("tagSuffix", Docx4jProperties.getProperty("docx4j.beetl.resource.tagSuffix", "tag"));
+                    cfg.setResourceMap(resourceMap);
+                    local = new GroupTemplate(loader, cfg);
+                    engine = local;
+                }
+            }
+        }
+        return local;
+    }
+}

easydoc-beetl/src/main/java/io/github/easy4j/doc/beetl/Renderer.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2018, hiwepy (https://github.com/easy-4-java).
+ *
+ * Licensed 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 io.github.easy4j.doc.beetl;
+
+import java.util.Map;
+
+import org.beetl.core.GroupTemplate;
+import org.beetl.core.Template;
+
+/**
+ * Stateless renderer that delegates to the Beetl {@link GroupTemplate} to
+ * produce output from a named template and a set of variables.
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ */
+public final class Renderer {
+
+    /**
+     * Renders the given template using the supplied engine and variables.
+     *
+     * @param template  the template name / path
+     * @param variables the template variables
+     * @param engine    the Beetl engine to use
+     * @return the rendered output
+     */
+    public String render(String template, Map<String, Object> variables, GroupTemplate engine) throws Exception {
+        Template beeTemplate = engine.getTemplate(template);
+        beeTemplate.binding(variables);
+        return beeTemplate.render();
+    }
+}

easydoc-beetl/src/main/java/io/github/easy4j/doc/beetl/WordprocessingMLBeetlTemplate.java

@@ -23,13 +23,8 @@
 
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
-import org.beetl.core.Configuration;
 import org.beetl.core.GroupTemplate;
-import org.beetl.core.Template;
-import org.beetl.core.resource.ClasspathResourceLoader;
-import org.docx4j.Docx4jProperties;
 import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
-import io.github.easy4j.doc.Docx4jConstants;
 import io.github.easy4j.doc.WordprocessingMLTemplate;
 import io.github.easy4j.doc.xhtml.WordprocessingMLHtmlTemplate;
 
@@ -39,18 +34,20 @@
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */
 public class WordprocessingMLBeetlTemplate implements WordprocessingMLTemplate {
-	
-	protected GroupTemplate engine;
+
+	private final EngineFactory factory = new EngineFactory();
+	private final Renderer renderer = new Renderer();
+	protected volatile GroupTemplate engine;
 	protected WordprocessingMLHtmlTemplate mlHtmlTemplate;
 
 	public WordprocessingMLBeetlTemplate() {
 		this(false, false);
 	}
-	
+
 	public WordprocessingMLBeetlTemplate(boolean landscape, boolean altChunk) {
-		this.mlHtmlTemplate = new WordprocessingMLHtmlTemplate(landscape, altChunk) ;
+		this.mlHtmlTemplate = new WordprocessingMLHtmlTemplate(landscape, altChunk);
 	}
-	
+
 	public WordprocessingMLBeetlTemplate(WordprocessingMLHtmlTemplate template) {
 		this.mlHtmlTemplate = template;
 	}
@@ -59,7 +56,7 @@ public WordprocessingMLBeetlTemplate(WordprocessingMLHtmlTemplate template) {
 	public WordprocessingMLPackage process(File template, Map<String, Object> variables) throws Exception {
 		return this.process(FileUtils.readFileToString(template, StandardCharsets.UTF_8), variables);
 	}
-	
+
 	@Override
 	public WordprocessingMLPackage process(InputStream template, Map<String, Object> variables) throws Exception {
 		return this.process(IOUtils.toString(template, StandardCharsets.UTF_8), variables);
@@ -74,12 +71,7 @@ public WordprocessingMLPackage process(InputStream template, Map<String, Object>
 	 */
 	@Override
 	public WordprocessingMLPackage process(String template, Map<String, Object> variables) throws Exception {
-		//使用Beetl模板引擎渲染模板
-		Template beeTemplate = getEngine().getTemplate(template);
-		beeTemplate.binding(variables);
-		//获取模板渲染后的结果
-		String html = beeTemplate.render();
-		//使用HtmlTemplate进行渲染
+		String html = renderer.render(template, variables, getEngine());
 		return mlHtmlTemplate.process(html, variables);
 	}
 
@@ -90,57 +82,9 @@ public GroupTemplate getEngine() throws IOException {
 	public void setEngine(GroupTemplate engine) {
 		this.engine = engine;
 	}
-	
-	protected synchronized GroupTemplate getInternalEngine() throws IOException{
-        ClasspathResourceLoader loader = new ClasspathResourceLoader();
-        //加载默认参数
-        Configuration cfg = Configuration.defaultConfiguration();
-        //模板字符集
-        cfg.setCharset(Docx4jProperties.getProperty("docx4j.beetl.charset", Docx4jConstants.DEFAULT_CHARSETNAME));
-        //模板占位起始符号 
-        cfg.setPlaceholderStart(Docx4jProperties.getProperty("docx4j.beetl.placeholderStart", "${"));
-        //模板占位结束符号
-        cfg.setPlaceholderEnd(Docx4jProperties.getProperty("docx4j.beetl.placeholderEnd", "<%"));
-        //控制语句起始符号
-        cfg.setStatementStart(Docx4jProperties.getProperty("docx4j.beetl.statementStart", "%>"));
-        //控制语句结束符号
-        cfg.setStatementEnd(Docx4jProperties.getProperty("docx4j.beetl.statementEnd", "}"));
-        //是否允许html tag，在web编程中，有可能用到html tag，最好允许 
-        cfg.setHtmlTagSupport(Docx4jProperties.getProperty("docx4j.beetl.htmlTagSupport", false));
-        //html tag 标示符号 
-        cfg.setHtmlTagFlag(Docx4jProperties.getProperty("docx4j.beetl.htmlTagFlag", "#"));
-        //html 绑定的属性，如&lt;aa var="customer">
-        cfg.setHtmlTagBindingAttribute(Docx4jProperties.getProperty("docx4j.beetl.htmlTagBindingAttribute", "var"));
-        //是否允许直接调用class
-        cfg.setNativeCall(Docx4jProperties.getProperty("docx4j.beetl.nativeCall", false));
-        //输出模式，默认是字符集输出，改成byte输出提高性能 
-        cfg.setDirectByteOutput(Docx4jProperties.getProperty("docx4j.beetl.directByteOutput", true));
-        //严格mvc应用，只有变态的的人才打开此选项 
-        cfg.setStrict(Docx4jProperties.getProperty("docx4j.beetl.strict", false));
-        //是否忽略客户端的网络异常
-        cfg.setIgnoreClientIOError(Docx4jProperties.getProperty("docx4j.beetl.ignoreClientIOError", true));
-        //错误处理类
-        cfg.setErrorHandlerClass(Docx4jProperties.getProperty("docx4j.beetl.errorHandlerClass", "org.beetl.core.ConsoleErrorHandler"));
-        
-        //资源参数
-        Map<String,String> resourceMap = cfg.getResourceMap();
-        //classpath 跟路径
-        resourceMap.put("root", Docx4jProperties.getProperty("docx4j.beetl.resource.root", "/"));
-        //是否检测文件变化
-        resourceMap.put("autoCheck", Docx4jProperties.getProperty("docx4j.beetl.resource.autoCheck", "true"));
-        //自定义脚本方法文件位置
-        resourceMap.put("functionRoot", Docx4jProperties.getProperty("docx4j.beetl.resource.functionRoot", "functions"));
-        //自定义脚本方法文件的后缀
-        resourceMap.put("functionSuffix", Docx4jProperties.getProperty("docx4j.beetl.resource.functionSuffix", "html"));
-        //自定义标签文件位置
-        resourceMap.put("tagRoot", Docx4jProperties.getProperty("docx4j.beetl.resource.tagRoot", "htmltag"));
-        //自定义标签文件后缀
-        resourceMap.put("tagSuffix", Docx4jProperties.getProperty("docx4j.beetl.resource.tagSuffix", "tag"));
-        cfg.setResourceMap(resourceMap);
-        GroupTemplate engine = new GroupTemplate(loader, cfg);
-        // 设置模板引擎，减少重复初始化消耗
-        this.setEngine(engine);
-        return engine;
+
+	protected GroupTemplate getInternalEngine() throws IOException {
+		return factory.get();
 	}
 
 }

easydoc-beetl/src/test/java/io/github/easy4j/doc/beetl/WordprocessingMLBeetlCoverageTest.java

@@ -0,0 +1,51 @@
+package io.github.easy4j.doc.beetl;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+
+import org.beetl.core.GroupTemplate;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Coverage tests for EngineFactory DCL short-circuit and Renderer statelessness.
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ */
+@DisplayName("WordprocessingMLBeetlTemplate Coverage Tests")
+class WordprocessingMLBeetlCoverageTest {
+
+    /**
+     * Exercises the EngineFactory DCL short-circuit: consecutive calls to
+     * {@code factory.get()} must return the same instance without re-entering
+     * the synchronized block.
+     */
+    @Test
+    @DisplayName("EngineFactory.get() returns same cached instance on consecutive calls")
+    void engineFactoryReturnsSameInstanceOnConsecutiveCalls() throws Exception {
+        EngineFactory factory = new EngineFactory();
+        GroupTemplate first = factory.get();
+        assertNotNull(first);
+        GroupTemplate second = factory.get();
+        assertSame(first, second, "EngineFactory.get() must return the same cached instance");
+    }
+
+    /**
+     * Verifies that Renderer is stateless: it has no mutable instance fields.
+     */
+    @Test
+    @DisplayName("Renderer has no mutable instance fields (stateless)")
+    void rendererIsStateless() {
+        Field[] fields = Renderer.class.getDeclaredFields();
+        for (Field f : fields) {
+            if (!Modifier.isStatic(f.getModifiers())) {
+                assertTrue(Modifier.isFinal(f.getModifiers()),
+                        "Renderer field '" + f.getName() + "' must be final to guarantee statelessness");
+            }
+        }
+    }
+}