freemarker.core

Class AliasTemplateDateFormatFactory

java.lang.Object

freemarker.core.TemplateValueFormatFactory

freemarker.core.TemplateDateFormatFactory

freemarker.core.AliasTemplateDateFormatFactory

public final class AliasTemplateDateFormatFactory
extends TemplateDateFormatFactory

Creates an alias to another format, so that the format can be referred to with a simple name in the template, rather than as a concrete pattern or other kind of format string.

Since:

2.3.24

Constructor Summary

Constructors

Constructor and Description
AliasTemplateDateFormatFactory(java.lang.String targetFormatString)
AliasTemplateDateFormatFactory(java.lang.String defaultTargetFormatString, java.util.Map<java.util.Locale,java.lang.String> localizedTargetFormatStrings)

Method Summary

Modifier and Type	Method and Description
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

AliasTemplateDateFormatFactory

public AliasTemplateDateFormatFactory(java.lang.String targetFormatString)

Parameters:

targetFormatString - The format string this format will be an alias to.

AliasTemplateDateFormatFactory

public AliasTemplateDateFormatFactory(java.lang.String defaultTargetFormatString,
                                      java.util.Map<java.util.Locale,java.lang.String> localizedTargetFormatStrings)

Parameters:

defaultTargetFormatString - The format string this format will be an alias to if there's no locale-specific format string for the requested locale in localizedTargetFormatStrings

localizedTargetFormatStrings - Maps Locale-s to format strings. If the desired locale doesn't occur in the map, a less specific locale is tried, repeatedly until only the language part remains. For example, if locale is new Locale("en", "US", "Linux"), then these keys will be attempted untol a match is found, in this order: new Locale("en", "US", "Linux"), new Locale("en", "US"), new Locale("en"). If there's still no matching key, the value of the targetFormatString will be used.

Method Detail

get

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

Description copied from class: TemplateDateFormatFactory

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.

Specified by:

get in class TemplateDateFormatFactory

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.