Repository: incubator-freemarker Updated Branches: refs/heads/2.3-gae 6819382e6 -> 0b6f0d235
Added OverrideResponseLocale to version hisotry, and some JavaDoc/Manual polish related to the new init-params. Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/0b6f0d23 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/0b6f0d23 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/0b6f0d23 Branch: refs/heads/2.3-gae Commit: 0b6f0d2357e241ad5f01babf016cdffdbe4f21e3 Parents: 6819382 Author: ddekany <ddek...@apache.org> Authored: Sun Nov 1 11:27:07 2015 +0100 Committer: ddekany <ddek...@apache.org> Committed: Sun Nov 1 11:27:36 2015 +0100 ---------------------------------------------------------------------- .../ext/servlet/FreemarkerServlet.java | 23 +++--- src/manual/book.xml | 78 +++++++++++++++----- .../ext/servlet/FreemarkerServletTest.java | 62 +++++++++------- 3 files changed, 104 insertions(+), 59 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/0b6f0d23/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 7b785d2..464be23 100644 --- a/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java +++ b/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java @@ -143,8 +143,9 @@ import freemarker.template.utility.StringUtil; * <li>If the {@value #INIT_PARAM_OVERRIDE_RESPONSE_CONTENT_TYPE} init-param is {@value #INIT_PARAM_VALUE_NEVER} (the * default is {@value #INIT_PARAM_VALUE_ALWAYS}), then the value of {@link HttpServletResponse#getContentType()} is used * if that's non-{@code null}. - * <li>The template's custom attribute name <tt>content_type</tt> in the <tt>attributes</tt> parameter of the - * <tt><#ftl></tt> directive. This is a legacy feature, deprecated by the {@link OutputFormat} mechanism. + * <li>The template's custom attribute name <tt>content_type</tt>, usually specified via the <tt>attributes</tt> + * parameter of the <tt><#ftl></tt> directive. This is a legacy feature, deprecated by the {@link OutputFormat} + * mechanism. * <li>The {@linkplain Template#getOutputFormat() output format of the template}, if that has non-{@code null} MIME-type * ({@link OutputFormat#getMimeType()}). When a template has no output format specified, {@link UndefinedOutputFormat} * is used, which has {@code null} MIME-type. (The output format of a template is deduced from {@link Configuration} @@ -157,7 +158,7 @@ import freemarker.template.utility.StringUtil; * </ol> * If none of the above gives a MIME type, then this init-param does. Defaults to <tt>"text/html"</tt>. The value may * include the charset (e.g. <tt>"text/html; charset=utf-8"</tt>). If the charset is not specified in this init-param, - * then the charset (encoding) of the actual template file will appended after it, which, as per the Servlet + * then the charset (encoding) of the actual template file will be appended after it, which, as per the Servlet * specification, also sets the actual encoding used to write the response body.</li> * * <li><strong>{@value #INIT_PARAM_OVERRIDE_RESPONSE_CONTENT_TYPE}</strong> (since 2.3.24): Specifies when we should @@ -171,10 +172,10 @@ import freemarker.template.utility.StringUtil; * {@code null}. Setting this init-param allows you to specify the content type before forwarding to * {@link FreemarkerServlet}.</li> * - * <li><strong>{@value #INIT_PARAM_OVERRIDE_RESPONSE_LOCALE}</strong> (since 2.3.24): Specifies when we should - * override the template {@code locale} that might be already set (i.e., non-{@code null}) in the {@link HttpServletRequest}. - * The default is {@value #INIT_PARAM_VALUE_ALWAYS}, which means that we always deduce the template {@code locale} - * by invoking {@link #deduceLocale(String, HttpServletRequest, HttpServletResponse)}. Another possible value is + * <li><strong>{@value #INIT_PARAM_OVERRIDE_RESPONSE_LOCALE}</strong> (since 2.3.24): Specifies if we should override + * the template {@code locale} that might be already set (i.e., non-{@code null}) in the {@link HttpServletRequest}. The + * default is {@value #INIT_PARAM_VALUE_ALWAYS}, which means that we always deduce the template {@code locale} by + * invoking {@link #deduceLocale(String, HttpServletRequest, HttpServletResponse)}. Another possible value is * {@value #INIT_PARAM_VALUE_NEVER}, which means that we don't deduce the template {@code locale}, unless * {@link HttpServletRequest#getLocale()} is {@code null}. * @@ -761,7 +762,6 @@ public class FreemarkerServlet extends HttpServlet { } Locale locale = request.getLocale(); - if (locale == null || overrideResponseLocale != OverrideResponseLocale.NEVER) { locale = deduceLocale(templatePath, request, response); } @@ -906,9 +906,10 @@ public class FreemarkerServlet extends HttpServlet { } /** - * Returns the locale used for the {@link Configuration#getTemplate(String, Locale)} call. The base implementation - * simply returns the locale setting of the configuration. Override this method to provide different behaviour, i.e. - * to use the locale indicated in the request. + * Returns the locale used for the {@link Configuration#getTemplate(String, Locale)} call (as far as the + * {@value #INIT_PARAM_OVERRIDE_RESPONSE_LOCALE} Servlet init-param allows that). The base implementation in + * {@link FreemarkerServlet} simply returns the {@code locale} setting of the configuration. Override this method to + * provide different behavior, for example, to use the locale indicated in the HTTP request. * * @param templatePath * The template path (template name) as it will be passed to {@link Configuration#getTemplate(String)}. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/0b6f0d23/src/manual/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/book.xml b/src/manual/book.xml index cf47f7a..cab5f2c 100644 --- a/src/manual/book.xml +++ b/src/manual/book.xml @@ -26038,16 +26038,35 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting> </listitem> <listitem> - <para>New <literal>FreemarkerServlet</literal> init-param: - <literal>OverrideResponseContentType</literal>. Specifies when - should we override the <literal>contentType</literal> that's - already set (i.e., non-<literal>null</literal>) in the - <literal>HttpServletResponse</literal>. Earlier, we have always - set it, and that's still the default behavior. But now that this - init-param exists, you can change that behavior, so that the - <literal>contentType</literal> you have specified before - forwarding to <literal>FreemarkerServlet</literal> - matters.</para> + <para>New <literal>FreemarkerServlet</literal> init-params (see + <link + xlink:href="http://freemarker.org/docs/api/freemarker/ext/servlet/FreemarkerServlet.html">the + <literal>FreemarkerSerlvet</literal> API documentation</link> + for details):</para> + + <itemizedlist> + <listitem> + <para><literal>OverrideResponseContentType</literal>. + Specifies when should we override the + <literal>contentType</literal> that's already set (i.e., + non-<literal>null</literal>) in the + <literal>HttpServletResponse</literal>. Earlier, we have + always set it, and that's still the default behavior. But + now that this init-param exists, you can change that + behavior, so that the <literal>contentType</literal> you + have specified before forwarding to + <literal>FreemarkerServlet</literal> matters.</para> + </listitem> + + <listitem> + <para><literal>OverrideResponseLocale</literal>. Specifies + if should we override the <literal>contentType</literal> + that's already set (i.e., non-<literal>null</literal>) in + the <literal>HttpServletResponse</literal>. Earlier, we have + always set it, but now this behavior can be changed so that + we only set it if it wasn't already set.</para> + </listitem> + </itemizedlist> </listitem> <listitem> @@ -26375,16 +26394,35 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting> </listitem> <listitem> - <para>New <literal>FreemarkerServlet</literal> init-param: - <literal>OverrideResponseContentType</literal>. Specifies when - should we override the <literal>contentType</literal> that's - already set (i.e., non-<literal>null</literal>) in the - <literal>HttpServletResponse</literal>. Earlier, we have always - set it, and that's still the default behavior. But now that this - init-param exists, you can change that behavior, so that the - <literal>contentType</literal> you have specified before - forwarding to <literal>FreemarkerServlet</literal> - matters.</para> + <para>New <literal>FreemarkerServlet</literal> init-params (see + <link + xlink:href="http://freemarker.org/docs/api/freemarker/ext/servlet/FreemarkerServlet.html">the + <literal>FreemarkerSerlvet</literal> API documentation</link> + for details):</para> + + <itemizedlist> + <listitem> + <para><literal>OverrideResponseContentType</literal>. + Specifies when should we override the + <literal>contentType</literal> that's already set (i.e., + non-<literal>null</literal>) in the + <literal>HttpServletResponse</literal>. Earlier, we have + always set it, and that's still the default behavior. But + now that this init-param exists, you can change that + behavior, so that the <literal>contentType</literal> you + have specified before forwarding to + <literal>FreemarkerServlet</literal> matters.</para> + </listitem> + + <listitem> + <para><literal>OverrideResponseLocale</literal>. Specifies + if should we override the <literal>contentType</literal> + that's already set (i.e., non-<literal>null</literal>) in + the <literal>HttpServletResponse</literal>. Earlier, we have + always set it, but now this behavior can be changed so that + we only set it if it wasn't already set.</para> + </listitem> + </itemizedlist> </listitem> <listitem> http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/0b6f0d23/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java ---------------------------------------------------------------------- diff --git a/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java b/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java index f18bbcb..fc81de9 100644 --- a/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java +++ b/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java @@ -135,34 +135,40 @@ public class FreemarkerServletTest { @Test public void testResponseLocaleInitParams() throws Exception { - // By default, the Configurable.locale is set to Locale.getDefault(). - final Locale defaultLocale = Locale.getDefault(); - - assertTemplateLocaleEquals( - defaultLocale, // <- expected template locale - null, // <- request locale - null, // <- init-param - "foo.ftl"); - assertTemplateLocaleEquals( - defaultLocale, // <- expected template locale - Locale.FRENCH, // <- request locale - null, // <- init-param - "foo.ftl"); - assertTemplateLocaleEquals( - defaultLocale, // <- expected template locale - Locale.FRENCH, // <- request locale - INIT_PARAM_VALUE_ALWAYS, // <- init-param - "foo.ftl"); - assertTemplateLocaleEquals( - defaultLocale, // <- expected template locale - null, // <- request locale - INIT_PARAM_VALUE_NEVER, // <- init-param - "foo.ftl"); - assertTemplateLocaleEquals( - Locale.FRENCH, // <- expected template locale - Locale.FRENCH, // <- request locale - INIT_PARAM_VALUE_NEVER, // <- init-param - "foo.ftl"); + Locale prevDefaultLocale = Locale.getDefault(); + Locale.setDefault(Locale.US); + try { + // By default, the Configurable.locale is set to Locale.getDefault(). + final Locale defaultLocale = Locale.getDefault(); + + assertTemplateLocaleEquals( + defaultLocale, // <- expected template locale + null, // <- request locale + null, // <- init-param + "foo.ftl"); + assertTemplateLocaleEquals( + defaultLocale, // <- expected template locale + Locale.FRENCH, // <- request locale + null, // <- init-param + "foo.ftl"); + assertTemplateLocaleEquals( + defaultLocale, // <- expected template locale + Locale.FRENCH, // <- request locale + INIT_PARAM_VALUE_ALWAYS, // <- init-param + "foo.ftl"); + assertTemplateLocaleEquals( + defaultLocale, // <- expected template locale + null, // <- request locale + INIT_PARAM_VALUE_NEVER, // <- init-param + "foo.ftl"); + assertTemplateLocaleEquals( + Locale.FRENCH, // <- expected template locale + Locale.FRENCH, // <- request locale + INIT_PARAM_VALUE_NEVER, // <- init-param + "foo.ftl"); + } finally { + Locale.setDefault(prevDefaultLocale); + } } private void assertResponseContentTypeEquals(