TemplateNameFormat (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.cache, class: TemplateNameFormat

Package freemarker.cache

# Class TemplateNameFormat

java.lang.Object
freemarker.cache.TemplateNameFormat

public abstract class TemplateNameFormat extends Object
Symbolizes a template name format, which defines the basic syntax of names through algorithms such as normalization. The API of this class isn't exposed as it's too immature, so custom template name formats aren't possible yet.

Since:
  2.3.22

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static TemplateNameFormat`
  `DEFAULT_2_3_0`
  The default template name format when `incompatible_improvements` is below 2.4.0.
  `static TemplateNameFormat`
  `DEFAULT_2_4_0`
  The default template name format only when `incompatible_improvements` is set to 2.4.0 (or higher).

- ## Method Summary

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_2_3_0

    public static final TemplateNameFormat DEFAULT_2_3_0
    The default template name format when `incompatible_improvements` is below 2.4.0. As of FreeMarker 2.4.0, the default `incompatible_improvements` is still `2.3.0`, and it will certainly remain so for a very long time. In new projects it's highly recommended to use `DEFAULT_2_4_0` instead.

  - ### DEFAULT_2_4_0

    public static final TemplateNameFormat DEFAULT_2_4_0
    The default template name format only when `incompatible_improvements` is set to 2.4.0 (or higher). This is not the out-of-the-box default format of FreeMarker 2.4.x, because the default `incompatible_improvements` is still 2.3.0 there.

    Differences to the `DEFAULT_2_3_0` format:

    - The scheme and the path need not be separated with `"://"` anymore, only with `":"`. This makes template names like `"classpath:foo.ftl"` interpreted as an absolute name with scheme `"classpath"` and absolute path "foo.ftl". The scheme name before the `":"` can't contain `"/"`, or else it's treated as a malformed name. The scheme part can be separated either with `"://"` or just `":"` from the path. Hence, `myscheme:/x` is normalized to `myscheme:x`, while `myscheme:///x` is normalized to `myscheme://x`, but `myscehme://x` or `myscheme:/x` aren't changed by normalization. It's up the `TemplateLoader` to which the normalized names are passed to decide which of these scheme separation conventions are valid (maybe both).
    - `":"` is not allowed in template names, except as the scheme separator (see previous point).
    - Malformed paths throw `MalformedTemplateNameException` instead of acting like if the template wasn't found.
    - `"\"` (backslash) is not allowed in template names, and causes `MalformedTemplateNameException`. With `DEFAULT_2_3_0` you would certainly end up with a `TemplateNotFoundException` (or worse, it would work, but steps like `".."` wouldn't be normalized by FreeMarker).
    - Template names might end with `/`, like `"foo/"`, and the presence or lack of the terminating `/` is seen as significant. While their actual interpretation is up to the `TemplateLoader`, operations that manipulate template names assume that the last step refers to a "directory" as opposed to a "file" exactly if the terminating `/` is present. Except, the empty name is assumed to refer to the root "directory" (despite that it doesn't end with `/`).
    - `//` is normalized to `/`, except of course if it's in the scheme name terminator. Like `foo//bar///baaz.ftl` is normalized to `foo/bar/baaz.ftl`. (In general, 0 long step names aren't possible anymore.)
    - The `".."` bugs of the legacy normalizer are fixed: `".."` steps has removed the preceding `"."` or `"*"` or scheme steps, not treating them specially as they should be. Now these work as expected. Examples: `"a/./../c"` has become to `"a/c"`, now it will be `"c"`; `"a/b/*` `/../c"` has become to `"a/b/c"`, now it will be `"a/*``/c"`; `"scheme://.."` has become to `"scheme:/"`, now it will be `null` (`TemplateNotFoundException`) for backing out of the root directory.
    - As now directory paths has to be handled as well, it recognizes terminating, leading, and lonely `".."` and `"."` steps. For example, `"foo/bar/.."` now becomes to `"foo/"`
    - Multiple consecutive `*` steps are normalized to one