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

freemarker.cache

## Class TemplateLookupContext

- java.lang.Object
- - freemarker.cache.TemplateLookupContext

-     public abstract class TemplateLookupContext
      extends Object

  Used as the parameter of `TemplateLookupStrategy.lookup(TemplateLookupContext)`. You can't create instances of this, only receive them from FreeMarker.
  Since:
    2.3.22

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TemplateLookupResult` | `createNegativeLookupResult()` Creates a not-found lookup result that then can be used as the return value of `TemplateLookupStrategy.lookup(TemplateLookupContext)`.
    `Object` | `getCustomLookupCondition()` Returns the value of the `customLookupCondition` parameter of `Configuration.getTemplate(String, Locale, Object, String, boolean, boolean)`; see requirements there, such as having a proper `Object.equals(Object)` and `Object.hashCode()` method.
    `Locale` | `getTemplateLocale()` `null` if localized lookup is disabled (see `Configuration.getLocalizedLookup()`), otherwise the locale requested.
    `String` | `getTemplateName()` The normalized name (path) of the template (relatively to the `TemplateLoader`).
    `abstract TemplateLookupResult` | `lookupWithAcquisitionStrategy(String templateName)` Finds the template source based on its normalized name; handles `*` steps (so called acquisition), otherwise it just calls `TemplateLoader.findTemplateSource(String)`.
    `abstract TemplateLookupResult` | `lookupWithLocalizedThenAcquisitionStrategy(String templateName, Locale templateLocale)` Finds the template source based on its normalized name; tries localized variations going from most specific to less specific, and for each variation it delegates to `lookupWithAcquisitionStrategy(String)`.

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

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

- - ### Method Detail

    - #### lookupWithAcquisitionStrategy

          public abstract TemplateLookupResult lookupWithAcquisitionStrategy(String templateName)
                                                                      throws IOException

      Finds the template source based on its normalized name; handles `*` steps (so called acquisition), otherwise it just calls `TemplateLoader.findTemplateSource(String)`.
      Parameters:
        `templateName` - Must be a normalized name, like `"foo/bar/baaz.ftl"`. A name is not normalized when, among others, it starts with `/`, or contains `.` or `..` paths steps, or it uses backslash (`\`) instead of `/`. A normalized name might contains "*" steps.
      Returns:
        The result of the lookup. Not `null`; check `TemplateLookupResult.isPositive()` to see if the lookup has found anything.
      Throws:
        `IOException`

    - #### lookupWithLocalizedThenAcquisitionStrategy

          public abstract TemplateLookupResult lookupWithLocalizedThenAcquisitionStrategy(String templateName,
                                                                                          Locale templateLocale)
                                                                                   throws IOException

      Finds the template source based on its normalized name; tries localized variations going from most specific to less specific, and for each variation it delegates to `lookupWithAcquisitionStrategy(String)`. If `templateLocale` is `null` (typically, because `Configuration.getLocalizedLookup()` is `false`)), then it's the same as calling `lookupWithAcquisitionStrategy(String)` directly. This is the default strategy of FreeMarker (at least in 2.3.x), so for more information, see `TemplateLookupStrategy.DEFAULT_2_3_0`.
      Throws:
        `IOException`

    - #### getTemplateName

          public String getTemplateName()

      The normalized name (path) of the template (relatively to the `TemplateLoader`). Not `null`.

    - #### getTemplateLocale

          public Locale getTemplateLocale()

      `null` if localized lookup is disabled (see `Configuration.getLocalizedLookup()`), otherwise the locale requested.

    - #### getCustomLookupCondition

          public Object getCustomLookupCondition()

      Returns the value of the `customLookupCondition` parameter of `Configuration.getTemplate(String, Locale, Object, String, boolean, boolean)`; see requirements there, such as having a proper `Object.equals(Object)` and `Object.hashCode()` method. The interpretation of this value is up to the custom `TemplateLookupStrategy`. Usually, it's used similarly to as the default lookup strategy uses `getTemplateLocale()`, that is, to look for a template variation that satisfies the condition, and then maybe fall back to more generic template if that's missing.

    - #### createNegativeLookupResult

          public TemplateLookupResult createNegativeLookupResult()

      Creates a not-found lookup result that then can be used as the return value of `TemplateLookupStrategy.lookup(TemplateLookupContext)`. (In the current implementation it just always returns the same static singleton, but that might need to change in the future.)