You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by di...@apache.org on 2012/07/03 17:05:12 UTC
svn commit: r1356777 -
/velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
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;
}