This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git
The following commit(s) were added to refs/heads/2.3-gae by this push:
new 3af7fe35 Some Javadoc improvements related to
incompatible_improvements and the object_wrapper setting
3af7fe35 is described below
commit 3af7fe3511e8db64a860305a69e8c41d610914ef
Author: ddekany <[email protected]>
AuthorDate: Thu Mar 14 09:44:20 2024 +0100
Some Javadoc improvements related to incompatible_improvements and the
object_wrapper setting
---
.../main/java/freemarker/core/Configurable.java | 16 +++++++++--
.../java/freemarker/ext/beans/BeansWrapper.java | 17 +++++++----
.../java/freemarker/template/Configuration.java | 33 ++++++++++++++--------
3 files changed, 47 insertions(+), 19 deletions(-)
diff --git a/freemarker-core/src/main/java/freemarker/core/Configurable.java
b/freemarker-core/src/main/java/freemarker/core/Configurable.java
index 6eaf8eda..63b7e85c 100644
--- a/freemarker-core/src/main/java/freemarker/core/Configurable.java
+++ b/freemarker-core/src/main/java/freemarker/core/Configurable.java
@@ -1460,8 +1460,20 @@ public class Configurable {
}
/**
- * Sets the object wrapper used to wrap objects to {@link TemplateModel}-s.
- * The default is {@link ObjectWrapper#DEFAULT_WRAPPER}.
+ * Sets the {@link ObjectWrapper} used to wrap objects to {@link
TemplateModel}-s when using this
+ * {@link Configurable}.
+ *
+ * <p>On {@link Configuration} level, the default is a {@link
DefaultObjectWrapper} instance with the same
+ * {@link Configuration#setIncompatibleImprovements
incompatible_improvements} setting value as of the
+ * {@link Configuration}. (Also, with very low incompatible improvements
it's
+ * {@link ObjectWrapper#DEFAULT_WRAPPER}.). Untill you called this method,
the default value will be
+ * automatically replaced when {@link
Configuration#setIncompatibleImprovements(Version)} is called, to follow
+ * the value of the {@code incompatible_improvements} setting.
+ *
+ * <p>Below {@link Configuration} level it's usually unset, so we fall
back to
+ * what's coming from {@link Configuration}.
+ *
+ * @param objectWrapper Not null.
*/
public void setObjectWrapper(ObjectWrapper objectWrapper) {
NullArgumentException.check("objectWrapper", objectWrapper);
diff --git
a/freemarker-core/src/main/java/freemarker/ext/beans/BeansWrapper.java
b/freemarker-core/src/main/java/freemarker/ext/beans/BeansWrapper.java
index 0e202662..3962bf9f 100644
--- a/freemarker-core/src/main/java/freemarker/ext/beans/BeansWrapper.java
+++ b/freemarker-core/src/main/java/freemarker/ext/beans/BeansWrapper.java
@@ -226,10 +226,13 @@ public class BeansWrapper implements RichObjectWrapper,
WriteProtectable {
* 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 version
- * numbers are technically independent. But it's recommended to keep
those two version numbers the same.
- *
- * <p>The changes enabled by {@code incompatibleImprovements} are:
+ * {@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. Actually,
+ * if you leave the {@link Configuration#setObjectWrapper(ObjectWrapper)
object_wrapper} setting at its default
+ * (and most do), then that will be kept the same as of the {@link
Configuration}.
+ *
+ * <p>The changes enabled by {@code incompatibleImprovements} are (but
also check the changes at
+ * {@link DefaultObjectWrapper#DefaultObjectWrapper(Version)}, if you
are using {@link DefaultObjectWrapper}):
* <ul>
* <li>
* <p>2.3.0: No changes; this is the starting point, the version
used in older projects.
@@ -268,7 +271,7 @@ public class BeansWrapper implements RichObjectWrapper,
WriteProtectable {
* <p>2.3.33 (or higher):
* The default of {@link
BeansWrapper#setRecordZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy)}
* has changed to {@link
ZeroArgumentNonVoidMethodPolicy#BOTH_PROPERTY_AND_METHOD}, from
- * {@link ZeroArgumentNonVoidMethodPolicy#METHOD_ONLY}. This means
that Java records public methods with
+ * {@link ZeroArgumentNonVoidMethodPolicy#METHOD_ONLY}. This means
that Java record public methods with
* 0-arguments and non-void return type are now exposed both as
properties, and as methods, while earlier they
* were only exposed as methods. That is, if in a record you have
{@code public String name()}, now in
* templates the value can be accessed both as {@code obj.name}
(like a property), and as {@code obj.name()}
@@ -280,6 +283,10 @@ public class BeansWrapper implements RichObjectWrapper,
WriteProtectable {
* {@link BeansWrapper} improvements were already present, so {@link
#getIncompatibleImprovements()} might return
* a lower version than what you have specified.
*
+ * <p>Note again that most projects use {@link DefaultObjectWrapper}
(which extends {@link BeansWrapper}), in
+ * which case see the additional changes at {@link
DefaultObjectWrapper#DefaultObjectWrapper(Version)}!
+ * </p>
+ *
* @since 2.3.21
*/
public BeansWrapper(Version incompatibleImprovements) {
diff --git
a/freemarker-core/src/main/java/freemarker/template/Configuration.java
b/freemarker-core/src/main/java/freemarker/template/Configuration.java
index 97a22cb3..d08f815f 100644
--- a/freemarker-core/src/main/java/freemarker/template/Configuration.java
+++ b/freemarker-core/src/main/java/freemarker/template/Configuration.java
@@ -619,9 +619,9 @@ public class Configuration extends Configurable implements
Cloneable, ParserConf
* <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>Do NOT ever use {@link #getVersion()} to set the "incompatible
improvements". Always use a fixed value, like
- * {@link #VERSION_2_3_30}. Otherwise your application can break as you
upgrade FreeMarker. (As of 2.3.30, doing
- * this will be logged as an error. As of 2.4.0, it will be probably
disallowed, by throwing exception.)
+ * <p><b>Do NOT ever use {@link #getVersion()} to set the "incompatible
improvements". Always use a fixed value</b>,
+ * like {@link #VERSION_2_3_33}. Otherwise, your application can break as
you upgrade FreeMarker. (As of 2.3.30,
+ * doing this will be logged as an error. As of 2.4.0, it will be probably
disallowed, by throwing exception.)
*
* <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
2.3.22, but accidentally the application
@@ -630,7 +630,12 @@ public class Configuration extends Configurable implements
Cloneable, ParserConf
*
* <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.
+ * won't bring back the old behavior anymore. Information about that will
be present here.
+ *
+ * <p>Note that {@link DefaultObjectWrapper} (and {@link BeansWrapper},
which it extends) has its own "incompatible
+ * improvements" setting (see {@link
DefaultObjectWrapper#DefaultObjectWrapper(Version)}), but if you leave the
+ * {@link #setObjectWrapper(ObjectWrapper) object_wrapper} setting at its
default (and most do), then that will be
+ * kept the same as of the {@link Configuration}.
*
* <p>Currently the effects of this setting are:
* <ul>
@@ -892,16 +897,16 @@ public class Configuration extends Configurable
implements Cloneable, ParserConf
* 2.3.26 (or higher):
* <ul>
* <li><p>
- * {@link BeansWrapper} and {@link DefaultObjectWrapper} now
exposes Java 8 default methods (and the bean
- * properties they define); see {@link
BeansWrapper#BeansWrapper(Version)}.
+ * The default {@link
Configuration#setObjectWrapper(ObjectWrapper) object_wrapper} now exposes Java
+ * 8 default methods (and the bean properties they define); see
{@link BeansWrapper#BeansWrapper(Version)}.
* </ul>
* </li>
* <li><p>
* 2.3.27 (or higher):
* <ul>
* <li><p>
- * {@link BeansWrapper} and {@link DefaultObjectWrapper} now
prefers the non-indexed JavaBean property
- * read method over the indexed read method when Java 8 exposes
both;
+ * The default {@link
Configuration#setObjectWrapper(ObjectWrapper) object_wrapper} now prefers the
+ * non-indexed JavaBean property read method over the indexed
read method when Java 8 exposes both;
* see {@link BeansWrapper#BeansWrapper(Version)}.
* <li><p>
* The following unchecked exceptions (but not their subclasses)
will be wrapped into
@@ -978,7 +983,7 @@ public class Configuration extends Configurable implements
Cloneable, ParserConf
* <p>
* 2.3.33 (or higher):
* <ul>
- * <li><p>Comparing strings is now way faster. If your template
does lot of string comparisons, this can
+ * <li><p>Comparing strings is now way faster. If your template
does lot of string comparisons, this can
* mean very significant speedup. We now use a simpler way of
comparing strings, and because templates
* were only ever allowed equality comparisons between strings
(not less-than, or greater-than), it's very
* unlikely to change the behavior of your templates.
(Technically, what changes is that instead of using
@@ -986,7 +991,11 @@ public class Configuration extends Configurable implements
Cloneable, ParserConf
* normalization. So, in theory it's possible that for some
locales two different but similarly looking
* characters were treated as equal by the collator, but will
count as different now. But it's very
* unlikely that anyone wanted to depend on such fragile logic
anyway. Note again that we still do UNICODE
- * normalization, so combining characters won't break your
comparison.)</p></li>
+ * normalization, so combining characters won't break your
comparisons.)</p></li>
+ * <li><p>
+ * The default {@link
Configuration#setObjectWrapper(ObjectWrapper) object_wrapper} now exposes Java
+ * records public methods with 0-arguments and non-void return
type are now exposed both as properties,
+ * and as methods; see {@link BeansWrapper#BeansWrapper(Version)}.
* </ul>
* </li>
* </ul>
@@ -1991,8 +2000,8 @@ public class Configuration extends Configurable
implements Cloneable, ParserConf
/**
* Use {@link #Configuration(Version)} instead if possible; see the
meaning of the parameter there.
*
- * <p>Do NOT ever use {@link #getVersion()} to set the "incompatible
improvements". Always use a fixed value, like
- * {@link #VERSION_2_3_30}. Otherwise your application can break as you
upgrade FreeMarker. (As of 2.3.30, doing
+ * <p><b>Do NOT ever use {@link #getVersion()} to set the "incompatible
improvements"! Always use a fixed value</b>,
+ * like {@link #VERSION_2_3_30}. Otherwise, your application can break as
you upgrade FreeMarker. (As of 2.3.30, doing
* this will be logged as an error. As of 2.4.0, it will be probably
disallowed, by throwing exception.)
*
* <p>If the default value of a setting depends on the {@code
incompatibleImprovements} and the value of that setting
