You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2016/03/26 16:20:02 UTC
[16/30] incubator-freemarker git commit: (JavaDoc refinements)
(JavaDoc refinements)
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/6b51f59d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/6b51f59d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/6b51f59d
Branch: refs/heads/2.3-gae
Commit: 6b51f59d54f149d655fcf912908e28af5e6eecb3
Parents: 416667c
Author: ddekany <dd...@apache.org>
Authored: Mon Feb 15 00:25:08 2016 +0100
Committer: ddekany <dd...@apache.org>
Committed: Mon Feb 15 00:25:08 2016 +0100
----------------------------------------------------------------------
.../freemarker/cache/WebappTemplateLoader.java | 2 +-
.../core/CommonTemplateMarkupOutputModel.java | 9 ++++---
.../freemarker/core/MarkupOutputFormat.java | 26 ++++++++++++++------
src/main/java/freemarker/core/OutputFormat.java | 2 +-
.../core/TemplateMarkupOutputModel.java | 21 +++++++++-------
.../java/freemarker/template/Configuration.java | 24 ++++++++++++------
.../java/freemarker/core/OutputFormatTest.java | 2 +-
7 files changed, 56 insertions(+), 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/cache/WebappTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/WebappTemplateLoader.java b/src/main/java/freemarker/cache/WebappTemplateLoader.java
index d4f32dc..44c40df 100644
--- a/src/main/java/freemarker/cache/WebappTemplateLoader.java
+++ b/src/main/java/freemarker/cache/WebappTemplateLoader.java
@@ -51,7 +51,7 @@ public class WebappTemplateLoader implements TemplateLoader {
private boolean attemptFileAccess = true;
/**
- * Creates a resource template cache that will use the specified servlet context to load the resources. It will use
+ * Creates a template loader that will use the specified servlet context to load the resources. It will use
* the base path of <code>"/"</code> meaning templates will be resolved relative to the servlet context root
* location.
*
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/core/CommonTemplateMarkupOutputModel.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/CommonTemplateMarkupOutputModel.java b/src/main/java/freemarker/core/CommonTemplateMarkupOutputModel.java
index 9d04428..3f1a43e 100644
--- a/src/main/java/freemarker/core/CommonTemplateMarkupOutputModel.java
+++ b/src/main/java/freemarker/core/CommonTemplateMarkupOutputModel.java
@@ -45,17 +45,20 @@ public abstract class CommonTemplateMarkupOutputModel<MO extends CommonTemplateM
public abstract CommonMarkupOutputFormat<MO> getOutputFormat();
- /** Maybe {@code null}, but then the other field isn't {@code null}. */
+ /** Maybe {@code null}, but then {@link #getMarkupContent()} isn't {@code null}. */
final String getPlainTextContent() {
return plainTextContent;
}
- /** Maybe {@code null}, but then the other field isn't {@code null}. */
+ /** Maybe {@code null}, but then {@link #getPlainTextContent()} isn't {@code null}. */
final String getMarkupContent() {
return markupContet;
}
- /** Use only to set {@code null} field to the value calculated from the other field! */
+ /**
+ * Use only to set the value calculated from {@link #getPlainTextContent()}, when {@link #getMarkupContent()} was
+ * still {@code null}!
+ */
final void setMarkupContet(String markupContet) {
this.markupContet = markupContet;
}
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/core/MarkupOutputFormat.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/MarkupOutputFormat.java b/src/main/java/freemarker/core/MarkupOutputFormat.java
index 0f1302c..b058591 100644
--- a/src/main/java/freemarker/core/MarkupOutputFormat.java
+++ b/src/main/java/freemarker/core/MarkupOutputFormat.java
@@ -21,13 +21,23 @@ package freemarker.core;
import java.io.IOException;
import java.io.Writer;
+import freemarker.template.Configuration;
import freemarker.template.TemplateModelException;
/**
- * An {@link OutputFormat}-s that represent a "markup", which is any format where certain character sequences have
- * special meaning and thus may need escaping. (Escaping is important for FreeMarker, as typically it has to insert
- * non-markup text from the data-model into the output markup.) This class, among others, defines the operations related
- * to {@link TemplateMarkupOutputModel}-s that belong to the output format.
+ * Superclass of {@link OutputFormat}-s that represent a "markup" format, which is any format where certain character
+ * sequences have special meaning and thus may need escaping. (Escaping is important for FreeMarker, as typically it has
+ * to insert non-markup text from the data-model into the output markup. See also:
+ * {@link Configuration#setOutputFormat(OutputFormat)}.)
+ *
+ * <p>
+ * An {@link OutputFormat} subclass always has a corresponding {@link TemplateMarkupOutputModel} subclass pair (like
+ * {@link HTMLOutputFormat} has {@link TemplateHTMLOutputModel}). The {@link OutputFormat} implements the operations
+ * related to {@link TemplateMarkupOutputModel} objects of that kind, while the {@link TemplateMarkupOutputModel} only
+ * encapsulates the data (the actual markup or text).
+ *
+ * <p>
+ * To implement a custom output format, you may want to extend {@link CommonMarkupOutputFormat}.
*
* @param <MO>
* The {@link TemplateMarkupOutputModel} class this output format can deal with.
@@ -105,15 +115,17 @@ public abstract class MarkupOutputFormat<MO extends TemplateMarkupOutputModel> e
public abstract boolean isEmpty(MO mo) throws TemplateModelException;
/**
- * Tells if a string built-in that can't handle a {@link TemplateMarkupOutputModel} left operand can bypass this
- * object as is. A typical such case would be when a {@link TemplateHTMLOutputModel} of "HTML" format bypasses
+ * Tells if a string built-in that can't handle a {@link TemplateMarkupOutputModel} left hand operand can bypass
+ * this object as is. A typical such case would be when a {@link TemplateHTMLOutputModel} of "HTML" format bypasses
* {@code ?html}.
*/
public abstract boolean isLegacyBuiltInBypassed(String builtInName) throws TemplateModelException;
/**
* Tells if by default auto-escaping should be on for this format. It should be {@code true} if you need to escape
- * on most of the places where you insert values.
+ * on most of the places where you insert values.
+ *
+ * @see Configuration#setAutoEscapingPolicy(int)
*/
public abstract boolean isAutoEscapedByDefault();
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/core/OutputFormat.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/OutputFormat.java b/src/main/java/freemarker/core/OutputFormat.java
index 72ea821..5f4bc60 100644
--- a/src/main/java/freemarker/core/OutputFormat.java
+++ b/src/main/java/freemarker/core/OutputFormat.java
@@ -23,7 +23,7 @@ import freemarker.template.utility.ClassUtil;
import freemarker.template.utility.StringUtil;
/**
- * Represents an output format.
+ * Represents an output format. If you need auto-escaping, see its subclass, {@link MarkupOutputFormat}.
*
* @see Configuration#setOutputFormat(OutputFormat)
* @see Configuration#setRegisteredCustomOutputFormats(java.util.Collection)
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateMarkupOutputModel.java b/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
index 3606379..3beead0 100644
--- a/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
+++ b/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
@@ -18,23 +18,23 @@
*/
package freemarker.core;
-import freemarker.template.Configuration;
import freemarker.template.TemplateModel;
import freemarker.template.TemplateScalarModel;
/**
* "markup output" template language data-type; stores markup (some kind of "rich text" / structured format, as opposed
- * to plain text) that meant to be printed as template output. Each implementation of this type has a
- * {@link OutputFormat} subclass pair (like {@link TemplateHTMLOutputModel} has {@link HTMLOutputFormat}). This type is
- * related to the {@link Configuration#setOutputFormat(OutputFormat)} and
- * {@link Configuration#setAutoEscapingPolicy(int)} mechanism; see more there. Values of this type are exempt from
- * automatic escaping with that mechanism.
+ * to plain text) that meant to be printed as template output. This type is related to the {@link OutputFormat}
+ * mechanism. Values of this kind are exempt from {@link OutputFormat}-based automatic escaping.
*
* <p>
- * Note that {@link TemplateMarkupOutputModel}-s are by design not handled like {@link TemplateScalarModel}-s, and so
+ * Each implementation of this type has a {@link OutputFormat} subclass pair, whose singleton instance is returned by
+ * {@link #getOutputFormat()}. See more about how markup output values work at {@link OutputFormat}.
+ *
+ * <p>
+ * Note that {@link TemplateMarkupOutputModel}-s are by design not treated like {@link TemplateScalarModel}-s, and so
* the implementations of this interface usually shouldn't implement {@link TemplateScalarModel}. (Because, operations
- * applicable on plain strings, like converting to upper case, substringing, etc., can corrupt markup.) The template
- * author should make conscious decision of passing in the markup as String by using {@code ?markup_string}.
+ * applicable on plain strings, like converting to upper case, substringing, etc., can corrupt markup.) If the template
+ * author wants to pass in the "source" of the markup as string somewhere, he should use {@code ?markup_string}.
*
* @param <MO>
* Refers to the interface's own type, which is useful in interfaces that extend
@@ -44,6 +44,9 @@ import freemarker.template.TemplateScalarModel;
*/
public interface TemplateMarkupOutputModel<MO extends TemplateMarkupOutputModel<MO>> extends TemplateModel {
+ /**
+ * Returns the singleton {@link OutputFormat} object that implements the operations for the "markup output" value.
+ */
MarkupOutputFormat<MO> getOutputFormat();
}
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/main/java/freemarker/template/Configuration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java
index 82c46b3..ec5f270 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -1374,12 +1374,20 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
}
/**
- * Sets the file system directory from which to load templates.
- * This is equivalent to {@code setTemplateLoader(new FileTemplateLoader(dir))},
- * so see {@link FileTemplateLoader#FileTemplateLoader(File)} for more details.
+ * Sets the file system directory from which to load templates. This is equivalent to
+ * {@code setTemplateLoader(new FileTemplateLoader(dir))}, so see
+ * {@link FileTemplateLoader#FileTemplateLoader(File)} for more details.
*
- * Note that FreeMarker can load templates from non-file-system sources too.
- * See {@link #setTemplateLoader(TemplateLoader)} from more details.
+ * <p>
+ * Note that FreeMarker can load templates from non-file-system sources too. See
+ * {@link #setTemplateLoader(TemplateLoader)} from more details.
+ *
+ * <p>
+ * Note that this shouldn't be used for loading templates that are coming from a WAR; use
+ * {@link #setServletContextForTemplateLoading(Object, String)} then. Servlet containers might not unpack the WAR
+ * file, in which case you clearly can't access the contained files via {@link File}. Even if the WAR is unpacked,
+ * the servlet container might not expose the location as a {@link File}.
+ * {@link #setServletContextForTemplateLoading(Object, String)} on the other hand will work in all these cases.
*/
public void setDirectoryForTemplateLoading(File dir) throws IOException {
TemplateLoader tl = getTemplateLoader();
@@ -1746,8 +1754,8 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
}
/**
- * Sets when auto-escaping should be enabled depending on the current output format; default is
- * {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}. Note that the default output format,
+ * Sets when auto-escaping should be enabled depending on the current {@linkplain OutputFormat output format};
+ * default is {@link #ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY}. Note that the default output format,
* {@link UndefinedOutputFormat}, is a non-escaping format, so there auto-escaping will be off.
* Note that the templates can turn auto-escaping on/off locally with directives like {@code <#ftl auto_esc=...>},
* which will ignore the policy.
@@ -1813,7 +1821,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
* Sets the default output format. Usually, you should leave this on its default, which is
* {@link UndefinedOutputFormat#INSTANCE}, and then use standard file extensions like "ftlh" (for HTML) or "ftlx"
* (for XML) and ensure that {@link #setRecognizeStandardFileExtensions(boolean)} is {@code true} (see more there).
- * Where you can't use standard the file extensions, templates still can be associated to output formats with
+ * Where you can't use the standard the extensions, templates still can be associated to output formats with
* patterns matching their name (their path) using {@link #setTemplateConfigurations(TemplateConfigurationFactory)}.
* But if all templates will have the same output format, you may use {@link #setOutputFormat(OutputFormat)} after
* all, to set a value like {@link HTMLOutputFormat#INSTANCE}, {@link XMLOutputFormat#INSTANCE}, etc. Also note
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/6b51f59d/src/test/java/freemarker/core/OutputFormatTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/core/OutputFormatTest.java b/src/test/java/freemarker/core/OutputFormatTest.java
index dc5e7d4..bab9619 100644
--- a/src/test/java/freemarker/core/OutputFormatTest.java
+++ b/src/test/java/freemarker/core/OutputFormatTest.java
@@ -944,7 +944,7 @@ public class OutputFormatTest extends TemplateTest {
}
@Test
- public void testBannedDirectivesIsWhenAutoEscaping() throws Exception {
+ public void testBannedDirectivesWhenAutoEscaping() throws Exception {
String commonFTL = "<#escape x as x?html>x</#escape>";
assertOutput(commonFTL, "x");
assertErrorContains("<#ftl outputFormat='HTML'>" + commonFTL, "escape", "HTML", "double-escaping");