001/**
002 * Copyright 2010 The Kuali Foundation Licensed under the
003 * Educational Community License, Version 2.0 (the "License"); you may
004 * not use this file except in compliance with the License. You may
005 * obtain a copy of the License at
006 *
007 * http://www.osedu.org/licenses/ECL-2.0
008 *
009 * Unless required by applicable law or agreed to in writing,
010 * software distributed under the License is distributed on an "AS IS"
011 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
012 * or implied. See the License for the specific language governing
013 * permissions and limitations under the License.
014 */
015
016package org.kuali.student.common.util;
017
018import java.io.BufferedReader;
019import java.io.IOException;
020import java.io.Reader;
021import java.io.StringReader;
022import java.io.StringWriter;
023import java.util.HashMap;
024import java.util.Map;
025
026import org.apache.velocity.VelocityContext;
027import org.apache.velocity.app.VelocityEngine;
028import org.apache.velocity.exception.VelocityException;
029import org.apache.velocity.tools.generic.ComparisonDateTool;
030import org.apache.velocity.tools.generic.DateTool;
031import org.apache.velocity.tools.generic.MathTool;
032import org.apache.velocity.tools.generic.NumberTool;
033import org.apache.velocity.tools.generic.SortTool;
034
035/**
036 * Velocity template engine.
037 * <p>Velocity tools supported (See <a href="http://velocity.apache.org/tools/devel/generic.html">http://velocity.apache.org/tools/devel/generic.html<a/>}:</p>
038 * <ul>
039 * <li><a href="http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/DateTool.html">DateTool</a></li>
040 * <li><a href="http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html">ComparisonDateTool</a></li>
041 * <li><a href="http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a></li>
042 * <li><a href="http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/NumberTool.html">NumberTool</a></li>
043 * <li><a href="http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a></li>
044 * </ul>
045 * 
046 * Examples:
047 * <pre>
048 * $dateTool:            <code>$dateTool.get('yyyy-M-d H:m:s')                                 -> 2003-10-19 21:54:50</code>
049 * 
050 * $dateComparisonTool:  <code>$dateComparisonTool.difference('2005-07-04','2007-02-15').abbr  -> 1 yr</code>
051 * 
052 * $mathTool:            <code>$mathTool.toNumber($value)                                      -> Converts java.lang.String $value to a java.lang.Number</code>
053 * 
054 * $numberTool:          <code>$numberTool.currency($myNumber)                                 -> $13.55</code>
055 * 
056 * $sortTool:            <code>$sorter.sort($collection, "name:asc")                           -> Sorts $collection with property 'name' in ascending order</code>
057 * </pre>
058 */
059public class VelocityTemplateEngine {
060
061        private final VelocityEngine velocityEngine = new VelocityEngine();
062        private VelocityContext defaultContext;
063        private Map<String,Object> configMap = new HashMap<String, Object>();
064
065        /**
066         * Constructs a velocity template engine.
067         */
068        public VelocityTemplateEngine() {
069                init();
070        }
071
072        /**
073         * Constructs a velocity template engine with velocity tools configurations.
074         * 
075         * @param config Velocity tools configurations
076         */
077        public VelocityTemplateEngine(final Map<String,Object> config) {
078                this.configMap = config;
079                init();
080        }
081
082        /**
083         * Initializes Velocity engine
084         */
085        private void init() {
086        velocityEngine.setProperty(VelocityEngine.RESOURCE_LOADER, "class");
087        velocityEngine.setProperty("class.resource.loader.class", "org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");
088        setLogFile();
089
090        DateTool dateTool = new DateTool();
091        dateTool.configure(this.configMap);
092        MathTool mathTool = new MathTool();
093        NumberTool numberTool = new NumberTool();
094        numberTool.configure(this.configMap);
095        SortTool sortTool = new SortTool();
096        
097        defaultContext = new VelocityContext();
098        defaultContext.put("dateTool", dateTool);
099        defaultContext.put("dateComparisonTool", new ComparisonDateTool());
100        defaultContext.put("mathTool", mathTool);
101        defaultContext.put("numberTool", numberTool);
102        defaultContext.put("sortTool", sortTool);
103        // Following tools need VelocityTools version 2.0+
104        //defaultContext.put("displayTool", new DisplayTool());
105        //defaultContext.put("xmlTool", new XmlTool());
106        
107        try {
108                        velocityEngine.init();
109                } catch (Exception e) {
110                        throw new VelocityException(e);
111                }
112        }
113
114        /**
115         * Sets logging on or off.
116         *   
117         * @param enableLogging True enables logging; false disables logging
118         */
119        public void setLogging(boolean enableLogging) {
120                if (!enableLogging) {
121                // Line below to disables logging, remove to enable
122                velocityEngine.setProperty(VelocityEngine.RUNTIME_LOG_LOGSYSTEM_CLASS, "org.apache.velocity.runtime.log.NullLogSystem");
123        } else {
124                velocityEngine.setProperty(VelocityEngine.RUNTIME_LOG_LOGSYSTEM_CLASS, null);
125                setLogFile();
126        }
127        }
128                
129        /**
130         * Sets the Velocity Log File to the default location.  Either 
131         * <code>{catalina.base}/velocity.log</code> or <code>target/velocity.log</code>. 
132         */
133        public void setLogFile() {
134                if (System.getProperty("catalina.base") != null) {
135                        setLogFile(System.getProperty("catalina.base") + "/logs/velocity.log");
136                } else {
137                        setLogFile("target/velocity.log");
138                }
139        }
140        
141        /**
142         * Sets the Velocity Log File.
143         *   
144         * @param logFile the path and filename for velocity logging 
145         */
146        public void setLogFile(final String logfile) {
147                velocityEngine.setProperty(VelocityEngine.RUNTIME_LOG, logfile);
148        }
149        
150        /**
151         * Evaluates a template with a map of objects. <code>contextMap</code> can
152         * be null if no keys/tokens are referenced in the <code>template</code>
153         * 
154         * @param contextMap Map of objects to be used in the template
155         * @param template Velocity Template
156         * @return Evaluated template
157         */
158        public String evaluate(final Map<String, Object> contextMap, final String template) throws VelocityException {
159                Reader readerOut = null;
160                try {
161                        readerOut = new BufferedReader(new StringReader(template));
162                        return evaluate(contextMap, readerOut);
163                } finally {
164                        if(readerOut != null) {
165                                try {
166                                        readerOut.close();
167                                } catch (IOException e) {
168                                        throw new VelocityException(e);
169                                }
170                                        
171                        }
172                }
173        }
174
175        /**
176         * Evaluates a template with a map of objects.
177         * 
178         * @param mapContext Map of Objects to be used in the template
179         * @param template Velocity Template
180         * @return Evaluated template
181         */
182        public String evaluate(final Map<String, Object> mapContext, final Reader template) throws VelocityException {
183                VelocityContext context = new VelocityContext(mapContext, defaultContext);
184                
185                StringWriter writerOut = new StringWriter();
186                try {
187                        velocityEngine.evaluate(context, writerOut, "VelocityEngine", template);
188                        return writerOut.toString();
189                } catch(Exception e) {
190                        throw new VelocityException(e);
191                }
192        }
193
194}