Author: dishara
Date: Tue Jul 3 15:05:11 2012
New Revision: 1356777
URL: http://svn.apache.org/viewvc?rev=1356777&view=rev
Log:
Adding comments to VelocityEngine
Modified:
velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
Modified:
velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
URL:
http://svn.apache.org/viewvc/velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java?rev=1356777&r1=1356776&r2=1356777&view=diff
==============================================================================
---
velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
(original)
+++
velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
Tue Jul 3 15:05:11 2012
@@ -29,16 +29,44 @@ import java.util.Properties;
public class VelocityScriptEngine implements ScriptEngine {
+ /**
+ * ScriptEngineFactory reference from whom this engine got created
+ */
private ScriptEngineFactory scriptEngineFactory;
+
+
+ /**
+ * Velocity core engine reference
+ */
private VelocityEngine velocityEngine;
+
+
+ /**
+ * unmodifiable property name which is ued to obtain properties from
context as well as from system to initialize velocity core engine
+ */
public static final String VELOCITY_PROPERTIES =
"org.apache.velocity.engine.properties";
+
+
+ /**
+ * script context reference which belongs to this engine instance
+ */
private ScriptContext scriptContext;
+
+ /**
+ * Constructor which gets created engine factory reference as input
+ * @param scriptEngineFactory ScriptEngineFactory reference from whom
this engine got created
+ */
public VelocityScriptEngine(ScriptEngineFactory scriptEngineFactory) {
this.scriptEngineFactory = scriptEngineFactory;
this.scriptContext = new VelocityScriptContext();
}
+ /**
+ *
+ * @param scriptEngineFactory ScriptEngineFactory reference from whom
this engine got created
+ * @param bindings required binding needs to initialize this engine,
unless it defaults to engine scope
+ */
public VelocityScriptEngine(ScriptEngineFactory
scriptEngineFactory,Bindings bindings) {
this.scriptEngineFactory = scriptEngineFactory;
this.scriptContext = new VelocityScriptContext();
@@ -51,17 +79,21 @@ public class VelocityScriptEngine implem
/**
- * @return a ScriptEngineFactory , if null return a newly created one .
Added creation inside sync block to avoid creating
- * two factories from a engine by two parallel threads at the same
time. Also the additional null check out from sync block is to avoid every
- * thread to get blocked inside it even there is an already
created factory..
+ * @return script engine factory who created this engine
*/
public ScriptEngineFactory getFactory() {
+
+ // if null return a newly created one
if (scriptEngineFactory == null) {
createNewFactory();
}
return scriptEngineFactory;
}
+ /**
+ * Added creation inside sync block to avoid creating two factories from a
engine by two parallel threads at the same time.
+ * Also the additional null check out from sync block is to avoid every
thread to get blocked inside it even there is an already created factory.
+ */
private void createNewFactory() {
synchronized (this) {
if (scriptEngineFactory == null) {
@@ -70,6 +102,10 @@ public class VelocityScriptEngine implem
}
}
+ /**
+ * Creates the velocity core engine by initializing it from reading
property file/system properties
+ * @param context
+ */
private void constructVelocityEngine(ScriptContext context) {
Properties props = getPropertiesFromContext(context);
@@ -89,8 +125,14 @@ public class VelocityScriptEngine implem
initVelocityEngine();
}
+ /**
+ * Init velocity engine without properties.
+ */
private void initVelocityEngine() {
+
if (velocityEngine != null) {
+
+// Add sync block from a parallel thread creating two velocity
engine instances
synchronized (this) {
velocityEngine = new VelocityEngine();
velocityEngine.init();
@@ -98,6 +140,10 @@ public class VelocityScriptEngine implem
}
}
+ /**
+ * Initializes the velocity engine with pre defined properties
+ * @param props
+ */
private void initVelocityEngine(Properties props) {
if (velocityEngine == null) {
synchronized (this) {
@@ -107,6 +153,10 @@ public class VelocityScriptEngine implem
}
}
+ /**
+ * Obtain properties from a property file which is taken from a system
property
+ * @return
+ */
private Properties getPropertiesFromSystem() {
String propFileName = System.getProperty(VELOCITY_PROPERTIES);
File propFile = new File(propFileName);
@@ -133,12 +183,38 @@ public class VelocityScriptEngine implem
}
}
+
+
+ /**
+ * Causes the immediate execution of the script whose source is the String
passed as the first argument. The script may be
+ * re-parsed or recompiled before execution. State left in the engine from
previous executions, including variable values and
+ * compiled procedures may be visible during this execution.
+ * @param s The script to be executed by the script engine.
+ * @param scriptContext A ScriptContext exposing sets of attributes in
different scopes. The meanings of the
+ * scopes ScriptContext.GLOBAL_SCOPE, and
ScriptContext.ENGINE_SCOPE are defined in the specification.
+ * @return The value returned from the execution of the script.
+ * @throws ScriptException
+ */
public Object eval(String s, ScriptContext scriptContext) throws
ScriptException {
return eval(new StringReader(s),scriptContext);
}
+
+
+ /**
+ * Same as eval(String, ScriptContext) where the source of the script is
read from a Reader.
+ * @param reader The source of the script to be executed by the script
engine.
+ * @param scriptContext The ScriptContext passed to the script engine.
+ * @return The value returned from the execution of the script.
+ * @throws
+ * ScriptException if an error occurrs in script.
+ * java.lang.NullPointerException - if either argument is null.
+ */
public Object eval(Reader reader, ScriptContext scriptContext) throws
ScriptException {
+ if(reader == null) {
+ throw new NullPointerException("Reader passed cannot be null");
+ }
constructVelocityEngine(scriptContext);
String fileName = getTargetFilename(scriptContext);
VelocityContext velocityContext = getVelocityContext(scriptContext);
@@ -159,19 +235,51 @@ public class VelocityScriptEngine implem
return String.valueOf(result);
}
+ /**
+ * Executes the specified script. The default ScriptContext for the
ScriptEngine is used.
+ * @param s The script language source to be executed.
+ * @return The value returned from the execution of the script.
+ * @throws ScriptException - if error occurrs in script.
+ * java.lang.NullPointerException - if either argument is null.
+ */
public Object eval(String s) throws ScriptException {
return eval(s,scriptContext);
}
+
+ /**
+ * Same as eval(String) except that the source of the script is provided
as a Reader
+ * @param reader The source of the script.
+ * @return The value returned by the script.
+ * @throws ScriptException
+ */
public Object eval(Reader reader) throws ScriptException {
return eval(reader,scriptContext);
}
+
+ /**
+ * Executes the script using the Bindings argument as the ENGINE_SCOPE
Bindings of the ScriptEngine during the script
+ * execution. The Reader, Writer and non-ENGINE_SCOPE Bindings of the
default ScriptContext are used.
+ * The ENGINE_SCOPE Bindings of the ScriptEngine is not changed, and its
mappings are unaltered by the script execution.
+ * @param s The source for the script.
+ * @param bindings The Bindings of attributes to be used for script
execution.
+ * @return The value returned by the script.
+ * @throws ScriptException
+ */
public Object eval(String s, Bindings bindings) throws ScriptException {
ScriptContext scriptContext =
getGeneratedScriptContextFromBinding(bindings);
return eval(new StringReader(s),scriptContext);
}
+
+ /**
+ * Same as eval(String, Bindings) except that the source of the script is
provided as a Reader.
+ * @param reader The source of the script.
+ * @param bindings The Bindings of attributes to be used for script
execution.
+ * @return The value returned by the script.
+ * @throws ScriptException
+ */
public Object eval(Reader reader, Bindings bindings) throws
ScriptException {
ScriptContext scriptContext =
getGeneratedScriptContextFromBinding(bindings);
return eval(reader,scriptContext);
@@ -199,33 +307,107 @@ public class VelocityScriptEngine implem
return tmpContext;
}
+ /**
+ * Sets a key/value pair in the state of the ScriptEngine that may either
create a Java Language Binding to be used in the
+ * execution of scripts or be used in some other way, depending on
whether the key is reserved. Must have the same effect
+ * as getBindings(ScriptContext.ENGINE_SCOPE).put.
+ * @param s The name of named value to add
+ * @param o The value of named value to add.
+ * Throws:
+ * java.lang.NullPointerException - if key is null.
+ * java.lang.IllegalArgumentException - if key is empty.
+ */
public void put(String s, Object o) {
+
+ if(s == null) {
+ throw new NullPointerException("Name cannot be null");
+ }
+
+ if("".equals(s)) {
+ throw new IllegalArgumentException("Name cannot be empty");
+ }
+
Bindings engineScope =
scriptContext.getBindings(ScriptContext.ENGINE_SCOPE);
engineScope.put(s,o);
}
+
+ /**
+ * Retrieves a value set in the state of this engine. The value might be
one which was set using setValue or some other value in
+ * the state of the ScriptEngine, depending on the implementation. Must
have the same effect as getBindings
+ * (ScriptContext.ENGINE_SCOPE).get
+ * @param s The key whose value is to be returned
+ * @return the value for the given key
+ * Throws:
+ * java.lang.NullPointerException - if key is null.
+ * java.lang.IllegalArgumentException - if key is empty.
+ */
public Object get(String s) {
+
+ if(s == null) {
+ throw new NullPointerException("Name cannot be null");
+ }
+
+ if("".equals(s)) {
+ throw new IllegalArgumentException("Name cannot be empty");
+ }
+
Bindings engineScope =
scriptContext.getBindings(ScriptContext.ENGINE_SCOPE);
return engineScope.get(s);
}
+
+ /**
+ * The Bindings instances that are returned must be identical to those
returned by the getBindings method of ScriptContext
+ * called with corresponding arguments on the default ScriptContext of
the ScriptEngine.
+ * @param i scope
+ * @return The Bindings with the specified scope.
+ */
public Bindings getBindings(int i) {
return scriptContext.getBindings(i);
}
+
+ /**
+ * Sets a scope of named values to be used by scripts. The possible
scopes are:
+ * ScriptContext.ENGINE_SCOPE - The specified Bindings replaces the engine
scope of the ScriptEngine.
+ * ScriptContext.GLOBAL_SCOPE - The specified Bindings must be visible as
the GLOBAL_SCOPE.
+ * Any other value of scope defined in the default ScriptContext of the
ScriptEngine.
+ * @param bindings The Bindings for the specified scope.
+ * @param i The specified scope. Either ScriptContext.ENGINE_SCOPE,
ScriptContext.GLOBAL_SCOPE, or any other valid value of scope.
+ */
public void setBindings(Bindings bindings, int i) {
scriptContext.setBindings(bindings,i);
}
+
+ /**
+ *
+ * @return A Bindings that can be used to replace the state of this
ScriptEngine.
+ */
public Bindings createBindings() {
return new VelocityBindings();
}
+ /**
+ * Returns the default ScriptContext of the ScriptEngine whose Bindings,
Reader and Writers are used for script executions when no ScriptContext is
specified.
+ * @return The default ScriptContext of the ScriptEngine.
+ */
public ScriptContext getContext() {
return scriptContext;
}
+
+ /**
+ * Sets the default ScriptContext of the ScriptEngine whose Bindings,
Reader and Writers are used for script executions when no ScriptContext is
specified.
+ * @param scriptContext A ScriptContext that will replace the default
ScriptContext in the ScriptEngine.
+ * Throws: java.lang.NullPointerException - if context is null.
+ */
public void setContext(ScriptContext scriptContext) {
+ if(scriptContext == null) {
+ throw new NullPointerException("script context cannot be null");
+ }
+
this.scriptContext = scriptContext;
}
