001    package org.apache.turbine.services.velocity;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    import java.io.OutputStream;
025    import java.io.Writer;
026    
027    import org.apache.turbine.pipeline.PipelineData;
028    import org.apache.turbine.services.TurbineServices;
029    import org.apache.turbine.util.RunData;
030    
031    import org.apache.velocity.context.Context;
032    
033    /**
034     * This is a simple static accessor to common Velocity tasks such as
035     * getting an instance of a context as well as handling a request for
036     * processing a template.
037     * <pre>
038     * Context context = TurbineVelocity.getContext(data);
039     * context.put("message", "Hello from Turbine!");
040     * String results = TurbineVelocity.handleRequest(context, "helloWorld.vm");
041     * data.getPage().getBody().addElement(results);
042     * </pre>
043     *
044     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
045     * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
046     * @author <a href="mailto:jvanzyl@periapt.com.com">Jason van Zyl</a>
047     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
048     * @version $Id: TurbineVelocity.java 615328 2008-01-25 20:25:05Z tv $
049     */
050    public abstract class TurbineVelocity
051    {
052        /**
053         * Utility method for accessing the service
054         * implementation
055         *
056         * @return a VelocityService implementation instance
057         */
058        public static VelocityService getService()
059        {
060            return (VelocityService) TurbineServices
061                    .getInstance().getService(VelocityService.SERVICE_NAME);
062        }
063    
064        /**
065         * This allows you to pass in a context and a path to a template
066         * file and then grabs an instance of the velocity service and
067         * processes the template and returns the results as a String
068         * object.
069         *
070         * @param context A Context.
071         * @param template The path for the template files.
072         * @return A String.
073         * @exception Exception a generic exception.
074         */
075        public static String handleRequest(Context context, String template)
076                throws Exception
077        {
078            return getService().handleRequest(context, template);
079        }
080    
081        /**
082         * Process the request and fill in the template with the values
083         * you set in the Context.
084         *
085         * @param context A Context.
086         * @param template A String with the filename of the template.
087         * @param out A OutputStream where we will write the process template as
088         * a String.
089         * @exception Exception a generic exception.
090         */
091        public static void handleRequest(Context context, String template,
092                                         OutputStream out)
093                throws Exception
094        {
095            getService().handleRequest(context, template, out);
096        }
097    
098        /**
099         * Process the request and fill in the template with the values
100         * you set in the Context.
101         *
102         * @param context A Context.
103         * @param template A String with the filename of the template.
104         * @param writer A Writer where we will write the process template as
105         * a String.
106         * @exception Exception a generic exception.
107         */
108        public static void handleRequest(Context context,
109                                         String template,
110                                         Writer writer)
111                throws Exception
112        {
113            getService().handleRequest(context, template, writer);
114        }
115    
116        /**
117         * This returns a Context that you can pass into handleRequest
118         * once you have populated it with information that the template
119         * will know about.
120         * @deprecated Use the PipelineData version instead.
121         * @param data A Turbine RunData.
122         * @return A Context.
123         */
124        public static Context getContext(RunData data)
125        {
126            return getService().getContext(data);
127        }
128    
129        /**
130         * This returns a Context that you can pass into handleRequest
131         * once you have populated it with information that the template
132         * will know about.
133         *
134         * @param data A Turbine RunData.
135         * @return A Context.
136         */
137        public static Context getContext(PipelineData pipelineData)
138        {
139            return getService().getContext(pipelineData);
140        }
141    
142        /**
143         * This method returns a blank Context object, which
144         * also contains the global context object. Do not use
145         * this method if you need an empty context object! Use
146         * getNewContext for this.
147         *
148         * @return A WebContext.
149         */
150        public static Context getContext()
151        {
152            return getService().getContext();
153        }
154    
155        /**
156         * This method returns a new, empty Context object.
157         *
158         * @return A WebContext.
159         */
160        public static Context getNewContext()
161        {
162            return getService().getNewContext();
163        }
164    
165        /**
166         * Performs post-request actions (releases context
167         * tools back to the object pool).
168         *
169         * @param context a Velocity Context
170         */
171        public static void requestFinished(Context context)
172        {
173            getService().requestFinished(context);
174        }
175    }