Some Javadoc improvements related to incompatible_improvements and the object_wrapper setting
diff --git a/freemarker-core/src/main/java/freemarker/core/Configurable.java b/freemarker-core/src/main/java/freemarker/core/Configurable.java
index 6eaf8ed..63b7e85 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 @@
}
/**
- * 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 0e20266..3962bf9 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 @@
* 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 @@
* <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 @@
* {@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 97a22cb..d08f815 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 @@
* <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 @@
*
* <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 @@
* 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 @@
* <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 @@
* 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 @@
/**
* 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
