Author: cbrisson
Date: Sat Jul 16 18:50:54 2016
New Revision: 1752992
URL: http://svn.apache.org/viewvc?rev=1752992&view=rev
Log:
[jsr223] enhance javadoc
Modified:
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngineFactory.java
Modified:
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java?rev=1752992&r1=1752991&r2=1752992&view=diff
==============================================================================
---
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
(original)
+++
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
Sat Jul 16 18:50:54 2016
@@ -60,34 +60,66 @@ import javax.script.SimpleBindings;
public class VelocityScriptEngine extends AbstractScriptEngine implements
Compilable
{
+ /**
+ * Key used to provide this engine with the pathname of the Velocity
properties file.
+ * This key is first searched in the ScriptContext attributes, then as a
System property
+ */
public static final String VELOCITY_PROPERTIES_KEY =
"org.apache.velocity.script.properties";
// my factory, may be null
private volatile ScriptEngineFactory factory;
private volatile RuntimeInstance velocityEngine;
+ /**
+ * contructs a new Velocity script engine, linked to the given factory
+ * @param factory
+ */
public VelocityScriptEngine(ScriptEngineFactory factory)
{
this.factory = factory;
- }
+ }
+ /**
+ * constructs a new standalone Velocity script engine
+ */
public VelocityScriptEngine()
{
this(null);
}
- public RuntimeInstance getVelocityEngine()
+ /**
+ * get the internal Velocity RuntimeInstance
+ * @return the internal Velocity RuntimeInstance
+ */
+ protected RuntimeInstance getVelocityEngine()
{
return velocityEngine;
}
-
- // ScriptEngine methods
- public Object eval(String str, ScriptContext ctx)
+
+ /**
+ * Evaluate the given script.
+ * If you wish to get a resulting string, call getContext().setWriter(new
StringWriter()) then call toString()
+ * on the returned writer.
+ * @param str script source
+ * @param ctx script context
+ * @return the script context writer (by default a PrintWriter towards
System.out)
+ * @throws ScriptException
+ */
+ public Object eval(String str, ScriptContext ctx)
throws ScriptException
{
return eval(new StringReader(str), ctx);
}
+ /**
+ * Evaluate the given script.
+ * If you wish to get a resulting string, call getContext().setWriter(new
StringWriter()) then call toString()
+ * on the returned writer.
+ * @param reader script source reader
+ * @param ctx script context
+ * @return the script context writer (by default a PrintWriter towards
System.out)
+ * @throws ScriptException
+ */
public Object eval(Reader reader, ScriptContext ctx)
throws ScriptException
{
@@ -112,6 +144,10 @@ public class VelocityScriptEngine extend
return out;
}
+ /**
+ * get the factory used to create this script engine
+ * @return factory
+ */
public ScriptEngineFactory getFactory()
{
if (factory == null)
@@ -127,12 +163,15 @@ public class VelocityScriptEngine extend
return factory;
}
+ /**
+ * creates a new Bindings to be used with this script
+ * @return new bindings
+ */
public Bindings createBindings()
{
return new SimpleBindings();
}
- // internals only below this point
private void initVelocityEngine(ScriptContext ctx)
{
if (ctx == null)
@@ -223,11 +262,23 @@ public class VelocityScriptEngine extend
return null;
}
+ /**
+ * Compile a template
+ * @param script template source
+ * @return compiled template
+ * @throws ScriptException
+ */
public CompiledScript compile(String script) throws ScriptException
{
return compile(new StringReader(script));
}
+ /**
+ * Compile a template
+ * @param script template source
+ * @return compiled template
+ * @throws ScriptException
+ */
public CompiledScript compile(Reader script) throws ScriptException
{
initVelocityEngine(null);
Modified:
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngineFactory.java
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngineFactory.java?rev=1752992&r1=1752991&r2=1752992&view=diff
==============================================================================
---
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngineFactory.java
(original)
+++
velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngineFactory.java
Sat Jul 16 18:50:54 2016
@@ -75,32 +75,59 @@ public class VelocityScriptEngineFactory
parameters.put(ScriptEngine.LANGUAGE_VERSION, VELOCITY_VERSION);
parameters.put("THREADING", "MULTITHREADED");
}
-
+
+ /**
+ * get engine name
+ * @return engine name, aka "Velocity"
+ */
public String getEngineName()
{
return VELOCITY_NAME;
}
+ /**
+ * get engine version
+ * @return engine version string
+ */
public String getEngineVersion()
{
return VELOCITY_VERSION;
}
+ /**
+ * get the list of file extensions handled by Velocity: vm, vtl, vhtml
+ * @return extentions list
+ */
public List<String> getExtensions()
{
return extensions;
}
+ /**
+ * get language name
+ * @return language name, aka "VTL"
+ */
public String getLanguageName()
{
return VELOCITY_NAME;
}
+ /**
+ * get language version (same as engine version)
+ * @return language version string
+ */
public String getLanguageVersion()
{
return VELOCITY_VERSION;
}
+ /**
+ * get Velocity syntax for calling method 'm' on bject 'obj' with provided
arguments
+ * @param obj
+ * @param m
+ * @param args
+ * @return VTL call ${obj.m(args...)}
+ */
public String getMethodCallSyntax(String obj, String m, String... args)
{
StringBuilder buf = new StringBuilder();
@@ -123,16 +150,29 @@ public class VelocityScriptEngineFactory
return buf.toString();
}
+ /**
+ * get the list of Velocity mime types
+ * @return singleton { 'text/x-velocity' }
+ */
public List<String> getMimeTypes()
{
return mimeTypes;
}
+ /**
+ * get the list of names
+ * @return { 'velocity', 'Velocity' }
+ */
public List<String> getNames()
{
return names;
}
+ /**
+ * get VTL expression used to display specified string
+ * @param toDisplay
+ * @return escaped string #[[toDisplay]]#
+ */
public String getOutputStatement(String toDisplay)
{
StringBuilder buf = new StringBuilder();
@@ -140,11 +180,21 @@ public class VelocityScriptEngineFactory
return buf.toString();
}
+ /**
+ * get engine parameter for provided key
+ * @param key
+ * @return found parameter, or null
+ */
public String getParameter(String key)
{
return parameters.getProperty(key);
- }
+ }
+ /**
+ * get whole VTL program given VTL lines
+ * @param statements VTL lines
+ * @return lines concatenated with carriage returns
+ */
public String getProgram(String... statements)
{
StringBuilder buf = new StringBuilder();
@@ -156,6 +206,10 @@ public class VelocityScriptEngineFactory
return buf.toString();
}
+ /**
+ * get a Velocity script engine
+ * @return a new Velocity script engine
+ */
public ScriptEngine getScriptEngine()
{
return new VelocityScriptEngine(this);
