Package 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'sDateFormat
, but made to fit the requirements of FreeMarker. Also, it makes easier to define formats that can't be represented with Java's existingDateFormat
implementations.Implementations need not be thread-safe if the
TemplateNumberFormatFactory
doesn't recycle them among differentEnvironment
-s. As far as FreeMarker's concerned, instances are bound to a singleEnvironment
, andEnvironment
-s are thread-local objects.- Since:
- 2.3.24
-
-
Constructor Summary
Constructors Constructor Description TemplateDateFormat()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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
-
-
-
-
Method Detail
-
formatToPlainText
public abstract java.lang.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 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 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
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 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
.
-
-