View Javadoc

1   package org.apache.turbine.services.velocity;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.io.OutputStream;
23  import java.io.Writer;
24  
25  import org.apache.turbine.services.Service;
26  import org.apache.turbine.util.RunData;
27  import org.apache.turbine.util.TurbineException;
28  
29  import org.apache.velocity.context.Context;
30  
31  /***
32   * Implementations of the VelocityService interface.
33   *
34   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
35   * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
36   * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
37   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
38   * @version $Id: VelocityService.java 534527 2007-05-02 16:10:59Z tv $
39   */
40  public interface VelocityService
41          extends Service
42  {
43      /*** The Service Name */
44      String SERVICE_NAME = "VelocityService";
45  
46      /*** Key for storing the Context in the RunData object */
47      String CONTEXT = "VELOCITY_CONTEXT";
48  
49      /*** The default extension of Velocity Pages */
50      String VELOCITY_EXTENSION = "vm";
51  
52      /*** The Key for storing the RunData Object in the Context */
53      String RUNDATA_KEY = "data";
54  
55      /*** Shall we catch Velocity Errors and report them? */
56      String CATCH_ERRORS_KEY = "catch.errors";
57  
58      /*** Default: Yes */
59      boolean CATCH_ERRORS_DEFAULT = true;
60  
61      /***
62       * Process the request and fill in the template with the values
63       * you set in the Context.
64       *
65       * @param context A Context.
66       * @param template A String with the filename of the template.
67       * @return The process template as a String.
68       * @exception Exception a generic exception.
69       */
70      String handleRequest(Context context, String template)
71              throws Exception;
72  
73      /***
74       * Process the request and fill in the template with the values
75       * you set in the Context.
76       *
77       * @param context A Context.
78       * @param filename A String with the filename of the template.
79       * @param out A OutputStream where we will write the process template as
80       *        a String.
81       * @throws TurbineException Any exception trown while processing will be
82       *         wrapped into a TurbineException and rethrown.
83       */
84      void handleRequest(Context context, String filename, OutputStream out)
85              throws TurbineException;
86  
87      /***
88       * Process the request and fill in the template with the values
89       * you set in the Context.
90       *
91       * @param context A Context.
92       * @param filename A String with the filename of the template.
93       * @param writer A Writer where we will write the process template as
94       *        a String.
95       * @throws TurbineException Any exception trown while processing will be
96       *         wrapped into a TurbineException and rethrown.
97       */
98      void handleRequest(Context context, String filename, Writer writer)
99              throws TurbineException;
100 
101     /***
102      * Create an empty WebContext object.
103      *
104      * @return An empty WebContext object.
105      */
106     Context getContext();
107 
108     /***
109      * This method returns a new, empty Context object.
110      *
111      * @return A WebContext.
112      */
113     Context getNewContext();
114 
115     /***
116      * Create a Context from the RunData object.  Adds a pointer to
117      * the RunData object to the Context so that RunData is available in
118      * the templates.
119      *
120      * @param data The Turbine RunData object.
121      * @return A clone of the Context needed by Velocity.
122      */
123     Context getContext(RunData data);
124 
125     /***
126      * Performs post-request actions (releases context
127      * tools back to the object pool).
128      *
129      * @param context a Velocity Context
130      */
131     void requestFinished(Context context);
132 }