View Javadoc

1   package org.apache.turbine.services.velocity;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" and
29   *    "Apache Turbine" must not be used to endorse or promote products
30   *    derived from this software without prior written permission. For
31   *    written permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    "Apache Turbine", nor may "Apache" appear in their name, without
35   *    prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  import java.io.OutputStream;
58  import java.io.Writer;
59  
60  import org.apache.turbine.pipeline.PipelineData;
61  import org.apache.turbine.services.Service;
62  import org.apache.turbine.util.RunData;
63  import org.apache.turbine.util.TurbineException;
64  
65  import org.apache.velocity.context.Context;
66  
67  /***
68   * Implementations of the VelocityService interface.
69   *
70   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
71   * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
72   * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
73   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
74   * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
75   * @version $Id: VelocityService.java,v 1.12 2004/08/02 08:57:31 epugh Exp $
76   */
77  public interface VelocityService
78          extends Service
79  {
80      /*** The Service Name */
81      String SERVICE_NAME = "VelocityService";
82  
83      /*** Key for storing the Context in the RunData object */
84      String CONTEXT = "VELOCITY_CONTEXT";
85  
86      /*** The default extension of Velocity Pages */
87      String VELOCITY_EXTENSION = "vm";
88  
89      /*** The Key for storing the RunData Object in the Context */
90      String RUNDATA_KEY = "data";
91  
92      /*** The Key for storing the PipelineData Object in the Context */
93      String PIPELINEDATA_KEY = "pipelineData";
94      
95      /*** Shall we catch Velocity Errors and report them? */
96      String CATCH_ERRORS_KEY = "catch.errors";
97  
98      /*** Default: Yes */
99      boolean CATCH_ERRORS_DEFAULT = true;
100 
101     /***
102      * Process the request and fill in the template with the values
103      * you set in the Context.
104      *
105      * @param context A Context.
106      * @param template A String with the filename of the template.
107      * @return The process template as a String.
108      * @exception Exception a generic exception.
109      */
110     String handleRequest(Context context, String template)
111             throws Exception;
112 
113     /***
114      * Process the request and fill in the template with the values
115      * you set in the Context.
116      *
117      * @param context A Context.
118      * @param filename A String with the filename of the template.
119      * @param out A OutputStream where we will write the process template as
120      *        a String.
121      * @throws TurbineException Any exception trown while processing will be
122      *         wrapped into a TurbineException and rethrown.
123      */
124     void handleRequest(Context context, String filename, OutputStream out)
125             throws TurbineException;
126 
127     /***
128      * Process the request and fill in the template with the values
129      * you set in the Context.
130      *
131      * @param context A Context.
132      * @param filename A String with the filename of the template.
133      * @param writer A Writer where we will write the process template as
134      *        a String.
135      * @throws TurbineException Any exception trown while processing will be
136      *         wrapped into a TurbineException and rethrown.
137      */
138     void handleRequest(Context context, String filename, Writer writer)
139             throws TurbineException;
140 
141     /***
142      * Create an empty WebContext object.
143      *
144      * @return An empty WebContext object.
145      */
146     Context getContext();
147 
148     /***
149      * This method returns a new, empty Context object.
150      *
151      * @return A WebContext.
152      */
153     Context getNewContext();
154 
155     /***
156      * Create a Context from the RunData object.  Adds a pointer to
157      * the RunData object to the Context so that RunData is available in
158      * the templates.
159      *
160      * @param data The Turbine RunData object.
161      * @return A clone of the Context needed by Velocity.
162      */
163     Context getContext(RunData data);
164 
165     /***
166      * Create a Context from the RunData object.  Adds a pointer to
167      * the RunData object to the Context so that RunData is available in
168      * the templates.
169      *
170      * @param data The Turbine RunData object.
171      * @return A clone of the Context needed by Velocity.
172      */
173     Context getContext(PipelineData pipelineData);
174 
175     
176     
177     /***
178      * Performs post-request actions (releases context
179      * tools back to the object pool).
180      *
181      * @param context a Velocity Context
182      */
183     void requestFinished(Context context);
184 }