001/*
002 * Copyright 2002-2013 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.ui.velocity;
018
019import java.io.StringWriter;
020import java.io.Writer;
021import java.util.Map;
022
023import org.apache.velocity.VelocityContext;
024import org.apache.velocity.app.VelocityEngine;
025import org.apache.velocity.exception.VelocityException;
026
027/**
028 * Utility class for working with a VelocityEngine.
029 * Provides convenience methods to merge a Velocity template with a model.
030 *
031 * @author Juergen Hoeller
032 * @since 22.01.2004
033 * @deprecated as of Spring 4.3, in favor of FreeMarker
034 */
035@Deprecated
036public abstract class VelocityEngineUtils {
037
038        /**
039         * Merge the specified Velocity template with the given model and write
040         * the result to the given Writer.
041         * @param velocityEngine VelocityEngine to work with
042         * @param templateLocation the location of template, relative to Velocity's resource loader path
043         * @param model the Map that contains model names as keys and model objects as values
044         * @param writer the Writer to write the result to
045         * @throws VelocityException if the template wasn't found or rendering failed
046         * @deprecated Use {@link #mergeTemplate(VelocityEngine, String, String, Map, Writer)}
047         * instead, following Velocity 1.6's corresponding deprecation in its own API.
048         */
049        @Deprecated
050        public static void mergeTemplate(
051                        VelocityEngine velocityEngine, String templateLocation, Map<String, Object> model, Writer writer)
052                        throws VelocityException {
053
054                VelocityContext velocityContext = new VelocityContext(model);
055                velocityEngine.mergeTemplate(templateLocation, velocityContext, writer);
056        }
057
058        /**
059         * Merge the specified Velocity template with the given model and write the result
060         * to the given Writer.
061         * @param velocityEngine VelocityEngine to work with
062         * @param templateLocation the location of template, relative to Velocity's resource loader path
063         * @param encoding the encoding of the template file
064         * @param model the Map that contains model names as keys and model objects as values
065         * @param writer the Writer to write the result to
066         * @throws VelocityException if the template wasn't found or rendering failed
067         */
068        public static void mergeTemplate(
069                        VelocityEngine velocityEngine, String templateLocation, String encoding,
070                        Map<String, Object> model, Writer writer) throws VelocityException {
071
072                VelocityContext velocityContext = new VelocityContext(model);
073                velocityEngine.mergeTemplate(templateLocation, encoding, velocityContext, writer);
074        }
075
076        /**
077         * Merge the specified Velocity template with the given model into a String.
078         * <p>When using this method to prepare a text for a mail to be sent with Spring's
079         * mail support, consider wrapping VelocityException in MailPreparationException.
080         * @param velocityEngine VelocityEngine to work with
081         * @param templateLocation the location of template, relative to Velocity's resource loader path
082         * @param model the Map that contains model names as keys and model objects as values
083         * @return the result as String
084         * @throws VelocityException if the template wasn't found or rendering failed
085         * @see org.springframework.mail.MailPreparationException
086         * @deprecated Use {@link #mergeTemplateIntoString(VelocityEngine, String, String, Map)}
087         * instead, following Velocity 1.6's corresponding deprecation in its own API.
088         */
089        @Deprecated
090        public static String mergeTemplateIntoString(VelocityEngine velocityEngine, String templateLocation,
091                        Map<String, Object> model) throws VelocityException {
092
093                StringWriter result = new StringWriter();
094                mergeTemplate(velocityEngine, templateLocation, model, result);
095                return result.toString();
096        }
097
098        /**
099         * Merge the specified Velocity template with the given model into a String.
100         * <p>When using this method to prepare a text for a mail to be sent with Spring's
101         * mail support, consider wrapping VelocityException in MailPreparationException.
102         * @param velocityEngine VelocityEngine to work with
103         * @param templateLocation the location of template, relative to Velocity's resource loader path
104         * @param encoding the encoding of the template file
105         * @param model the Map that contains model names as keys and model objects as values
106         * @return the result as String
107         * @throws VelocityException if the template wasn't found or rendering failed
108         * @see org.springframework.mail.MailPreparationException
109         */
110        public static String mergeTemplateIntoString(VelocityEngine velocityEngine, String templateLocation,
111                        String encoding, Map<String, Object> model) throws VelocityException {
112
113                StringWriter result = new StringWriter();
114                mergeTemplate(velocityEngine, templateLocation, encoding, model, result);
115                return result.toString();
116        }
117
118}