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 6765b587 FREEMARKER-218: Added documentation/comments
6765b587 is described below
commit 6765b5875201aa67d023125feed8d50f7525bae4
Author: ddekany <[email protected]>
AuthorDate: Tue Jan 23 10:07:43 2024 +0100
FREEMARKER-218: Added documentation/comments
---
.../freemarker/cache/WebappTemplateLoader.java | 5 ++-
.../java/freemarker/ext/jsp/EventForwarding.java | 3 ++
.../ext/jsp/FreeMarkerJspApplicationContext.java | 2 -
.../java/freemarker/ext/jsp/TaglibFactory.java | 3 ++
.../src/main/java/freemarker/ext/jsp/package.html | 4 ++
.../ext/servlet/AllHttpScopesHashModel.java | 3 ++
.../freemarker/ext/servlet/FreemarkerServlet.java | 6 ++-
.../ext/servlet/HttpRequestHashModel.java | 3 ++
.../servlet/HttpRequestParametersHashModel.java | 4 +-
.../ext/servlet/HttpSessionHashModel.java | 4 +-
.../java/freemarker/ext/servlet/IncludePage.java | 3 ++
.../ext/servlet/ServletContextHashModel.java | 3 ++
.../main/java/freemarker/ext/servlet/package.html | 4 ++
freemarker-manual/src/main/docgen/en_US/book.xml | 46 +++++++++++++++++++++-
14 files changed, 84 insertions(+), 9 deletions(-)
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/cache/WebappTemplateLoader.java
b/freemarker-javax-servlet/src/main/java/freemarker/cache/WebappTemplateLoader.java
index ddd654ff..b586b5f9 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/cache/WebappTemplateLoader.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/cache/WebappTemplateLoader.java
@@ -42,7 +42,10 @@ import freemarker.template.utility.StringUtil;
/**
* A {@link TemplateLoader} that uses streams reachable through {@link
ServletContext#getResource(String)} as its source
- * of templates.
+ * of templates.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet API; for Jakarta (that
is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.WebappTemplateLoader} instead (since
2.3.33).
*/
public class WebappTemplateLoader implements TemplateLoader {
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/EventForwarding.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/EventForwarding.java
index 493edd3b..1d3c7833 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/EventForwarding.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/EventForwarding.java
@@ -40,6 +40,9 @@ import freemarker.log.Logger;
* An instance of this class should be registered as a
<code><listener></code> in
* the {@code web.xml} descriptor in order to correctly dispatch events to
* event listeners that are specified in TLD files.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.jsp.EventForwarding} instead (since 2.3.33).
*/
public class EventForwarding
implements
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/FreeMarkerJspApplicationContext.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/FreeMarkerJspApplicationContext.java
index f83dae1b..d1ea9610 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/FreeMarkerJspApplicationContext.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/FreeMarkerJspApplicationContext.java
@@ -43,8 +43,6 @@ import javax.servlet.jsp.el.ScopedAttributeELResolver;
import freemarker.log.Logger;
import freemarker.template.utility.ClassUtil;
-/**
- */
class FreeMarkerJspApplicationContext implements JspApplicationContext {
private static final Logger LOG = Logger.getLogger("freemarker.jsp");
private static final ExpressionFactory expressionFactoryImpl =
findExpressionFactoryImplementation();
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/TaglibFactory.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/TaglibFactory.java
index 91b79790..e28057ac 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/TaglibFactory.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/TaglibFactory.java
@@ -92,6 +92,9 @@ import freemarker.template.utility.StringUtil;
* An instance of this class is made available in the root data model of
templates executed by
* {@link freemarker.ext.servlet.FreemarkerServlet} under key {@code
JspTaglibs}. It can be added to custom servlets as
* well to enable JSP taglib integration in them as well.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.jsp.TaglibFactory} instead (since 2.3.33).
*/
public class TaglibFactory implements TemplateHashModel {
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/package.html
b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/package.html
index 6a974800..f04a3d14 100644
--- a/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/package.html
+++ b/freemarker-javax-servlet/src/main/java/freemarker/ext/jsp/package.html
@@ -25,5 +25,9 @@ Classes for two-way FreeMarker-JSP integration. It contains
both a JSP
custom tag that allows embedding of FreeMarker templates inside JSP
pages, as well as the infrastructure that allows JSP custom tags to be
used inside FreeMarker templates.
+
+<p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta (that
is, in modern Servlet containers), use
+the <code>freemarker.ext.jakarta.jsp</code> package instead (since 2.3.33).
+
</body>
</html>
\ No newline at end of file
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/AllHttpScopesHashModel.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/AllHttpScopesHashModel.java
index bd74070b..70abe02b 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/AllHttpScopesHashModel.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/AllHttpScopesHashModel.java
@@ -43,6 +43,9 @@ import freemarker.template.utility.NullArgumentException;
* subclass of {@code FreemarkerServlet} that overrides
* {@code preTemplateProcess}) are discovered as "page" variables by the FM
* JSP PageContext implementation.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.AllHttpScopesHashModel} instead
(since 2.3.33).
*/
public class AllHttpScopesHashModel extends SimpleHash {
private final ServletContext context;
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
index 40ca7a47..9d165417 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
@@ -70,8 +70,10 @@ import freemarker.template.utility.StringUtil;
* FreeMarker MVC View servlet that can be used similarly to JSP views. That
is, you put the variables to expose into
* HTTP servlet request attributes, then forward to an FTL file (instead of to
a JSP file) that's mapped to this servet
* (usually via the {@code <url-pattern>*.ftl<url-pattern>}). See web.xml
example (and more) in the FreeMarker Manual!
- *
- *
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.FreemarkerServlet} instead (since
2.3.33).
+ *
* <p>
* <b>Main features</b>
* </p>
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestHashModel.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestHashModel.java
index 0b602830..806e7b5a 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestHashModel.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestHashModel.java
@@ -35,6 +35,9 @@ import freemarker.template.TemplateModelException;
/**
* TemplateHashModel wrapper for a HttpServletRequest attributes.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.HttpRequestHashModel} instead (since
2.3.33).
*/
public final class HttpRequestHashModel implements TemplateHashModelEx {
private final HttpServletRequest request;
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestParametersHashModel.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestParametersHashModel.java
index f1d8f41f..a2cf3946 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestParametersHashModel.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpRequestParametersHashModel.java
@@ -34,8 +34,10 @@ import freemarker.template.TemplateModel;
/**
* TemplateHashModel wrapper for a HttpServletRequest parameters.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.HttpRequestParametersHashModel}
instead (since 2.3.33).
*/
-
public class HttpRequestParametersHashModel
implements
TemplateHashModelEx {
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpSessionHashModel.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpSessionHashModel.java
index c3bf0fc9..fd2b7f27 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpSessionHashModel.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/HttpSessionHashModel.java
@@ -32,8 +32,10 @@ import freemarker.template.TemplateModelException;
/**
* TemplateHashModel wrapper for a HttpSession attributes.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.HttpSessionHashModel} instead (since
2.3.33).
*/
-
public final class HttpSessionHashModel implements TemplateHashModel,
Serializable {
private static final long serialVersionUID = 1L;
private transient HttpSession session;
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/IncludePage.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/IncludePage.java
index 2f2b5be2..36608c5e 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/IncludePage.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/IncludePage.java
@@ -58,6 +58,9 @@ import freemarker.template.utility.DeepUnwrap;
* means that the include inherits the request parameters from the current
* request. In this case values in 'params' will get prepended to the existing
* values of parameters.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.IncludePage} instead (since 2.3.33).
*/
public class IncludePage implements TemplateDirectiveModel {
private final HttpServletRequest request;
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/ServletContextHashModel.java
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/ServletContextHashModel.java
index 88c72530..a63e2706 100644
---
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/ServletContextHashModel.java
+++
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/ServletContextHashModel.java
@@ -29,6 +29,9 @@ import freemarker.template.TemplateModelException;
/**
* TemplateHashModel wrapper for a ServletContext attributes.
+ *
+ * <p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta
(that is, in modern Servlet containers), use
+ * {@code freemarker.ext.jakarta.servlet.ServletContextHashModel} instead
(since 2.3.33).
*/
public final class ServletContextHashModel implements TemplateHashModel {
private final GenericServlet servlet;
diff --git
a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/package.html
b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/package.html
index 707a05c3..9f610666 100644
--- a/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/package.html
+++ b/freemarker-javax-servlet/src/main/java/freemarker/ext/servlet/package.html
@@ -21,5 +21,9 @@
<p>Servlet for legacy "Model 2" frameworks that allows using FreeMarker
templates instead of JSP as the MVC View
(see <a href="https://freemarker.apache.org/docs/pgui_misc_servlet.html";
target="_blank">in the Manual</a>).</p>
+
+<p>Note that this is for the legacy "javax" Servlet/JSP API; for Jakarta (that
is, in modern Servlet containers), use
+the <code>freemarker.ext.jakarta.servlet</code> package instead (since 2.3.33).
+
</body>
</html>
diff --git a/freemarker-manual/src/main/docgen/en_US/book.xml
b/freemarker-manual/src/main/docgen/en_US/book.xml
index dfeadb1e..06fa9f9e 100644
--- a/freemarker-manual/src/main/docgen/en_US/book.xml
+++ b/freemarker-manual/src/main/docgen/en_US/book.xml
@@ -11589,6 +11589,10 @@ TemplateHashModel roundingModeEnums =
<primary>Struts</primary>
</indexterm>
+ <indexterm>
+ <primary>Jakarta</primary>
+ </indexterm>
+
<indexterm>
<primary>Web application framework</primary>
</indexterm>
@@ -11612,6 +11616,18 @@ TemplateHashModel roundingModeEnums =
then read on. For other frameworks please refer to the documentation
of the framework.</para>
+ <note>
+ <para>FreeMarker supports both traditional <quote>javax</quote>
+ Servet/JSP, and Jakarta Servlet/JSP. However, you have to use a
+ different Java package for them:
+ <literal>freemarker.ext.servet</literal>, and
+ <literal>freemarker.ext.jsp</literal> for <quote>javax</quote>, and
+ <literal>freemarker.ext.jakarta.servet</literal>, and
+ <literal>freemarker.ext.jakarta.jsp</literal> for Jakarta. On modern
+ Servlet containers you must use the Jakarta packages, while on older
+ ones you must use the non-Jakarte packages.</para>
+ </note>
+
<section xml:id="pgui_misc_servlet_model2">
<title>Using FreeMarker for <quote>Model 2</quote></title>
@@ -11653,7 +11669,9 @@ TemplateHashModel roundingModeEnums =
<programlisting role="unspecified"><servlet>
<servlet-name>freemarker</servlet-name>
+
<servlet-class><emphasis>freemarker.ext.servlet.FreemarkerServlet</emphasis></servlet-class>
+ <!-- Or
freemarker.ext.<emphasis>jakarta</emphasis>.servlet.FreemarkerServlet! -->
<!--
Init-param documentation:
@@ -12162,6 +12180,7 @@ ${bar?trim}</programlisting>
<programlisting role="unspecified"><listener>
<listener-class>freemarker.ext.jsp.EventForwarding</listener-class>
+ <!-- Or freemarker.ext.<emphasis>jakarta</emphasis>.jsp.EventForwarding!
-->
</listener></programlisting>
<para>Note that you can use JSP taglibs with FreeMarker even if the
@@ -29280,8 +29299,9 @@ End book</programlisting>
<para>If the FreeMarker support of the Web Application Framework
is based on
- <literal>freemarker.ext.servlet.FreemarkerServlet</literal>, then
- you can also do this (since FreeMarker 2.3.15):</para>
+ <literal>freemarker.ext.servlet.FreemarkerServlet</literal>
+
(<literal>freemarker.ext.jakarta.servlet.FreemarkerServlet</literal>),
+ then you can also do this (since FreeMarker 2.3.15):</para>
<programlisting role="template"><@include_page
path="/WEB-INF/just-an-example.jspf" /></programlisting>
@@ -30245,6 +30265,28 @@ TemplateModel x = env.getVariable("x"); // get
variable x</programlisting>
for each <literal>FMParser</literal> instance.</para>
</listitem>
+ <listitem>
+ <para><link
+
xlink:href="https://issues.apache.org/jira/browse/FREEMARKER-218";>FREEMARKER-218</link>:
+ Servlet, and JSP support classes now has a Jakarta variant in
+ the new <literal>freemarker.ext.jakarta.jsp</literal> and
+ <literal>freemarker.ext.jakarta.servlet</literal> packages.
+ These are the slightly modified copies of
+ <literal>freemarker.ext.servlet</literal>,
+ <literal>freemarker.ext.jsp</literal> (which are also present in
+ the same FreeMarker jar), that depend on the Jakarata API-s
+ (<literal>jakarta.servlet</literal>,
+ <literal>jakarta.servlet.jsp</literal>,
+ <literal>jakarta.el</literal>, etc.), instead of the tradition
+ <literal>javax</literal> Serlvet/JSP/EL API-s. There's also
+
<literal>freemarker.ext.jakarta.servlet.WebappTemplateLoader</literal>,
+ which is the Jakarta equivalent of
+ <literal>freemarker.cache.WebappTemplateLoader</literal>. (Note
+ that Jakarta packages/classes are not visible in the FreeMarker
+ source code, as they are generated during build from the
+ pre-Jakarta classes.)</para>
+ </listitem>
+
<listitem>
<para>When <literal>FreemarkerServlet</literal> was used with
the <literal>TemplateExceptionHandler.DEBUG_HANDLER</literal> or
