freemarker.core

Class TemplateDateFormatFactory

java.lang.Object

freemarker.core.TemplateValueFormatFactory

freemarker.core.TemplateDateFormatFactory

Direct Known Subclasses:

AliasTemplateDateFormatFactory

public abstract class TemplateDateFormatFactory
extends TemplateValueFormatFactory

Factory for a certain kind of date/time/dateTime formatting (TemplateDateFormat). Usually a singleton (one-per-VM or one-per-Configuration), and so must be thread-safe.

Since:

2.3.24

See Also:

Configurable.setCustomDateFormats(java.util.Map)

Constructor Summary

Constructors

Constructor and Description
TemplateDateFormatFactory()

Method Summary

Modifier and Type	Method and Description
abstract TemplateDateFormat	get(java.lang.String params, int dateType, java.util.Locale locale, java.util.TimeZone timeZone, boolean zonelessInput, Environment env) Returns a formatter for the given parameters.

Methods inherited from class java.lang.Object

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

Constructor Detail

TemplateDateFormatFactory

public TemplateDateFormatFactory()

Method Detail

get

public abstract TemplateDateFormat get(java.lang.String params,
                                       int dateType,
                                       java.util.Locale locale,
                                       java.util.TimeZone timeZone,
                                       boolean zonelessInput,
                                       Environment env)
                                throws TemplateValueFormatException

Returns a formatter for the given parameters.

The returned formatter can be a new instance or a reused (cached) instance. Note that Environment itself caches the returned instances, though that cache is lost with the Environment (i.e., when the top-level template execution ends), also it might flushes lot of entries if the locale or time zone is changed during template execution. So caching on the factory level is still useful, unless creating the formatters is sufficiently cheap.

Parameters:

params - The string that further describes how the format should look. For example, when the dateFormat is "@fooBar 1, 2", then it will be "1, 2" (and "@fooBar" selects the factory). The format of this string is up to the TemplateDateFormatFactory implementation. Not null, often an empty string.

dateType - TemplateDateModel.DATE, TemplateDateModel.TIME, TemplateDateModel.DATETIME or TemplateDateModel.UNKNOWN. Supporting TemplateDateModel.UNKNOWN is not necessary, in which case the method should throw an UnknownDateTypeFormattingUnsupportedException exception.

locale - The locale to format for. Not null. The resulting format should be bound to this locale forever (i.e. locale changes in the Environment must not be followed).

timeZone - The time zone to format for. Not null. The resulting format must be bound to this time zone forever (i.e. time zone changes in the Environment must not be followed).

zonelessInput - Indicates that the input Java Date is not from a time zone aware source. When this is true, the formatters shouldn't override the time zone provided to its constructor (most formatters don't do that anyway), and it shouldn't show the time zone, if it can hide it (like a SimpleDateFormat pattern-based formatter may can't do that, as the pattern prescribes what to show).

As of FreeMarker 2.3.21, this is true exactly when the date is an SQL "date without time of the day" (i.e., a java.sql.Date) or an SQL "time of the day" value (i.e., a java.sql.Time, although this rule can change in future, depending on configuration settings and such, so you shouldn't rely on this rule, just accept what this parameter says.

env - The runtime environment from which the formatting was called. This is mostly meant to be used for Environment.setCustomState(Object, Object)/Environment.getCustomState(Object).

Throws:

TemplateValueFormatException - If any problem occurs while parsing/getting the format. Notable subclasses: InvalidFormatParametersException if params is malformed; UnknownDateTypeFormattingUnsupportedException if dateType is TemplateDateModel.UNKNOWN and that's unsupported by this factory.