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