From 942f03e08fce6abd0a6caf6444c0c8ea8176498f Mon Sep 17 00:00:00 2001 From: ddekany Date: Wed, 2 Sep 2015 01:01:12 +0200 Subject: [PATCH] (Static utility methods for custom format creation now also deals with dates. Some JavaDoc comments on API stability.) --- .../core/ISOLikeTemplateDateFormat.java | 2 +- .../core/JavaTemplateDateFormat.java | 2 +- .../core/JavaTemplateNumberFormat.java | 2 +- .../freemarker/core/TemplateDateFormat.java | 19 +++++++------------ ...ormatUtil.java => TemplateFormatUtil.java} | 19 +++++++++++++++++-- .../freemarker/core/TemplateNumberFormat.java | 2 ++ .../BaseNTemplateNumberFormatFactory.java | 2 +- ...ochMillisDivTemplateDateFormatFactory.java | 2 +- .../EpochMillisTemplateDateFormatFactory.java | 4 ++-- .../core/HexTemplateNumberFormatFactory.java | 4 ++-- ...dTZSensitiveTemplateDateFormatFactory.java | 4 ++-- ...eSensitiveTemplateNumberFormatFactory.java | 2 +- 12 files changed, 38 insertions(+), 26 deletions(-) rename src/main/java/freemarker/core/{TemplateNumberFormatUtil.java => TemplateFormatUtil.java} (72%) diff --git a/src/main/java/freemarker/core/ISOLikeTemplateDateFormat.java b/src/main/java/freemarker/core/ISOLikeTemplateDateFormat.java index a18b789a..2589976b 100644 --- a/src/main/java/freemarker/core/ISOLikeTemplateDateFormat.java +++ b/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, diff --git a/src/main/java/freemarker/core/JavaTemplateDateFormat.java b/src/main/java/freemarker/core/JavaTemplateDateFormat.java index d764c392..797849ca 100644 --- a/src/main/java/freemarker/core/JavaTemplateDateFormat.java +++ b/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 diff --git a/src/main/java/freemarker/core/JavaTemplateNumberFormat.java b/src/main/java/freemarker/core/JavaTemplateNumberFormat.java index 9c0b7a5c..ed8e1ea3 100644 --- a/src/main/java/freemarker/core/JavaTemplateNumberFormat.java +++ b/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); } diff --git a/src/main/java/freemarker/core/TemplateDateFormat.java b/src/main/java/freemarker/core/TemplateDateFormat.java index b7f51f67..a8bc976e 100644 --- a/src/main/java/freemarker/core/TemplateDateFormat.java +++ b/src/main/java/freemarker/core/TemplateDateFormat.java @@ -54,6 +54,7 @@ public abstract String format(TemplateDateModel dateModel) throws UnformattableDateException, TemplateModelException; /** + * [Not yet used, might changes in 2.3.24 final] * 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 format(TemplateDateMod throws UnformattableNumberException, TemplateModelException; /** + * [Not yet used, might changes in 2.3.24 final] * 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 boolean format(TemplateDateModel d } /** + * [Unfinished - will change in 2.3.24 final]. + * + * 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 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; - } } diff --git a/src/main/java/freemarker/core/TemplateNumberFormatUtil.java b/src/main/java/freemarker/core/TemplateFormatUtil.java similarity index 72% rename from src/main/java/freemarker/core/TemplateNumberFormatUtil.java rename to src/main/java/freemarker/core/TemplateFormatUtil.java index 84f1edaf..c10544e5 100644 --- a/src/main/java/freemarker/core/TemplateNumberFormatUtil.java +++ b/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; + } + } diff --git a/src/main/java/freemarker/core/TemplateNumberFormat.java b/src/main/java/freemarker/core/TemplateNumberFormat.java index 51e0e354..7a2a4e73 100644 --- a/src/main/java/freemarker/core/TemplateNumberFormat.java +++ b/src/main/java/freemarker/core/TemplateNumberFormat.java @@ -56,6 +56,7 @@ public abstract String format(TemplateNumberModel numberModel) throws UnformattableNumberException, TemplateModelException; /** + * [Not yet used, might changes in 2.3.24 final] * 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 format( throws UnformattableNumberException, TemplateModelException; /** + * [Not yet used, might changes in 2.3.24 final] * 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 diff --git a/src/test/java/freemarker/core/BaseNTemplateNumberFormatFactory.java b/src/test/java/freemarker/core/BaseNTemplateNumberFormatFactory.java index f553ec64..12c8e99c 100644 --- a/src/test/java/freemarker/core/BaseNTemplateNumberFormatFactory.java +++ b/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) { diff --git a/src/test/java/freemarker/core/EpochMillisDivTemplateDateFormatFactory.java b/src/test/java/freemarker/core/EpochMillisDivTemplateDateFormatFactory.java index 0a648ad6..e3f1b3ff 100644 --- a/src/test/java/freemarker/core/EpochMillisDivTemplateDateFormatFactory.java +++ b/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 diff --git a/src/test/java/freemarker/core/EpochMillisTemplateDateFormatFactory.java b/src/test/java/freemarker/core/EpochMillisTemplateDateFormatFactory.java index 92feda56..04fb5d11 100644 --- a/src/test/java/freemarker/core/EpochMillisTemplateDateFormatFactory.java +++ b/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 diff --git a/src/test/java/freemarker/core/HexTemplateNumberFormatFactory.java b/src/test/java/freemarker/core/HexTemplateNumberFormatFactory.java index d53f6407..d7aafbf2 100644 --- a/src/test/java/freemarker/core/HexTemplateNumberFormatFactory.java +++ b/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) { diff --git a/src/test/java/freemarker/core/LocAndTZSensitiveTemplateDateFormatFactory.java b/src/test/java/freemarker/core/LocAndTZSensitiveTemplateDateFormatFactory.java index ff4b2234..5a2f08c7 100644 --- a/src/test/java/freemarker/core/LocAndTZSensitiveTemplateDateFormatFactory.java +++ b/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 diff --git a/src/test/java/freemarker/core/LocaleSensitiveTemplateNumberFormatFactory.java b/src/test/java/freemarker/core/LocaleSensitiveTemplateNumberFormatFactory.java index 46605a24..178b07e5 100644 --- a/src/test/java/freemarker/core/LocaleSensitiveTemplateNumberFormatFactory.java +++ b/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); }