Move to 2.0 (#312)

.github/workflows/integrate-docx4j.yml

@@ -29,15 +29,15 @@ jobs:
           # - 11.1.2
           # - 11.1.3
           # - 11.1.7
-          - 11.1.8
+          # - 11.1.8
           # - 11.2.5
           # - 11.2.8
-          - 11.2.9
-          - 11.3.2
-          - 11.4.5
-          - 11.4.6
-          - 11.4.7
-          - 11.4.8
+          # - 11.2.9
+          # - 11.3.2
+          # - 11.4.5
+          # - 11.4.6
+          # - 11.4.7
+          # - 11.4.8
           - 11.4.9
           - 11.4.10
           - 11.4.11

.github/workflows/pages.yml

@@ -30,12 +30,12 @@ jobs:
           distribution: 'temurin'
           cache: 'maven'
 
-      - run: mvn -B -ntp verify site -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120
+      - run: mvn -B -ntp verify site -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120 -f engine/pom.xml
 
       - uses: actions/configure-pages@v4
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: 'target/site'
+          path: 'engine/target/site'
 
       - uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
           cat <(echo -e "${{ secrets.GPG_SECRET_KEY }}") | gpg --batch --import
           gpg --list-secret-keys --keyid-format LONG
 
-      - run: mvn -B -ntp deploy -P gpg,!mut -Dgpg.passphrase=${{ secrets.GPG_SECRET_PASS }}
+      - run: mvn -B -ntp deploy -P gpg,!mut -Dgpg.passphrase=${{ secrets.GPG_SECRET_PASS }} -f engine/pom.xml
         env:
           MAVEN_USERNAME: ${{ secrets.OSS_SONATYPE_NAME }}
           MAVEN_PASSWORD: ${{ secrets.OSS_SONATYPE_PASS }}

README.adoc

@@ -1,13 +1,47 @@
 :proj: https://github.com/verronpro/docx-stamper
 :repo: https://github.com/verronpro/docx-stamper/tree/master
 
-= docx-stamper
+= Office-Stamper
+
+== Introduction
+
+Office-Stamper (formerly Docx-Stamper) is a Java template engine that allows for dynamic creation of docx documents at runtime.
+You design a template using your preferred Word processor; and Office-Stamper will generate documents based on that template.
 
 image:{proj}/actions/workflows/integrate.yml/badge.svg[Build Status,link={proj}/actions/workflows/integrate.yml] image:{proj}/actions/workflows/analyze.yml/badge.svg[Build Status,link={proj}/actions/workflows/analyze.yml] image:{proj}/actions/workflows/pages.yml/badge.svg[Build Status,link={proj}/actions/workflows/pages.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.
-Example code:
+== Project Update
+
+The project name has changed from Docx-Stamper to Office-Stamper to better signify its functionality and scope.
+
+== Release Notes
+
+=== Version 1.6.8
+
+This release marks an important milestone in our plans to transition to version 2.0.
+It introduces new APIs and deprecates some legacy ones.
+We recommend all users to start using the new APIs to reduce disruption in the future.
+
+=== Transition to Java 9 Modularization
+
+We are transitioning to Java 9 Modularization for added efficiency and developer-friendliness.
+It aids in separating the project's core details from the interfaces that developers work with.
+
+=== Upcoming in Version 2.0
+
+Our upcoming release, version 2.0, is set to be a significant update with major improvements over the preceding versions.
+Please note the following changes:
+
+1. Discontinuation of legacy APIs and complete adoption of new ones.
+2. Full embrace of Java 9 modularization.
+3. Other improvements and optimizations which will be detailed in the release notes.
+
+We appreciate your input and suggestions.
+Please feel free to contribute or share your thoughts with us.
+
+== Usage
+
+Here is a simple code snippet exemplifying how to use Office-Stamper:
 
 [source,java]
 ----
@@ -33,13 +67,16 @@ class Example {
 }
 ----
 
-== Replacing Expressions in a .docx Template
+== Template Expressions and Their Usage
 
-The main feature of docx-stamper is *replacement of expressions* within the text of the template document.
-Simply add expressions like `${person.name}` or `${person.name.equals("Homer") ? "Duff" : "Budweiser"}` in the text of your .docx template and provide a context object against which the placeholder can be resolved. docx-stamper will try to keep the original formatting of the text in the template intact.
-You can use the full feature set of http://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html[Spring Expression Language] (SpEL).
+The foundation of Office-Stamper lies in its ability to *replace expressions* within the text of a .docx template document.
+Conveniently, add expressions such as `${person.name}` or `${person.name.equals("Homer") ? "Duff" :
+"Budweiser"}` in the text of the .docx file you're using as a template.
+Then, provide a context object to resolve the placeholder.
+Don't worry about formatting, Office-Stamper will maintain the original text's formatting in the template.
+You have full access to the extensive feature set of [Spring Expression Language (SpEL)](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html).
 
-The value that a placeholder resolves to may be of the following types:
+Each placeholder's resolution corresponds to the following types:
 
 .Type that can be resolved to an element in the .docx document
 [cols=">1,3"]
@@ -54,9 +91,10 @@ The value that a placeholder resolves to may be of the following types:
 | `link:{repo}/src/main/java/org/wickedsource/docxstamper/replace/typeresolver/image/Image.java[org.wickedsource...Image]` |The placeholder is replaced with an inline image.
 |===
 
-If a placeholder cannot be resolved successfully, it will be skipped (meaning the placeholder 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/pro/verron/docxstamper/api/ObjectResolver.java[ObjectResolver]`.
-To register your it with docx-stamper, use the following code:
+If a placeholder fails to resolve successfully, Office-Stamper will skip it, the placeholder in the document remains the same as its initial state in the template.
+You can expand this resolution functionality by implementing your `link:{repo}/src/main/java/pro/verron/docxstamper/api/ObjectResolver.java[ObjectResolver]`.
+
+Here's a code snippet on how to proceed:
 
 [source,java]
 ----
@@ -76,11 +114,16 @@ class Main {
 }
 ----
 
-== Customizing the SpEL Evaluation Context
+== Refining SpEL Evaluation Context
+
+At times, you might want to exert more control over how expressions are evaluated.
+With Office-Stamper, there's provision for such scenarios.
+Here’s how:
 
-If you want to take more control over the evaluation of expressions, you can implement a `link:{repo}/src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java[EvaluationContextConfigurer]`
-and customize Springs `StandardEvaluationContext` to your needs.
-You can register an `link:{repo}/src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java[EvaluationContextConfigurer]` like this:
+Implement your own `link:{repo}/src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java[EvaluationContextConfigurer]`.
+This allows you to customize Springs `StandardEvaluationContext` according to your requirements.
+
+Use the following code snippet to register your `link:{repo}/src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java[EvaluationContextConfigurer]`:
 
 [source,java ]
 ----
@@ -94,11 +137,18 @@ class Main {
 }
 ----
 
-== Adding custom functions to the Expression Language
+In this code, `NoOpEvaluationContextConfigurer` is your custom implementation of `EvaluationContextConfigurer`.
+Substitute it with the actual name of your implementation as you use the code above.
+
+This feature empowers you with greater flexibility and enhanced control over the expression evaluation process, fitting Office-Stamper seamlessly into complex scenarios and requirements.
 
-If you want to create custom functions (for different number formats or different date formats, for example), you can register functions which can then be used in the placeholder language.
-The following code, for example, adds a function `toUppercase(String)`
-which can be used within the .docx document to uppercase a String:
+== Enhancing the Expression Language with Custom Functions
+
+Office-Stamper lets you add custom functions to the tool’s expression language.
+For example, if you need specific formats for numbers or dates, you can register such functions which can then be used in the placeholders throughout your template.
+
+Below is a sample code demonstrating how to extend the expression language with a custom function.
+This particular example adds a function `toUppercase(String)`, enabling you to convert any text in your .docx document to uppercase.
 
 [source,java]
 ----
@@ -115,10 +165,13 @@ class Main {
 }
 ----
 
-== Comment Processors
+Chains of such custom functions can enhance the versatility of Office-Stamper, making it capable of handling complex and unique templating situations.
+
+== Processing Comments for Enhanced Functionality
 
-Besides replacing expressions, docx-stamper can *process comments on paragraphs of text* in the template .docx document and do manipulations on the template based on these comments.
-By default, you can use the following expressions in comments:
+Alongside expression replacement, Office-Stamper presents the feature of *processing comments* associated with paragraphs in your .docx template.
+These comments act as directives for manipulating the template.
+As a standard, the following expressions can be used within comments:
 
 .Default activated comment processors
 [cols=">1,4"]
@@ -134,10 +187,11 @@ By default, you can use the following expressions in comments:
 |`resolveTable(StampTable)` | Replace a table (that must have one column and two rows) with the values given by the StampTable. The StampTable contains a list of headers for columns, and a 2-level list of rows containing values for each column.
 |===
 
-If a comment cannot be processed, by default an exception will be thrown.
-Successfully processed comments are removed from the document.
-You can add support to more expressions in comments by implementing your own link:{repo}/src/main/java/org/wickedsource/docxstamper/api/commentprocessor/ICommentProcessor.java[ICommentProcessor].
-To register your comment processor to docx-stamper, use the following code:
+By default, an exception is thrown if a comment fails to process.
+However, successfully processed comments are wiped from the document.
+For additional flexibility, create your own expression within comments by implementing your `link:{repo}/src/main/java/org/wickedsource/docxstamper/api/commentprocessor/ICommentProcessor.java[ICommentProcessor]`.
+
+Here's an example of how to create and register a custom comment processor:
 
 [source,java]
 ----
@@ -163,28 +217,41 @@ class Main {
 
 For an in-depth description of how to create a comment processor, see the javadoc of link:{repo}/src/main/java/org/wickedsource/docxstamper/api/commentprocessor/ICommentProcessor.java[ICommentProcessor].
 
-== Conditional Display and Repeating of Elements in Headers or Footers
+== Conditional and Repetitive Displays within Headers and Footers
+
+The .docx file format does not permit comments within headers or footers.
+But there's a workaround in Office-Stamper.
+If you want to display contents within headers or footers conditionally, or require repetitive elements, all you got to do is :
+
+1. Craft the expression as you would in a comment.
+2. Encapsulate it with "#{}".
+3. Position it at the starting of the paragraph you intend to manipulate.
 
-The docx file format does not allow comments in Headers or Footers of a document.
-To be able to conditionally display content in a header or footer, surround the expression you would put in a comment with "#{}" and put it at the beginning of the paragraph you want to manipulate.
-The expression will be evaluated as it would be in a comment.
+The assigned expression will be processed in the same way it would be in a comment, allowing you to maximize template customization.
 
-== Error Handling
+Remember, this workaround unlocks the power of conditional display and repetition in your document's headers and footers, enhancing document dynamics.
 
-By default, DocxStamper fails with an UnresolvedExpressionException if a placeholder within the document or within the comments cannot be resolved successfully.
-If you want to change this behavior, you can do the following:
+== Graceful Error Handling
+
+In general, DocxStamper employs an `UnresolvedExpressionException`
+if there's a failure in resolving an expression within a document or the associated comments.
+However, you can modify this behavior.
+
+Follow the given example to silence the exception and keep DocxStamper from failing even when it encounters unresolved expressions:
 
 [source,java]
 ----
 class Main {
     public static void main(String... args) {
         var configuration = new DocxStamperConfiguration()
-                .setFailOnUnresolvedExpression(false);
+                            .setFailOnUnresolvedExpression(false);
         var stamper = new DocxStamper<>(configuration);
     }
 }
 ----
 
+This customization allows you to control the failure behavior of DocxStamper according to your specific requirements.
+
 == Sample Code
 
 The source code contains a set of tests show how to use the features.
@@ -213,7 +280,7 @@ Note that as of version 1.4.0, you have to provide the dependency to your versio
 
 This way, you can choose which version of Docx4J you want to use instead of having it dictated by docx-stamper.
 
-Status of compatibility available here ->  https://github.com/verronpro/docx-stamper/actions/workflows/integrate-docx4j.yml)
+Status of compatibility available here -> https://github.com/verronpro/docx-stamper/actions/workflows/integrate-docx4j.yml)
 
 == Contribute