FREEMARKER-63: Bit of API/javadoc cleanup
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/a6399a79 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/a6399a79 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/a6399a79 Branch: refs/heads/3 Commit: a6399a793f54f531a11a7a9d13b9eb47d648563a Parents: 1e27397 Author: ddekany <[email protected]> Authored: Thu Jul 27 21:24:14 2017 +0200 Committer: ddekany <[email protected]> Committed: Thu Jul 27 21:24:14 2017 +0200 ---------------------------------------------------------------------- .../core/userpkg/AllFeaturesDirective.java | 4 +-- .../core/userpkg/TwoNamedParamsDirective.java | 4 +-- .../userpkg/TwoPositionalParamsDirective.java | 4 +-- .../core/userpkg/UpperCaseDirective.java | 4 +-- .../freemarker/core/ASTDirDynamicCall.java | 4 +-- .../freemarker/core/BuiltInsForStringsMisc.java | 34 ++++++-------------- .../core/model/TemplateCallableModel.java | 22 ++++++------- .../core/model/TemplateDirectiveModel2.java | 20 +++++++++--- 8 files changed, 47 insertions(+), 49 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/AllFeaturesDirective.java ---------------------------------------------------------------------- diff --git a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/AllFeaturesDirective.java b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/AllFeaturesDirective.java index 59f084d..437bb72 100644 --- a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/AllFeaturesDirective.java +++ b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/AllFeaturesDirective.java @@ -122,7 +122,7 @@ public class AllFeaturesDirective extends TestTemplateDirectiveModel { } @Override - public int getNamedArgumentIndex(String name) { + public int getPredefinedNamedArgumentIndex(String name) { return PARAM_NAME_TO_IDX.get(name); } @@ -137,7 +137,7 @@ public class AllFeaturesDirective extends TestTemplateDirectiveModel { } @Override - public int getTotalArgumentCount() { + public int getArgumentArraySize() { return N_OTHERS_IDX + 1; } } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoNamedParamsDirective.java ---------------------------------------------------------------------- diff --git a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoNamedParamsDirective.java b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoNamedParamsDirective.java index 2978bf1..ed1b501 100644 --- a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoNamedParamsDirective.java +++ b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoNamedParamsDirective.java @@ -60,7 +60,7 @@ public class TwoNamedParamsDirective extends TestTemplateDirectiveModel { } @Override - public int getNamedArgumentIndex(String name) { + public int getPredefinedNamedArgumentIndex(String name) { return PARAM_NAME_TO_IDX.get(name); } @@ -70,7 +70,7 @@ public class TwoNamedParamsDirective extends TestTemplateDirectiveModel { } @Override - public int getTotalArgumentCount() { + public int getArgumentArraySize() { return PARAM_NAME_TO_IDX.size(); } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoPositionalParamsDirective.java ---------------------------------------------------------------------- diff --git a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoPositionalParamsDirective.java b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoPositionalParamsDirective.java index 3603069..ef51640 100644 --- a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoPositionalParamsDirective.java +++ b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/TwoPositionalParamsDirective.java @@ -50,7 +50,7 @@ public class TwoPositionalParamsDirective extends TestTemplateDirectiveModel { } @Override - public int getNamedArgumentIndex(String name) { + public int getPredefinedNamedArgumentIndex(String name) { return -1; } @@ -60,7 +60,7 @@ public class TwoPositionalParamsDirective extends TestTemplateDirectiveModel { } @Override - public int getTotalArgumentCount() { + public int getArgumentArraySize() { return getPredefinedPositionalArgumentCount(); } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/UpperCaseDirective.java ---------------------------------------------------------------------- diff --git a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/UpperCaseDirective.java b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/UpperCaseDirective.java index 38c438c..b23e56c 100644 --- a/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/UpperCaseDirective.java +++ b/freemarker-core-test/src/test/java/org/apache/freemarker/core/userpkg/UpperCaseDirective.java @@ -50,7 +50,7 @@ public class UpperCaseDirective extends TestTemplateDirectiveModel { } @Override - public int getNamedArgumentIndex(String name) { + public int getPredefinedNamedArgumentIndex(String name) { return -1; } @@ -60,7 +60,7 @@ public class UpperCaseDirective extends TestTemplateDirectiveModel { } @Override - public int getTotalArgumentCount() { + public int getArgumentArraySize() { return 0; } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core/src/main/java/org/apache/freemarker/core/ASTDirDynamicCall.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/ASTDirDynamicCall.java b/freemarker-core/src/main/java/org/apache/freemarker/core/ASTDirDynamicCall.java index ecab36a..23e081f 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/ASTDirDynamicCall.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/ASTDirDynamicCall.java @@ -159,7 +159,7 @@ class ASTDirDynamicCall extends ASTDirective implements CallPlace { positionalArgs.length, " such arguments."); } - TemplateModel[] execArgs = new TemplateModel[callableValue.getTotalArgumentCount()]; + TemplateModel[] execArgs = new TemplateModel[callableValue.getArgumentArraySize()]; // Fill predefined positional args: if (positionalArgs != null) { @@ -188,7 +188,7 @@ class ASTDirDynamicCall extends ASTDirective implements CallPlace { NativeHashEx2 namedVarargsHash = null; if (namedArgs != null) { for (NamedArgument namedArg : namedArgs) { - int argIdx = callableValue.getNamedArgumentIndex(namedArg.name); + int argIdx = callableValue.getPredefinedNamedArgumentIndex(namedArg.name); if (argIdx != -1) { execArgs[argIdx] = namedArg.value.eval(env); } else { http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core/src/main/java/org/apache/freemarker/core/BuiltInsForStringsMisc.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/BuiltInsForStringsMisc.java b/freemarker-core/src/main/java/org/apache/freemarker/core/BuiltInsForStringsMisc.java index 21c2a9d..1e82923 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/BuiltInsForStringsMisc.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/BuiltInsForStringsMisc.java @@ -21,12 +21,13 @@ package org.apache.freemarker.core; import java.io.IOException; import java.io.StringReader; -import java.io.Writer; import java.util.List; import java.util.Map; import org.apache.freemarker.core.model.ObjectWrapper; import org.apache.freemarker.core.model.TemplateBooleanModel; +import org.apache.freemarker.core.model.TemplateDirectiveBody; +import org.apache.freemarker.core.model.TemplateDirectiveModel; import org.apache.freemarker.core.model.TemplateMethodModelEx; import org.apache.freemarker.core.model.TemplateModel; import org.apache.freemarker.core.model.TemplateModelException; @@ -189,19 +190,18 @@ class BuiltInsForStringsMisc { return new TemplateProcessorModel(interpretedTemplate); } - private class TemplateProcessorModel - implements - TemplateTransformModel { + private class TemplateProcessorModel implements TemplateDirectiveModel { private final Template template; TemplateProcessorModel(Template template) { this.template = template; } - + @Override - public Writer getWriter(final Writer out, Map args) throws TemplateModelException, IOException { + public void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body) + throws TemplateException, IOException { + // TODO [FM3] Disallow params, loop vars, and nested content try { - Environment env = Environment.getCurrentEnvironment(); boolean lastFIRE = env.setFastInvalidReferenceExceptions(false); try { env.include(template); @@ -215,23 +215,9 @@ class BuiltInsForStringsMisc { new _DelayedGetMessage(e), MessageUtil.EMBEDDED_MESSAGE_END); } - - return new Writer(out) - { - @Override - public void close() { - } - - @Override - public void flush() throws IOException { - out.flush(); - } - - @Override - public void write(char[] cbuf, int off, int len) throws IOException { - out.write(cbuf, off, len); - } - }; + if (body != null) { + body.render(env.getOut()); + } } } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateCallableModel.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateCallableModel.java b/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateCallableModel.java index 00fd2d8..3588ea7 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateCallableModel.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateCallableModel.java @@ -55,12 +55,12 @@ public interface TemplateCallableModel extends TemplateModel { * * @return -1 if there's no such named argument */ - int getNamedArgumentIndex(String name); + int getPredefinedNamedArgumentIndex(String name); /** * Returns the index of the named varargs argument in the argument array, or -1 if there's no named varargs * argument. The named varargs argument is a {@link TemplateHashModelEx2} with string keys that collects all - * the named arguments for which {@link #getNamedArgumentIndex(String)} returns -1. The iteration order of this + * the named arguments for which {@link #getPredefinedNamedArgumentIndex(String)} returns -1. The iteration order of this * hash follows the order in which the arguments were specified in the calling template. * * @return -1 if there's no named varargs argument @@ -68,6 +68,14 @@ public interface TemplateCallableModel extends TemplateModel { int getNamedVarargsArgumentIndex(); /** + * The valid names for arguments that are passed by name (not by position), in the order as they should be displayed + * in error messages, or {@code null} if there's none. If you have implemented + * {@link #getPredefinedNamedArgumentIndex(String)} with a {@link StringToIndexMap}, you should return + * {@link StringToIndexMap#getKeys()} here. + */ + Collection<String> getPredefinedNamedArgumentNames(); + + /** * The required (minimum) length of the {@code args} array passed to the {@code execute} method. This length always * includes the space reserved for optional arguments; it's not why it's said to be a minimum length. It's a minimum * length because a longer array might be reused for better performance (but {@code execute} should never read @@ -82,14 +90,6 @@ public interface TemplateCallableModel extends TemplateModel { * {@link #getNamedVarargsArgumentIndex()} is not -1, then it's one less than the return value of this method.) * </ul> */ - int getTotalArgumentCount(); - - /** - * The valid names for arguments that are passed by name (not by position), in the order as they should be displayed - * in error messages, or {@code null} if there's none. If you have implemented - * {@link #getNamedArgumentIndex(String)} with a {@link StringToIndexMap}, you should return - * {@link StringToIndexMap#getKeys()} here. - */ - Collection<String> getPredefinedNamedArgumentNames(); + int getArgumentArraySize(); } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a6399a79/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateDirectiveModel2.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateDirectiveModel2.java b/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateDirectiveModel2.java index 688e43f..75bf2f2 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateDirectiveModel2.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/model/TemplateDirectiveModel2.java @@ -22,16 +22,28 @@ public interface TemplateDirectiveModel2 extends TemplateCallableModel { /** * @param args - * Array with {@link #getTotalArgumentCount()} elements (or more, in which case the extra elements should be - * ignored). Not {@code null}. If a parameter was omitted, the corresponding array element will be {@code - * null}. + * Array with {@link #getArgumentArraySize()} elements (or more, in which case the extra elements should be + * ignored). Not {@code null}. If a parameter was omitted on the caller side, the corresponding array + * element will be {@code null}. Parameters passed by position will be at the index that corresponds to the + * position (the 1st argument is at index 0). However, positional parameters over {@link + * #getPredefinedPositionalArgumentCount()} will be in the positional varargs sequence at index one higher, + * assuming {@link #hasPositionalVarargsArgument()} is {@code true}. Parameters passed by name (rather than + * by position) will be at the index returned be {@link #getPredefinedNamedArgumentIndex(String)}, or in the + * named varargs hash at index {@link #getNamedVarargsArgumentIndex()}, assuming that's not -1. * @param callPlace * The place (in a template, normally) where this directive was called from. Not {@code null}. Note that - * {@link CallPlace#executeNestedContent(TemplateModel[], Writer, Environment)} can be used to + * {@link CallPlace#executeNestedContent(TemplateModel[], Writer, Environment)} can be used to execute the + * nested content. If the directive doesn't support nested content, it should check {@link + * CallPlace#hasNestedContent()} that return {@code false}, and otherwise throw exception. * @param out * Print the output here (if there's any) * @param env * The current processing environment. Not {@code null}. + * + * @throws TemplateException + * If any problem occurs that's not an {@link IOException} during writing the template output. + * @throws IOException + * When writing the template output fails. */ void execute(TemplateModel[] args, CallPlace callPlace, Writer out, Environment env) throws TemplateException, IOException;
