Package freemarker.core
Class TemplateDateFormat
java.lang.Object
freemarker.core.TemplateValueFormat
freemarker.core.TemplateDateFormat
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 -
Method Summary
Modifier and TypeMethodDescriptionformat(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 String
formatToPlainText(TemplateDateModel dateModel)
abstract boolean
Tells if this formatter should be re-created if the locale changes.abstract boolean
Tells if this formatter should be re-created if the time zone changes.abstract Object
Parsers a string to date/time/datetime, according to this format.Methods inherited from class freemarker.core.TemplateValueFormat
getDescription
-
Constructor Details
-
TemplateDateFormat
public TemplateDateFormat()
-
-
Method Details
-
formatToPlainText
public abstract String formatToPlainText(TemplateDateModel dateModel) throws TemplateValueFormatException, TemplateModelException- Parameters:
dateModel
- The date/time/dateTime to format; notnull
. Most implementations will just work with the return value ofTemplateDateModel.getAsDate()
, but some may format differently depending on the properties of a customTemplateDateModel
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 thedateModel
object when calling its methods.
-
format
public Object format(TemplateDateModel dateModel) throws TemplateValueFormatException, TemplateModelExceptionFormats 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 offormatToPlainText(TemplateDateModel)
escaped, it must return theString
thatformatToPlainText(TemplateDateModel)
does.The implementation in
TemplateDateFormat
simply callsformatToPlainText(TemplateDateModel)
.- Returns:
- A
String
or aTemplateMarkupOutputModel
; notnull
. - Throws:
TemplateValueFormatException
TemplateModelException
-
parse
Parsers a string to date/time/datetime, according to this format. Some format implementations may throwParsingNotSupportedException
here.- Parameters:
s
- The string to parsedateType
- The expected date type of the result. Not allTemplateDateFormat
-s will care about this; though those who return aTemplateDateModel
instead ofDate
often will. When strings are parsed via?date
,?time
, or?datetime
, then this parameter isTemplateDateModel.DATE
,TemplateDateModel.TIME
, orTemplateDateModel.DATETIME
, respectively. This parameter rarely if everTemplateDateModel.UNKNOWN
, but the implementation that cares about this parameter should be prepared for that. If nothing else, it should throwUnknownDateTypeParsingUnsupportedException
then.- Returns:
- The interpretation of the text either as a
Date
orTemplateDateModel
. Typically, aDate
.TemplateDateModel
is used if you have to attach some application-specific meta-information thats also extracted duringformatToPlainText(TemplateDateModel)
(so if you format something and then parse it, you get back an equivalent result). It can't benull
. Known issue (at least in FTL 2):?date
/?time
/?datetime
, when not invoked as a method, can't return theTemplateDateModel
, only theDate
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 alwaystrue
.
-