velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1752992 - in /velocity/engine/trunk/velocity-engine-scripting/src/main/java/org/apache/velocity/script: VelocityScriptEngine.java VelocityScriptEngineFactory.java
Date Sat, 16 Jul 2016 18:50:54 GMT
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);



Mime
View raw message