Author: dishara
Date: Thu Aug 16 17:13:49 2012
New Revision: 1373929
URL: http://svn.apache.org/viewvc?rev=1373929&view=rev
Log:
Adding scripting api guide which include two samples with codes and detail
description of using hellowworld with api and using tools
Added:
velocity/sandbox/jsr223/src/site/xdoc/script-api-guide.xml
Added: velocity/sandbox/jsr223/src/site/xdoc/script-api-guide.xml
URL:
http://svn.apache.org/viewvc/velocity/sandbox/jsr223/src/site/xdoc/script-api-guide.xml?rev=1373929&view=auto
==============================================================================
--- velocity/sandbox/jsr223/src/site/xdoc/script-api-guide.xml (added)
+++ velocity/sandbox/jsr223/src/site/xdoc/script-api-guide.xml Thu Aug 16
17:13:49 2012
@@ -0,0 +1,154 @@
+
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Hello World: Velocity Scripting JSR-223 API</title>
+ <author email="[email protected]">Velocity Documentation
Team</author>
+ </properties>
+
+ <body>
+
+ <section name="About this Guide" href="AboutthisGuide">
+ <p>
+ This is a brief illustration of how to use Velocity Scripting
framework through JSR-223 API.
+ This article will also illustrate how to work with velocity
tools through the API.
+ </p>
+
+ </section>
+
+ <section name="Main" href="Main">
+ <subsection name="HelloWorld example for JSR-223 API"
href="HelloWorldJSR223API">
+ <p>
+ <strong>I). HelloWorld example for JSR-223 API.</strong>
+ </p>
+
+ <p>
+ 1. ScriptEngineManager manager = new ScriptEngineManager();
+
+ 2. manager.registerEngineName("velocity", new
VelocityScriptEngineFactory());
+
+ 3. ScriptEngine engine =
manager.getEngineByName("velocity");
+
+ 4.
System.setProperty(VelocityScriptEngine.VELOCITY_PROPERTIES, PROP_PATH) ;
+
+ 5. String script = "ADD_YOUR_SIMPLE_VELOCITY_SCRIPT";
+
+ 6. Writer writer = new StringWriter();
+
+ 7. engine.getContext().setWriter(writer);
+
+ 8. Object result = engine.eval(script);
+
+ 9. System.out.println(writer);
+
+ </p>
+ <p>Description: against line number</p>
+
+ <p>
+
+ L-1. First we need to obtain the script engine manager
+
+ L-2. Lets register a engine with a vanilla velocity
scripting engine factory. Hence we use the
+ default
+ constructor to instantiate the factory. If want we can
pass a customized factory instance. For this
+ example we are fine with the default settings.
+
+ L-3. We can obtain the registered engine through manager.
+
+ L-4. Set system property whose value will be the path to
the properties file used normally when
+ creating a VelocityEngine.
+
+ L-5. The script that is need to evaluate
+
+ L-6,7. Create your own writer and set it to the context so
that you can use that to view the final
+ output.
+ Similar manner you can obtain an error writer and see the
exceptions occurred.
+
+ L-8. And finally evaluate the script itself. And the
result return will be a boolean which indicates
+ the successfulness of the operation.
+
+ </p>
+
+ </subsection>
+
+ <subsection name="How to use velocity tools through JSR 223 API"
href="ToolsJSR223API">
+ <p>
+ <strong>II) How to use velocity tools through JSR 223
API</strong>
+ </p>
+
+ <p>
+ 1. ScriptContext context = engine.getContext();
+
+ 2. Properties properties = new Properties();
+ 3. properties.put("resource.loader", "class");
+ 4. properties.put("class.resource.loader.description",
"Template Class Loader");
+ 5.
properties.put("class.resource.loader.class","org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");
+
+ 6.
context.setAttribute(VelocityScriptEngine.VELOCITY_PROPERTIES,properties,ScriptContext.ENGINE_SCOPE);
+
+ 7. CustomEvent event = new CustomEvent("MyEvent");
+
+ 8.
context.getBindings(ScriptContext.ENGINE_SCOPE).put("event", event);
+
+ 9. context.setAttribute(VelocityScriptEngine.FILENAME,
"eventtool.vm", ScriptContext.ENGINE_SCOPE);
+
+ 10. Writer writer = new StringWriter();
+
+ 11. context.setWriter(writer);
+
+ 12. engine.eval("$event;\n" +
+ "Event Created by $event.getName()\n" +
+ "Event Created on $event.getDate()\n" +
+ "Event ID is $event.getID()
+ ");
+
+ 13.System.out.println("####### Tools output #########\n" +
writer);
+
+
+ </p>
+
+ <p>
+ L-1. Lets assume we obtain the script engine as mentioned
above.
+
+ L-2,3,4,5 We create required properties to use the
velocity tool and set them to the context.
+
+ L-6 We set the properties in the engine scope. If want we
can set it as global scope so that all
+ others can see.
+
+ L-7,8 This is a plain old bean class which has attributes
of an event i.e name, ID, date and etc
+
+ L-9 Here we must set the name of the vm file which is
passed as the script to evaluate, if we want
+ cache the template(This is recommended for better
performance). Remember when you do so, you must
+ put the eventtool.vm file in your class path.
+
+ L-12. Evaluate the script itself.
+
+ </p>
+ </subsection>
+ </section>
+
+ </body>
+</document>
+
+
+
