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

Package freemarker.cache

# Class TemplateLookupStrategy

java.lang.Object
freemarker.cache.TemplateLookupStrategy

public abstract class TemplateLookupStrategy extends Object
Finds the `TemplateLoader`-level (storage-level) template source for the template name with which the template was requested (as in `Configuration.getTemplate(String)`). This usually means trying various `TemplateLoader`-level template names (so called source names; see also `Template.getSourceName()`) that were deduced from the requested name. Trying a name usually means calling `TemplateLookupContext.lookupWithAcquisitionStrategy(String)` with it and checking the value of `TemplateLookupResult.isPositive()`.

Before you write your own lookup strategy, know that:

- A template lookup strategy meant to operate solely with template names, not with `TemplateLoader`-s directly. Basically, it's a mapping between the template names that templates and API-s like `Configuration.getTemplate(String)` see, and those that the underlying `TemplateLoader` sees.
- A template lookup strategy doesn't influence the template's name (`Template.getName()`), which is the normalized form of the template name as it was requested (with `Configuration.getTemplate(String)`, etc.). It only influences the so-called source name of the template (`Template.getSourceName()`). The template's name is used as the basis for resolving relative inclusions/imports in the template. The source name is pretty much only used in error messages as error location, and of course, to actually load the template "file".
- Understand the impact of the last point if your template lookup strategy fiddles not only with the file name part of the template name, but also with the directory part. For example, one may want to map "foo.ftl" to "en/foo.ftl", "fr/foo.ftl", etc. That's legal, but the result is kind of like if you had several root directories ("en/", "fr/", etc.) that are layered over each other to form a single merged directory. (This is what's desirable in typical applications, yet it can be confusing.)

Since:
  2.3.22
See Also:
  `Configuration.setTemplateLookupStrategy(TemplateLookupStrategy)`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static TemplateLookupStrategy`
  `DEFAULT_2_3_0`
  The default lookup strategy of FreeMarker.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TemplateLookupStrategy()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract TemplateLookupResult`
  `lookup​(TemplateLookupContext ctx)`
  Finds the template source that matches the template name, locale (if not `null`) and other parameters specified in the `TemplateLookupContext`.

  ### 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 TemplateLookupStrategy DEFAULT_2_3_0
    The default lookup strategy of FreeMarker.

    Through an example: Assuming localized lookup is enabled and that a template is requested for the name `example.ftl` and `Locale("es", "ES", "Traditional_WIN")`, it will try the following template names, in this order: `"foo_en_AU_Traditional_WIN.ftl"`, `"foo_en_AU_Traditional.ftl"`, `"foo_en_AU.ftl"`, `"foo_en.ftl"`, `"foo.ftl"`. It stops at the first variation where it finds a template. (If the template name contains "*" steps, finding the template for the attempted localized variation happens with the template acquisition mechanism.) If localized lookup is disabled, it won't try to add any locale strings, so it just looks for `"foo.ftl"`.

    The generation of the localized name variation with the default lookup strategy, happens like this: It removes the file extension (the part starting with the last dot), then appends `Locale.toString()` after it, and puts back the extension. Then it starts to remove the parts from the end of the locale, considering `"_"` as the separator between the parts. It won't remove parts that are not part of the locale string (like if the requested template name is `foo_bar.ftl`, it won't remove the `"_bar"`).

- ## Constructor Details

  - ### TemplateLookupStrategy

    public TemplateLookupStrategy()

- ## Method Details

  - ### lookup

    public abstract TemplateLookupResult lookup​(TemplateLookupContext ctx) throws IOException
    Finds the template source that matches the template name, locale (if not `null`) and other parameters specified in the `TemplateLookupContext`. See also the class-level `TemplateLookupStrategy` documentation to understand lookup strategies more.
    Parameters:
      `ctx` - Contains the parameters for which the matching template need to be found, and operations that are needed to implement the strategy. Some of the important input parameters are: `TemplateLookupContext.getTemplateName()`, `TemplateLookupContext.getTemplateLocale()`. The most important operations are `TemplateLookupContext.lookupWithAcquisitionStrategy(String)` and `TemplateLookupContext.createNegativeLookupResult()`. (Note that you deliberately can't use `TemplateLoader`-s directly to implement lookup.)
    Returns:
      Usually the return value of `TemplateLookupContext.lookupWithAcquisitionStrategy(String)`, or `TemplateLookupContext#createNegativeLookupResult()` if no matching template exists. Can't be `null`.
    Throws:
      `IOException`