You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2015/12/19 17:43:04 UTC
[5/7] incubator-freemarker git commit: The new (in 2.3.24-pre01)
TemplateConfigurer class was renamed to TemplateConfiguration,
and the related configuration setting from template_configurers to
template_configurations. Also, the TemplateConfigurer.confi
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/main/java/freemarker/core/TemplateConfigurer.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateConfigurer.java b/src/main/java/freemarker/core/TemplateConfigurer.java
deleted file mode 100644
index 78c627f..0000000
--- a/src/main/java/freemarker/core/TemplateConfigurer.java
+++ /dev/null
@@ -1,580 +0,0 @@
-/*
- * 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 freemarker.core;
-
-import java.io.Reader;
-import java.util.LinkedHashMap;
-import java.util.Map;
-
-import freemarker.cache.TemplateCache;
-import freemarker.template.Configuration;
-import freemarker.template.Template;
-import freemarker.template.Version;
-import freemarker.template._TemplateAPI;
-import freemarker.template.utility.NullArgumentException;
-
-/**
- * Used for customizing the configuration settings for individual {@link Template}-s, relatively to the common setting
- * values coming from the {@link Configuration}. This was designed with the standard template loading mechanism of
- * FreeMarker in mind ({@link Configuration#getTemplate(String)} and {@link TemplateCache}), though can also be reused
- * for custom template loading and caching solutions.
- *
- * <p>
- * Note on the {@code locale} setting: When used with the standard template loading/caching mechanism
- * ({@link Configuration#getTemplate(String)} and its overloads), localized lookup happens before the {@code locale}
- * specified here could have effect. The {@code locale} will be only set in the template that the localized looks has
- * already found.
- *
- * <p>
- * Note on encoding setting {@code encoding}: See {@link #setEncoding(String)}.
- *
- * <p>
- * Note that the result value of the reader methods (getter and "is" methods) is usually not useful unless the value of
- * that setting was already set on this object. Otherwise you will get the value from the parent {@link Configuration},
- * which is {@link Configuration#getDefaultConfiguration()} before this object is associated to a {@link Configuration}.
- *
- * <p>
- * If you are using this class for your own template loading and caching solution, rather than with the standard one,
- * you should be aware of a few more details:
- *
- * <ul>
- * <li>This class implements both {@link Configurable} and
- * {@link ParserConfiguration}. This means that it can influence both the template parsing phase and the runtime
- * settings. For both aspects (i.e., {@link Configurable} and {@link ParserConfiguration}) to take effect, you have
- * first pass this object to the {@link Template} constructor (this is where the {@link ParserConfiguration} interface
- * is used), and then you have to call {@link #configure(Template)} on the resulting {@link Template} object (this is
- * where the {@link Configurable} aspect is used).
- *
- * <li>{@link #configure(Template)} only change the settings that weren't yet set on the {@link Template} (but are
- * inherited from the {@link Configuration}). This is primarily because if the template configures itself via the
- * {@code #ftl} header, those values should have precedence. A consequence of this is that if you want to configure
- * the same {@link Template} with multiple {@link TemplateConfigurer}-s, you either should merge them to a single one
- * before that (with {@link #merge(TemplateConfigurer)}), or you have to apply them in reverse order of their intended
- * precedence.
- * </ul>
- *
- * @see Template#Template(String, String, Reader, Configuration, ParserConfiguration, String)
- *
- * @since 2.3.24
- */
-public final class TemplateConfigurer extends Configurable implements ParserConfiguration {
-
- private boolean parentConfigurationSet;
- private Integer tagSyntax;
- private Integer namingConvention;
- private Boolean whitespaceStripping;
- private Boolean strictSyntaxMode;
- private Integer autoEscapingPolicy;
- private Boolean recognizeStandardFileExtensions;
- private OutputFormat outputFormat;
- private String encoding;
-
- /**
- * Creates a new instance. The parent will be {@link Configuration#getDefaultConfiguration()} initially, but it will
- * be changed to the real parent {@link Configuration} when this object is added to the {@link Configuration}. (It's
- * not allowed to add the same instance to multiple {@link Configuration}-s).
- */
- public TemplateConfigurer() {
- super(Configuration.getDefaultConfiguration());
- }
-
- /**
- * Same as {@link #setParentConfiguration(Configuration)}.
- *
- * @throws IllegalArgumentException
- * if the argument is {@code null} or not a {@link Configuration}.
- */
- @Override
- void setParent(Configurable cfg) {
- NullArgumentException.check("cfg", cfg);
- if (!(cfg instanceof Configuration)) {
- throw new IllegalArgumentException("The parent of a TemplateConfigurer can only be a Configuration");
- }
-
- if (parentConfigurationSet) {
- if (getParent() != cfg) {
- throw new IllegalStateException(
- "This TemplateConfigurer is already associated with a different Configuration instance.");
- }
- return;
- }
-
- if (((Configuration) cfg).getIncompatibleImprovements().intValue() < _TemplateAPI.VERSION_INT_2_3_22
- && hasAnyConfigurableSet()) {
- throw new IllegalStateException(
- "This TemplateConfigurer can't be associated to a Configuration that has incompatibleImprovements "
- + "less than 2.3.22, because it changes non-parser settings.");
- }
-
- super.setParent(cfg);
- parentConfigurationSet = true;
- }
-
- /**
- * Associates this instance with a {@link Configuration}; usually you don't call this, as it's called internally
- * when this instance is added to a {@link Configuration}. This method can be called only once (except with the same
- * {@link Configuration} parameter again, as that changes nothing anyway).
- *
- * @throws IllegalStateException
- * If the parent configuration was already set to a different {@link Configuration} instance.
- * @throws IllegalArgumentException
- * if the argument is {@code null}.
- */
- public void setParentConfiguration(Configuration cfg) {
- setParent(cfg);
- }
-
- /**
- * Returns the parent {@link Configuration}, or {@code null} if none was associated yet.
- */
- public Configuration getParentConfiguration() {
- return parentConfigurationSet ? (Configuration) getParent() : null;
- }
-
- /**
- * Set all settings in this {@link TemplateConfigurer} that that were set in the parameter
- * {@link TemplateConfigurer}, possibly overwriting the earlier value in this object. (A setting is said to be set
- * in a {@link TemplateConfigurer} if it was explicitly set via a setter method, as opposed to be inherited.)
- */
- public void merge(TemplateConfigurer tc) {
- if (tc.isAPIBuiltinEnabledSet()) {
- setAPIBuiltinEnabled(tc.isAPIBuiltinEnabled());
- }
- if (tc.isArithmeticEngineSet()) {
- setArithmeticEngine(tc.getArithmeticEngine());
- }
- if (tc.isAutoEscapingPolicySet()) {
- setAutoEscapingPolicy(tc.getAutoEscapingPolicy());
- }
- if (tc.isAutoFlushSet()) {
- setAutoFlush(tc.getAutoFlush());
- }
- if (tc.isBooleanFormatSet()) {
- setBooleanFormat(tc.getBooleanFormat());
- }
- if (tc.isClassicCompatibleSet()) {
- setClassicCompatibleAsInt(tc.getClassicCompatibleAsInt());
- }
- if (tc.isCustomDateFormatsSet()) {
- setCustomDateFormats(mergeMaps(getCustomDateFormats(), tc.getCustomDateFormats()));
- }
- if (tc.isCustomNumberFormatsSet()) {
- setCustomNumberFormats(mergeMaps(getCustomNumberFormats(), tc.getCustomNumberFormats()));
- }
- if (tc.isDateFormatSet()) {
- setDateFormat(tc.getDateFormat());
- }
- if (tc.isDateTimeFormatSet()) {
- setDateTimeFormat(tc.getDateTimeFormat());
- }
- if (tc.isEncodingSet()) {
- setEncoding(tc.getEncoding());
- }
- if (tc.isLocaleSet()) {
- setLocale(tc.getLocale());
- }
- if (tc.isLogTemplateExceptionsSet()) {
- setLogTemplateExceptions(tc.getLogTemplateExceptions());
- }
- if (tc.isNamingConventionSet()) {
- setNamingConvention(tc.getNamingConvention());
- }
- if (tc.isNewBuiltinClassResolverSet()) {
- setNewBuiltinClassResolver(tc.getNewBuiltinClassResolver());
- }
- if (tc.isNumberFormatSet()) {
- setNumberFormat(tc.getNumberFormat());
- }
- if (tc.isObjectWrapperSet()) {
- setObjectWrapper(tc.getObjectWrapper());
- }
- if (tc.isOutputEncodingSet()) {
- setOutputEncoding(tc.getOutputEncoding());
- }
- if (tc.isOutputFormatSet()) {
- setOutputFormat(tc.getOutputFormat());
- }
- if (tc.isRecognizeStandardFileExtensionsSet()) {
- setRecognizeStandardFileExtensions(tc.getRecognizeStandardFileExtensions());
- }
- if (tc.isShowErrorTipsSet()) {
- setShowErrorTips(tc.getShowErrorTips());
- }
- if (tc.isSQLDateAndTimeTimeZoneSet()) {
- setSQLDateAndTimeTimeZone(tc.getSQLDateAndTimeTimeZone());
- }
- if (tc.isStrictSyntaxModeSet()) {
- setStrictSyntaxMode(tc.getStrictSyntaxMode());
- }
- if (tc.isTagSyntaxSet()) {
- setTagSyntax(tc.getTagSyntax());
- }
- if (tc.isTemplateExceptionHandlerSet()) {
- setTemplateExceptionHandler(tc.getTemplateExceptionHandler());
- }
- if (tc.isTimeFormatSet()) {
- setTimeFormat(tc.getTimeFormat());
- }
- if (tc.isTimeZoneSet()) {
- setTimeZone(tc.getTimeZone());
- }
- if (tc.isURLEscapingCharsetSet()) {
- setURLEscapingCharset(tc.getURLEscapingCharset());
- }
- if (tc.isWhitespaceStrippingSet()) {
- setWhitespaceStripping(tc.getWhitespaceStripping());
- }
-
- tc.copyDirectCustomAttributes(this, true);
- }
-
- /**
- * Sets the settings of the {@link Template} which are not yet set in the {@link Template} and are set in this
- * {@link TemplateConfigurer}, leaves the other settings as is. A setting is said to be set in a
- * {@link TemplateConfigurer} or {@link Template} if it was explicitly set via a setter method on that object, as
- * opposed to be inherited from the {@link Configuration}.
- *
- * <p>
- * Note that the {@code encoding} setting of the {@link Template} counts as unset if it's {@code null},
- * even if {@code null} was set via {@link Template#setEncoding(String)}.
- *
- * @throws IllegalStateException
- * If the parent configuration wasn't yet set.
- */
- public void configure(Template template) {
- checkParentConfigurationSet();
- Configuration cfg = getParentConfiguration();
- if (template.getConfiguration() != cfg) {
- // This is actually not a problem right now, but for future BC we enforce this.
- throw new IllegalArgumentException(
- "The argument Template doesn't belong to the same Configuration as the TemplateConfigurer");
- }
-
- if (isAPIBuiltinEnabledSet() && !template.isAPIBuiltinEnabledSet()) {
- template.setAPIBuiltinEnabled(isAPIBuiltinEnabled());
- }
- if (isArithmeticEngineSet() && !template.isArithmeticEngineSet()) {
- template.setArithmeticEngine(getArithmeticEngine());
- }
- if (isAutoFlushSet() && !template.isAutoFlushSet()) {
- template.setAutoFlush(getAutoFlush());
- }
- if (isBooleanFormatSet() && !template.isBooleanFormatSet()) {
- template.setBooleanFormat(getBooleanFormat());
- }
- if (isClassicCompatibleSet() && !template.isClassicCompatibleSet()) {
- template.setClassicCompatibleAsInt(getClassicCompatibleAsInt());
- }
- if (isCustomDateFormatsSet() && !template.isCustomDateFormatsSet()) {
- template.setCustomDateFormats(getCustomDateFormats());
- }
- if (isCustomNumberFormatsSet() && !template.isCustomNumberFormatsSet()) {
- template.setCustomNumberFormats(getCustomNumberFormats());
- }
- if (isDateFormatSet() && !template.isDateFormatSet()) {
- template.setDateFormat(getDateFormat());
- }
- if (isDateTimeFormatSet() && !template.isDateTimeFormatSet()) {
- template.setDateTimeFormat(getDateTimeFormat());
- }
- if (isEncodingSet() && template.getEncoding() == null) {
- template.setEncoding(getEncoding());
- }
- if (isLocaleSet() && !template.isLocaleSet()) {
- template.setLocale(getLocale());
- }
- if (isLogTemplateExceptionsSet() && !template.isLogTemplateExceptionsSet()) {
- template.setLogTemplateExceptions(getLogTemplateExceptions());
- }
- if (isNewBuiltinClassResolverSet() && !template.isNewBuiltinClassResolverSet()) {
- template.setNewBuiltinClassResolver(getNewBuiltinClassResolver());
- }
- if (isNumberFormatSet() && !template.isNumberFormatSet()) {
- template.setNumberFormat(getNumberFormat());
- }
- if (isObjectWrapperSet() && !template.isObjectWrapperSet()) {
- template.setObjectWrapper(getObjectWrapper());
- }
- if (isOutputEncodingSet() && !template.isOutputEncodingSet()) {
- template.setOutputEncoding(getOutputEncoding());
- }
- if (isShowErrorTipsSet() && !template.isShowErrorTipsSet()) {
- template.setShowErrorTips(getShowErrorTips());
- }
- if (isSQLDateAndTimeTimeZoneSet() && !template.isSQLDateAndTimeTimeZoneSet()) {
- template.setSQLDateAndTimeTimeZone(getSQLDateAndTimeTimeZone());
- }
- if (isTemplateExceptionHandlerSet() && !template.isTemplateExceptionHandlerSet()) {
- template.setTemplateExceptionHandler(getTemplateExceptionHandler());
- }
- if (isTimeFormatSet() && !template.isTimeFormatSet()) {
- template.setTimeFormat(getTimeFormat());
- }
- if (isTimeZoneSet() && !template.isTimeZoneSet()) {
- template.setTimeZone(getTimeZone());
- }
- if (isURLEscapingCharsetSet() && !template.isURLEscapingCharsetSet()) {
- template.setURLEscapingCharset(getURLEscapingCharset());
- }
-
- copyDirectCustomAttributes(template, false);
- }
-
- /**
- * See {@link Configuration#setTagSyntax(int)}.
- */
- public void setTagSyntax(int tagSyntax) {
- _TemplateAPI.valideTagSyntaxValue(tagSyntax);
- this.tagSyntax = Integer.valueOf(tagSyntax);
- }
-
- /**
- * The getter pair of {@link #setTagSyntax(int)}.
- */
- public int getTagSyntax() {
- return tagSyntax != null ? tagSyntax.intValue() : getParentConfiguration().getTagSyntax();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isTagSyntaxSet() {
- return tagSyntax != null;
- }
-
- /**
- * See {@link Configuration#setNamingConvention(int)}.
- */
- public void setNamingConvention(int namingConvention) {
- _TemplateAPI.validateNamingConventionValue(namingConvention);
- this.namingConvention = Integer.valueOf(namingConvention);
- }
-
- /**
- * The getter pair of {@link #setNamingConvention(int)}.
- */
- public int getNamingConvention() {
- return namingConvention != null ? namingConvention.intValue() : getParentConfiguration().getNamingConvention();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isNamingConventionSet() {
- return namingConvention != null;
- }
-
- /**
- * See {@link Configuration#setWhitespaceStripping(boolean)}.
- */
- public void setWhitespaceStripping(boolean whitespaceStripping) {
- this.whitespaceStripping = Boolean.valueOf(whitespaceStripping);
- }
-
- /**
- * The getter pair of {@link #getWhitespaceStripping()}.
- */
- public boolean getWhitespaceStripping() {
- return whitespaceStripping != null ? whitespaceStripping.booleanValue()
- : getParentConfiguration().getWhitespaceStripping();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isWhitespaceStrippingSet() {
- return whitespaceStripping != null;
- }
-
- /**
- * Sets the output format of the template; see {@link Configuration#setAutoEscapingPolicy(int)} for more.
- */
- public void setAutoEscapingPolicy(int autoEscapingPolicy) {
- _TemplateAPI.validateAutoEscapingPolicyValue(autoEscapingPolicy);
- this.autoEscapingPolicy = Integer.valueOf(autoEscapingPolicy);
- }
-
- /**
- * The getter pair of {@link #setAutoEscapingPolicy(int)}.
- */
- public int getAutoEscapingPolicy() {
- return autoEscapingPolicy != null ? autoEscapingPolicy.intValue()
- : getParentConfiguration().getAutoEscapingPolicy();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isAutoEscapingPolicySet() {
- return autoEscapingPolicy != null;
- }
-
- /**
- * Sets the output format of the template; see {@link Configuration#setOutputFormat(OutputFormat)} for more.
- */
- public void setOutputFormat(OutputFormat outputFormat) {
- NullArgumentException.check("outputFormat", outputFormat);
- this.outputFormat = outputFormat;
- }
-
- /**
- * The getter pair of {@link #setOutputFormat(OutputFormat)}.
- */
- public OutputFormat getOutputFormat() {
- return outputFormat != null ? outputFormat : getParentConfiguration().getOutputFormat();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isOutputFormatSet() {
- return outputFormat != null;
- }
-
- /**
- * See {@link Configuration#setRecognizeStandardFileExtensions(boolean)}.
- */
- public void setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions) {
- this.recognizeStandardFileExtensions = Boolean.valueOf(recognizeStandardFileExtensions);
- }
-
- /**
- * Getter pair of {@link #setRecognizeStandardFileExtensions(boolean)}.
- */
- public boolean getRecognizeStandardFileExtensions() {
- return recognizeStandardFileExtensions != null ? recognizeStandardFileExtensions.booleanValue()
- : getParentConfiguration().getRecognizeStandardFileExtensions();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isRecognizeStandardFileExtensionsSet() {
- return recognizeStandardFileExtensions != null;
- }
-
- /**
- * See {@link Configuration#setStrictSyntaxMode(boolean)}.
- */
- public void setStrictSyntaxMode(boolean strictSyntaxMode) {
- this.strictSyntaxMode = Boolean.valueOf(strictSyntaxMode);
- }
-
- /**
- * The getter pair of {@link #setStrictSyntaxMode(boolean)}.
- */
- public boolean getStrictSyntaxMode() {
- return strictSyntaxMode != null ? strictSyntaxMode.booleanValue()
- : getParentConfiguration().getStrictSyntaxMode();
- }
-
- /**
- * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
- */
- public boolean isStrictSyntaxModeSet() {
- return strictSyntaxMode != null;
- }
-
- @Override
- public void setStrictBeanModels(boolean strict) {
- throw new UnsupportedOperationException(
- "Setting strictBeanModels on " + TemplateConfigurer.class.getSimpleName() + " level isn't supported.");
- }
-
- public String getEncoding() {
- return encoding != null ? encoding : getParentConfiguration().getDefaultEncoding();
- }
-
- /**
- * When the standard template loading/caching mechanism is used, this forces the charset used for reading the
- * template "file", overriding everything but the encoding coming from the {@code #ftl} header. This setting
- * overrides the locale-specific encodings set via {@link Configuration#setEncoding(java.util.Locale, String)}. It
- * also overrides the {@code encoding} parameter of {@link Configuration#getTemplate(String, String)} (and of its
- * overloads) and the {@code encoding} parameter of the {@code #include} directive. This works like that because
- * specifying the encoding where you are requesting the template is error prone and deprecated.
- *
- * <p>
- * If you are developing your own template loading/caching mechanism instead of the standard one, note that the
- * above behavior is not guaranteed by this class alone; you have to ensure it. Also, read the note on
- * {@code encoding} in the documentation of {@link #configure(Template)}.
- */
- public void setEncoding(String encoding) {
- NullArgumentException.check("encoding", encoding);
- this.encoding = encoding;
- }
-
- public boolean isEncodingSet() {
- return encoding != null;
- }
-
- /**
- * Returns {@link Configuration#getIncompatibleImprovements()} from the parent {@link Configuration}. This mostly
- * just exist to satisfy the {@link ParserConfiguration} interface.
- *
- * @throws IllegalStateException
- * If the parent configuration wasn't yet set.
- */
- public Version getIncompatibleImprovements() {
- checkParentConfigurationSet();
- return getParentConfiguration().getIncompatibleImprovements();
- }
-
- private void checkParentConfigurationSet() {
- if (!parentConfigurationSet) {
- throw new IllegalStateException("The TemplateConfigurer wasn't associated with a Configuration yet.");
- }
- }
-
- private boolean hasAnyConfigurableSet() {
- return
- isAPIBuiltinEnabledSet()
- || isArithmeticEngineSet()
- || isAutoFlushSet()
- || isBooleanFormatSet()
- || isClassicCompatibleSet()
- || isCustomDateFormatsSet()
- || isCustomNumberFormatsSet()
- || isDateFormatSet()
- || isDateTimeFormatSet()
- || isLocaleSet()
- || isLogTemplateExceptionsSet()
- || isNewBuiltinClassResolverSet()
- || isNumberFormatSet()
- || isObjectWrapperSet()
- || isOutputEncodingSet()
- || isShowErrorTipsSet()
- || isSQLDateAndTimeTimeZoneSet()
- || isTemplateExceptionHandlerSet()
- || isTimeFormatSet()
- || isTimeZoneSet()
- || isURLEscapingCharsetSet();
- }
-
- private Map mergeMaps(Map m1, Map m2) {
- if (m1 == null) return m2;
- if (m2 == null) return m1;
- if (m1.isEmpty()) return m2;
- if (m2.isEmpty()) return m1;
-
- LinkedHashMap mergedM = new LinkedHashMap(m1);
- mergedM.putAll(m2);
- return mergedM;
- }
-
-}
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/main/java/freemarker/core/UndefinedOutputFormat.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/UndefinedOutputFormat.java b/src/main/java/freemarker/core/UndefinedOutputFormat.java
index d4cbdd1..4dce258 100644
--- a/src/main/java/freemarker/core/UndefinedOutputFormat.java
+++ b/src/main/java/freemarker/core/UndefinedOutputFormat.java
@@ -23,9 +23,9 @@ import freemarker.template.Configuration;
/**
* 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#setTemplateConfigurers(freemarker.cache.TemplateConfigurerFactory)}). This format doesn't
- * support auto-escaping ({@link Configuration#setAutoEscapingPolicy(int)}). It will print {@link TemplateMarkupOutputModel}-s
- * as is (doesn't try to convert them).
+ * {@link Configuration#setTemplateConfigurations(freemarker.cache.TemplateConfigurationFactory)}). This format doesn't
+ * support auto-escaping ({@link Configuration#setAutoEscapingPolicy(int)}). 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/ea5c47d1/src/main/java/freemarker/core/_ObjectBuilderSettingEvaluator.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/_ObjectBuilderSettingEvaluator.java b/src/main/java/freemarker/core/_ObjectBuilderSettingEvaluator.java
index efcd3cc..a1e1c22 100644
--- a/src/main/java/freemarker/core/_ObjectBuilderSettingEvaluator.java
+++ b/src/main/java/freemarker/core/_ObjectBuilderSettingEvaluator.java
@@ -36,11 +36,11 @@ import java.util.Map;
import java.util.Properties;
import freemarker.cache.AndMatcher;
-import freemarker.cache.ConditionalTemplateConfigurerFactory;
+import freemarker.cache.ConditionalTemplateConfigurationFactory;
import freemarker.cache.FileExtensionMatcher;
import freemarker.cache.FileNameGlobMatcher;
-import freemarker.cache.FirstMatchTemplateConfigurerFactory;
-import freemarker.cache.MergingTemplateConfigurerFactory;
+import freemarker.cache.FirstMatchTemplateConfigurationFactory;
+import freemarker.cache.MergingTemplateConfigurationFactory;
import freemarker.cache.NotMatcher;
import freemarker.cache.OrMatcher;
import freemarker.cache.PathGlobMatcher;
@@ -661,7 +661,7 @@ public class _ObjectBuilderSettingEvaluator {
addWithSimpleName(SHORTHANDS, BeansWrapper.class);
addWithSimpleName(SHORTHANDS, SimpleObjectWrapper.class);
- addWithSimpleName(SHORTHANDS, TemplateConfigurer.class);
+ addWithSimpleName(SHORTHANDS, TemplateConfiguration.class);
addWithSimpleName(SHORTHANDS, PathGlobMatcher.class);
addWithSimpleName(SHORTHANDS, FileNameGlobMatcher.class);
@@ -671,9 +671,9 @@ public class _ObjectBuilderSettingEvaluator {
addWithSimpleName(SHORTHANDS, OrMatcher.class);
addWithSimpleName(SHORTHANDS, NotMatcher.class);
- addWithSimpleName(SHORTHANDS, ConditionalTemplateConfigurerFactory.class);
- addWithSimpleName(SHORTHANDS, MergingTemplateConfigurerFactory.class);
- addWithSimpleName(SHORTHANDS, FirstMatchTemplateConfigurerFactory.class);
+ addWithSimpleName(SHORTHANDS, ConditionalTemplateConfigurationFactory.class);
+ addWithSimpleName(SHORTHANDS, MergingTemplateConfigurationFactory.class);
+ addWithSimpleName(SHORTHANDS, FirstMatchTemplateConfigurationFactory.class);
addWithSimpleName(SHORTHANDS, HTMLOutputFormat.class);
addWithSimpleName(SHORTHANDS, XMLOutputFormat.class);
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java b/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
index 6ad1040..498466e 100644
--- a/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
+++ b/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
@@ -199,7 +199,7 @@ import freemarker.template.utility.StringUtil;
* {@link HttpServletResponse#setCharacterEncoding(String)} method. Note that the charset of a template usually comes
* from {@link Configuration#getDefaultEncoding()} (i.e., from the {@code default_encoding} FreeMarker setting),
* occasionally from {@link Configuration#getEncoding(Locale)} (when FreeMarker was configured to use different charsets
- * depending on the locale) or even more rarely from {@link Configuration#getTemplateConfigurers()} (when FreeMarker was
+ * depending on the locale) or even more rarely from {@link Configuration#getTemplateConfigurations()} (when FreeMarker was
* configured to use a specific charset for certain templates).
* <li>{@value #INIT_PARAM_VALUE_FROM_TEMPLATE}: This should be used in most applications, but it's not the default for
* backward compatibility. It reads the {@link Configurable#getOutputEncoding()} setting of the template (note that the
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/main/java/freemarker/template/Configuration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java
index c04f37a..0e67121 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -51,7 +51,7 @@ import freemarker.cache.MultiTemplateLoader;
import freemarker.cache.SoftCacheStorage;
import freemarker.cache.TemplateCache;
import freemarker.cache.TemplateCache.MaybeMissingTemplate;
-import freemarker.cache.TemplateConfigurerFactory;
+import freemarker.cache.TemplateConfigurationFactory;
import freemarker.cache.TemplateLoader;
import freemarker.cache.TemplateLookupContext;
import freemarker.cache.TemplateLookupStrategy;
@@ -68,7 +68,7 @@ import freemarker.core.ParseException;
import freemarker.core.ParserConfiguration;
import freemarker.core.PlainTextOutputFormat;
import freemarker.core.RTFOutputFormat;
-import freemarker.core.TemplateConfigurer;
+import freemarker.core.TemplateConfiguration;
import freemarker.core.TemplateMarkupOutputModel;
import freemarker.core.UndefinedOutputFormat;
import freemarker.core.UnregisteredOutputFormatException;
@@ -268,11 +268,11 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
public static final String TEMPLATE_NAME_FORMAT_KEY = TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE;
/** Legacy, snake case ({@code like_this}) variation of the setting name. @since 2.3.24 */
- public static final String TEMPLATE_CONFIGURERS_KEY_SNAKE_CASE = "template_configurers";
+ public static final String TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE = "template_configurations";
/** Modern, camel case ({@code likeThis}) variation of the setting name. @since 2.3.24 */
- public static final String TEMPLATE_CONFIGURERS_KEY_CAMEL_CASE = "templateConfigurers";
+ public static final String TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE = "templateConfigurations";
/** Alias to the {@code ..._SNAKE_CASE} variation. @since 2.3.24 */
- public static final String TEMPLATE_CONFIGURERS_KEY = TEMPLATE_CONFIGURERS_KEY_SNAKE_CASE;
+ public static final String TEMPLATE_CONFIGURATIONS_KEY = TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE;
/** Legacy, snake case ({@code like_this}) variation of the setting name. @since 2.3.23 */
public static final String INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE = "incompatible_improvements";
@@ -303,7 +303,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_SNAKE_CASE,
STRICT_SYNTAX_KEY_SNAKE_CASE,
TAG_SYNTAX_KEY_SNAKE_CASE,
- TEMPLATE_CONFIGURERS_KEY_SNAKE_CASE,
+ TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE,
TEMPLATE_LOADER_KEY_SNAKE_CASE,
TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE,
TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE,
@@ -326,7 +326,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE,
STRICT_SYNTAX_KEY_CAMEL_CASE,
TAG_SYNTAX_KEY_CAMEL_CASE,
- TEMPLATE_CONFIGURERS_KEY_CAMEL_CASE,
+ TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE,
TEMPLATE_LOADER_KEY_CAMEL_CASE,
TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE,
TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE,
@@ -815,10 +815,10 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
private void recreateTemplateCacheWith(
TemplateLoader loader, CacheStorage storage,
TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat,
- TemplateConfigurerFactory templateConfigurers) {
+ TemplateConfigurationFactory templateConfigurations) {
TemplateCache oldCache = cache;
cache = new TemplateCache(
- loader, storage, templateLookupStrategy, templateNameFormat, templateConfigurers, this);
+ loader, storage, templateLookupStrategy, templateNameFormat, templateConfigurations, this);
cache.clear(); // for fully BC behavior
cache.setDelay(oldCache.getDelay());
cache.setLocalizedLookup(localizedLookup);
@@ -827,7 +827,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
private void recreateTemplateCache() {
recreateTemplateCacheWith(cache.getTemplateLoader(), cache.getCacheStorage(),
cache.getTemplateLookupStrategy(), cache.getTemplateNameFormat(),
- getTemplateConfigurers());
+ getTemplateConfigurations());
}
private TemplateLoader getDefaultTemplateLoader() {
@@ -932,7 +932,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
copy.recreateTemplateCacheWith(
cache.getTemplateLoader(), cache.getCacheStorage(),
cache.getTemplateLookupStrategy(), cache.getTemplateNameFormat(),
- cache.getTemplateConfigurers());
+ cache.getTemplateConfigurations());
return copy;
} catch (CloneNotSupportedException e) {
throw new BugException("Cloning failed", e);
@@ -1122,7 +1122,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
if (cache.getTemplateLoader() != templateLoader) {
recreateTemplateCacheWith(templateLoader, cache.getCacheStorage(),
cache.getTemplateLookupStrategy(), cache.getTemplateNameFormat(),
- cache.getTemplateConfigurers());
+ cache.getTemplateConfigurations());
}
templateLoaderExplicitlySet = true;
}
@@ -1171,7 +1171,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
if (cache.getTemplateLookupStrategy() != templateLookupStrategy) {
recreateTemplateCacheWith(cache.getTemplateLoader(), cache.getCacheStorage(),
templateLookupStrategy, cache.getTemplateNameFormat(),
- cache.getTemplateConfigurers());
+ cache.getTemplateConfigurations());
}
templateLookupStrategyExplicitlySet = true;
}
@@ -1220,7 +1220,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
if (cache.getTemplateNameFormat() != templateNameFormat) {
recreateTemplateCacheWith(cache.getTemplateLoader(), cache.getCacheStorage(),
cache.getTemplateLookupStrategy(), templateNameFormat,
- cache.getTemplateConfigurers());
+ cache.getTemplateConfigurations());
}
templateNameFormatExplicitlySet = true;
}
@@ -1259,38 +1259,38 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
}
/**
- * Sets a {@link TemplateConfigurerFactory} that will configure individual templates where their settings differ
+ * Sets a {@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 TemplateConfigurer#setOutputFormat(OutputFormat) outputFormat} for templates based on their file
+ * {@link TemplateConfiguration#setOutputFormat(OutputFormat) outputFormat} 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 #setRecognizeStandardFileExtensions(boolean)} for more information about standard file extensions.
*
- * <p>See "Template configurers" in the FreeMarker Manual for examples.
+ * <p>See "Template configurations" in the FreeMarker Manual for examples.
*
* @since 2.3.24
*/
- public void setTemplateConfigurers(TemplateConfigurerFactory templateConfigurers) {
- if (cache.getTemplateConfigurers() != templateConfigurers) {
- if (templateConfigurers != null) {
- templateConfigurers.setConfiguration(this);
+ public void setTemplateConfigurations(TemplateConfigurationFactory templateConfigurations) {
+ if (cache.getTemplateConfigurations() != templateConfigurations) {
+ if (templateConfigurations != null) {
+ templateConfigurations.setConfiguration(this);
}
recreateTemplateCacheWith(cache.getTemplateLoader(), cache.getCacheStorage(),
cache.getTemplateLookupStrategy(), cache.getTemplateNameFormat(),
- templateConfigurers);
+ templateConfigurations);
}
}
/**
- * The getter pair of {@link #setTemplateConfigurers(TemplateConfigurerFactory)}.
+ * The getter pair of {@link #setTemplateConfigurations(TemplateConfigurationFactory)}.
*/
- public TemplateConfigurerFactory getTemplateConfigurers() {
+ public TemplateConfigurationFactory getTemplateConfigurations() {
if (cache == null) {
return null;
}
- return cache.getTemplateConfigurers();
+ return cache.getTemplateConfigurations();
}
/**
@@ -1311,7 +1311,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
if (getCacheStorage() != cacheStorage) {
recreateTemplateCacheWith(cache.getTemplateLoader(), cacheStorage,
cache.getTemplateLookupStrategy(), cache.getTemplateNameFormat(),
- cache.getTemplateConfigurers());
+ cache.getTemplateConfigurations());
}
cacheStorageExplicitlySet = true;
}
@@ -1740,7 +1740,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* Auto-escaping has significance when a value is printed with <code>${...}</code> (or <code>#{...}</code>). If
* auto-escaping is on, FreeMarker will assume that the value is plain text (as opposed to markup or some kind of
* rich text), so it will escape it according the current output format (see {@link #setOutputFormat(OutputFormat)}
- * and {@link TemplateConfigurer#setOutputFormat(OutputFormat)}). If auto-escaping is off, FreeMarker will assume
+ * and {@link TemplateConfiguration#setOutputFormat(OutputFormat)}). If auto-escaping is off, FreeMarker will assume
* that the string value is already in the output format, so it prints it as is to the output.
*
* <p>Further notes on auto-escaping:
@@ -1759,16 +1759,16 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* </ul>
*
* <p>Note that what you set here is just a default, which can be overridden for individual templates via
- * {@link #setTemplateConfigurers(TemplateConfigurerFactory)}. This setting is also overridden by the standard file
+ * {@link #setTemplateConfigurations(TemplateConfigurationFactory)}. This setting is also overridden by the standard file
* extensions; see them at {@link #setRecognizeStandardFileExtensions(boolean)}.
*
* @param autoEscapingPolicy
* One of the {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY},
* {@link #ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY}, and {@link #DISABLE_AUTO_ESCAPING_POLICY} constants.
*
- * @see TemplateConfigurer#setAutoEscapingPolicy(int)
+ * @see TemplateConfiguration#setAutoEscapingPolicy(int)
* @see Configuration#setOutputFormat(OutputFormat)
- * @see TemplateConfigurer#setOutputFormat(OutputFormat)
+ * @see TemplateConfiguration#setOutputFormat(OutputFormat)
*
* @since 2.3.24
*/
@@ -1794,7 +1794,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
/**
* Sets the (default) output format. Usually, you leave this on its default, which is
* {@link UndefinedOutputFormat#INSTANCE}, and then override it for individual templates based on their name (like
- * based on their "file" extension) with {@link #setTemplateConfigurers(TemplateConfigurerFactory)}. This setting is
+ * based on their "file" extension) with {@link #setTemplateConfigurations(TemplateConfigurationFactory)}. This setting is
* also overridden by the standard file extensions; see them at
* {@link #setRecognizeStandardFileExtensions(boolean)}.
*
@@ -1803,7 +1803,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* also used by the embedding application to set the HTTP response MIME type, etc.
*
* @see #setRegisteredCustomOutputFormats(Collection)
- * @see #setTemplateConfigurers(TemplateConfigurerFactory)
+ * @see #setTemplateConfigurations(TemplateConfigurationFactory)
* @see #setRecognizeStandardFileExtensions(boolean)
* @see #setAutoEscapingPolicy(int)
*
@@ -2018,26 +2018,26 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* Sets 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, defaults to {@code true}, so the following standard file extensions take their effect:
+ * 2.3.24, it defaults to {@code true}, so the following standard file extensions take their effect:
*
* <ul>
- * <li>{@code ftlh}: Sets {@link TemplateConfigurer#setOutputFormat(OutputFormat) outputFormat} to {@code "HTML"}
- * (i.e., {@link HTMLOutputFormat#INSTANCE} unless the {@code "HTML"} name is overridden by
+ * <li>{@code ftlh}: Sets {@link TemplateConfiguration#setOutputFormat(OutputFormat) outputFormat} to
+ * {@code "HTML"} (i.e., {@link HTMLOutputFormat#INSTANCE}, unless the {@code "HTML"} name is overridden by
* {@link #setRegisteredCustomOutputFormats(Collection)}) and
- * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}
- * {@link TemplateConfigurer#setAutoEscapingPolicy(int) autoEscapingPolicy}.
- * <li>{@code ftlx}: Sets {@link TemplateConfigurer#setOutputFormat(OutputFormat) outputFormat} to {@code "XML"}
- * (i.e., {@link XMLOutputFormat#INSTANCE} unless the {@code "XML"} name is overridden by
+ * {@link TemplateConfiguration#setAutoEscapingPolicy(int) autoEscapingPolicy} to
+ * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}.
+ * <li>{@code ftlx}: Sets {@link TemplateConfiguration#setOutputFormat(OutputFormat) outputFormat} to
+ * {@code "XML"} (i.e., {@link XMLOutputFormat#INSTANCE}, unless the {@code "XML"} name is overridden by
* {@link #setRegisteredCustomOutputFormats(Collection)}) and
- * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}
- * {@link TemplateConfigurer#setAutoEscapingPolicy(int) autoEscapingPolicy}.
+ * {@link TemplateConfiguration#setAutoEscapingPolicy(int) autoEscapingPolicy} 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 settings values dictated by
- * {@link #setTemplateConfigurers(TemplateConfigurerFactory)}.
+ * <p>The settings activated by these file extensions override the setting values dictated by
+ * {@link #setTemplateConfigurations(TemplateConfigurationFactory)}.
*/
public void setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions) {
boolean prevEffectiveValue = getRecognizeStandardFileExtensions();
@@ -2274,7 +2274,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
*
* @param locale
* The requested locale of the template. This is what {@link Template#getLocale()} on the resulting
- * {@link Template} will return (unless it's overridden via {@link #getTemplateConfigurers()}). This
+ * {@link Template} will return (unless it's overridden via {@link #getTemplateConfigurations()}). This
* parameter can be {@code null} since 2.3.22, in which case it defaults to
* {@link Configuration#getLocale()} (note that {@link Template#getLocale()} will give the default value,
* not {@code null}). This parameter also drives localized template lookup. Assuming that you have
@@ -2284,7 +2284,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* retrieve {@code myTemplate_en_US.html}, then {@code myTemplate.en.ftl}, and finally
* {@code myTemplate.ftl}. Note that that the template's locale will be {@code en_US} even if it only
* finds {@code myTemplate.ftl}. Note that when the {@code locale} setting is overridden with a
- * {@link TemplateConfigurer} provided by {@link #getTemplateConfigurers()}, that overrides the
+ * {@link TemplateConfiguration} provided by {@link #getTemplateConfigurations()}, that overrides the
* value specified here, but only after the localized lookup, that is, it modifies the template
* found by the localized lookup.
*
@@ -2305,7 +2305,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* instead). Why is this deprecated: It doesn't make sense to get the <em>same</em> template with
* different encodings, hence, it's error prone to specify the encoding where you get the template.
* Instead, if you have template "files" with different charsets, you should use
- * {@link #setTemplateConfigurers(TemplateConfigurerFactory)}, where you can associate encodings to
+ * {@link #setTemplateConfigurations(TemplateConfigurationFactory)}, where you can associate encodings to
* individual templates based on their names (like which "directory" are they in, what's their file
* extension, etc.). The encoding associated with the templates that way overrides the encoding that you
* specify here.
@@ -2900,13 +2900,13 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
} else {
throw invalidSettingValueException(name, value);
}
- } else if (TEMPLATE_CONFIGURERS_KEY_SNAKE_CASE.equals(name)
- || TEMPLATE_CONFIGURERS_KEY_CAMEL_CASE.equals(name)) {
+ } else if (TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE.equals(name)
+ || TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE.equals(name)) {
if (value.equals(NULL)) {
- setTemplateConfigurers(null);
+ setTemplateConfigurations(null);
} else {
- setTemplateConfigurers((TemplateConfigurerFactory) _ObjectBuilderSettingEvaluator.eval(
- value, TemplateConfigurerFactory.class, false, _SettingEvaluationEnvironment.getCurrent()));
+ setTemplateConfigurations((TemplateConfigurationFactory) _ObjectBuilderSettingEvaluator.eval(
+ value, TemplateConfigurationFactory.class, false, _SettingEvaluationEnvironment.getCurrent()));
}
} else {
unknown = true;
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/main/java/freemarker/template/Template.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Template.java b/src/main/java/freemarker/template/Template.java
index 0530fe2..f785768 100644
--- a/src/main/java/freemarker/template/Template.java
+++ b/src/main/java/freemarker/template/Template.java
@@ -48,7 +48,7 @@ import freemarker.core.Macro;
import freemarker.core.OutputFormat;
import freemarker.core.ParseException;
import freemarker.core.ParserConfiguration;
-import freemarker.core.TemplateConfigurer;
+import freemarker.core.TemplateConfiguration;
import freemarker.core.TemplateElement;
import freemarker.core.TextBlock;
import freemarker.core.TokenMgrError;
@@ -73,7 +73,7 @@ import freemarker.debug.impl.DebuggerService;
* 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
- * see {@link Configuration#setTemplateConfigurers(freemarker.cache.TemplateConfigurerFactory)}.
+ * see {@link Configuration#setTemplateConfigurations(freemarker.cache.TemplateConfigurationFactory)}.
*/
public class Template extends Configurable {
public static final String DEFAULT_NAMESPACE_PREFIX = "D";
@@ -207,25 +207,25 @@ public class Template extends Configurable {
/**
* Same as {@link #Template(String, String, Reader, Configuration, String)}, but also specifies a
- * {@link TemplateConfigurer}. This is mostly meant to be used by FreeMarker internally, but advanced users might
+ * {@link TemplateConfiguration}. This is mostly meant to be used by FreeMarker internally, but advanced users might
* still find this useful.
*
* @param customParserConfiguration
* Overrides the parsing related configuration settings of the {@link Configuration} parameter; can be
* {@code null}. This is useful as the {@link Configuration} is normally a singleton shared by all
- * templates, and so it's not good for specifying template-specific settings. (While
- * {@link Template} itself has methods to specify settings just for that template, those don't influence
- * the parsing, and you only have opportunity to call them after the parsing anyway.) This objects is
- * often a {@link TemplateConfigurer} whose parent is the {@link Configuration} parameter, and then it
+ * templates, and so it's not good for specifying template-specific settings. (While {@link Template}
+ * itself has methods to specify settings just for that template, those don't influence the parsing, and
+ * you only have opportunity to call them after the parsing anyway.) This objects is often a
+ * {@link TemplateConfiguration} whose parent is the {@link Configuration} parameter, and then it
* practically just overrides some of the parser settings, as the others are inherited from the
- * {@link Configuration}. Note that if this is a {@link TemplateConfigurer}, you will also want to call
- * {@link TemplateConfigurer#configure(Template)} on the resulting {@link Template} so that
+ * {@link Configuration}. Note that if this is a {@link TemplateConfiguration}, you will also want to
+ * call {@link TemplateConfiguration#apply(Template)} on the resulting {@link Template} so that
* {@link Configurable} settings will be set too, because this constructor only uses it as a
- * {@link ParserConfiguration}.
+ * {@link ParserConfiguration}.
* @param encoding
* Same as in {@link #Template(String, String, Reader, Configuration, String)}. When it's non-{@code
- * null}, it overrides the value coming from the {@code TemplateConfigurer#getEncoding()} method of the
- * {@code templateConfigurer} parameter.
+ * null}, it overrides the value coming from the {@link TemplateConfiguration#getEncoding()} method of
+ * the {@code templateConfiguration} parameter.
*
* @since 2.3.24
*/
@@ -572,7 +572,7 @@ public class Template extends Configurable {
/**
* Returns the {@link ParserConfiguration} that was used for parsing this template. This is most often the same
- * object as {@link #getConfiguration()}, but sometimes it's a {@link TemplateConfigurer}, or something else. It's
+ * object as {@link #getConfiguration()}, but sometimes it's a {@link TemplateConfiguration}, or something else. It's
* never {@code null}.
*
* @since 2.3.24
@@ -663,7 +663,7 @@ public class Template extends Configurable {
* Returns the output format (see {@link Configuration#setOutputFormat(OutputFormat)}) used for this template.
* The output format of a template can come from various places, in order of increasing priority:
* {@link Configuration#getOutputFormat()}, {@link ParserConfiguration#getOutputFormat()} (which is usually
- * provided by {@link Configuration#getTemplateConfigurers()}) and the {@code #ftl} header's {@code output_format}
+ * provided by {@link Configuration#getTemplateConfigurations()}) and the {@code #ftl} header's {@code output_format}
* option in the template.
*
* @since 2.3.24
@@ -683,7 +683,7 @@ public class Template extends Configurable {
* Returns if the template actually uses auto-escaping (see {@link Configuration#setAutoEscapingPolicy(int)}). This value
* is decided by the parser based on the actual {@link OutputFormat}, and the auto-escaping enums, in order of
* increasing priority: {@link Configuration#getAutoEscapingPolicy()}, {@link ParserConfiguration#getAutoEscapingPolicy()}
- * (which is usually provided by {@link Configuration#getTemplateConfigurers()}), and finally on the {@code #ftl}
+ * (which is usually provided by {@link Configuration#getTemplateConfigurations()}), and finally on the {@code #ftl}
* header's {@code auto_esc} option in the template.
*
* @since 2.3.24
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/ea5c47d1/src/manual/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/book.xml b/src/manual/book.xml
index 0b80c41..c561322 100644
--- a/src/manual/book.xml
+++ b/src/manual/book.xml
@@ -7991,10 +7991,10 @@ myCfg.setDefaultEncoding("UTF-8");</programlisting>
<listitem>
<para><literal>Template</literal> layer: Settings on individual
templates are normally set by <link
- linkend="pgui_config_templateconfigurers">template configurers
- (see them in their own chapter)</link>, which basically associate
- setting assignments to template name (template path) patterns.
- There's a deviation from this approach with the
+ linkend="pgui_config_templateconfigurations">template
+ configurations (see them in their own chapter)</link>, which
+ basically associate setting assignments to template name (template
+ path) patterns. There's a deviation from this approach with the
<literal>locale</literal> setting, because that you can also
specify to <literal>Configuration.getTemplate(...)</literal> as
parameter, to get the template for the requested locale (so called
@@ -8689,13 +8689,13 @@ c</programlisting>
</section>
</section>
- <section xml:id="pgui_config_templateconfigurers">
- <title>Template configurers</title>
+ <section xml:id="pgui_config_templateconfigurations">
+ <title>Template configurations</title>
- <para>Template configurers refers to the
- <literal>template_configurers</literal> setting of
+ <para><quote>Template configurations</quote> refers to the
+ <literal>template_configurations</literal> setting of
<literal>Configuration</literal>
- (<literal>Configuration.setTemplateConfigurers(<replaceable>...</replaceable>)</literal>).
+ (<literal>Configuration.setTemplateConfigurations(<replaceable>...</replaceable>)</literal>).
This setting lets you override individual settings coming from the
common <literal>Configuration</literal> object, depending on the name
(path) of the template.</para>
@@ -8713,13 +8713,13 @@ c</programlisting>
<itemizedlist>
<listitem>
- <para><literal>TemplateConfigurer</literal>-s: These store the
+ <para><literal>TemplateConfiguration</literal>-s: These store the
actual setting assignments that you want to do. For example, this
- <literal>TemplateConfigurer</literal> will set the encoding and
+ <literal>TemplateConfiguration</literal> will set the encoding and
the output format of the matched template (and leave all other
settings of it alone):</para>
- <programlisting role="unspecified">TemplateConfigurer tcUTF8XML = new TemplateConfigurer();
+ <programlisting role="unspecified">TemplateConfiguration tcUTF8XML = new TemplateConfiguration();
tc.setEncoding("utf-8");
tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
</listitem>
@@ -8736,11 +8736,11 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
</listitem>
<listitem>
- <para><literal>TemplateConfigurerFactory</literal>-es: This is
- what connects <literal>TemplateConfigurer</literal> and
+ <para><literal>TemplateConfigurationFactory</literal>-es: This is
+ what connects <literal>TemplateConfiguration</literal> and
<literal>TemplateSourceMatcher</literal> together. This is the
- Java type of the <literal>template_configurers</literal> setting.
- See the examples below for more.</para>
+ Java type of the <literal>template_configurations</literal>
+ setting. See the examples below for more.</para>
</listitem>
</itemizedlist>
@@ -8748,12 +8748,12 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
<title>Example 1</title>
<para>This setup combines our earlier two example object with a
- <literal>ConditionalTemplateConfigurerFactory</literal>, causing all
- templates with <literal>xml</literal> extension to get UTF-8
+ <literal>ConditionalTemplateConfigurationFactory</literal>, causing
+ all templates with <literal>xml</literal> extension to get UTF-8
encoding and XML output format:</para>
- <programlisting role="unspecified">cfg.setTemplateConfigurers(
- new ConditionalTemplateConfigurerFactory(
+ <programlisting role="unspecified">cfg.setTemplateConfigurations(
+ new ConditionalTemplateConfigurationFactory(
new FileExtensionMatcher("xml"),
tcUTF8XML));</programlisting>
@@ -8763,10 +8763,10 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
key value pairs (the <literal>\</literal>-s are prescribed by the
Java Properties file format):</para>
- <programlisting role="unspecified">templateConfigurers = \
- ConditionalTemplateConfigurerFactory( \
+ <programlisting role="unspecified">templateConfigurations = \
+ ConditionalTemplateConfigurationFactory( \
FileExtensionMatcher("xml"), \
- TemplateConfigurer( \
+ TemplateConfiguration( \
encoding = "utf-8", \
outputFormat = XMLOutputFormat() \
) \
@@ -8784,20 +8784,20 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
Subject templates must get <literal>plainText</literal> output
format, while body templates must get <literal>HTML</literal> output
format. So we have to make a choice here, and that's when you need a
- <literal>FirstMatchTemplateConfigurerFactory</literal>.</para>
+ <literal>FirstMatchTemplateConfigurationFactory</literal>.</para>
<para>Assuming <literal>cfg</literal> stores the shared
<literal>Configuration</literal> singleton, you set this up like
this:</para>
- <programlisting role="unspecified">cfg.setTemplateConfigurers(
- new ConditionalTemplateConfigurerFactory(
+ <programlisting role="unspecified">cfg.setTemplateConfigurations(
+ new ConditionalTemplateConfigurationFactory(
new PathGlobMatcher("mail/**"),
- new FirstMatchTemplateConfigurerFactory(
- new ConditionalTemplateConfigurerFactory(
+ new FirstMatchTemplateConfigurationFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileNameGlobMatcher("*.subject.*"),
tcSubject),
- new ConditionalTemplateConfigurerFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileNameGlobMatcher("*.body.*"),
tcBody)
)
@@ -8810,17 +8810,17 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
key value pairs (the <literal>\</literal>-s are prescribed by the
Java Properties file format only):</para>
- <programlisting role="unspecified">templateConfigurers = \
- ConditionalTemplateConfigurerFactory( \
+ <programlisting role="unspecified">templateConfigurations = \
+ ConditionalTemplateConfigurationFactory( \
PathGlobMatcher("mail/**"), \
- FirstMatchTemplateConfigurerFactory( \
- ConditionalTemplateConfigurerFactory( \
+ FirstMatchTemplateConfigurationFactory( \
+ ConditionalTemplateConfigurationFactory( \
FileNameGlobMatcher("*.subject.*"), \
- TemplateConfigurer(outputFormat = PlainTextOutputFormat()) \
+ TemplateConfiguration(outputFormat = PlainTextOutputFormat()) \
), \
- ConditionalTemplateConfigurerFactory( \
+ ConditionalTemplateConfigurationFactory( \
FileNameGlobMatcher("*.body.*"), \
- TemplateConfigurer(outputFormat = HTMLOutputFormat()) \
+ TemplateConfiguration(outputFormat = HTMLOutputFormat()) \
), \
noMatchErrorDetails = 'Mail template names must contain ".subject." or ".body."!' \
) \
@@ -8858,42 +8858,42 @@ tc.setOutputFormat(XMLOutputFormat.INSTANCE);</programlisting>
<para>Here we have 3 independent concerns, and possibly multiple (or
none) of those apply to a template; that's when you need a
- <literal>MergingTemplateConfigurerFactory</literal>. The last point
- describes a rule where you have mutually exclusive choices; that's
- when you need a
- <literal>FirstMatchTemplateConfigurerFactory</literal>, but this
+ <literal>MergingTemplateConfigurationFactory</literal>. The last
+ point describes a rule where you have mutually exclusive choices;
+ that's when you need a
+ <literal>FirstMatchTemplateConfigurationFactory</literal>, but this
time no choice is also allowed. Here's the source code, assuming
<literal>cfg</literal> stores the shared
<literal>Configuration</literal> instance:</para>
- <programlisting role="unspecified">TemplateConfigurer tcStats = new TemplateConfigurer();
+ <programlisting role="unspecified">TemplateConfiguration tcStats = new TemplateConfiguration();
tcStats.setDateTimeFormat("iso");
tcStats.setDateFormat("iso");
tcStats.setTimeFormat("iso");
tcStats.setTimeZone(DateUtil.UTC);
-TemplateConfigurer tcMail = new TemplateConfigurer();
+TemplateConfiguration tcMail = new TemplateConfiguration();
tcMail.setEncoding("utf-8");
-TemplateConfigurer tcHTML = new TemplateConfigurer();
+TemplateConfiguration tcHTML = new TemplateConfiguration();
tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE);
-TemplateConfigurer tcXML = new TemplateConfigurer();
+TemplateConfiguration tcXML = new TemplateConfiguration();
tcXML.setOutputFormat(XMLOutputFormat.INSTANCE);
-cfg.setTemplateConfigurers(
- new MergingTemplateConfigurerFactory(
- new ConditionalTemplateConfigurerFactory(
+cfg.setTemplateConfigurations(
+ new MergingTemplateConfigurationFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileNameGlobMatcher("*.stats.*"),
tcStats),
- new ConditionalTemplateConfigurerFactory(
+ new ConditionalTemplateConfigurationFactory(
new PathGlobMatcher("mail/**"),
tcMail),
- new FirstMatchTemplateConfigurerFactory(
- new ConditionalTemplateConfigurerFactory(
+ new FirstMatchTemplateConfigurationFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileExtensionMatcher("xml"),
tcXML),
- new ConditionalTemplateConfigurerFactory(
+ new ConditionalTemplateConfigurationFactory(
new OrMatcher(
new FileExtensionMatcher("html"),
new FileExtensionMatcher("htm")),
@@ -8907,32 +8907,32 @@ cfg.setTemplateConfigurers(
key value pairs (the <literal>\</literal>-s are prescribed by the
Java Properties file format only):</para>
- <programlisting role="unspecified">templateConfigurers = \
- MergingTemplateConfigurerFactory( \
- ConditionalTemplateConfigurerFactory( \
+ <programlisting role="unspecified">templateConfigurations = \
+ MergingTemplateConfigurationFactory( \
+ ConditionalTemplateConfigurationFactory( \
FileNameGlobMatcher("*.stats.*"), \
- TemplateConfigurer( \
+ TemplateConfiguration( \
dateTimeFormat = "iso", \
dateFormat = "iso", \
timeFormat = "iso", \
timeZone = TimeZone("UTC") \
) \
), \
- ConditionalTemplateConfigurerFactory( \
+ ConditionalTemplateConfigurationFactory( \
PathGlobMatcher("mail/**"), \
- TemplateConfigurer(encoding = "utf-8") \
+ TemplateConfiguration(encoding = "utf-8") \
), \
- FirstMatchTemplateConfigurerFactory( \
- ConditionalTemplateConfigurerFactory( \
+ FirstMatchTemplateConfigurationFactory( \
+ ConditionalTemplateConfigurationFactory( \
FileExtensionMatcher("xml"), \
- TemplateConfigurer(outputFormat = XMLOutputFormat()) \
+ TemplateConfiguration(outputFormat = XMLOutputFormat()) \
), \
- ConditionalTemplateConfigurerFactory( \
+ ConditionalTemplateConfigurationFactory( \
OrMatcher( \
FileExtensionMatcher("html"), \
FileExtensionMatcher("htm") \
), \
- TemplateConfigurer(outputFormat = HTMLOutputFormat()) \
+ TemplateConfiguration(outputFormat = HTMLOutputFormat()) \
), \
allowNoMatch = true \
) \
@@ -8970,7 +8970,7 @@ cfg.setTemplateConfigurers(
file extensions is the recommended way of activating HTML and XML
auto-escaping. You can also associate output formats to templates
based on arbitrary name patterns with the <link
- linkend="pgui_config_templateconfigurers"><literal>template_configurers</literal>
+ linkend="pgui_config_templateconfigurations"><literal>template_configurations</literal>
setting</link>; see some examples of that below.</para>
<para>There's another a related setting, called
@@ -9038,11 +9038,11 @@ cfg.setRecognizeStandardFileExtensions(true);</programlisting>
<programlisting role="unspecified">// Where you initalize the Configuration singletion, add:
-TemplateConfigurer tcHTML = new TemplateConfigurer();
+TemplateConfiguration tcHTML = new TemplateConfiguration();
tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE);
-cfg.setTemplateConfigurers(
- new ConditionalTemplateConfigurerFactory(
+cfg.setTemplateConfigurations(
+ new ConditionalTemplateConfigurationFactory(
new PathGlobMatcher("mail/**"),
tcHTML));</programlisting>
@@ -9050,10 +9050,10 @@ cfg.setTemplateConfigurers(
<literal>*.properties</literal> file (the <literal>\</literal>-s
are required for the Java Properties file format only):</para>
- <programlisting role="unspecified">templateConfigurers = \
- ConditionalTemplateConfigurerFactory( \
+ <programlisting role="unspecified">templateConfigurations = \
+ ConditionalTemplateConfigurationFactory( \
PathGlobMatcher("mail/**"), \
- TemplateConfigurer(outputFormat = HTMLOutputFormat()))</programlisting>
+ TemplateConfiguration(outputFormat = HTMLOutputFormat()))</programlisting>
</listitem>
<listitem>
@@ -9067,26 +9067,26 @@ cfg.setTemplateConfigurers(
<literal>cfg.getTemplate(<replaceable>...</replaceable>)</literal>,
and not instantiating them yourself):</para>
- <programlisting role="unspecified">TemplateConfigurer tcHTML = new TemplateConfigurer();
+ <programlisting role="unspecified">TemplateConfiguration tcHTML = new TemplateConfiguration();
tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE);
-TemplateConfigurer tcXML = new TemplateConfigurer();
+TemplateConfiguration tcXML = new TemplateConfiguration();
tcXML.setOutputFormat(XMLOutputFormat.INSTANCE);
-TemplateConfigurer tcRTF = new TemplateConfigurer();
+TemplateConfiguration tcRTF = new TemplateConfiguration();
tcRTF.setOutputFormat(RTFOutputFormat.INSTANCE);
-cfg.setTemplateConfigurers(
- new FirstMatchTemplateConfigurerFactory(
- new ConditionalTemplateConfigurerFactory(
+cfg.setTemplateConfigurations(
+ new FirstMatchTemplateConfigurationFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileExtensionMatcher("xml"),
tcXML),
- new ConditionalTemplateConfigurerFactory(
+ new ConditionalTemplateConfigurationFactory(
new OrMatcher(
new FileExtensionMatcher("html"),
new FileExtensionMatcher("htm")),
tcHTML),
- new ConditionalTemplateConfigurerFactory(
+ new ConditionalTemplateConfigurationFactory(
new FileExtensionMatcher("rtf"),
tcRTF)
).allowNoMatch(true)
@@ -9096,26 +9096,26 @@ cfg.setTemplateConfigurers(
<literal>*.properties</literal> file (the <literal>\</literal>-s
are required for the Java Properties file format only):</para>
- <programlisting role="unspecified">templateConfigurers = \
- FirstMatchTemplateConfigurerFactory( \
- ConditionalTemplateConfigurerFactory( \
+ <programlisting role="unspecified">templateConfigurations = \
+ FirstMatchTemplateConfigurationFactory( \
+ ConditionalTemplateConfigurationFactory( \
FileExtensionMatcher("xml"), \
- TemplateConfigurer(outputFormat = XMLOutputFormat())), \
- ConditionalTemplateConfigurerFactory( \
+ TemplateConfiguration(outputFormat = XMLOutputFormat())), \
+ ConditionalTemplateConfigurationFactory( \
OrMatcher( \
FileExtensionMatcher("html"), \
FileExtensionMatcher("htm")), \
- TemplateConfigurer(outputFormat = HTMLOutputFormat())), \
- ConditionalTemplateConfigurerFactory( \
+ TemplateConfiguration(outputFormat = HTMLOutputFormat())), \
+ ConditionalTemplateConfigurationFactory( \
FileExtensionMatcher("rtf"), \
- TemplateConfigurer(outputFormat = RTFOutputFormat())), \
+ TemplateConfiguration(outputFormat = RTFOutputFormat())), \
allowNoMatch = true)</programlisting>
</listitem>
</itemizedlist>
<para>(You can find some more complex
- <literal>template_configurers</literal> setups <link
- linkend="pgui_config_templateconfigurers">here...</link>)</para>
+ <literal>template_configurations</literal> setups <link
+ linkend="pgui_config_templateconfigurations">here...</link>)</para>
</section>
<section xml:id="pgui_config_custom_formats">
@@ -19091,9 +19091,9 @@ All rights reserved.</emphasis></programlisting>
included template. You shouldn't use this option anymore; if
different template use different encodings, then the programmers
should associated the encoding to the templates via
- <literal>Configuration.setTemplateConfigurers(<replaceable>...</replaceable>)</literal>-s
+ <literal>Configuration.setTemplateConfigurations(<replaceable>...</replaceable>)</literal>-s
(which also overrides that you specify here). If
- <literal>Configuration.setTemplateConfigurers(<replaceable>...</replaceable>)</literal>
+ <literal>Configuration.setTemplateConfigurations(<replaceable>...</replaceable>)</literal>
doesn't specify an encoding for the included template, then the
included file inherits the encoding (the charset) of the
top-level template, unless you specify an encoding with this
@@ -25881,11 +25881,11 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<listitem>
<para>Added new configuration setting:
- <literal>template_configurers</literal>. This allows overriding
- the settings coming from the shared
+ <literal>template_configurations</literal>. This allows
+ overriding the settings coming from the shared
<literal>Configuration</literal> object for individual
templates, based on template name patterns. <link
- linkend="pgui_config_templateconfigurers">See more
+ linkend="pgui_config_templateconfigurations">See more
here...</link></para>
</listitem>
@@ -25921,7 +25921,7 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<literal>XML</literal>, <literal>plainText</literal>, etc.)
that governs auto-escaping. The output format can be
different for different templates, using the
- <literal>template_configurers</literal> setting (<link
+ <literal>template_configurations</literal> setting (<link
linkend="pgui_config_outputformatsautoesc">see here
how...</link>).</para>
</listitem>
@@ -25997,7 +25997,7 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<literal>custom_number_formats</literal> and
<literal>custom_date_formats</literal> settings can be set
per-template (via the new
- <literal>template_configurers</literal> settings) or
+ <literal>template_configurations</literal> settings) or
per-<literal>Environment</literal> too, thus
<literal>@foo</literal> can mean something different in
different templates.</para>
@@ -26508,6 +26508,17 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
</listitem>
<listitem>
+ <para>The new <literal>TemplateConfigurer</literal> class was
+ renamed to <literal>TemplateConfiguration</literal>, and the
+ related configuration setting from
+ <literal>template_configurers</literal> to
+ <literal>template_configurations</literal>. Also, the
+ <literal>TemplateConfigurer.configure</literal> method was
+ renamed to
+ <literal>TemplateConfiguration.apply</literal>.</para>
+ </listitem>
+
+ <listitem>
<para>Bug fixed: It wasn't well defined when a Java
<literal>Iterator</literal> counts as empty. Depending on what
<literal>ObjectWrapper</literal> you are using, one of these