freemarker-java-8

This is a tiny Java library that adds basic format support for the new Java 8 date/time api in FreeMarker. Unfortunately FreeMarker doesn’t support formatting these classes, and there are no implementations being worked on at the moment (http://freemarker.org/contribute.html).

The library has basic formatting support for all classes in the java.time api introduced in Java 8, using the new java.time.format.DateTimeFormatter.

This is not a perfect solution as we cannot add built-ins to FreeMarker from outside code. But its the best we can do until FreeMarker adds full support in the future.

Requirements

Java 8 or higher.

Installation

freemarker-java-8 is not deployed to the Maven Central Repository. This can be done if anyone wants to use it. Just add a request in an issue, then we will do it within a reasonable amount of time.

In the meantime, just clone the repo and run a ´mvn clean install´. Then you can include the package in your Maven POM like this:

<dependency>
    <groupId>no.api.freemarker</groupId>
    <artifactId>freemarker-java-8</artifactId>
    <version>1.0.1-SNAPSHOT</version>
</dependency>

Make sure to replace the version with the current version found in the pom.

Usage

You need to tell FreeMarker about this package by adding the Java8ObjectWrapper to the FreeMarker configuration.

this.configuration = new Configuration(); // Or get the configuration from your framework like DropWizard or Spring Boot.
this.configuration.setObjectWrapper(new Java8ObjectWrapper(Configuration.VERSION_2_3_23));

java.time support

Since we are not allowed to add extra built in methods to FreeMarker we have to cheat a little bit to add format methods to our date.time classes. Therefore you will see that the syntax we are using differs from the standard.

All format methods uses the java.time.format.DateTimeFormatter for formatting.

Table 1. java.time template methods

java.time class	methods	comment	example
Clock	format()	This is a simple implementation where format just prints the toString() value of the object.	${myclock.format()}
Duration	nano(), seconds()	Gives access to the Duration values	${myduration.seconds}, ${myduration.nano}
Instant	format()	This is a simple implementation where format just prints the toString() value of the object.	${myinstant.format()}
LocalDate	format(), format(pattern)	Allows you to print a LocalDate on a default pattern or by providing a custom pattern.	${mylocaldate.format()} or ${mylocaldate.format('yyyy MM dd')}
LocalDateTime	format(), format(pattern)	Allows you to print a LocalDateTime on a default pattern or by providing a custom pattern.	${mylocaldatetime.format()} or ${mylocaldatetime.format('yyyy-MM-dd HH : mm : ss')}
LocalTime	format(), format(pattern)	Allows you to print a LocalTime on a default pattern or by providing a custom pattern.	${mylocaltime.format()} or ${mylocaltime.format('HH : mm : ss')}
MonthDay	format(), format(pattern)	Allows you to print a MonthDay on a default pattern or by providing a custom pattern.	${mymonthday.format()} or ${mymonthday.format('MM dd')}
OffsetDateTime	format(), format(pattern)	Allows you to print a OffsetDateTime on a default pattern or by providing a custom pattern.	${myoffsetdatetime.format()} or ${myoffsetdatetime.format('yyyy MM dd HH mm ss')}
OffsetTime	format(), format(pattern)	Allows you to print a OffsetTime on a default pattern or by providing a custom pattern.	${myoffsettime.format()} or ${myoffsettime.format('HH mm ss')}
Period	days(), months(), years()	Gives access to the values of the Period object.	${myperiod.days}, ${myperiod.months}, ${myperiod.years}
Year	format(), format(pattern)	Allows you to print a Year on a default pattern or by providing a custom pattern.	${myyear.format()} or ${myyear.format('yyyy')}
YearMonth	format(), format(pattern)	Allows you to print a YearMonth on a default pattern or by providing a custom pattern.	${myyear.format()} or ${myyear.format('yyyy MM')}
ZonedDateTime	format(), format(pattern), format(pattern, zoneId)	Allows you to print a YearMonth on a default pattern/timezone or by providing a custom pattern and timezone.	${myzoneddatetime.format()} or ${myzoneddatetime.format('yyyy-MM-dd Z')} or ${myzoneddatetime.format('yyyy-MM-dd Z', 'Asia/Seoul')}
ZoneId	format(), format(textStyle), format(textstyle, locale)	Prints the ZoneId display name. You can override the textstyle with one of these values [FULL, FULL_STANDALONE, SHORT, SHORT_STANDALONE, NARROW and NARROW_STANDALONE]. You can also override the locale, but Java only seems to have locale support for a few languages.	${myzoneid.format()} or ${myzoneid.format('short')} or ${myzoneid.format('short', 'no-NO')}