1 package org.apache.turbine.services.velocity; 2 3 4 /* 5 * Licensed to the Apache Software Foundation (ASF) under one 6 * or more contributor license agreements. See the NOTICE file 7 * distributed with this work for additional information 8 * regarding copyright ownership. The ASF licenses this file 9 * to you under the Apache License, Version 2.0 (the 10 * "License"); you may not use this file except in compliance 11 * with the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, 16 * software distributed under the License is distributed on an 17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 18 * KIND, either express or implied. See the License for the 19 * specific language governing permissions and limitations 20 * under the License. 21 */ 22 23 24 import java.io.OutputStream; 25 import java.io.Writer; 26 27 import org.apache.turbine.pipeline.PipelineData; 28 import org.apache.turbine.services.TurbineServices; 29 import org.apache.turbine.util.RunData; 30 31 import org.apache.velocity.context.Context; 32 33 /** 34 * This is a simple static accessor to common Velocity tasks such as 35 * getting an instance of a context as well as handling a request for 36 * processing a template. 37 * <pre> 38 * Context context = TurbineVelocity.getContext(data); 39 * context.put("message", "Hello from Turbine!"); 40 * String results = TurbineVelocity.handleRequest(context, "helloWorld.vm"); 41 * data.getPage().getBody().addElement(results); 42 * </pre> 43 * 44 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a> 45 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a> 46 * @author <a href="mailto:jvanzyl@periapt.com.com">Jason van Zyl</a> 47 * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a> 48 * @version $Id: TurbineVelocity.java 615328 2008-01-25 20:25:05Z tv $ 49 */ 50 public abstract class TurbineVelocity 51 { 52 /** 53 * Utility method for accessing the service 54 * implementation 55 * 56 * @return a VelocityService implementation instance 57 */ 58 public static VelocityService getService() 59 { 60 return (VelocityService) TurbineServices 61 .getInstance().getService(VelocityService.SERVICE_NAME); 62 } 63 64 /** 65 * This allows you to pass in a context and a path to a template 66 * file and then grabs an instance of the velocity service and 67 * processes the template and returns the results as a String 68 * object. 69 * 70 * @param context A Context. 71 * @param template The path for the template files. 72 * @return A String. 73 * @exception Exception a generic exception. 74 */ 75 public static String handleRequest(Context context, String template) 76 throws Exception 77 { 78 return getService().handleRequest(context, template); 79 } 80 81 /** 82 * Process the request and fill in the template with the values 83 * you set in the Context. 84 * 85 * @param context A Context. 86 * @param template A String with the filename of the template. 87 * @param out A OutputStream where we will write the process template as 88 * a String. 89 * @exception Exception a generic exception. 90 */ 91 public static void handleRequest(Context context, String template, 92 OutputStream out) 93 throws Exception 94 { 95 getService().handleRequest(context, template, out); 96 } 97 98 /** 99 * 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 }