(Static utility methods for custom format creation now also deals wit…

…h dates. Some JavaDoc comments on API stability.)

src/main/java/freemarker/core/ISOLikeTemplateDateFormat.java

@@ -174,7 +174,7 @@ private void checkForceUTCNotSet(Boolean fourceUTC) throws InvalidFormatParamete
 
     @Override
     public final String format(TemplateDateModel dateModel) throws TemplateModelException {
-        final Date date = getNonNullDate(dateModel);
+        final Date date = TemplateFormatUtil.getNonNullDate(dateModel);
         return format(
                 date,
                 dateType != TemplateDateModel.TIME,

src/main/java/freemarker/core/JavaTemplateDateFormat.java

@@ -37,7 +37,7 @@ public JavaTemplateDateFormat(DateFormat javaDateFormat) {
 
     @Override
     public String format(TemplateDateModel dateModel) throws TemplateModelException {
-        return javaDateFormat.format(getNonNullDate(dateModel));
+        return javaDateFormat.format(TemplateFormatUtil.getNonNullDate(dateModel));
     }
 
     @Override

src/main/java/freemarker/core/JavaTemplateNumberFormat.java

@@ -32,7 +32,7 @@ public JavaTemplateNumberFormat(NumberFormat javaNumberFormat, String formatStri
 
     @Override
     public String format(TemplateNumberModel numberModel) throws UnformattableNumberException, TemplateModelException {
-        Number number = TemplateNumberFormatUtil.getNonNullNumber(numberModel);
+        Number number = TemplateFormatUtil.getNonNullNumber(numberModel);
         return format(number);
     }
 

src/main/java/freemarker/core/TemplateDateFormat.java

@@ -54,6 +54,7 @@ public abstract String format(TemplateDateModel dateModel)
             throws UnformattableDateException, TemplateModelException;
 
     /**
+     * <b>[Not yet used, might changes in 2.3.24 final]</b>
      * Formats the date/time/dateTime to markup instead of to plain text, or returns {@code null} that will make
      * FreeMarker call {@link #format(TemplateDateModel)} and escape its result. If the markup format would be just the
      * result of {@link #format(TemplateDateModel)} escaped, it should return {@code null}.
@@ -63,6 +64,7 @@ public abstract <MO extends TemplateMarkupOutputModel> MO format(TemplateDateMod
                     throws UnformattableNumberException, TemplateModelException;
 
     /**
+     * <b>[Not yet used, might changes in 2.3.24 final]</b>
      * Same as {@link #format(TemplateDateModel, MarkupOutputFormat)}, but prints the result to a {@link Writer}
      * instead of returning it. This can be utilized for some optimizatoin. In the case where
      * {@link #format(TemplateDateModel, MarkupOutputFormat)} would return {@code null}, it returns {@code false}. It
@@ -84,6 +86,11 @@ public <MO extends TemplateMarkupOutputModel> boolean format(TemplateDateModel d
     }
 
     /**
+     * <b>[Unfinished - will change in 2.3.24 final]</b>.
+     * 
+     * TODO Thrown exceptions.
+     * TODO How can one return a TemplateDateModel instead?
+     * 
      * @return The interpretation of the text as {@link Date}. Can't be {@code null}.
      */
     public abstract Date parse(String s) throws java.text.ParseException;
@@ -102,17 +109,5 @@ public <MO extends TemplateMarkupOutputModel> boolean format(TemplateDateModel d
      * Tells if this formatter should be re-created if the time zone changes. Currently always {@code true}.
      */
     public abstract boolean isTimeZoneBound();
-
-    /**
-     * Utility method to extract the {@link Date} from an {@link TemplateDateModel}, and throw
-     * {@link UnformattableDateException} with a standard error message if that's {@code null}.
-     */
-    protected Date getNonNullDate(TemplateDateModel dateModel) throws TemplateModelException {
-        Date date = dateModel.getAsDate();
-        if (date == null) {
-            throw EvalUtil.newModelHasStoredNullException(Date.class, dateModel, null);
-        }
-        return date;
-    }
 
 }

src/main/java/freemarker/core/TemplateNumberFormatUtil.java → src/main/java/freemarker/core/TemplateFormatUtil.java

@@ -15,15 +15,18 @@
  */
 package freemarker.core;
 
+import java.util.Date;
+
+import freemarker.template.TemplateDateModel;
 import freemarker.template.TemplateModelException;
 import freemarker.template.TemplateNumberModel;
 
 /**
  * @since 2.3.24 
  */
-public final class TemplateNumberFormatUtil {
+public final class TemplateFormatUtil {
 
-    private TemplateNumberFormatUtil() {
+    private TemplateFormatUtil() {
         // Not meant to be instantiated
     }
 
@@ -48,4 +51,16 @@ public static Number getNonNullNumber(TemplateNumberModel numberModel)
         return number;
     }
 
+    /**
+     * Utility method to extract the {@link Date} from an {@link TemplateDateModel}, and throw
+     * {@link UnformattableDateException} with a standard error message if that's {@code null}.
+     */
+    public static Date getNonNullDate(TemplateDateModel dateModel) throws TemplateModelException {
+        Date date = dateModel.getAsDate();
+        if (date == null) {
+            throw EvalUtil.newModelHasStoredNullException(Date.class, dateModel, null);
+        }
+        return date;
+    }
+
 }

src/main/java/freemarker/core/TemplateNumberFormat.java

@@ -56,6 +56,7 @@ public abstract String format(TemplateNumberModel numberModel)
             throws UnformattableNumberException, TemplateModelException;
 
     /**
+     * <b>[Not yet used, might changes in 2.3.24 final]</b>
      * Formats the number to markup instead of to plain text, or returns {@code null} that will make FreeMarker call
      * {@link #format(TemplateNumberModel)} and escape its result. If the markup format would be just the result of
      * {@link #format(TemplateNumberModel)} escaped, it should return {@code null}.
@@ -65,6 +66,7 @@ public abstract <MO extends TemplateMarkupOutputModel> MO format(
                     throws UnformattableNumberException, TemplateModelException;
 
     /**
+     * <b>[Not yet used, might changes in 2.3.24 final]</b>
      * Same as {@link #format(TemplateNumberModel, MarkupOutputFormat)}, but prints the result to a {@link Writer}
      * instead of returning it. This can be utilized for some optimizatoin. In the case where
      * {@link #format(TemplateNumberModel, MarkupOutputFormat)} would return {@code null}, it returns {@code false}. It

src/test/java/freemarker/core/BaseNTemplateNumberFormatFactory.java

@@ -79,7 +79,7 @@ private BaseNTemplateNumberFormat(int base, TemplateNumberFormat fallbackFormat)
         @Override
         public String format(TemplateNumberModel numberModel)
                 throws UnformattableNumberException, TemplateModelException {
-            Number n = TemplateNumberFormatUtil.getNonNullNumber(numberModel);
+            Number n = TemplateFormatUtil.getNonNullNumber(numberModel);
             try {
                 return Integer.toString(NumberUtil.toIntExact(n), base);
             } catch (ArithmeticException e) {

src/test/java/freemarker/core/EpochMillisDivTemplateDateFormatFactory.java

@@ -63,7 +63,7 @@ private EpochMillisDivTemplateDateFormat(int divisor) {
         @Override
         public String format(TemplateDateModel dateModel)
                 throws UnformattableDateException, TemplateModelException {
-            return String.valueOf(getNonNullDate(dateModel).getTime() / divisor);
+            return String.valueOf(TemplateFormatUtil.getNonNullDate(dateModel).getTime() / divisor);
         }
 
         @Override

src/test/java/freemarker/core/EpochMillisTemplateDateFormatFactory.java

@@ -37,7 +37,7 @@ private EpochMillisTemplateDateFormatFactory() {
     public TemplateDateFormat get(int dateType, boolean zonelessInput, String params, Locale locale, TimeZone timeZone,
             Environment env) throws TemplateModelException, UnknownDateTypeFormattingUnsupportedException,
                     InvalidFormatParametersException {
-        TemplateNumberFormatUtil.checkHasNoParameters(params);
+        TemplateFormatUtil.checkHasNoParameters(params);
         return EpochMillisTemplateDateFormat.INSTANCE;
     }
 
@@ -50,7 +50,7 @@ private EpochMillisTemplateDateFormat() { }
         @Override
         public String format(TemplateDateModel dateModel)
                 throws UnformattableDateException, TemplateModelException {
-            return String.valueOf(getNonNullDate(dateModel).getTime());
+            return String.valueOf(TemplateFormatUtil.getNonNullDate(dateModel).getTime());
         }
 
         @Override

src/test/java/freemarker/core/HexTemplateNumberFormatFactory.java

@@ -32,7 +32,7 @@ private HexTemplateNumberFormatFactory() {
     @Override
     public TemplateNumberFormat get(String params, Locale locale, Environment env)
             throws InvalidFormatParametersException {
-        TemplateNumberFormatUtil.checkHasNoParameters(params);
+        TemplateFormatUtil.checkHasNoParameters(params);
         return HexTemplateNumberFormat.INSTANCE;
     }
 
@@ -45,7 +45,7 @@ private HexTemplateNumberFormat() { }
         @Override
         public String format(TemplateNumberModel numberModel)
                 throws UnformattableNumberException, TemplateModelException {
-            Number n = TemplateNumberFormatUtil.getNonNullNumber(numberModel);
+            Number n = TemplateFormatUtil.getNonNullNumber(numberModel);
             try {
                 return Integer.toHexString(NumberUtil.toIntExact(n));
             } catch (ArithmeticException e) {

src/test/java/freemarker/core/LocAndTZSensitiveTemplateDateFormatFactory.java

@@ -37,7 +37,7 @@ private LocAndTZSensitiveTemplateDateFormatFactory() {
     public TemplateDateFormat get(int dateType, boolean zonelessInput, String params, Locale locale, TimeZone timeZone,
             Environment env) throws TemplateModelException, UnknownDateTypeFormattingUnsupportedException,
                     InvalidFormatParametersException {
-        TemplateNumberFormatUtil.checkHasNoParameters(params);
+        TemplateFormatUtil.checkHasNoParameters(params);
         return new LocAndTZSensitiveTemplateDateFormat(locale, timeZone);
     }
 
@@ -54,7 +54,7 @@ public LocAndTZSensitiveTemplateDateFormat(Locale locale, TimeZone timeZone) {
         @Override
         public String format(TemplateDateModel dateModel)
                 throws UnformattableDateException, TemplateModelException {
-            return String.valueOf(getNonNullDate(dateModel).getTime() + "@" + locale + ":" + timeZone.getID());
+            return String.valueOf(TemplateFormatUtil.getNonNullDate(dateModel).getTime() + "@" + locale + ":" + timeZone.getID());
         }
 
         @Override

src/test/java/freemarker/core/LocaleSensitiveTemplateNumberFormatFactory.java

@@ -31,7 +31,7 @@ private LocaleSensitiveTemplateNumberFormatFactory() {
     @Override
     public TemplateNumberFormat get(String params, Locale locale, Environment env)
             throws InvalidFormatParametersException {
-        TemplateNumberFormatUtil.checkHasNoParameters(params);
+        TemplateFormatUtil.checkHasNoParameters(params);
         return new LocaleSensitiveTemplateNumberFormat(locale);
     }