freemarker.core

Class TemplateDateFormat

java.lang.Object

freemarker.core.TemplateValueFormat

freemarker.core.TemplateDateFormat

public abstract class TemplateDateFormat
extends TemplateValueFormat

Represents a date/time/dateTime format; used in templates for formatting and parsing with that format. This is similar to Java's DateFormat, but made to fit the requirements of FreeMarker. Also, it makes easier to define formats that can't be represented with Java's existing DateFormat implementations.

Implementations need not be thread-safe if the TemplateNumberFormatFactory doesn't recycle them among different Environment-s. As far as FreeMarker's concerned, instances are bound to a single Environment, and Environment-s are thread-local objects.

Since:

2.3.24

Constructor Summary

Constructors

Constructor and Description
TemplateDateFormat()

Method Summary

Modifier and Type	Method and Description
java.lang.Object	format(TemplateDateModel dateModel) Formats the model to markup instead of to plain text if the result markup will be more than just plain text escaped, otherwise falls back to formatting to plain text.
abstract java.lang.String	formatToPlainText(TemplateDateModel dateModel)
abstract boolean	isLocaleBound() Tells if this formatter should be re-created if the locale changes.
abstract boolean	isTimeZoneBound() Tells if this formatter should be re-created if the time zone changes.
abstract java.lang.Object	parse(java.lang.String s, int dateType) Parsers a string to date/time/datetime, according to this format.

Methods inherited from class freemarker.core.TemplateValueFormat

getDescription

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TemplateDateFormat

public TemplateDateFormat()

Method Detail

formatToPlainText

public abstract java.lang.String formatToPlainText(TemplateDateModel dateModel)
                                            throws TemplateValueFormatException,
                                                   TemplateModelException

Parameters:

dateModel - The date/time/dateTime to format; not null. Most implementations will just work with the return value of TemplateDateModel.getAsDate(), but some may format differently depending on the properties of a custom TemplateDateModel implementation.

Returns:

The date/time/dateTime as text, with no escaping (like no HTML escaping); can't be null.

Throws:

TemplateValueFormatException - When a problem occurs during the formatting of the value. Notable subclass: UnknownDateTypeFormattingUnsupportedException

TemplateModelException - Exception thrown by the dateModel object when calling its methods.

format

public java.lang.Object format(TemplateDateModel dateModel)
                        throws TemplateValueFormatException,
                               TemplateModelException

Formats the model to markup instead of to plain text if the result markup will be more than just plain text escaped, otherwise falls back to formatting to plain text. If the markup result would be just the result of formatToPlainText(TemplateDateModel) escaped, it must return the String that formatToPlainText(TemplateDateModel) does.

The implementation in TemplateDateFormat simply calls formatToPlainText(TemplateDateModel).

Returns:

A String or a TemplateMarkupOutputModel; not null.

Throws:

TemplateValueFormatException

TemplateModelException

parse

public abstract java.lang.Object parse(java.lang.String s,
                                       int dateType)
                                throws TemplateValueFormatException

Parsers a string to date/time/datetime, according to this format. Some format implementations may throw ParsingNotSupportedException here.

Parameters:

s - The string to parse

dateType - The expected date type of the result. Not all TemplateDateFormat-s will care about this; though those who return a TemplateDateModel instead of Date often will. When strings are parsed via ?date, ?time, or ?datetime, then this parameter is TemplateDateModel.DATE, TemplateDateModel.TIME, or TemplateDateModel.DATETIME, respectively. This parameter rarely if ever TemplateDateModel.UNKNOWN, but the implementation that cares about this parameter should be prepared for that. If nothing else, it should throw UnknownDateTypeParsingUnsupportedException then.

Returns:

The interpretation of the text either as a Date or TemplateDateModel. Typically, a Date. TemplateDateModel is used if you have to attach some application-specific meta-information thats also extracted during formatToPlainText(TemplateDateModel) (so if you format something and then parse it, you get back an equivalent result). It can't be null. Known issue (at least in FTL 2): ?date/?time/?datetime, when not invoked as a method, can't return the TemplateDateModel, only the Date from inside it, hence the additional application-specific meta-info will be lost.

Throws:

TemplateValueFormatException

isLocaleBound

public abstract boolean isLocaleBound()

Tells if this formatter should be re-created if the locale changes.

isTimeZoneBound

public abstract boolean isTimeZoneBound()

Tells if this formatter should be re-created if the time zone changes. Currently always true.