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 }