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.TurbineServices;
23  import org.apache.turbine.util.RunData;
24  
25  import org.apache.velocity.context.Context;
26  
27  /***
28   * This is a simple static accessor to common Velocity tasks such as
29   * getting an instance of a context as well as handling a request for
30   * processing a template.
31   * <pre>
32   * Context context = TurbineVelocity.getContext(data);
33   * context.put("message", "Hello from Turbine!");
34   * String results = TurbineVelocity.handleRequest(context, "helloWorld.vm");
35   * data.getPage().getBody().addElement(results);
36   * </pre>
37   *
38   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
39   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
40   * @author <a href="mailto:jvanzyl@periapt.com.com">Jason van Zyl</a>
41   * @version $Id: TurbineVelocity.java 264148 2005-08-29 14:21:04Z henning $
42   */
43  public abstract class TurbineVelocity
44  {
45      /***
46       * Utility method for accessing the service
47       * implementation
48       *
49       * @return a VelocityService implementation instance
50       */
51      public static VelocityService getService()
52      {
53          return (VelocityService) TurbineServices
54                  .getInstance().getService(VelocityService.SERVICE_NAME);
55      }
56  
57      /***
58       * This allows you to pass in a context and a path to a template
59       * file and then grabs an instance of the velocity service and
60       * processes the template and returns the results as a String
61       * object.
62       *
63       * @param context A Context.
64       * @param template The path for the template files.
65       * @return A String.
66       * @exception Exception a generic exception.
67       */
68      public static String handleRequest(Context context, String template)
69              throws Exception
70      {
71          return getService().handleRequest(context, template);
72      }
73  
74      /***
75       * Process the request and fill in the template with the values
76       * you set in the Context.
77       *
78       * @param context A Context.
79       * @param template A String with the filename of the template.
80       * @param out A OutputStream where we will write the process template as
81       * a String.
82       * @exception Exception a generic exception.
83       */
84      public static void handleRequest(Context context, String template,
85                                       OutputStream out)
86              throws Exception
87      {
88          getService().handleRequest(context, template, out);
89      }
90  
91      /***
92       * Process the request and fill in the template with the values
93       * you set in the Context.
94       *
95       * @param context A Context.
96       * @param template A String with the filename of the template.
97       * @param writer A Writer where we will write the process template as
98       * a String.
99       * @exception Exception a generic exception.
100      */
101     public static void handleRequest(Context context,
102                                      String template,
103                                      Writer writer)
104             throws Exception
105     {
106         getService().handleRequest(context, template, writer);
107     }
108 
109     /***
110      * This returns a Context that you can pass into handleRequest
111      * once you have populated it with information that the template
112      * will know about.
113      *
114      * @param data A Turbine RunData.
115      * @return A Context.
116      */
117     public static Context getContext(RunData data)
118     {
119         return getService().getContext(data);
120     }
121 
122     /***
123      * This method returns a blank Context object, which
124      * also contains the global context object. Do not use
125      * this method if you need an empty context object! Use
126      * getNewContext for this.
127      *
128      * @return A WebContext.
129      */
130     public static Context getContext()
131     {
132         return getService().getContext();
133     }
134 
135     /***
136      * This method returns a new, empty Context object.
137      *
138      * @return A WebContext.
139      */
140     public static Context getNewContext()
141     {
142         return getService().getNewContext();
143     }
144 
145     /***
146      * Performs post-request actions (releases context
147      * tools back to the object pool).
148      *
149      * @param context a Velocity Context
150      */
151     public static void requestFinished(Context context)
152     {
153         getService().requestFinished(context);
154     }
155 }