TemplateNameFormat (FreeMarker 2.3.23 API)
Date: 2015-07-05

freemarker.cache

## Class TemplateNameFormat

- java.lang.Object
- - freemarker.cache.TemplateNameFormat

-     public abstract class TemplateNameFormat
      extends Object

  Symbolized template name format. 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 and 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 Detail

    - #### 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, `myschme:/x` is normalized to `myschme:x`, while `myschme:///x` is normalized to `myschme://x`, but `myschme://x` or `myschme:/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