View Javadoc

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