Mailing-List: contact notifications-help@freemarker.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@freemarker.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: ddekany@apache.org
To: notifications@freemarker.incubator.apache.org
Date: Sun, 12 Jun 2016 16:54:13 -0000
Message-Id: <09cfb232c5c04b44ba391b1276df2a46@git.apache.org>
In-Reply-To: <a911f579a4be4b33907d6d6cc7e7a175@git.apache.org>
References: <a911f579a4be4b33907d6d6cc7e7a175@git.apache.org>
Subject: [32/50] incubator-freemarker git commit: Added
 Configurable.getCustomNumberFormatsWithoutFallback and
 Configurable.getCustomDateFormatsWithoutFallback methods to make it easier
 for custom code to investigate the Map hierarchy. Improved JavaDoc of the rel
archived-at: Sun, 12 Jun 2016 16:53:51 -0000

Added Configurable.getCustomNumberFormatsWithoutFallback and Configurable.getCustomDateFormatsWithoutFallback methods to make it easier for custom code to investigate the Map hierarchy. Improved JavaDoc of the related getters.


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/2b564880
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/2b564880
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/2b564880

Branch: refs/heads/2.3
Commit: 2b56488043930b7dc3be1144dac9ed6e23b9582f
Parents: 964757b
Author: ddekany <ddekany@apache.org>
Authored: Wed Jun 8 00:57:02 2016 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Wed Jun 8 00:57:02 2016 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/Configurable.java | 55 ++++++++++++++++++--
 src/manual/en_US/book.xml                       |  9 ++++
 2 files changed, 61 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/2b564880/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index 18e6fcd..f5776cc 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -791,13 +791,35 @@ public class Configurable {
     }
     
     /**
-     * Getter pair of {@link #setCustomNumberFormats(Map)};  do not modify the returned {@link Map}!
+     * Getter pair of {@link #setCustomNumberFormats(Map)}; do not modify the returned {@link Map}! To be consistent
+     * with other setting getters, if this setting was set directly on this {@link Configurable} object, this simply
+     * returns that value, otherwise it returns the value from the parent {@link Configurable}. So beware, the returned
+     * value doesn't reflect the {@link Map} key granularity fallback logic that FreeMarker actually uses for this
+     * setting (for that, use {@link #getCustomNumberFormat(String)}). The returned value isn't a snapshot; it may or
+     * may not shows the changes later made to this setting on this {@link Configurable} level (but usually it's well
+     * defined if until what point settings are possibly modified).
+     * 
+     * <p>
+     * The return value is never {@code null}; called on the {@link Configuration} (top) level, it defaults to an empty
+     * {@link Map}.
+     * 
+     * @see #getCustomNumberFormatsWithoutFallback()
      * 
      * @since 2.3.24
      */
     public Map<String, ? extends TemplateNumberFormatFactory> getCustomNumberFormats() {
         return customNumberFormats == null ? parent.getCustomNumberFormats() : customNumberFormats;
     }
+
+    /**
+     * Like {@link #getCustomNumberFormats()}, but doesn't fall back to the parent {@link Configurable}, nor does it
+     * provide a non-{@code null} default when called as the method of a {@link Configuration}.
+     * 
+     * @since 2.3.25
+     */
+    public Map<String, ? extends TemplateNumberFormatFactory> getCustomNumberFormatsWithoutFallback() {
+        return customNumberFormats;
+    }
     
     /**
      * Associates names with formatter factories, which then can be referred by the {@link #setNumberFormat(String)
@@ -843,6 +865,8 @@ public class Configurable {
     }
 
     /**
+     * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
+     *  
      * @since 2.3.24
      */
     public boolean isCustomNumberFormatsSet() {
@@ -1166,7 +1190,19 @@ public class Configurable {
     }
     
     /**
-     * Getter pair of {@link #setCustomDateFormats(Map)}; do not modify the returned {@link Map}!
+     * Getter pair of {@link #setCustomDateFormats(Map)}; do not modify the returned {@link Map}! To be consistent with
+     * other setting getters, if this setting was set directly on this {@link Configurable} object, this simply returns
+     * that value, otherwise it returns the value from the parent {@link Configurable}. So beware, the returned value
+     * doesn't reflect the {@link Map} key granularity fallback logic that FreeMarker actually uses for this setting
+     * (for that, use {@link #getCustomDateFormat(String)}). The returned value isn't a snapshot; it may or may not
+     * shows the changes later made to this setting on this {@link Configurable} level (but usually it's well defined if
+     * until what point settings are possibly modified).
+     * 
+     * <p>
+     * The return value is never {@code null}; called on the {@link Configuration} (top) level, it defaults to an empty
+     * {@link Map}.
+     * 
+     * @see #getCustomDateFormatsWithoutFallback()
      * 
      * @since 2.3.24
      */
@@ -1175,6 +1211,16 @@ public class Configurable {
     }
 
     /**
+     * Like {@link #getCustomDateFormats()}, but doesn't fall back to the parent {@link Configurable}, nor does it
+     * provide a non-{@code null} default when called as the method of a {@link Configuration}.
+     * 
+     * @since 2.3.25
+     */
+    public Map<String, ? extends TemplateDateFormatFactory> getCustomDateFormatsWithoutFallback() {
+        return customDateFormats;
+    }
+    
+    /**
      * Associates names with formatter factories, which then can be referred by the {@link #setDateTimeFormat(String)
      * date_format}, {@link #setDateTimeFormat(String) time_format}, and {@link #setDateTimeFormat(String)
      * datetime_format} settings with values starting with <code>@<i>name</i></code>. Beware, if you specify any custom
@@ -1196,6 +1242,8 @@ public class Configurable {
     }
     
     /**
+     * Tells if this setting is set directly in this object or its value is coming from the {@link #getParent() parent}.
+     * 
      * @since 2.3.24
      */
     public boolean isCustomDateFormatsSet() {
@@ -1620,7 +1668,8 @@ public class Configurable {
      * key is the {@code namespaceVarName}). The order of the auto-imports will be the same as {@link Map#keySet()}
      * returns the keys (but the order of imports doesn't mater for properly designed libraries anyway).
      * 
-     * @param map Maps the namepsace variable names to the template names; not {@code null}
+     * @param map
+     *            Maps the namespace variable names to the template names; not {@code null}
      */
     public void setAutoImports(Map map) {
         NullArgumentException.check("map", map);

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/2b564880/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index 6d56358..cefae69 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -26649,6 +26649,15 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
             </listitem>
 
             <listitem>
+              <para>Added
+              <literal>Configurable.getCustomNumberFormatsWithoutFallback</literal>
+              and
+              <literal>Configurable.getCustomDateFormatsWithoutFallback</literal>
+              methods to make it easier for custom code to investigate the
+              <literal>Map</literal> hierarchy.</para>
+            </listitem>
+
+            <listitem>
               <para>Bug fixed (<link
               xlink:href="https://issues.apache.org/jira/browse/FREEMARKER-18">FREEMARKER-18</link>):
               If you had a JSP custom tag and an EL function defined in the