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

All Methods Instance Methods Abstract Methods Concrete Methods
`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 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 Object` `parse(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 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 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 Object parse(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`.