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.Service; 29 import org.apache.turbine.util.RunData; 30 import org.apache.turbine.util.TurbineException; 31 32 import org.apache.velocity.context.Context; 33 34 /** 35 * Implementations of the VelocityService interface. 36 * 37 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a> 38 * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a> 39 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a> 40 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> 41 * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a> 42 * @version $Id: VelocityService.java 615328 2008-01-25 20:25:05Z tv $ 43 */ 44 public interface VelocityService 45 extends Service 46 { 47 /** The Service Name */ 48 String SERVICE_NAME = "VelocityService"; 49 50 /** Key for storing the Context in the RunData object */ 51 String CONTEXT = "VELOCITY_CONTEXT"; 52 53 /** The default extension of Velocity Pages */ 54 String VELOCITY_EXTENSION = "vm"; 55 56 /** The Key for storing the RunData Object in the Context */ 57 String RUNDATA_KEY = "data"; 58 59 /** The Key for storing the PipelineData Object in the Context */ 60 String PIPELINEDATA_KEY = "pipelineData"; 61 62 /** Shall we catch Velocity Errors and report them? */ 63 String CATCH_ERRORS_KEY = "catch.errors"; 64 65 /** Default: Yes */ 66 boolean CATCH_ERRORS_DEFAULT = true; 67 68 /** 69 * Process the request and fill in the template with the values 70 * you set in the Context. 71 * 72 * @param context A Context. 73 * @param template A String with the filename of the template. 74 * @return The process template as a String. 75 * @exception Exception a generic exception. 76 */ 77 String handleRequest(Context context, String template) 78 throws Exception; 79 80 /** 81 * Process the request and fill in the template with the values 82 * you set in the Context. 83 * 84 * @param context A Context. 85 * @param filename A String with the filename of the template. 86 * @param out A OutputStream where we will write the process template as 87 * a String. 88 * @throws TurbineException Any exception trown while processing will be 89 * wrapped into a TurbineException and rethrown. 90 */ 91 void handleRequest(Context context, String filename, OutputStream out) 92 throws TurbineException; 93 94 /** 95 * Process the request and fill in the template with the values 96 * you set in the Context. 97 * 98 * @param context A Context. 99 * @param filename A String with the filename of the template. 100 * @param writer A Writer where we will write the process template as 101 * a String. 102 * @throws TurbineException Any exception trown while processing will be 103 * wrapped into a TurbineException and rethrown. 104 */ 105 void handleRequest(Context context, String filename, Writer writer) 106 throws TurbineException; 107 108 /** 109 * Create an empty WebContext object. 110 * 111 * @return An empty WebContext object. 112 */ 113 Context getContext(); 114 115 /** 116 * This method returns a new, empty Context object. 117 * 118 * @return A WebContext. 119 */ 120 Context getNewContext(); 121 122 /** 123 * Create a Context from the RunData object. Adds a pointer to 124 * the RunData object to the Context so that RunData is available in 125 * the templates. 126 * 127 * @param data The Turbine RunData object. 128 * @return A clone of the Context needed by Velocity. 129 */ 130 Context getContext(RunData data); 131 132 /** 133 * Create a Context from the RunData object. Adds a pointer to 134 * the RunData object to the Context so that RunData is available in 135 * the templates. 136 * 137 * @param data The Turbine RunData object. 138 * @return A clone of the Context needed by Velocity. 139 */ 140 Context getContext(PipelineData pipelineData); 141 142 143 144 /** 145 * Performs post-request actions (releases context 146 * tools back to the object pool). 147 * 148 * @param context a Velocity Context 149 */ 150 void requestFinished(Context context); 151 }