refactor: sync null-check guards and engine comments from 3.0.x

Author: loong10k

easypdf-beetl/src/main/java/io/github/easy4j/pdf/beetl/BeetlPdfTemplate.java

@@ -28,7 +28,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l beetl template extending WordprocessingMLTemplate.
+ * Beetl 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-core/src/main/java/io/github/easy4j/pdf/PdfTemplate.java

@@ -3,6 +3,7 @@
 import java.io.ByteArrayOutputStream;
 import java.io.OutputStream;
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * PDF 模板抽象：引擎适配器渲染模板为 HTML 后输出 PDF。
@@ -13,15 +14,17 @@ public abstract class PdfTemplate {
     /**
      * 渲染模板并输出 PDF。
      *
-     * @param template  模板内容/路径
-     * @param variables 模板变量
-     * @param out       PDF 输出流
+     * @param template  模板内容/路径，不能为 null
+     * @param variables 模板变量，不能为 null
+     * @param out       PDF 输出流，不能为 null
      * @throws Exception 渲染或转换异常
      */
     public abstract void process(String template, Map<String, Object> variables, OutputStream out) throws Exception;
 
     /** 便捷方法：渲染模板并返回 PDF 字节。 */
     public ByteArrayOutputStream process(String template, Map<String, Object> variables) throws Exception {
+        Objects.requireNonNull(template, "template must not be null");
+        Objects.requireNonNull(variables, "variables must not be null");
         ByteArrayOutputStream out = new ByteArrayOutputStream();
         process(template, variables, out);
         return out;

easypdf-core/src/main/java/io/github/easy4j/pdf/core/convert/HtmlPdfConverter.java

@@ -3,6 +3,7 @@
 import java.io.File;
 import java.io.IOException;
 import java.io.OutputStream;
+import java.util.Objects;
 
 import com.itextpdf.html2pdf.ConverterProperties;
 import com.itextpdf.html2pdf.HtmlConverter;
@@ -28,18 +29,22 @@ private HtmlPdfConverter() {
 
     /** 追加注册字体文件（服务器缺少系统字体时的扩展点）。 */
     public static void registerFont(String fontPath) {
+        Objects.requireNonNull(fontPath, "fontPath must not be null");
         FONT_PROVIDER.addFont(fontPath);
     }
 
     /** 将 HTML 字符串渲染为 PDF 写入输出流（自动处理中文字体）。 */
     public static void htmlToPdf(String html, OutputStream out) throws IOException {
+        Objects.requireNonNull(html, "html must not be null");
+        Objects.requireNonNull(out, "out must not be null");
         ConverterProperties props = new ConverterProperties();
         props.setFontProvider(FONT_PROVIDER);
         HtmlConverter.convertToPdf(html, out, props);
     }
 
     /** 从 PDF 文件逐页提取纯文本。 */
     public static String pdfToText(File pdf) throws IOException {
+        Objects.requireNonNull(pdf, "pdf must not be null");
         StringBuilder sb = new StringBuilder();
         try (PdfDocument doc = new PdfDocument(new PdfReader(pdf))) {
             for (int i = 1; i <= doc.getNumberOfPages(); i++) {

easypdf-core/src/main/java/io/github/easy4j/pdf/template/AbstractStringTemplateWrappingPdfTemplate.java

@@ -2,6 +2,7 @@
 
 import java.io.OutputStream;
 import java.util.Map;
+import java.util.Objects;
 
 import io.github.easy4j.pdf.PdfTemplate;
 import io.github.easy4j.pdf.core.convert.HtmlPdfConverter;
@@ -17,6 +18,9 @@ protected AbstractStringTemplateWrappingPdfTemplate() {
 
     @Override
     public void process(String template, Map<String, Object> variables, OutputStream out) throws Exception {
+        Objects.requireNonNull(template, "template must not be null");
+        Objects.requireNonNull(variables, "variables must not be null");
+        Objects.requireNonNull(out, "out must not be null");
         String html = render(template, variables);
         HtmlPdfConverter.htmlToPdf(html, out);
     }

easypdf-httl/src/main/java/io/github/easy4j/pdf/httl/HttlPdfTemplate.java

@@ -29,7 +29,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l httl template extending WordprocessingMLTemplate.
+ * Httl 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-jetbrick/src/main/java/io/github/easy4j/pdf/jetbrick/JetbrickPdfTemplate.java

@@ -32,7 +32,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l jetbrick template extending WordprocessingMLTemplate.
+ * Jetbrick 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-jsp/src/main/java/io/github/easy4j/pdf/jsp/JspPdfTemplate.java

@@ -34,7 +34,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l jsp template extending WordprocessingMLTemplate.
+ * Jsp 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-rythm/src/main/java/io/github/easy4j/pdf/rythm/RythmPdfTemplate.java

@@ -29,7 +29,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l rythm template extending WordprocessingMLTemplate.
+ * Rythm 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-thymeleaf/src/main/java/io/github/easy4j/pdf/thymeleaf/ThymeleafPdfTemplate.java

@@ -32,7 +32,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l thymeleaf template extending WordprocessingMLTemplate.
+ * Thymeleaf 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */

easypdf-velocity/src/main/java/io/github/easy4j/pdf/velocity/VelocityPdfTemplate.java

@@ -29,7 +29,7 @@
 import io.github.easy4j.pdf.template.AbstractStringTemplateWrappingPdfTemplate;
 
 /**
- * Implementation of wordprocessing m l velocity template extending WordprocessingMLTemplate.
+ * Velocity 模板引擎适配器：渲染模板为 HTML 后输出 PDF。
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  */