001package 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 024import java.io.OutputStream; 025import java.io.Writer; 026 027import org.apache.turbine.pipeline.PipelineData; 028import org.apache.turbine.services.Service; 029import org.apache.turbine.util.TurbineException; 030import org.apache.velocity.context.Context; 031 032/** 033 * Implementations of the VelocityService interface. 034 * 035 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a> 036 * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a> 037 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a> 038 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> 039 * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a> 040 * @version $Id$ 041 */ 042public interface VelocityService 043 extends Service 044{ 045 /** The Service Name */ 046 String SERVICE_NAME = "VelocityService"; 047 048 /** Key for storing the Context in the RunData object */ 049 String CONTEXT = "VELOCITY_CONTEXT"; 050 051 /** The default extension of Velocity Pages */ 052 String VELOCITY_EXTENSION = "vm"; 053 054 /** The Key for storing the RunData Object in the Context */ 055 String RUNDATA_KEY = "data"; 056 057 /** The Key for storing the PipelineData Object in the Context */ 058 String PIPELINEDATA_KEY = "pipelineData"; 059 060 /** Shall we catch Velocity Errors and report them? */ 061 String CATCH_ERRORS_KEY = "catch.errors"; 062 063 /** Default: Yes */ 064 boolean CATCH_ERRORS_DEFAULT = true; 065 066 /** 067 * Process the request and fill in the template with the values 068 * you set in the Context. 069 * 070 * @param context A Context. 071 * @param template A String with the filename of the template. 072 * @return The process template as a String. 073 * @throws Exception a generic exception. 074 */ 075 String handleRequest(Context context, String template) 076 throws Exception; 077 078 /** 079 * Process the request and fill in the template with the values 080 * you set in the Context. 081 * 082 * @param context A Context. 083 * @param filename A String with the filename of the template. 084 * @param out A OutputStream where we will write the process template as 085 * a String. 086 * @throws TurbineException Any exception thrown while processing will be 087 * wrapped into a TurbineException and rethrown. 088 */ 089 void handleRequest(Context context, String filename, OutputStream out) 090 throws TurbineException; 091 092 /** 093 * Process the request and fill in the template with the values 094 * you set in the Context. 095 * 096 * @param context A Context. 097 * @param filename A String with the filename of the template. 098 * @param writer A Writer where we will write the process template as 099 * 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}