jocument DDSG features

build.gradle

@@ -8,10 +8,10 @@ plugins {
 }
 
 group 'com.docutools'
-version = '1.3.2'
+version = '1.4.0-rc.9'
 
-sourceCompatibility = 17
-targetCompatibility = 17
+sourceCompatibility = JavaVersion.VERSION_17
+targetCompatibility = JavaVersion.VERSION_17
 
 repositories {
     mavenCentral()
@@ -75,6 +75,7 @@ test {
 }
 
 task automatedTests(type: Test) {
+    environment 'DT_JT_RR_PLACEHOLDER_MAPPINGS', 'src/test/resources/mappings.txt'
     useJUnitPlatform{
         includeTags "automated"
     }
@@ -86,8 +87,8 @@ publishing {
             name = "GitHubPackages"
             url = uri("https://maven.pkg.github.com/DDS-GmbH/jocument")
             credentials {
-                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
-                password = project.findProperty("gpr.token") ?: System.getenv("GITHUB_TOKEN")
+                username = project.findProperty("gpr.gh.user") ?: System.getenv("GITHUB_USERNAME")
+                password = project.findProperty("gpr.gh.token") ?: System.getenv("GITHUB_TOKEN")
             }
         }
     }

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

src/main/java/com/docutools/jocument/CustomPlaceholderRegistry.java

@@ -7,8 +7,8 @@
 public interface CustomPlaceholderRegistry {
   void addHandler(String placeholder, Class<? extends CustomWordPlaceholderData> customWordPlaceholderDataClass);
 
-  Optional<PlaceholderData> resolve(String placeholder)
+  Optional<PlaceholderData> resolve(String placeholder, Object object)
       throws NoSuchMethodException, IllegalAccessException, InvocationTargetException, InstantiationException;
 
-  boolean governs(String placeholderName);
+  boolean governs(String placeholderName, Object object);
 }

src/main/java/com/docutools/jocument/GenerationOptions.java

@@ -1,12 +1,68 @@
 package com.docutools.jocument;
 
+import com.docutools.jocument.formatting.PlaceholderDataFormattingOption;
 import com.docutools.jocument.image.ImageStrategy;
+import com.docutools.jocument.impl.ScalarPlaceholderData;
+import java.time.Duration;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.function.BiFunction;
 
 /**
  * Options for generating {@link Document}s, passed to the {@link Template}s.
  *
  * @author partschi
  * @since 2021-03-24
  */
-public record GenerationOptions(ImageStrategy imageStrategy) {
+public record GenerationOptions(ImageStrategy imageStrategy,
+                                Duration maximumWaitTime,
+                                List<PlaceholderDataFormattingOption> formattingOptions,
+                                BiFunction<String, Locale, Optional<String>> translationFunction) {
+
+  /**
+   * Try to format a {@link PlaceholderData} with the given {@link Locale}.
+   *
+   * @param locale          The locale to use for formatting
+   * @param placeholderData The data to format
+   * @return An {@link Optional} containing the formatted {@link PlaceholderData} if successful, {@link Optional#empty()} otherwise.
+   */
+  public Optional<PlaceholderData> tryToFormat(Locale locale, PlaceholderData placeholderData) {
+    return formattingOptions.stream()
+        .filter(option -> option.filter().accepts(placeholderData.getRawValue()))
+        .findFirst()
+        .map(option -> option.formatter().format(locale, placeholderData.getRawValue()))
+        .map(ScalarPlaceholderData::new);
+
+  }
+
+  /**
+   * Try to format an object with the given {@link Locale}.
+   *
+   * @param locale   The locale to use for formatting
+   * @param toFormat The data to format
+   * @return An {@link Optional} containing the formatted {@link String} if successful, {@link Optional#empty()} otherwise.
+   */
+  public <T> Optional<String> tryToFormat(Locale locale, T toFormat) {
+    return formattingOptions.stream()
+        .filter(option -> option.filter().accepts(toFormat))
+        .findFirst()
+        .map(option -> option.formatter().format(locale, toFormat));
+
+  }
+
+  /**
+   * Translate a given term to the given locale.
+   *
+   * @param term   The term to translate
+   * @param locale The locale to translate the term to
+   * @return An {@link Optional} containing the translated term if successful, {@link Optional#empty()} otherwise
+   */
+  public Optional<String> translate(String term, Locale locale) {
+    if (translationFunction != null) {
+      return translationFunction.apply(term, locale);
+    }
+    return Optional.empty();
+  }
+
 }

src/main/java/com/docutools/jocument/GenerationOptionsBuilder.java

@@ -1,8 +1,17 @@
 package com.docutools.jocument;
 
+import com.docutools.jocument.formatting.LocalisedPlaceholderDataFormatter;
+import com.docutools.jocument.formatting.PlaceholderDataFormatter;
+import com.docutools.jocument.formatting.PlaceholderDataFormattingOption;
 import com.docutools.jocument.image.DefaultImageStrategy;
 import com.docutools.jocument.image.ImageStrategy;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
 import java.util.Objects;
+import java.util.Optional;
+import java.util.function.BiFunction;
 
 /**
  * Builder for {@link GenerationOptions}, use {@link this#buildDefaultOptions()} to take all default options for {@link GenerationOptions}.
@@ -17,6 +26,9 @@ public static GenerationOptions buildDefaultOptions() {
   }
 
   private ImageStrategy imageStrategy;
+  private final List<PlaceholderDataFormattingOption> formattingOptions = new ArrayList<>();
+  private BiFunction<String, Locale, Optional<String>> translationFunction = null;
+  private Duration waitTime = Duration.ofSeconds(30);
 
   public GenerationOptionsBuilder() {
     this.imageStrategy = DefaultImageStrategy.instance();
@@ -27,8 +39,27 @@ public GenerationOptionsBuilder withImageStrategy(ImageStrategy imageStrategy) {
     return this;
   }
 
+  public <T> GenerationOptionsBuilder format(Class<T> filter, PlaceholderDataFormatter<T> formatter) {
+    return format(filter, (l, v) -> formatter.format(v));
+  }
+
+  public <T> GenerationOptionsBuilder format(Class<T> filter, LocalisedPlaceholderDataFormatter<T> formatter) {
+    formattingOptions.add(new PlaceholderDataFormattingOption<>(obj -> obj.getClass().isAssignableFrom(filter), formatter));
+    return this;
+  }
+
+  public GenerationOptionsBuilder withTranslation(BiFunction<String, Locale, Optional<String>> translationFunction) {
+    this.translationFunction = translationFunction;
+    return this;
+  }
+
+  public GenerationOptionsBuilder withMaximumWaitTime(Duration waitTime) {
+    this.waitTime = waitTime;
+    return this;
+  }
+
   public GenerationOptions build() {
-    return new GenerationOptions(imageStrategy);
+    return new GenerationOptions(imageStrategy, waitTime, formattingOptions, translationFunction);
   }
 
 }

src/main/java/com/docutools/jocument/PlaceholderData.java

@@ -1,5 +1,6 @@
 package com.docutools.jocument;
 
+import java.util.Locale;
 import java.util.stream.Stream;
 
 /**
@@ -49,10 +50,38 @@ default long count() {
    * <p>Only used when {@link this#getType()} returns {@link com.docutools.jocument.PlaceholderType#CUSTOM}.</p>
    *
    * @param placeholder the placeholder
+   * @param locale the {@link Locale}
    * @param options the {@link GenerationOptions}
    */
-  default void transform(Object placeholder, GenerationOptions options) {
+  default void transform(Object placeholder, Locale locale, GenerationOptions options) {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Tries to return the raw value behind the {@link PlaceholderData}. May not be implemented in all sepcifications.
+   *
+   * @return the raw value
+   */
+  default Object getRawValue() {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Evaluates if this {@link PlaceholderData} is a truthy value. Non-truthy values are defined as:
+   *
+   * <ul>
+   *   <li>Empty string</li>
+   *   <li>Empty collection or array</li>
+   *   <li>{@code null}</li>
+   *   <li>0</li>
+   *   <li>{@code false}</li>
+   *   <li>Empty {@link java.util.Optional}</li>
+   * </ul>
+   *
+   * @return {@code true} if truthy
+   */
+  default boolean isTruthy() {
+    return count() > 0;
+  }
+
 }

src/main/java/com/docutools/jocument/PlaceholderMapper.java

@@ -0,0 +1,9 @@
+package com.docutools.jocument;
+
+import java.util.Optional;
+
+public interface PlaceholderMapper {
+  Optional<String> map(String placeholder);
+
+  String tryToMap(String placeholder);
+}

src/main/java/com/docutools/jocument/PlaceholderResolver.java

@@ -1,5 +1,6 @@
 package com.docutools.jocument;
 
+import com.docutools.jocument.impl.ScalarPlaceholderData;
 import java.util.Locale;
 import java.util.Objects;
 import java.util.Optional;
@@ -41,6 +42,18 @@ public Optional<PlaceholderData> resolve(String placeholderName) {
    * @param locale          the localisation settings
    * @return if the name could've been resolved the localised {@link com.docutools.jocument.PlaceholderData}
    */
-  public abstract Optional<PlaceholderData> resolve(String placeholderName, Locale locale);
+  public Optional<PlaceholderData> resolve(String placeholderName, Locale locale) {
+    return doResolve(placeholderName, locale)
+        .map(placeholderData -> format(locale, placeholderData));
+  }
+
+  private PlaceholderData format(Locale locale, PlaceholderData original) {
+    if (original instanceof ScalarPlaceholderData<?>) {
+      return options.tryToFormat(locale, original).orElse(original);
+    }
+    return original;
+  }
+
+  protected abstract Optional<PlaceholderData> doResolve(String placeholderName, Locale locale);
 
 }

src/main/java/com/docutools/jocument/annotations/MatchPlaceholder.java

@@ -0,0 +1,28 @@
+package com.docutools.jocument.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.Locale;
+
+/**
+ * Allows to define a regular expression pattern for a method to be resolved in a {@link com.docutools.jocument.impl.ReflectionResolver} if the
+ * placeholder name passed to {@link com.docutools.jocument.impl.ReflectionResolver#resolve(String, Locale)} matches against the {@link
+ * this#pattern()}.
+ *
+ * <p>{@link MatchPlaceholder}-annotated methods precede any other properties.
+ *
+ * <p>Can be applied to a public method taking a {@link String} and an optional {@link java.util.Locale} as second parameter, returning an {@link
+ * java.util.Optional} of {@link String}.
+ *
+ * @author amp
+ * @since 2022-03-01
+ */
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MatchPlaceholder {
+  /**
+   * A RegEx pattern.
+   *
+   * @return {@link String}
+   */
+  String pattern();
+}

src/main/java/com/docutools/jocument/annotations/Translatable.java

@@ -0,0 +1,8 @@
+package com.docutools.jocument.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Translatable {
+}

src/main/java/com/docutools/jocument/formatting/LocalisedPlaceholderDataFormatter.java

@@ -0,0 +1,9 @@
+package com.docutools.jocument.formatting;
+
+import java.util.Locale;
+
+public interface LocalisedPlaceholderDataFormatter<T> {
+
+  String format(Locale locale, T value);
+
+}

src/main/java/com/docutools/jocument/formatting/PlaceholderDataFormatter.java

@@ -0,0 +1,7 @@
+package com.docutools.jocument.formatting;
+
+public interface PlaceholderDataFormatter<T> {
+
+  String format(T value);
+
+}

src/main/java/com/docutools/jocument/formatting/PlaceholderDataFormatterFilter.java

@@ -0,0 +1,7 @@
+package com.docutools.jocument.formatting;
+
+public interface PlaceholderDataFormatterFilter {
+
+  boolean accepts(Object value);
+
+}

src/main/java/com/docutools/jocument/formatting/PlaceholderDataFormattingOption.java

@@ -0,0 +1,13 @@
+package com.docutools.jocument.formatting;
+
+import com.docutools.jocument.PlaceholderData;
+
+/**
+ * An option for formatting {@link PlaceholderData} by a specific {@link PlaceholderDataFormatter}, given the {@link PlaceholderDataFormatterFilter}
+ * accepts it.
+ *
+ * @param <T> the {@link PlaceholderData#getRawValue()} type.
+ */
+public record PlaceholderDataFormattingOption<T>(PlaceholderDataFormatterFilter filter,
+                                                 LocalisedPlaceholderDataFormatter<T> formatter) {
+}

src/main/java/com/docutools/jocument/image/DefaultImageReference.java

@@ -45,7 +45,7 @@ public Path saveAsJpeg() throws IOException {
       throw new ImageReferenceClosedException("Image was already closed.");
     }
 
-    var filePath = Files.createTempFile("jocument", "jpg");
+    var filePath = Files.createTempFile("jocument-", ".jpg");
     log.trace("Saving image {} to '{}'...", id, filePath);
 
     ImageIO.write(image, "JPEG", filePath.toFile());