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