http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/NonStringOrTemplateOutputException.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/NonStringOrTemplateOutputException.java b/src/main/java/org/apache/freemarker/core/NonStringOrTemplateOutputException.java index 7be9458..ddeb811 100644 --- a/src/main/java/org/apache/freemarker/core/NonStringOrTemplateOutputException.java +++ b/src/main/java/org/apache/freemarker/core/NonStringOrTemplateOutputException.java @@ -30,7 +30,7 @@ import org.apache.freemarker.core.model.TemplateScalarModel; public class NonStringOrTemplateOutputException extends UnexpectedTypeException { static final String STRING_COERCABLE_TYPES_OR_TOM_DESC - = NonStringException.STRING_COERCABLE_TYPES_DESC + ", or \"template output\" "; + = NonStringException.STRING_COERCABLE_TYPES_DESC + ", or \"template output\""; static final Class[] STRING_COERCABLE_TYPES_AND_TOM; static {
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java b/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java index b62daac..0eb9569 100644 --- a/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java +++ b/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java @@ -21,24 +21,73 @@ package org.apache.freemarker.core; import java.nio.charset.Charset; import org.apache.freemarker.core.arithmetic.ArithmeticEngine; +import org.apache.freemarker.core.outputformat.MarkupOutputFormat; import org.apache.freemarker.core.outputformat.OutputFormat; +import org.apache.freemarker.core.outputformat.impl.HTMLOutputFormat; +import org.apache.freemarker.core.outputformat.impl.UndefinedOutputFormat; +import org.apache.freemarker.core.outputformat.impl.XMLOutputFormat; /** * Implemented by FreeMarker core classes (not by you) that provide configuration settings that affect template parsing * (as opposed to {@linkplain Template#process (Object, Writer) template processing}). <b>New methods may be added - * anytime in future FreeMarker versions, so don't try to implement this interface yourself!</b> + * any time in future FreeMarker versions, so don't try to implement this interface yourself!</b> * * @see ProcessingConfiguration + * @see ParsingAndProcessingConfiguration */ -// TODO Clean up API docs like in ProcessingConfiguration, when Configuration is done public interface ParsingConfiguration { + int AUTO_DETECT_NAMING_CONVENTION = 10; + int LEGACY_NAMING_CONVENTION = 11; + int CAMEL_CASE_NAMING_CONVENTION = 12; + + int AUTO_DETECT_TAG_SYNTAX = 0; + int ANGLE_BRACKET_TAG_SYNTAX = 1; + int SQUARE_BRACKET_TAG_SYNTAX = 2; + + /** + * Don't enable auto-escaping, regardless of what the {@link OutputFormat} is. Note that a {@code + * <#ftl auto_esc=true>} in the template will override this. + */ + int DISABLE_AUTO_ESCAPING_POLICY = 20; + /** + * Enable auto-escaping if the output format supports it and {@link MarkupOutputFormat#isAutoEscapedByDefault()} is + * {@code true}. + */ + int ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY = 21; + /** Enable auto-escaping if the {@link OutputFormat} supports it. */ + int ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY = 22; + + /** + * The template language used; this is often overridden for certain file extension with the + * {@link Configuration#getTemplateConfigurations() templateConfigurations} setting of the {@link Configuration}. + */ TemplateLanguage getTemplateLanguage(); boolean isTemplateLanguageSet(); /** - * See {@link Configuration#getTagSyntax()}. + * Determines the syntax of the template files (angle bracket VS square bracket) + * that has no {@code #ftl} in it. The {@code tagSyntax} + * parameter must be one of: + * <ul> + * <li>{@link #AUTO_DETECT_TAG_SYNTAX}: + * use the syntax of the first FreeMarker tag (can be anything, like <tt>#list</tt>, + * <tt>#include</tt>, user defined, etc.) + * <li>{@link #ANGLE_BRACKET_TAG_SYNTAX}: + * use the angle bracket syntax (the normal syntax) + * <li>{@link #SQUARE_BRACKET_TAG_SYNTAX}: + * use the square bracket syntax + * </ul> + * + * <p>In FreeMarker 2.3.x {@link #ANGLE_BRACKET_TAG_SYNTAX} is the + * default for better backward compatibility. Starting from 2.4.x {@link + * ParsingConfiguration#AUTO_DETECT_TAG_SYNTAX} is the default, so it's recommended to use + * that even for 2.3.x. + * + * <p>This setting is ignored for the templates that have {@code ftl} directive in + * it. For those templates the syntax used for the {@code ftl} directive determines + * the syntax. */ int getTagSyntax(); @@ -50,7 +99,44 @@ public interface ParsingConfiguration { boolean isTagSyntaxSet(); /** - * See {@link Configuration#getNamingConvention()}. + * The naming convention used for the identifiers that are part of the template language. The available naming + * conventions are legacy (directive (tag) names are all-lower-case {@code likethis}, others are snake case + * {@code like_this}), and camel case ({@code likeThis}). The default is auto-detect, which detects the naming + * convention used and enforces that same naming convention for the whole template. + * + * <p> + * This setting doesn't influence what naming convention is used for the setting names outside templates. Also, it + * won't ever convert the names of user-defined things, like of data-model members, or the names of user defined + * macros/functions. It only influences the names of the built-in directives ({@code #elseIf} VS {@code elseif}), + * built-ins ({@code ?upper_case} VS {@code ?upperCase} ), special variables ({@code .data_model} VS + * {@code .dataModel}). + * + * <p> + * Which convention to use: FreeMarker prior to 2.3.23 has only supported + * {@link #LEGACY_NAMING_CONVENTION}, so that's how most templates and examples out there are written + * as of 2015. But as templates today are mostly written by programmers and often access Java API-s which already + * use camel case, {@link #CAMEL_CASE_NAMING_CONVENTION} is the recommended option for most projects. + * However, it's no necessary to make a application-wide decision; see auto-detection below. + * + * <p> + * FreeMarker will decide the naming convention automatically for each template individually when this setting is + * set to {@link #AUTO_DETECT_NAMING_CONVENTION} (which is the default). The naming convention of a template is + * decided when the first core (non-user-defined) identifier is met during parsing (not during processing) where the + * naming convention is relevant (like for {@code s?upperCase} or {@code s?upper_case} it's relevant, but for + * {@code s?length} it isn't). At that point, the naming convention of the template is decided, and any later core + * identifier that uses a different convention will be a parsing error. As the naming convention is decided per + * template, it's not a problem if a template and the other template it {@code #include}-s/{@code #import} uses a + * different convention. + * + * <p> + * FreeMarker always enforces the same naming convention to be used consistently within the same template "file". + * Additionally, when this setting is set to non-{@link #AUTO_DETECT_NAMING_CONVENTION}, the selected naming + * convention is enforced on all templates. Thus such a setup can be used to enforce an application-wide naming + * convention. + * + * @return + * One of the {@link #AUTO_DETECT_NAMING_CONVENTION} or + * {@link #LEGACY_NAMING_CONVENTION} or {@link #CAMEL_CASE_NAMING_CONVENTION}. */ int getNamingConvention(); @@ -62,7 +148,7 @@ public interface ParsingConfiguration { boolean isNamingConventionSet(); /** - * See {@link Configuration#getWhitespaceStripping()}. + * Whether the template parser will try to remove superfluous white-space around certain tags. */ boolean getWhitespaceStripping(); @@ -99,7 +185,25 @@ public interface ParsingConfiguration { boolean isAutoEscapingPolicySet(); /** - * See {@link Configuration#getOutputEncoding()}. + * The output format to use, which among others influences auto-escaping (see {@link #getAutoEscapingPolicy} + * autoEscapingPolicy}), and possibly the MIME type of the output. + * <p> + * On the {@link Configuration} level, usually, you should leave this on its default, which is + * {@link UndefinedOutputFormat#INSTANCE}, and then use standard file extensions like "ftlh" (for HTML) or "ftlx" + * (for XML) (and ensure that {@link #getRecognizeStandardFileExtensions() recognizeStandardFileExtensions} is + * {@code true}; see more there). Where you can't use the standard extensions, templates still can be associated + * to output formats with patterns matching their name (their path) using the + * {@link Configuration#getTemplateConfigurations() templateConfigurations} setting of the {@link Configuration}. + * But if all templates will have the same output format, you may set the + * {@link #getOutputFormat() outputFormat} setting of the {@link Configuration} + * after all, to a value like {@link HTMLOutputFormat#INSTANCE}, {@link XMLOutputFormat#INSTANCE}, etc. Also + * note that templates can specify their own output format like {@code <#ftl output_format="HTML">}, which + * overrides any configuration settings. + * + * @see Configuration#getRegisteredCustomOutputFormats() + * @see Configuration#getTemplateConfigurations() + * @see #getRecognizeStandardFileExtensions() + * @see #getAutoEscapingPolicy() */ OutputFormat getOutputFormat(); @@ -111,7 +215,29 @@ public interface ParsingConfiguration { boolean isOutputFormatSet(); /** - * See {@link Configuration#getRecognizeStandardFileExtensions()}. + * Tells if the "file" extension part of the source name ({@link Template#getSourceName()}) will influence certain + * parsing settings. For backward compatibility, it defaults to {@code false} if + * {@link #getIncompatibleImprovements()} is less than 2.3.24. Starting from {@code incompatibleImprovements} + * 2.3.24, it defaults to {@code true}, so the following standard file extensions take their effect: + * + * <ul> + * <li>{@code ftlh}: Sets the {@link #getOutputFormat() outputFormat} setting to {@code "HTML"} + * (i.e., {@link HTMLOutputFormat#INSTANCE}, unless the {@code "HTML"} name is overridden by + * the {@link Configuration#getRegisteredCustomOutputFormats registeredOutputFormats} setting) and + * the {@link #getAutoEscapingPolicy() autoEscapingPolicy} setting to + * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}. + * <li>{@code ftlx}: Sets the {@link #getOutputFormat() outputFormat} setting to + * {@code "XML"} (i.e., {@link XMLOutputFormat#INSTANCE}, unless the {@code "XML"} name is overridden by + * the {@link Configuration#getRegisteredCustomOutputFormats registeredOutputFormats} setting) and + * the {@link #getAutoEscapingPolicy() autoEscapingPolicy} setting to + * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}. + * </ul> + * + * <p>These file extensions are not case sensitive. The file extension is the part after the last dot in the source + * name. If the source name contains no dot, then it has no file extension. + * + * <p>The settings activated by these file extensions override the setting values dictated by the + * {@link Configuration#getTemplateConfigurations templateConfigurations} setting of the {@link Configuration}. */ boolean getRecognizeStandardFileExtensions(); @@ -123,15 +249,18 @@ public interface ParsingConfiguration { boolean isRecognizeStandardFileExtensionsSet(); /** - * See {@link Configuration#getIncompatibleImprovements()}; as this is normally directly delegates to - * {@link Configuration#getIncompatibleImprovements()}, it's always set. + * See {@link TopLevelConfiguration#getIncompatibleImprovements()}; this is normally directly delegates to + * {@link Configuration#getIncompatibleImprovements()}, and it's always set. */ Version getIncompatibleImprovements(); /** - * See {@link Configuration#getTabSize()}. - * - * @since 2.3.25 + * The assumed display width of the tab character (ASCII 9), which influences the column number shown in error + * messages (or the column number you get through other API-s). So for example if the users edit templates in an + * editor where the tab width is set to 4, you should set this to 4 so that the column numbers printed by FreeMarker + * will match the column number shown in the editor. This setting doesn't affect the output of templates, as a tab + * in the template will remain a tab in the output too. + * It's value is at least 1, at most 256. */ int getTabSize(); @@ -143,12 +272,28 @@ public interface ParsingConfiguration { boolean isTabSizeSet(); /** - * Gets the default encoding for converting bytes to characters when - * reading template files in a locale for which no explicit encoding - * was specified. Defaults to the default system encoding. + * Sets the charset used for decoding template files. + * <p> + * Defaults to the default system {@code fileEncoding}, which can change from one server to + * another, so <b>you should always set this setting</b>. If you don't know what charset your should chose, + * {@code "UTF-8"} is usually a good choice. + * <p> + * When a project contains groups (like folders) of template files where the groups use different encodings, + * consider using the {@link Configuration#getTemplateConfigurations() templateConfigurations} setting on the + * {@link Configuration} level. + * <p> + * Individual templates may specify their own charset by starting with + * <tt><#ftl sourceEncoding="..."></tt>. However, before that's detected, at least part of template must be + * decoded with some charset first, so this setting (and + * {@link Configuration#getTemplateConfigurations() templateConfigurations}) still have role. */ Charset getSourceEncoding(); + /** + * Tells if this setting is set directly in this object. If not, then depending on the implementing class, reading + * the setting might returns a default value, or returns the value of the setting from a parent parsing + * configuration or throws a {@link SettingValueNotSetException}. + */ boolean isSourceEncodingSet(); } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/ProcessingConfiguration.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/ProcessingConfiguration.java b/src/main/java/org/apache/freemarker/core/ProcessingConfiguration.java index e90ceb3..545a313 100644 --- a/src/main/java/org/apache/freemarker/core/ProcessingConfiguration.java +++ b/src/main/java/org/apache/freemarker/core/ProcessingConfiguration.java @@ -40,9 +40,10 @@ import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory; /** * Implemented by FreeMarker core classes (not by you) that provide configuration settings that affect {@linkplain * Template#process(Object, Writer) template processing} (as opposed to template parsing). <b>New methods may be added - * anytime in future FreeMarker versions, so don't try to implement this interface yourself!</b> + * any time in future FreeMarker versions, so don't try to implement this interface yourself!</b> * * @see ParsingConfiguration + * @see ParsingAndProcessingConfiguration */ public interface ProcessingConfiguration { @@ -608,9 +609,9 @@ public interface ProcessingConfiguration { * it only affects the main template directly, as the imports will create a global variable there, the imports * will be visible from the further imported templates too. * <p> - * It's recommended to set the {@code lazy_auto_imports} setting ({@link Configuration#setLazyAutoImports(Boolean)}) - * to {@code true} when using this, so that auto-imports that are unused in a template won't degrade performance by - * unnecessary loading and initializing the imported library. + * It's recommended to set the {@link Configuration#getLazyAutoImports() lazyAutoImports} setting to {@code true} + * when using this, so that auto-imports that are unused in a template won't degrade performance by unnecessary + * loading and initializing the imported library. * <p> * If the imports aren't lazy, the order of the imports will be the same as the order in which the {@link Map} * iterates through its entries. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/Template.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/Template.java b/src/main/java/org/apache/freemarker/core/Template.java index 23082b2..c4787e4 100644 --- a/src/main/java/org/apache/freemarker/core/Template.java +++ b/src/main/java/org/apache/freemarker/core/Template.java @@ -53,11 +53,14 @@ import org.apache.freemarker.core.outputformat.OutputFormat; import org.apache.freemarker.core.templateresolver.TemplateLoader; import org.apache.freemarker.core.templateresolver.TemplateLookupStrategy; import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateResolver; +import org.apache.freemarker.core.templateresolver.impl.FileTemplateLoader; import org.apache.freemarker.core.util.BugException; import org.apache.freemarker.core.util._NullArgumentException; import org.apache.freemarker.core.valueformat.TemplateDateFormatFactory; import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory; +import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; + /** * <p> * Stores an already parsed template, ready to be processed (rendered) for unlimited times, possibly from multiple @@ -76,7 +79,7 @@ import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory; * changing FreeMarker settings. Those must not be used while the template is being processed, or if the template object * is already accessible from multiple threads. If some templates need different settings that those coming from the * shared {@link Configuration}, and you are using {@link Configuration#getTemplate(String)} (or its overloads), then - * use {@link Configuration#setTemplateConfigurations(org.apache.freemarker.core.templateresolver.TemplateConfigurationFactory)} to achieve that. + * use the {@link Configuration#getTemplateConfigurations() templateConfigurations} setting to achieve that. */ // TODO [FM3] Try to make Template serializable for distributed caching. Transient fields will have to be restored. public class Template implements ProcessingConfiguration, CustomStateScope { @@ -119,7 +122,7 @@ public class Template implements ProcessingConfiguration, CustomStateScope { private int actualNamingConvention; // Custom state: - private final Object lock = new Object(); + private final Object customStateMapLock = new Object(); private final ConcurrentHashMap<CustomStateKey, Object> customStateMap = new ConcurrentHashMap<>(0); /** @@ -175,7 +178,7 @@ public class Template implements ProcessingConfiguration, CustomStateScope { * straightforwardly in real files (they often aren't; see {@link TemplateLoader}), the name shouldn't be * an absolute file path. Like if the template is stored in {@code "/www/templates/forum/main.ftl"}, and * you are using {@code "/www/templates/"} as the template root directory via - * {@link Configuration#setDirectoryForTemplateLoading(java.io.File)}, then the template name will be + * {@link FileTemplateLoader#FileTemplateLoader(java.io.File)}, then the template name will be * {@code "forum/main.ftl"}. The name can be {@code null} (should be used for template made on-the-fly * instead of being loaded from somewhere), in which case relative paths in it will be relative to * the template root directory (and here again, it's the {@link TemplateLoader} that knows what that @@ -393,10 +396,10 @@ public class Template implements ProcessingConfiguration, CustomStateScope { * also use an object that already implements {@link TemplateHashModel}; in that case it won't be * wrapped. If it's {@code null}, an empty data model is used. * @param out - * The {@link Writer} where the output of the template will go. Note that unless you have used - * {@link Configuration#setAutoFlush(boolean)} to disable this, {@link Writer#flush()} will be called at - * the when the template processing was finished. {@link Writer#close()} is not called. Can't be - * {@code null}. + * The {@link Writer} where the output of the template will go. Note that unless you have set + * {@link ProcessingConfiguration#getAutoFlush() autoFlush} to {@code false} to disable this, + * {@link Writer#flush()} will be called at the when the template processing was finished. + * {@link Writer#close()} is not called. Can't be {@code null}. * * @throws TemplateException * if an exception occurs during template processing @@ -656,10 +659,10 @@ public class Template implements ProcessingConfiguration, CustomStateScope { /** * Returns the tag syntax the parser has chosen for this template. If the syntax could be determined, it's - * {@link Configuration#SQUARE_BRACKET_TAG_SYNTAX} or {@link Configuration#ANGLE_BRACKET_TAG_SYNTAX}. If the syntax + * {@link ParsingConfiguration#SQUARE_BRACKET_TAG_SYNTAX} or {@link ParsingConfiguration#ANGLE_BRACKET_TAG_SYNTAX}. If the syntax * couldn't be determined (like because there was no tags in the template, or it was a plain text template), this * returns whatever the default is in the current configuration, so it's maybe - * {@link Configuration#AUTO_DETECT_TAG_SYNTAX}. + * {@link ParsingConfiguration#AUTO_DETECT_TAG_SYNTAX}. * * @since 2.3.20 */ @@ -669,10 +672,10 @@ public class Template implements ProcessingConfiguration, CustomStateScope { /** * Returns the naming convention the parser has chosen for this template. If it could be determined, it's - * {@link Configuration#LEGACY_NAMING_CONVENTION} or {@link Configuration#CAMEL_CASE_NAMING_CONVENTION}. If it + * {@link ParsingConfiguration#LEGACY_NAMING_CONVENTION} or {@link ParsingConfiguration#CAMEL_CASE_NAMING_CONVENTION}. If it * couldn't be determined (like because there no identifier that's part of the template language was used where * the naming convention matters), this returns whatever the default is in the current configuration, so it's maybe - * {@link Configuration#AUTO_DETECT_TAG_SYNTAX}. + * {@link ParsingConfiguration#AUTO_DETECT_TAG_SYNTAX}. * * @since 2.3.23 */ @@ -681,7 +684,7 @@ public class Template implements ProcessingConfiguration, CustomStateScope { } /** - * Returns the output format (see {@link Configuration#setOutputFormat(OutputFormat)}) used for this template. + * Returns the output format (see {@link Configuration#getOutputFormat()}) used for this template. * The output format of a template can come from various places, in order of increasing priority: * {@link Configuration#getOutputFormat()}, {@link ParsingConfiguration#getOutputFormat()} (which is usually * provided by {@link Configuration#getTemplateConfigurations()}) and the {@code #ftl} header's @@ -701,8 +704,8 @@ public class Template implements ProcessingConfiguration, CustomStateScope { } /** - * Returns if the auto-escaping policy (see {@link Configuration#setAutoEscapingPolicy(int)}) that this template - * uses. This is decided from these, in increasing priority: + * Returns the {@link Configuration#getAutoEscapingPolicy()} autoEscapingPolicy) that this template uses. + * This is decided from these, in increasing priority: * {@link Configuration#getAutoEscapingPolicy()}, {@link ParsingConfiguration#getAutoEscapingPolicy()}, * {@code #ftl} header's {@code auto_esc} option in the template. */ @@ -1315,10 +1318,11 @@ public class Template implements ProcessingConfiguration, CustomStateScope { @Override @SuppressWarnings("unchecked") + @SuppressFBWarnings("AT_OPERATION_SEQUENCE_ON_CONCURRENT_ABSTRACTION") public <T> T getCustomState(CustomStateKey<T> customStateKey) { T customState = (T) customStateMap.get(customStateKey); if (customState == null) { - synchronized (lock) { + synchronized (customStateMapLock) { customState = (T) customStateMap.get(customStateKey); if (customState == null) { customState = customStateKey.create(); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/TemplateConfiguration.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/TemplateConfiguration.java b/src/main/java/org/apache/freemarker/core/TemplateConfiguration.java index 5f62202..a8fc5ae 100644 --- a/src/main/java/org/apache/freemarker/core/TemplateConfiguration.java +++ b/src/main/java/org/apache/freemarker/core/TemplateConfiguration.java @@ -676,140 +676,145 @@ public final class TemplateConfiguration implements ParsingAndProcessingConfigur } @Override - protected Locale getInheritedLocale() { + protected Locale getDefaultLocale() { throw new SettingValueNotSetException("locale"); } @Override - protected TimeZone getInheritedTimeZone() { + protected TimeZone getDefaultTimeZone() { throw new SettingValueNotSetException("timeZone"); } @Override - protected TimeZone getInheritedSQLDateAndTimeTimeZone() { + protected TimeZone getDefaultSQLDateAndTimeTimeZone() { throw new SettingValueNotSetException("SQLDateAndTimeTimeZone"); } @Override - protected String getInheritedNumberFormat() { + protected String getDefaultNumberFormat() { throw new SettingValueNotSetException("numberFormat"); } @Override - protected Map<String, TemplateNumberFormatFactory> getInheritedCustomNumberFormats() { + protected Map<String, TemplateNumberFormatFactory> getDefaultCustomNumberFormats() { throw new SettingValueNotSetException("customNumberFormats"); } @Override - protected TemplateNumberFormatFactory getInheritedCustomNumberFormat(String name) { + protected TemplateNumberFormatFactory getDefaultCustomNumberFormat(String name) { return null; } @Override - protected String getInheritedBooleanFormat() { + protected String getDefaultBooleanFormat() { throw new SettingValueNotSetException("booleanFormat"); } @Override - protected String getInheritedTimeFormat() { + protected String getDefaultTimeFormat() { throw new SettingValueNotSetException("timeFormat"); } @Override - protected String getInheritedDateFormat() { + protected String getDefaultDateFormat() { throw new SettingValueNotSetException("dateFormat"); } @Override - protected String getInheritedDateTimeFormat() { + protected String getDefaultDateTimeFormat() { throw new SettingValueNotSetException("dateTimeFormat"); } @Override - protected Map<String, TemplateDateFormatFactory> getInheritedCustomDateFormats() { + protected Map<String, TemplateDateFormatFactory> getDefaultCustomDateFormats() { throw new SettingValueNotSetException("customDateFormats"); } @Override - protected TemplateDateFormatFactory getInheritedCustomDateFormat(String name) { + protected TemplateDateFormatFactory getDefaultCustomDateFormat(String name) { throw new SettingValueNotSetException("customDateFormat"); } @Override - protected TemplateExceptionHandler getInheritedTemplateExceptionHandler() { + protected TemplateExceptionHandler getDefaultTemplateExceptionHandler() { throw new SettingValueNotSetException("templateExceptionHandler"); } @Override - protected ArithmeticEngine getInheritedArithmeticEngine() { + protected ArithmeticEngine getDefaultArithmeticEngine() { throw new SettingValueNotSetException("arithmeticEngine"); } @Override - protected ObjectWrapper getInheritedObjectWrapper() { + protected ObjectWrapper getDefaultObjectWrapper() { throw new SettingValueNotSetException("objectWrapper"); } @Override - protected Charset getInheritedOutputEncoding() { + protected Charset getDefaultOutputEncoding() { throw new SettingValueNotSetException("outputEncoding"); } @Override - protected Charset getInheritedURLEscapingCharset() { + protected Charset getDefaultURLEscapingCharset() { throw new SettingValueNotSetException("URLEscapingCharset"); } @Override - protected TemplateClassResolver getInheritedNewBuiltinClassResolver() { + protected TemplateClassResolver getDefaultNewBuiltinClassResolver() { throw new SettingValueNotSetException("newBuiltinClassResolver"); } @Override - protected boolean getInheritedAutoFlush() { + protected boolean getDefaultAutoFlush() { throw new SettingValueNotSetException("autoFlush"); } @Override - protected boolean getInheritedShowErrorTips() { + protected boolean getDefaultShowErrorTips() { throw new SettingValueNotSetException("showErrorTips"); } @Override - protected boolean getInheritedAPIBuiltinEnabled() { + protected boolean getDefaultAPIBuiltinEnabled() { throw new SettingValueNotSetException("APIBuiltinEnabled"); } @Override - protected boolean getInheritedLogTemplateExceptions() { + protected boolean getDefaultLogTemplateExceptions() { throw new SettingValueNotSetException("logTemplateExceptions"); } @Override - protected boolean getInheritedLazyImports() { + protected boolean getDefaultLazyImports() { throw new SettingValueNotSetException("lazyImports"); } @Override - protected Boolean getInheritedLazyAutoImports() { + protected Boolean getDefaultLazyAutoImports() { throw new SettingValueNotSetException("lazyAutoImports"); } @Override - protected Map<String, String> getInheritedAutoImports() { + protected Map<String, String> getDefaultAutoImports() { throw new SettingValueNotSetException("autoImports"); } @Override - protected List<String> getInheritedAutoIncludes() { + protected List<String> getDefaultAutoIncludes() { throw new SettingValueNotSetException("autoIncludes"); } @Override - protected Object getInheritedCustomAttribute(Object name) { + protected Object getDefaultCustomAttribute(Object name) { return null; } + @Override + protected Map<Object, Object> getDefaultCustomAttributes() { + throw new SettingValueNotSetException("customAttributes"); + } + /** * Set all settings in this {@link Builder} that were set in the parameter * {@link TemplateConfiguration}, possibly overwriting the earlier value in this object. (A setting is said to be @@ -937,47 +942,47 @@ public final class TemplateConfiguration implements ParsingAndProcessingConfigur } @Override - protected int getInheritedTagSyntax() { + protected int getDefaultTagSyntax() { throw new SettingValueNotSetException("tagSyntax"); } @Override - protected TemplateLanguage getInheritedTemplateLanguage() { + protected TemplateLanguage getDefaultTemplateLanguage() { throw new SettingValueNotSetException("templateLanguage"); } @Override - protected int getInheritedNamingConvention() { + protected int getDefaultNamingConvention() { throw new SettingValueNotSetException("namingConvention"); } @Override - protected boolean getInheritedWhitespaceStripping() { + protected boolean getDefaultWhitespaceStripping() { throw new SettingValueNotSetException("whitespaceStripping"); } @Override - protected int getInheritedAutoEscapingPolicy() { + protected int getDefaultAutoEscapingPolicy() { throw new SettingValueNotSetException("autoEscapingPolicy"); } @Override - protected OutputFormat getInheritedOutputFormat() { + protected OutputFormat getDefaultOutputFormat() { throw new SettingValueNotSetException("outputFormat"); } @Override - protected boolean getInheritedRecognizeStandardFileExtensions() { + protected boolean getDefaultRecognizeStandardFileExtensions() { throw new SettingValueNotSetException("recognizeStandardFileExtensions"); } @Override - protected Charset getInheritedSourceEncoding() { + protected Charset getDefaultSourceEncoding() { throw new SettingValueNotSetException("sourceEncoding"); } @Override - protected int getInheritedTabSize() { + protected int getDefaultTabSize() { throw new SettingValueNotSetException("tabSize"); } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java b/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java new file mode 100644 index 0000000..8b253a2 --- /dev/null +++ b/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java @@ -0,0 +1,194 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.apache.freemarker.core; + +import java.util.Map; + +import org.apache.freemarker.core.templateresolver.CacheStorage; +import org.apache.freemarker.core.templateresolver.TemplateConfigurationFactory; +import org.apache.freemarker.core.templateresolver.TemplateLoader; +import org.apache.freemarker.core.templateresolver.TemplateLookupStrategy; +import org.apache.freemarker.core.templateresolver.TemplateNameFormat; +import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateLookupStrategy; +import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateNameFormat; +import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateNameFormatFM2; +import org.apache.freemarker.core.templateresolver.impl.FileTemplateLoader; +import org.apache.freemarker.core.templateresolver.impl.MultiTemplateLoader; +import org.apache.freemarker.core.templateresolver.impl.SoftCacheStorage; + +/** + * Implemented by FreeMarker core classes (not by you) that provide {@link Configuration}-level settings. <b>New + * methods may be added any time in future FreeMarker versions, so don't try to implement this interface yourself!</b> + * + * @see ParsingAndProcessingConfiguration + */ +public interface TopLevelConfiguration extends ParsingAndProcessingConfiguration { + + /** + * The {@link TemplateLoader} that is used to look up and load templates. + * By providing your own {@link TemplateLoader} implementation, you can load templates from whatever kind of + * storages, like from relational databases, NoSQL-storages, etc. + * + * <p>You can chain several {@link TemplateLoader}-s together with {@link MultiTemplateLoader}. + * + * <p>Default value: You should always set the template loader instead of relying on the default value. + * (But if you still care what it is, before "incompatible improvements" 2.3.21 it's a {@link FileTemplateLoader} + * that uses the current directory as its root; as it's hard tell what that directory will be, it's not very useful + * and dangerous. Starting with "incompatible improvements" 2.3.21 the default is {@code null}.) + */ + TemplateLoader getTemplateLoader(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isTemplateLoaderSet(); + + /** + * The {@link TemplateLookupStrategy} that is used to look up templates based on the requested name, locale and + * custom lookup condition. Its default is {@link DefaultTemplateLookupStrategy#INSTANCE}. + */ + TemplateLookupStrategy getTemplateLookupStrategy(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isTemplateLookupStrategySet(); + + /** + * The template name format used; see {@link TemplateNameFormat}. The default is + * {@link DefaultTemplateNameFormatFM2#INSTANCE}, while the recommended value for new projects is + * {@link DefaultTemplateNameFormat#INSTANCE}. + */ + TemplateNameFormat getTemplateNameFormat(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isTemplateNameFormatSet(); + + /** + * The {@link TemplateConfigurationFactory} that will configure individual templates where their settings differ + * from those coming from the common {@link Configuration} object. A typical use case for that is specifying the + * {@link #getOutputFormat() outputFormat} or {@link #getSourceEncoding() sourceEncoding} for templates based on + * their file extension or parent directory. + * <p> + * Note that the settings suggested by standard file extensions are stronger than that you set here. See + * {@link #getRecognizeStandardFileExtensions()} for more information about standard file extensions. + * <p> + * See "Template configurations" in the FreeMarker Manual for examples. + */ + TemplateConfigurationFactory getTemplateConfigurations(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isTemplateConfigurationsSet(); + + /** + * The map-like object used for caching templates to avoid repeated loading and parsing of the template "files". + * Its {@link Configuration}-level default is a {@link SoftCacheStorage}. + */ + CacheStorage getCacheStorage(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isCacheStorageSet(); + + /** + * The time in milliseconds that must elapse before checking whether there is a newer version of a template + * "file" than the cached one. Defaults to 5000 ms. + */ + long getTemplateUpdateDelayMilliseconds(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isTemplateUpdateDelayMillisecondsSet(); + + /** + * Returns the value of the "incompatible improvements" setting; this is the FreeMarker version number where the + * not 100% backward compatible bug fixes and improvements that you want to enable were already implemented. In + * new projects you should set this to the FreeMarker version that you are actually using. In older projects it's + * also usually better to keep this high, however you better check the changes activated (find them below), at + * least if not only the 3rd version number (the micro version) of {@code incompatibleImprovements} is increased. + * Generally, as far as you only increase the last version number of this setting, the changes are always low + * risk. + * <p> + * Bugfixes and improvements that are fully backward compatible, also those that are important security fixes, + * are enabled regardless of the incompatible improvements setting. + * <p> + * An important consequence of setting this setting is that now your application will check if the stated minimum + * FreeMarker version requirement is met. Like if you set this setting to 3.0.1, but accidentally the + * application is deployed with FreeMarker 3.0.0, then FreeMarker will fail, telling that a higher version is + * required. After all, the fixes/improvements you have requested aren't available on a lower version. + * <p> + * Note that as FreeMarker's minor (2nd) or major (1st) version number increments, it's possible that emulating + * some of the old bugs will become unsupported, that is, even if you set this setting to a low value, it + * silently wont bring back the old behavior anymore. Information about that will be present here. + * + * <p>Currently the effects of this setting are: + * <ul> + * <li><p> + * 3.0.0: This is the lowest supported value in FreeMarker 3. + * </li> + * </ul> + * + * @return Never {@code null}. + */ + @Override + Version getIncompatibleImprovements(); + + /** + * Whether localized template lookup is enabled. Enabled by default. + * + * <p> + * With the default {@link TemplateLookupStrategy}, localized lookup works like this: Let's say your locale setting + * is {@code Locale("en", "AU")}, and you call {@link Configuration#getTemplate(String) cfg.getTemplate("foo.ftl")}. + * Then FreeMarker will look for the template under these names, stopping at the first that exists: + * {@code "foo_en_AU.ftl"}, {@code "foo_en.ftl"}, {@code "foo.ftl"}. See the description of the default value at + * {@link #getTemplateLookupStrategy()} for a more details. If you need to generate different + * template names, set your own a {@link TemplateLookupStrategy} implementation as the value of the + * {@link #getTemplateLookupStrategy() templateLookupStrategy} setting. + */ + boolean getLocalizedLookup(); + + /** + * Tells if this setting was explicitly set (otherwise its value will be the default value). + */ + boolean isLocalizedLookupSet(); + + /** + * Shared variables are variables that are visible as top-level variables for all templates, except where the data + * model contains a variable with the same name (which then shadows the shared variable). + * + * @return Not {@code null}; the {@link Map} is possibly mutable in builders, but immutable in + * {@link Configuration}. + * + * @see Configuration.Builder#setSharedVariables(Map) + */ + Map<String, Object> getSharedVariables(); + + /** + * Tells if this setting was explicitly set (if not, the default value of the setting will be used). + */ + boolean isSharedVariablesSet(); + +} http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/UnknownConfigurationSettingException.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/UnknownConfigurationSettingException.java b/src/main/java/org/apache/freemarker/core/UnknownConfigurationSettingException.java index a3a266f..a4e562c 100644 --- a/src/main/java/org/apache/freemarker/core/UnknownConfigurationSettingException.java +++ b/src/main/java/org/apache/freemarker/core/UnknownConfigurationSettingException.java @@ -18,10 +18,11 @@ */ package org.apache.freemarker.core; +import org.apache.freemarker.core.Configuration.ExtendableBuilder; import org.apache.freemarker.core.util._StringUtil; /** - * Thrown by {@link Configuration#setSetting(String, String)}; The setting name was not recognized. + * Thrown by {@link ExtendableBuilder#setSetting(String, String)} if the setting name was not recognized. */ @SuppressWarnings("serial") public class UnknownConfigurationSettingException extends ConfigurationException { http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/_ErrorDescriptionBuilder.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/_ErrorDescriptionBuilder.java b/src/main/java/org/apache/freemarker/core/_ErrorDescriptionBuilder.java index 29ded29..2d09062 100644 --- a/src/main/java/org/apache/freemarker/core/_ErrorDescriptionBuilder.java +++ b/src/main/java/org/apache/freemarker/core/_ErrorDescriptionBuilder.java @@ -225,7 +225,7 @@ public class _ErrorDescriptionBuilder { || (partStr.charAt(1) == '/') && (partStr.charAt(2) == '#' || partStr.charAt(2) == '@') ) && partStr.charAt(partStr.length() - 1) == '>') { - if (template.getActualTagSyntax() == Configuration.SQUARE_BRACKET_TAG_SYNTAX) { + if (template.getActualTagSyntax() == ParsingConfiguration.SQUARE_BRACKET_TAG_SYNTAX) { sb.append('['); sb.append(partStr.substring(1, partStr.length() - 1)); sb.append(']'); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/arithmetic/ArithmeticEngine.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/arithmetic/ArithmeticEngine.java b/src/main/java/org/apache/freemarker/core/arithmetic/ArithmeticEngine.java index 29dc9ad..afe22be 100644 --- a/src/main/java/org/apache/freemarker/core/arithmetic/ArithmeticEngine.java +++ b/src/main/java/org/apache/freemarker/core/arithmetic/ArithmeticEngine.java @@ -26,7 +26,7 @@ import org.apache.freemarker.core.TemplateException; /** * Implements the arithmetic operations executed by the template language; see - * {@link Configuration#setArithmeticEngine(ArithmeticEngine)}. + * {@link Configuration#getArithmeticEngine()}. */ public abstract class ArithmeticEngine { http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/debug/RmiDebuggedEnvironmentImpl.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/debug/RmiDebuggedEnvironmentImpl.java b/src/main/java/org/apache/freemarker/core/debug/RmiDebuggedEnvironmentImpl.java index ce49afb..38b1d0a 100644 --- a/src/main/java/org/apache/freemarker/core/debug/RmiDebuggedEnvironmentImpl.java +++ b/src/main/java/org/apache/freemarker/core/debug/RmiDebuggedEnvironmentImpl.java @@ -197,12 +197,12 @@ class RmiDebuggedEnvironmentImpl extends RmiDebugModelImpl implements DebuggedEn { @Override Collection keySet() { - return ((Configuration) ProcessingConfiguration).getSharedVariableNames(); + return ((Configuration) ProcessingConfiguration).getSharedVariables().keySet(); } @Override public TemplateModel get(String key) { - return ((Configuration) ProcessingConfiguration).getSharedVariable(key); + return ((Configuration) ProcessingConfiguration).getWrappedSharedVariable(key); } }; http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/model/ObjectWrapper.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/model/ObjectWrapper.java b/src/main/java/org/apache/freemarker/core/model/ObjectWrapper.java index 46d6f72..42f09d8 100644 --- a/src/main/java/org/apache/freemarker/core/model/ObjectWrapper.java +++ b/src/main/java/org/apache/freemarker/core/model/ObjectWrapper.java @@ -34,7 +34,7 @@ import org.apache.freemarker.core.model.impl.DefaultObjectWrapper; * {@link TemplateHashModel} implementation that will call {@link Map#get(Object)} or the getter method, transparently * to the template language. * - * @see Configuration#setObjectWrapper(ObjectWrapper) + * @see Configuration#getObjectWrapper() */ public interface ObjectWrapper { @@ -49,10 +49,10 @@ public interface ObjectWrapper { * * @return a {@link TemplateModel} wrapper of the object passed in. To support un-wrapping, you may consider the * return value to implement {@link WrapperTemplateModel} and {@link AdapterTemplateModel}. - * The default expectation is that the {@link TemplateModel} isn't less thread safe than the wrapped object. - * If the {@link ObjectWrapper} returns less thread safe objects, that should be clearly documented, as it - * restricts how it can be used, like, then it can't be used to wrap "shared variables" - * ({@link Configuration#setSharedVariables(Map)}). + * It's normally expectated that the {@link TemplateModel} isn't less thread safe than the wrapped object. + * If the {@link ObjectWrapper} returns less thread safe objects that should be clearly documented, as it + * restricts how it can be used, like, then it can't be used to wrap + * {@linkplain Configuration#getSharedVariables() shared variables}). */ TemplateModel wrap(Object obj) throws TemplateModelException; http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/model/TemplateModel.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/model/TemplateModel.java b/src/main/java/org/apache/freemarker/core/model/TemplateModel.java index fb5f9fb..bbe3c03 100644 --- a/src/main/java/org/apache/freemarker/core/model/TemplateModel.java +++ b/src/main/java/org/apache/freemarker/core/model/TemplateModel.java @@ -30,7 +30,7 @@ import org.apache.freemarker.core.util.FTLUtil; * {@link TemplateModel}-s. * * <p>Mapping the plain Java objects to {@link TemplateModel}-s (or the other way around sometimes) is the - * responsibility of the {@link ObjectWrapper} (can be set via {@link Configuration#setObjectWrapper(ObjectWrapper)}). + * responsibility of the {@link ObjectWrapper} (see the {@link Configuration#getObjectWrapper objectWrapper} setting). * But not all {@link TemplateModel}-s are for wrapping a plain object. For example, a value created within a template * is not made to wrap an earlier existing object; it's a value that has always existed in the template language's * domain. Users can also write {@link TemplateModel} implementations and put them directly into the data-model for http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/model/impl/DefaultObjectWrapper.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/model/impl/DefaultObjectWrapper.java b/src/main/java/org/apache/freemarker/core/model/impl/DefaultObjectWrapper.java index a20695a..7e04776 100644 --- a/src/main/java/org/apache/freemarker/core/model/impl/DefaultObjectWrapper.java +++ b/src/main/java/org/apache/freemarker/core/model/impl/DefaultObjectWrapper.java @@ -43,7 +43,6 @@ import java.util.WeakHashMap; import org.apache.freemarker.core.Configuration; import org.apache.freemarker.core.Version; import org.apache.freemarker.core._CoreAPI; -import org.apache.freemarker.core._CoreLogs; import org.apache.freemarker.core._DelayedFTLTypeDescription; import org.apache.freemarker.core._DelayedShortClassName; import org.apache.freemarker.core._TemplateModelException; @@ -67,28 +66,25 @@ import org.apache.freemarker.core.util.BugException; import org.apache.freemarker.core.util.CommonBuilder; import org.apache.freemarker.core.util._ClassUtil; import org.apache.freemarker.dom.NodeModel; -import org.slf4j.Logger; import org.w3c.dom.Node; /** * The default implementation of the {@link ObjectWrapper} interface. Usually, you don't need to invoke instances of * this, as an instance of this is already the default value of the - * {@link Configuration#setObjectWrapper(ObjectWrapper) object_wrapper setting}. Then the + * {@link Configuration#getObjectWrapper() objectWrapper} setting. Then the * {@link ExtendableBuilder#ExtendableBuilder(Version, boolean) incompatibleImprovements} of the * {@link DefaultObjectWrapper} will be the same that you have set for the {@link Configuration} itself. * * <p> * If you still need to invoke an instance, that should be done with {@link Builder#build()} (or - * with {@link Configuration#setSetting(String, String)} with {@code "objectWrapper"} key); the constructor isn't - * public. + * with {@link org.apache.freemarker.core.Configuration.ExtendableBuilder#setSetting(String, String)} with + * {@code "objectWrapper"} key); the constructor isn't public. * * <p> * This class is thread-safe. */ public class DefaultObjectWrapper implements RichObjectWrapper { - private static final Logger LOG = _CoreLogs.OBJECT_WRAPPER; - /** * At this level of exposure, all methods and properties of the * wrapped objects are exposed to the template. @@ -1179,9 +1175,9 @@ public class DefaultObjectWrapper implements RichObjectWrapper { } /** - * Gets/creates a {@link DefaultObjectWrapper} singleton instance that's already configured as specified in the properties of - * this object; this is recommended over using the {@link DefaultObjectWrapper} constructors. The returned instance can't be - * further configured (it's write protected). + * Gets/creates a {@link DefaultObjectWrapper} singleton instance that's already configured as specified in the + * properties of this object; this is recommended over using the {@link DefaultObjectWrapper} constructors. The + * returned instance can't be further configured (it's write protected). * * <p>The builder meant to be used as a drop-away object (not stored in a field), like in this example: * <pre> @@ -1318,11 +1314,10 @@ public class DefaultObjectWrapper implements RichObjectWrapper { } /** - * Holds {@link DefaultObjectWrapper} configuration settings and defines their defaults. - * You will not use this abstract class directly, but concrete subclasses like {@link Builder}. - * Unless, you are developing a builder for a custom {@link DefaultObjectWrapper} subclass. In that case, note that - * overriding the {@link #equals} and {@link #hashCode} is important, as these objects are used as {@link ObjectWrapper} - * singleton lookup keys. + * You will not use this abstract class directly, but concrete subclasses like {@link Builder}, unless you are + * developing a builder for a custom {@link DefaultObjectWrapper} subclass. In that case, note that overriding the + * {@link #equals} and {@link #hashCode} is important, as these objects are used as {@link ObjectWrapper} singleton + * lookup keys. */ protected abstract static class ExtendableBuilder< ProductT extends DefaultObjectWrapper, SelfT extends ExtendableBuilder<ProductT, SelfT>> @@ -1362,8 +1357,8 @@ public class DefaultObjectWrapper implements RichObjectWrapper { * check the list of effects below. Increasing the 2nd or 1st version number possibly mean substantial * changes with higher risk of breaking the application, but again, see the list of effects below. * <p> - * The reason it's separate from {@link Configuration#setIncompatibleImprovements(Version)} is that - * {@link ObjectWrapper} objects are often shared among multiple {@link Configuration}-s, so the two + * The reason it's separate from {@link Configuration#getIncompatibleImprovements()} is that + * {@link ObjectWrapper} objects are sometimes shared among multiple {@link Configuration}-s, so the two * version numbers are technically independent. But it's recommended to keep those two version numbers * the same. * <p> @@ -1605,6 +1600,7 @@ public class DefaultObjectWrapper implements RichObjectWrapper { * @deprecated Does nothing in FreeMarker 3 - we kept it for now to postopne reworking some JUnit tests. */ // [FM3] Remove + @Deprecated public void setUseModelCache(boolean useModelCache) { this.useModelCache = useModelCache; useModelCacheSet = true; @@ -1614,6 +1610,7 @@ public class DefaultObjectWrapper implements RichObjectWrapper { * Fluent API equivalent of {@link #setUseModelCache(boolean)}. * @deprecated Does nothing in FreeMarker 3 - we kept it for now to postopne reworking some JUnit tests. */ + @Deprecated public SelfT useModelCache(boolean useModelCache) { setUseModelCache(useModelCache); return self(); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/outputformat/MarkupOutputFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/outputformat/MarkupOutputFormat.java b/src/main/java/org/apache/freemarker/core/outputformat/MarkupOutputFormat.java index b584ea7..aac7d54 100644 --- a/src/main/java/org/apache/freemarker/core/outputformat/MarkupOutputFormat.java +++ b/src/main/java/org/apache/freemarker/core/outputformat/MarkupOutputFormat.java @@ -30,8 +30,8 @@ import org.apache.freemarker.core.outputformat.impl.TemplateHTMLOutputModel; /** * Superclass of {@link OutputFormat}-s that represent a "markup" format, which is any format where certain character * sequences have special meaning and thus may need escaping. (Escaping is important for FreeMarker, as typically it has - * to insert non-markup text from the data-model into the output markup. See also: - * {@link Configuration#setOutputFormat(OutputFormat)}.) + * to insert non-markup text from the data-model into the output markup. See also the + * {@link Configuration#getOutputFormat() outputFormat} configuration setting.) * * <p> * A {@link MarkupOutputFormat} subclass always has a corresponding {@link TemplateMarkupOutputModel} subclass pair @@ -128,7 +128,7 @@ public abstract class MarkupOutputFormat<MO extends TemplateMarkupOutputModel> e * Tells if by default auto-escaping should be on for this format. It should be {@code true} if you need to escape * on most of the places where you insert values. * - * @see Configuration#setAutoEscapingPolicy(int) + * @see Configuration#getAutoEscapingPolicy() */ public abstract boolean isAutoEscapedByDefault(); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/outputformat/OutputFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/outputformat/OutputFormat.java b/src/main/java/org/apache/freemarker/core/outputformat/OutputFormat.java index ced33f5..8004ae2 100644 --- a/src/main/java/org/apache/freemarker/core/outputformat/OutputFormat.java +++ b/src/main/java/org/apache/freemarker/core/outputformat/OutputFormat.java @@ -27,8 +27,8 @@ import org.apache.freemarker.core.util._StringUtil; /** * Represents an output format. If you need auto-escaping, see its subclass, {@link MarkupOutputFormat}. * - * @see Configuration#setOutputFormat(OutputFormat) - * @see Configuration#setRegisteredCustomOutputFormats(java.util.Collection) + * @see Configuration#getOutputFormat() + * @see Configuration#getRegisteredCustomOutputFormats() * @see MarkupOutputFormat * * @since 2.3.24 http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/outputformat/impl/UndefinedOutputFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/outputformat/impl/UndefinedOutputFormat.java b/src/main/java/org/apache/freemarker/core/outputformat/impl/UndefinedOutputFormat.java index 4dceb80..b5412e2 100644 --- a/src/main/java/org/apache/freemarker/core/outputformat/impl/UndefinedOutputFormat.java +++ b/src/main/java/org/apache/freemarker/core/outputformat/impl/UndefinedOutputFormat.java @@ -24,9 +24,8 @@ import org.apache.freemarker.core.outputformat.OutputFormat; /** * Represents the output format used when the template output format is undecided. This is the default output format if - * FreeMarker can't select anything more specific (see - * {@link Configuration#setTemplateConfigurations(org.apache.freemarker.core.templateresolver.TemplateConfigurationFactory)}). This format doesn't - * support auto-escaping ({@link Configuration#setAutoEscapingPolicy(int)}). It will print + * FreeMarker can't select anything more specific (see {@link Configuration#getTemplateConfigurations()}). This format + * doesn't support auto-escaping ({@link Configuration#getAutoEscapingPolicy()}). It will print * {@link TemplateMarkupOutputModel}-s as is (doesn't try to convert them). * * @see PlainTextOutputFormat http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/CacheStorage.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/CacheStorage.java b/src/main/java/org/apache/freemarker/core/templateresolver/CacheStorage.java index d497e55..c70fa94 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/CacheStorage.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/CacheStorage.java @@ -19,13 +19,15 @@ package org.apache.freemarker.core.templateresolver; +import org.apache.freemarker.core.Configuration; + /** * Cache storage abstracts away the storage aspects of a cache - associating * an object with a key, retrieval and removal via the key. It is actually a * small subset of the {@link java.util.Map} interface. * The implementations must be thread safe. * - * @see org.apache.freemarker.core.Configuration#setCacheStorage(CacheStorage) + * @see Configuration#getCacheStorage() */ public interface CacheStorage { Object get(Object key); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoader.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoader.java b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoader.java index 60992d6..fc6a4aa 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoader.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoader.java @@ -32,7 +32,8 @@ import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateResolver; * implementations. * * <p> - * To set the {@link TemplateLoader} used by FreeMaker, use {@link Configuration#setTemplateLoader(TemplateLoader)}. + * The {@link TemplateLoader} used by FreeMaker is specified by the {@link Configuration#getTemplateLoader() + * templateLoader} configuration setting. * * <p> * Implementations of this interface should be thread-safe. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoadingResult.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoadingResult.java b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoadingResult.java index 2253384..c685d93 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoadingResult.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLoadingResult.java @@ -27,6 +27,7 @@ import java.nio.charset.Charset; import java.util.Date; import org.apache.freemarker.core.Configuration; +import org.apache.freemarker.core.Configuration.ExtendableBuilder; import org.apache.freemarker.core.TemplateConfiguration; import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateResolver; import org.apache.freemarker.core.util._NullArgumentException; @@ -96,7 +97,7 @@ public final class TemplateLoadingResult { * Usually {@code null}, as usually the backing storage mechanism doesn't store such information; see * {@link #getTemplateConfiguration()}. The most probable application is supplying the charset (encoding) * used by the {@link InputStream} (via - * {@link TemplateConfiguration.Builder#setSourceEncoding(Charset)}), but only do that if the storage + * {@link ExtendableBuilder#setSourceEncoding(Charset)}), but only do that if the storage * mechanism really knows what the charset is. */ public TemplateLoadingResult(TemplateLoadingSource source, Serializable version, InputStream inputStream, http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLookupStrategy.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLookupStrategy.java b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLookupStrategy.java index 25efdf0..7021b5b 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLookupStrategy.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateLookupStrategy.java @@ -50,7 +50,7 @@ import org.apache.freemarker.core.Template; * applications, yet it can be confusing.) * </ul> * - * @see Configuration#setTemplateLookupStrategy(TemplateLookupStrategy) + * @see Configuration#getTemplateLookupStrategy() * * @since 2.3.22 */ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/TemplateNameFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateNameFormat.java b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateNameFormat.java index 3795148..57773f4 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateNameFormat.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateNameFormat.java @@ -20,11 +20,9 @@ package org.apache.freemarker.core.templateresolver; /** - * 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 + * Symbolizes a template name format, which defines the basic syntax of names through algorithms such as normalization. */ +// TODO [FM3] Before it becomes a BC problem, shouldn't we add methods like splitting to directory name and file name? public abstract class TemplateNameFormat { protected TemplateNameFormat() { http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/TemplateResolver.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateResolver.java b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateResolver.java index f257e2b..bf7280a 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/TemplateResolver.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/TemplateResolver.java @@ -35,10 +35,10 @@ import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateResolver; * delegate some of those duties back to the {@link Configuration} setting: * * <ul> - * <li>{@link Configuration#setTemplateLoader(TemplateLoader) template_loader} - * <li>{@link Configuration#setTemplateNameFormat(TemplateNameFormat) template_name_format} - * <li>{@link Configuration#setTemplateLookupStrategy(TemplateLookupStrategy) template_lookup_strategy} - * <li>{@link Configuration#setCacheStorage(CacheStorage) cache_storage} + * <li>{@link Configuration#getTemplateLoader() templateLoader} + * <li>{@link Configuration#getTemplateNameFormat() templateNameFormat} + * <li>{@link Configuration#getTemplateLookupStrategy() templateLookupStrategy} + * <li>{@link Configuration#getCacheStorage() cacheStorage} * </ul> * * @since 3.0.0 @@ -104,8 +104,8 @@ public abstract class TemplateResolver { /** * Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested; - * this is an optional operation. This is to give the application finer control over cache updating than - * {@link Configuration#setTemplateUpdateDelayMilliseconds(long)} alone does. + * this is an optional operation. This is to give the application finer control over cache updating than the + * {@link Configuration#getTemplateUpdateDelayMilliseconds() templateUpdateDelayMilliseconds} setting alone gives. * * <p> * For the meaning of the parameters, see {@link #getTemplate(String, Locale, Serializable)} http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormat.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormat.java index f85a1f8..69fa390 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormat.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormat.java @@ -20,16 +20,15 @@ package org.apache.freemarker.core.templateresolver.impl; import org.apache.freemarker.core.Configuration; import org.apache.freemarker.core.TemplateNotFoundException; -import org.apache.freemarker.core.Version; import org.apache.freemarker.core.templateresolver.MalformedTemplateNameException; import org.apache.freemarker.core.templateresolver.TemplateLoader; import org.apache.freemarker.core.templateresolver.TemplateNameFormat; import org.apache.freemarker.core.util._StringUtil; /** - * The default template name format only when {@link Configuration#Configuration(Version) 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 {@code incompatible_improvements} is still 2.3.0 there. + * The default template name format only when {@link Configuration#getIncompatibleImprovements() + * 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 {@code incompatible_improvements} is still 2.3.0 there. * * <p> * Differences to the {@link DefaultTemplateNameFormatFM2} format: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormatFM2.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormatFM2.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormatFM2.java index 29b953b..c5db8e5 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormatFM2.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateNameFormatFM2.java @@ -19,13 +19,12 @@ package org.apache.freemarker.core.templateresolver.impl; import org.apache.freemarker.core.Configuration; -import org.apache.freemarker.core.Version; import org.apache.freemarker.core.templateresolver.MalformedTemplateNameException; import org.apache.freemarker.core.templateresolver.TemplateNameFormat; /** - * The default template name format when {@link Configuration#Configuration(Version) incompatible_improvements} is - * below 2.4.0. As of FreeMarker 2.4.0, the default {@code incompatible_improvements} is still {@code 2.3.0}, and it + * The default template name format when {@link Configuration#getIncompatibleImprovements() incompatible_improvements} + * is below 2.4.0. As of FreeMarker 2.4.0, the default {@code incompatible_improvements} is still {@code 2.3.0}, and it * will certainly remain so for a very long time. In new projects it's highly recommended to use * {@link DefaultTemplateNameFormat#INSTANCE} instead. * http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateResolver.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateResolver.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateResolver.java index 48650e8..ea1cc63 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateResolver.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/DefaultTemplateResolver.java @@ -63,16 +63,16 @@ import org.slf4j.Logger; * The actual template "file" loading is delegated to a {@link TemplateLoader} that you can specify in the constructor. * Some aspects of caching is delegated to a {@link CacheStorage} that you can also specify in the constructor. * - * <p>Typically you don't instantiate or otherwise use this class directly. The {@link Configuration} embeds an - * instance of this class, that you access indirectly through {@link Configuration#getTemplate(String)} and other - * {@link Configuration} API-s. Then {@link TemplateLoader} and {@link CacheStorage} can be set with - * {@link Configuration#setTemplateLoader(TemplateLoader)} and - * {@link Configuration#setCacheStorage(CacheStorage)}. + * <p>Typically you don't instantiate or otherwise use this class directly. By default the {@link Configuration} embeds + * an instance of this class, that you access indirectly through {@link Configuration#getTemplate(String)} and other + * {@link Configuration} API-s. When you set the {@link Configuration#getTemplateLoader() templateLoader} or + * {@link Configuration#getCacheStorage() cacheStorage} of the {@link Configuration}, you indirectly configure the + * {@link TemplateResolver}. */ public class DefaultTemplateResolver extends TemplateResolver { /** - * The default template update delay; see {@link Configuration#setTemplateUpdateDelayMilliseconds(long)}. + * The default template update delay; see {@link Configuration#getTemplateUpdateDelayMilliseconds()}. * * @since 2.3.23 */ @@ -92,28 +92,12 @@ public class DefaultTemplateResolver extends TemplateResolver { private final TemplateLookupStrategy templateLookupStrategy; private final TemplateNameFormat templateNameFormat; private final TemplateConfigurationFactory templateConfigurations; - - /** {@link Configuration#setTemplateUpdateDelayMilliseconds(long)} */ - private long templateUpdateDelayMilliseconds = DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS; - /** {@link Configuration#setLocalizedLookup(boolean)} */ - private boolean localizedLookup = true; + private final long templateUpdateDelayMilliseconds; + private final boolean localizedLookup; private Configuration config; /** - * Same as - * {@link #DefaultTemplateResolver(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, - * TemplateConfigurationFactory, Configuration)} with {@code null} for {@code templateConfigurations}-s. - * - * @since 2.3.22 - */ - public DefaultTemplateResolver(TemplateLoader templateLoader, CacheStorage cacheStorage, - TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, - Configuration config) { - this(templateLoader, cacheStorage, templateLookupStrategy, templateNameFormat, null, config); - } - - /** * @param templateLoader * The {@link TemplateLoader} to use. Can be {@code null}, though then every request will result in * {@link TemplateNotFoundException}. @@ -121,6 +105,8 @@ public class DefaultTemplateResolver extends TemplateResolver { * The {@link CacheStorage} to use. Can't be {@code null}. * @param templateLookupStrategy * The {@link TemplateLookupStrategy} to use. Can't be {@code null}. + * @param templateUpdateDelayMilliseconds + * See {@link Configuration#getTemplateUpdateDelayMilliseconds()} * @param templateNameFormat * The {@link TemplateNameFormat} to use. Can't be {@code null}. * @param templateConfigurations @@ -132,8 +118,11 @@ public class DefaultTemplateResolver extends TemplateResolver { * * @since 2.3.24 */ - public DefaultTemplateResolver(TemplateLoader templateLoader, CacheStorage cacheStorage, - TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, + public DefaultTemplateResolver( + TemplateLoader templateLoader, + CacheStorage cacheStorage, long templateUpdateDelayMilliseconds, + TemplateLookupStrategy templateLookupStrategy, boolean localizedLookup, + TemplateNameFormat templateNameFormat, TemplateConfigurationFactory templateConfigurations, Configuration config) { super(config); @@ -143,6 +132,10 @@ public class DefaultTemplateResolver extends TemplateResolver { _NullArgumentException.check("cacheStorage", cacheStorage); this.cacheStorage = cacheStorage; + this.templateUpdateDelayMilliseconds = templateUpdateDelayMilliseconds; + + this.localizedLookup = localizedLookup; + _NullArgumentException.check("templateLookupStrategy", templateLookupStrategy); this.templateLookupStrategy = templateLookupStrategy; @@ -518,7 +511,6 @@ public class DefaultTemplateResolver extends TemplateResolver { cacheStorage.put(cacheKey, cachedResult); } - @SuppressWarnings("deprecation") private Template loadTemplate( TemplateLoadingResult templateLoaderResult, final String name, final String sourceName, Locale locale, final Serializable customLookupCondition) @@ -633,18 +625,6 @@ public class DefaultTemplateResolver extends TemplateResolver { } /** - * Sets the delay in milliseconds between checking for newer versions of a - * template sources. - * @param templateUpdateDelayMilliseconds the new value of the delay - */ - public void setTemplateUpdateDelayMilliseconds(long templateUpdateDelayMilliseconds) { - // synchronized was moved here so that we don't advertise that it's thread-safe, as it's not. - synchronized (this) { - this.templateUpdateDelayMilliseconds = templateUpdateDelayMilliseconds; - } - } - - /** * Returns if localized template lookup is enabled or not. */ public boolean getLocalizedLookup() { @@ -655,19 +635,6 @@ public class DefaultTemplateResolver extends TemplateResolver { } /** - * Setis if localized template lookup is enabled or not. - */ - public void setLocalizedLookup(boolean localizedLookup) { - // synchronized was moved here so that we don't advertise that it's thread-safe, as it's not. - synchronized (this) { - if (this.localizedLookup != localizedLookup) { - this.localizedLookup = localizedLookup; - clearTemplateCache(); - } - } - } - - /** * Removes all entries from the cache, forcing reloading of templates on subsequent * {@link #getTemplate(String, Locale, Serializable)} calls. * @@ -698,8 +665,8 @@ public class DefaultTemplateResolver extends TemplateResolver { /** * Removes an entry from the cache, hence forcing the re-loading of it when it's next time requested. (It doesn't - * delete the template file itself.) This is to give the application finer control over cache updating than - * {@link #setTemplateUpdateDelayMilliseconds(long)} alone does. + * delete the template file itself.) This is to give the application finer control over cache updating than the + * update delay ({@link #getTemplateUpdateDelayMilliseconds()}) alone does. * * For the meaning of the parameters, see * {@link Configuration#getTemplate(String, Locale, Serializable, boolean)} http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/MruCacheStorage.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/MruCacheStorage.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/MruCacheStorage.java index 0387d64..9f004fe 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/MruCacheStorage.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/MruCacheStorage.java @@ -24,7 +24,7 @@ import java.lang.ref.SoftReference; import java.util.HashMap; import java.util.Map; -import org.apache.freemarker.core.templateresolver.CacheStorage; +import org.apache.freemarker.core.Configuration; import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; /** @@ -55,7 +55,7 @@ import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; * memory-sensitive) most-recently-used caching through * {@link SoftCacheStorage} as well. * - * @see org.apache.freemarker.core.Configuration#setCacheStorage(CacheStorage) + * @see Configuration#getCacheStorage() */ public class MruCacheStorage implements CacheStorageWithGetSize { private final MruEntry strongHead = new MruEntry(); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/NullCacheStorage.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/NullCacheStorage.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/NullCacheStorage.java index 33d3d02..c8ff55c 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/NullCacheStorage.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/NullCacheStorage.java @@ -19,6 +19,7 @@ package org.apache.freemarker.core.templateresolver.impl; +import org.apache.freemarker.core.Configuration; import org.apache.freemarker.core.templateresolver.CacheStorage; import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; @@ -26,7 +27,7 @@ import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; * A cache storage that doesn't store anything. Use this if you * don't want caching. * - * @see org.apache.freemarker.core.Configuration#setCacheStorage(CacheStorage) + * @see Configuration#getCacheStorage() * * @since 2.3.17 */ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/SoftCacheStorage.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/SoftCacheStorage.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/SoftCacheStorage.java index a5546fe..3e22c33 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/SoftCacheStorage.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/SoftCacheStorage.java @@ -25,6 +25,7 @@ import java.lang.ref.SoftReference; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; +import org.apache.freemarker.core.Configuration.ExtendableBuilder; import org.apache.freemarker.core.templateresolver.CacheStorage; import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; @@ -34,7 +35,7 @@ import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; * class is thread-safe to the extent that its underlying map is. The parameterless constructor uses a thread-safe map * since 2.3.24 or Java 5. * - * @see org.apache.freemarker.core.Configuration#setCacheStorage(CacheStorage) + * @see ExtendableBuilder#setCacheStorage(CacheStorage) */ public class SoftCacheStorage implements CacheStorage, CacheStorageWithGetSize { http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7d61a45d/src/main/java/org/apache/freemarker/core/templateresolver/impl/StrongCacheStorage.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/freemarker/core/templateresolver/impl/StrongCacheStorage.java b/src/main/java/org/apache/freemarker/core/templateresolver/impl/StrongCacheStorage.java index eea7331..1d0533b 100644 --- a/src/main/java/org/apache/freemarker/core/templateresolver/impl/StrongCacheStorage.java +++ b/src/main/java/org/apache/freemarker/core/templateresolver/impl/StrongCacheStorage.java @@ -23,6 +23,7 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; +import org.apache.freemarker.core.Configuration; import org.apache.freemarker.core.templateresolver.CacheStorage; import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; @@ -31,7 +32,7 @@ import org.apache.freemarker.core.templateresolver.CacheStorageWithGetSize; * it was passed, therefore prevents the cache from being purged during garbage collection. This class is always * thread-safe since 2.3.24, before that if we are running on Java 5 or later. * - * @see org.apache.freemarker.core.Configuration#setCacheStorage(CacheStorage) + * @see Configuration#getCacheStorage() */ public class StrongCacheStorage implements CacheStorage, CacheStorageWithGetSize {
