View Javadoc

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