velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dish...@apache.org
Subject svn commit: r1356777 - /velocity/sandbox/jsr223/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java
Date Tue, 03 Jul 2012 15:05:12 GMT
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;
     }
 



Mime
View raw message