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 }