Skip to content

Commit

Permalink
FREEMARKER-218: Added documentation/comments
Browse files Browse the repository at this point in the history
  • Loading branch information
ddekany committed Jan 23, 2024
1 parent babdccb commit 6765b58
Show file tree
Hide file tree
Showing 14 changed files with 84 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,10 @@

/**
* 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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@
* An instance of this class should be registered as a <code>&lt;listener&gt;</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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,6 @@
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();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,9 @@
* 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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,9 @@
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>
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@
* 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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,10 @@
* 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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@

/**
* 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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@

/**
* 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 {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,10 @@

/**
* 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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,9 @@
* 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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@

/**
* 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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
46 changes: 44 additions & 2 deletions freemarker-manual/src/main/docgen/en_US/book.xml
Original file line number Diff line number Diff line change
Expand Up @@ -11589,6 +11589,10 @@ TemplateHashModel roundingModeEnums =
<primary>Struts</primary>
</indexterm>

<indexterm>
<primary>Jakarta</primary>
</indexterm>

<indexterm>
<primary>Web application framework</primary>
</indexterm>
Expand All @@ -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>

Expand Down Expand Up @@ -11653,7 +11669,9 @@ TemplateHashModel roundingModeEnums =

<programlisting role="unspecified">&lt;servlet&gt;
&lt;servlet-name&gt;freemarker&lt;/servlet-name&gt;

&lt;servlet-class&gt;<emphasis>freemarker.ext.servlet.FreemarkerServlet</emphasis>&lt;/servlet-class&gt;
&lt;!-- Or freemarker.ext.<emphasis>jakarta</emphasis>.servlet.FreemarkerServlet! --&gt;

&lt;!--
Init-param documentation:
Expand Down Expand Up @@ -12162,6 +12180,7 @@ ${bar?trim}</programlisting>

<programlisting role="unspecified">&lt;listener&gt;
&lt;listener-class&gt;freemarker.ext.jsp.EventForwarding&lt;/listener-class&gt;
&lt;!-- Or freemarker.ext.<emphasis>jakarta</emphasis>.jsp.EventForwarding! --&gt;
&lt;/listener&gt;</programlisting>

<para>Note that you can use JSP taglibs with FreeMarker even if the
Expand Down Expand Up @@ -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">&lt;@include_page path="/WEB-INF/just-an-example.jspf" /&gt;</programlisting>

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 6765b58

Please sign in to comment.