FREEMARKER-60: Document interaction between lazy import and #global
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/96d3971c Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/96d3971c Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/96d3971c Branch: refs/heads/2.3 Commit: 96d3971cc6f21974729f4fc0a7dec159b5a4ff42 Parents: 5d81db7 Author: ddekany <ddek...@apache.org> Authored: Tue Jul 4 21:05:06 2017 +0200 Committer: ddekany <ddek...@apache.org> Committed: Tue Jul 4 21:05:06 2017 +0200 ---------------------------------------------------------------------- src/main/java/freemarker/core/Configurable.java | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/96d3971c/src/main/java/freemarker/core/Configurable.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java index 4887dfe..492282a 100644 --- a/src/main/java/freemarker/core/Configurable.java +++ b/src/main/java/freemarker/core/Configurable.java @@ -1703,16 +1703,20 @@ public class Configurable { /** * Specifies if {@code <#import ...>} (and {@link Environment#importLib(String, String)}) should delay the loading * and processing of the imported templates until the content of the imported namespace is actually accessed. This - * makes the overhead of <em>unused</em> imports negligible. A drawback is that importing a missing or otherwise - * broken template will be successful, and the problem will remain hidden until (and if) the namespace content is - * actually used. Also, you lose the strict control over when the namespace initializing code in the imported - * template will be executed, though it shouldn't mater for well written imported templates anyway. Note that the - * namespace initializing code will run with the same {@linkplain Configurable#getLocale() locale} as it was at the - * point of the {@code <#import ...>} call (other settings won't be handled specially like that). + * makes the overhead of <em>unused</em> imports negligible. Note that turning on lazy importing isn't entirely + * transparent, as accessing global variables (usually created with {@code <#global ...=...>}) that should be + * created by the imported template won't trigger the loading and processing of the lazily imported template + * (because globals aren't accessed through the namespace variable), so the global variable will just be missing. + * In general, you lose the strict control over when the namespace initializing code in the imported template will + * be executed, though it shouldn't mater for most well designed imported templates. + * Another drawback is that importing a missing or otherwise broken template will be successful, and the problem + * will remain hidden until (and if) the namespace content is actually used. Note that the namespace initializing + * code will run with the same {@linkplain Configurable#getLocale() locale} as it was at the point of the + * {@code <#import ...>} call (other settings won't be handled specially like that). * * <p> * The default is {@code false} (and thus imports are eager) for backward compatibility, which can cause - * perceivable overhead if you have many imports and only a few of them is used. + * perceivable overhead if you have many imports and only a few of them is actually used. * * <p> * This setting also affects {@linkplain #setAutoImports(Map) auto-imports}, unless you have set a non-{@code null}