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