Next version (#260)

.github/workflows/qodana.yml

@@ -1,11 +1,11 @@
 name: Qodana
+
 on:
   workflow_dispatch:
   pull_request:
   push:
     branches:
       - main
-
 jobs:
   qodana:
     runs-on: ubuntu-latest
@@ -18,7 +18,17 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
           fetch-depth: 0  # a full history is required for pull request analysis
-
+
+      - name: Setup Java JDK
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: Build with Maven
+        run: mvn --batch-mode --no-transfer-progress verify
+
       - name: 'Qodana Scan'
         uses: JetBrains/qodana-action@v2023.3
         env:

CODE_OF_CONDUCT.md

@@ -6,7 +6,7 @@ In the interest of fostering an open and welcoming environment, we as
 contributors and maintainers pledge to make participation in our project and
 our community a harassment-free experience for everyone, regardless of age, body
 size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
+level of experience, education, socioeconomic status, nationality, personal
 appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
@@ -24,13 +24,13 @@ community include:
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+* The use of sexual language or imagery, and sexual attention or
   advances
 * Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+* Another conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities
@@ -56,11 +56,11 @@ representative at an online or offline event.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at .
+reported to the community leaders responsible for enforcement at abuse@verron.pro.
 All complaints will be reviewed and investigated promptly and fairly.
 
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
+All community leaders are obligated to respect the privacy and security of any incident
+reporter.
 
 ## Enforcement Guidelines
 
@@ -101,9 +101,9 @@ Violating these terms may lead to a permanent ban.
 
 ### 4. Permanent Ban
 
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
+**Community Impact**: Demonstrating a pattern of community
+standards violation, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes.
 
 **Consequence**: A permanent ban from any sort of public interaction within
 the community.
@@ -113,4 +113,4 @@ the community.
 This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version
 [1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and
 [2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md),
-and was generated by [contributing-gen](https://github.com/bttger/contributing-gen).
+and was generated by [contributing-gen](https://github.com/bttger/contributing-gen).

CONTRIBUTING.md

@@ -78,7 +78,8 @@ A good bug report shouldn't leave others needing to chase you up for more inform
 - Make sure that you are using the latest version.
 - Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](https://verronpro.github.io/docx-stamper/). If you are looking for support, you might want to check [this section](#i-have-a-question)).
 - To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/verronpro/docx-stamperissues?q=label%3Abug).
-- Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue.
+- Also make sure to search the internet (including Stack Overflow) to see if users outside the GitHub community have
+  discussed the issue.
 - Collect information about the bug:
 - Stack trace (Traceback)
 - OS, Platform and Version (Windows, Linux, macOS, x86, ARM)
@@ -89,7 +90,8 @@ A good bug report shouldn't leave others needing to chase you up for more inform
 <!-- omit in toc -->
 #### How Do I Submit a Good Bug Report?
 
-> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to security@verron.pro.
+> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue
+> tracker, or elsewhere in public. Instead, sensitive bugs must be sent by email to security@verron.pro.
 <!-- You may add a PGP key to allow the messages to be sent encrypted as well. -->
 
 We use GitHub issues to track bugs and errors. If you run into an issue with the project:
@@ -151,4 +153,4 @@ TODO
 
 <!-- omit in toc -->
 ## Attribution
-This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)!
+This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)!

README.adoc

@@ -2,7 +2,7 @@
 
 = docx-stamper
 
-image:https://github.com/verronpro/docx-stamper/actions/workflows/maven.yml/badge.svg[Build Status,link=https://github.com/verronpro/docx-stamper/actions/workflows/maven.yml]
+image:https://github.com/verronpro/docx-stamper/actions/workflows/maven.yml/badge.svg[Build Status,link=https://github.com/verronpro/docx-stamper/actions/workflows/integrate-ubuntu.yml] image:https://github.com/verronpro/docx-stamper/actions/workflows/maven.yml/badge.svg[Build Status,link=https://github.com/verronpro/docx-stamper/actions/workflows/integrate-windows.yml]
 
 docx-stamper is a Java template engine for docx documents.
 You create a template .docx document with your favorite word processor and feed it to a DocxStamper instance to create a document based on the template at runtime.
@@ -12,12 +12,22 @@ Example code:
 ----
 class Example {
     public static void main(String[] args) {
-        MyContext context = ...// your own POJO against which expressions found in the template will be resolved
-        InputStream template = ...// InputStream to your .docx template file
-        OutputStream out = ...// OutputStream in which to write the resulting .docx document
-        DocxStamper stamper = new DocxStamperConfiguration().build();
-        stamper.stamp(template, context, out);
-        out.close();
+        // your own POJO against which expressions found in the template will be resolved
+        var context = new YourPojoContext(_, _ , _);
+
+        // Path to your .docx template file
+        var templatePath = Paths.get("your/docx/template/file.docx");
+        // Path to write the resulting .docx document
+        var outputPath = Paths.get("your/desired/output/path.docx");
+
+        var stamper = new DocxStamper();
+
+        try(
+            var template = Files.newInputStream(templatePath);
+            var output = Files.newOutputStream(outputPath)
+        ) {
+            stamper.stamp(template, context, output);
+        }
     }
 }
 
@@ -45,18 +55,23 @@ The value an expression resolves to may be of the following types:
 |===
 
 If an expression cannot be resolved successfully, it will be skipped (meaning the expression stays in the document as it was in the template).
-To support more than the above types you can implement your own link:{repo}/src/main/java/org/wickedsource/docxstamper/api/typeresolver/ITypeResolver.java[TypeResolver].
-To register your own TypeResolver with docx-stamper, use the following code:
+To support more than the above types you can implement your own link:{repo}/src/main/java/pro/verron/docxstamper/api/ObjectResolver.java[ObjectResolver].
+To register your it with docx-stamper, use the following code:
 
 [source,java]
 ----
 class Main {
     public static void main(String... args) {
-        ITypeResolver typeResolver = ...// instance of your own ITypeResolver implementation
-        Class<?> type ...// class of expression values your resolver handles
-        DocxStamper stamper=new DocxStamperConfiguration()
-        .addTypeResolver(type,typeResolver)
-        .build();
+        // instance of your own ObjectResolver implementation
+        var resolver = new StringResolver(YourCustomType.class){
+            @Override public String resolve(YourCustomType object){
+                return custom.yourCustomProperty(); // or any convoluted method
+            }
+        };
+
+        var configuration = new DocxStamperConfiguration();
+        configuration.addResolver(resolver);
+        var stamper = new DocxStamper<>(configuration);
     }
 }
 ----
@@ -71,10 +86,10 @@ You can register an `EvaluationContextConfigurer` like this:
 ----
 class Main {
     public static void main(String... args) {
-        EvaluationContextConfigurer configurer = ...
-        DocxStamper stamper = new DocxStamperConfiguration()
-                .setEvaluationContextConfigurer(configurer)
-                .build();
+        var evalContextConfigurer = new NoOpEvaluationContextConfigurer();
+        var configuration = new DocxStamperConfiguration()
+            .setEvaluationContextConfigurer(configurer);
+        var stamper = new DocxStamper<>(configuration);
     }
 }
 ----
@@ -92,7 +107,7 @@ class Main {
         interface UppercaseFunction {
             String toUppercase(String string);
         }
-        
+
         DocxStamper stamper = new DocxStamperConfiguration()
                 .exposeInterfaceToExpressionLanguage(UppercaseFunction.class, String::toUppercase)
                 .build();
@@ -128,12 +143,20 @@ To register you comment processor to docx-stamper, use the following code:
 ----
 class Main {
     public static void main(String... args) {
-        ICommentProcessor commentProcessor = ...// instance of your own ICommentProcessor implementation
-        Class<?> interfaceClass = ...
-        // class of the interface that defines the methods that are exposed into the expression language
-        DocxStamper stamper = new DocxStamperConfiguration()
-                .addCommentProcessor(interfaceClass, commentProcessor)
-                .build();
+        // interface defining the methods to expose to the expression language
+        interface IYourCommentProcessor {
+            void yourComment(String _); // 1+ argument of the type you expect to see in the document
+            void yourSecondComment(String _, CustomType _); // theoretically, any number of comment can be added
+        }
+        class YourCommentProcessor extends BaseCommentProcessor {
+            @Override public void commitChanges(WordprocessingMLPackage document) {/*Do something to the document*/}
+            @Override public void reset() {/* reset processor state for re-run of the stamper */}
+        }
+        var commentProcessor = new YourCommentProcessor();
+        var configuration = new DocxStamperConfiguration()
+                .addCommentProcessor(IYourCommentProcessor.class, commentProcessor);
+        var stamper = new DocxStamper<>(configuration);
+
     }
 }
 ----
@@ -153,19 +176,19 @@ If you want to change this behavior, you can do the following:
 
 [source,java]
 ----
-class Main {
+import org.wickedsource.docxstamper.DocxStamper;class Main {
     public static void main(String... args) {
-        DocxStamper stamper = new DocxStamperConfiguration()
-                .setFailOnUnresolvedExpression(false)
-                .build();
+        var configuration = new DocxStamperConfiguration()
+                .setFailOnUnresolvedExpression(false);
+        var stamper = new DocxStamper<>(configuration);
     }
 }
 ----
 
 == Sample Code
 
 The source code contains a set of tests show how to use the features.
-If you want to run them yourself, clone the repository and run link:{repo}/src/test/java/org/wickedsource/docxstamper[the tests in the main package] with the system property `-DkeepOutputFile=true` so that the resulting .docx documents will not be cleaned up so you can view them.
+If you want to run them yourself, clone the repository and run link:{repo}/src/test/java/org/wickedsource/docxstamper[the tests in the main package] with the system property `-DkeepOutputFile=true` so that the resulting .docx documents will not be cleaned up and let you view them.
 The resulting files will be stored in your local temp folder (watch the logging output for the exact location of the files).
 
 If you want to have a look at the .docx templates used in the tests, have a look at the link:{repo}/src/test/resources/org/wickedsource/docxstamper[resources subfolder] in the test folder.
@@ -190,4 +213,4 @@ This way, you can choose which version of Docx4J you want to use instead having
 
 == Contribute
 
-If you have an issue or created a comment processor or type resolver that you think deserves to be part of the default distribution, feel free to open an issue or - even better - a pull request with your contribution.
+If you have an issue or created a comment processor or type resolver that you think deserves to be part of the default distribution, feel free to open an issue or - even better - a pull request with your contribution.

SECURITY.md

@@ -4,10 +4,10 @@
 
 Currently, only the latest version of our project is being supported with security updates.
 
-Version | Supported          
-------- | ------------------
-Latest  | :white_check_mark:
-< Older | :x:
+| Version | Supported          |
+|---------|--------------------|
+| Latest  | :white_check_mark: |
+| < Older | :x:                |
 
 ## Reporting a Vulnerability
 

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>pro.verron</groupId>
     <artifactId>docx-stamper</artifactId>
-    <version>1.6.7-SNAPSHOT</version>
+    <version>1.6.7</version>
     <packaging>jar</packaging>
     <name>docx-stamper</name>
 
@@ -91,7 +91,7 @@
                         </dependencies>
                         <executions>
                             <execution>
-                                <phase>pre-site</phase>
+                                <phase>post-integration-test</phase>
                                 <goals>
                                     <goal>mutationCoverage</goal>
                                 </goals>
@@ -126,6 +126,12 @@
     </developers>
 
     <build>
+        <resources>
+            <resource>
+                <directory>src</directory>
+                <filtering>true</filtering>
+            </resource>
+        </resources>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -154,6 +160,7 @@
                     <defaultVersion>${project.version}</defaultVersion>
                     <defaultSince>${project.version}</defaultSince>
                     <encoding>UTF-8</encoding>
+                    <docencoding>UTF-8</docencoding>
                 </configuration>
                 <executions>
                     <execution>

src/main/java/org/wickedsource/docxstamper/CommentProcessorBuilder.java

@@ -6,7 +6,7 @@
  * Factory interface for creating {@link org.wickedsource.docxstamper.api.commentprocessor.ICommentProcessor} instances.
  *
  * @author Joseph Verron
- * @version 1.6.6
+ * @version ${version}
  */
 public interface CommentProcessorBuilder {
     /**

src/main/java/org/wickedsource/docxstamper/DocxStamper.java

@@ -28,7 +28,7 @@
  *
  * @param <T> The type of the context that can be stamped
  * @author Joseph Verron
- * @version 1.6.7
+ * @version ${version}
  */
 public class DocxStamper<T> implements OpcStamper<WordprocessingMLPackage> {
 	private final List<PreProcessor> preprocessors;

src/main/java/org/wickedsource/docxstamper/api/DocxStamperException.java

@@ -5,7 +5,7 @@
  * It extends the RuntimeException class and provides additional constructors to handle different scenarios.
  *
  * @author Joseph Verron
- * @version 1.6.6
+ * @version ${version}
  */
 public class DocxStamperException extends RuntimeException {
 

src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java

@@ -7,7 +7,7 @@
  * This can  for example be used to add custom {@link org.springframework.expression.PropertyAccessor}s and {@link org.springframework.expression.MethodResolver}s.
  *
  * @author Joseph Verron
- * @version 1.6.6
+ * @version ${version}
  */
 public interface EvaluationContextConfigurer {
     /**

src/main/java/org/wickedsource/docxstamper/api/UnresolvedExpressionException.java

@@ -4,7 +4,7 @@
  * This exception is thrown if an expression could not be processed by any comment processor.
  *
  * @author Joseph Verron
- * @version 1.6.6
+ * @version ${version}
  */
 public class UnresolvedExpressionException extends DocxStamperException {
     /**