    001package org.apache.turbine.services.velocity;
    002
    003
    004/*
    005 * Licensed to the Apache Software Foundation (ASF) under one
    006 * or more contributor license agreements.  See the NOTICE file
    007 * distributed with this work for additional information
    008 * regarding copyright ownership.  The ASF licenses this file
    009 * to you under the Apache License, Version 2.0 (the
    010 * "License"); you may not use this file except in compliance
    011 * with the License.  You may obtain a copy of the License at
    012 *
    013 *   http://www.apache.org/licenses/LICENSE-2.0
    014 *
    015 * Unless required by applicable law or agreed to in writing,
    016 * software distributed under the License is distributed on an
    017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    018 * KIND, either express or implied.  See the License for the
    019 * specific language governing permissions and limitations
    020 * under the License.
    021 */
    022
    023
    024import java.io.OutputStream;
    025import java.io.Writer;
    026
    027import org.apache.turbine.pipeline.PipelineData;
    028import org.apache.turbine.services.Service;
    029import org.apache.turbine.util.TurbineException;
    030import org.apache.velocity.context.Context;
    031
    032/**
    033 * Implementations of the VelocityService interface.
    034 *
    035 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    036 * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
    037 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
    038 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    039 * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    040 * @version $Id: VelocityService.java 1695634 2015-08-13 00:35:47Z tv $
    041 */
    042public interface VelocityService
    043        extends Service
    044{
    045    /** The Service Name */
    046    String SERVICE_NAME = "VelocityService";
    047
    048    /** Key for storing the Context in the RunData object */
    049    String CONTEXT = "VELOCITY_CONTEXT";
    050
    051    /** The default extension of Velocity Pages */
    052    String VELOCITY_EXTENSION = "vm";
    053
    054    /** The Key for storing the RunData Object in the Context */
    055    String RUNDATA_KEY = "data";
    056
    057    /** The Key for storing the PipelineData Object in the Context */
    058    String PIPELINEDATA_KEY = "pipelineData";
    059
    060    /** Shall we catch Velocity Errors and report them? */
    061    String CATCH_ERRORS_KEY = "catch.errors";
    062
    063    /** Default: Yes */
    064    boolean CATCH_ERRORS_DEFAULT = true;
    065
    066    /**
    067     * Process the request and fill in the template with the values
    068     * you set in the Context.
    069     *
    070     * @param context A Context.
    071     * @param template A String with the filename of the template.
    072     * @return The process template as a String.
    073     * @exception Exception a generic exception.
    074     */
    075    String handleRequest(Context context, String template)
    076            throws Exception;
    077
    078    /**
    079     * Process the request and fill in the template with the values
    080     * you set in the Context.
    081     *
    082     * @param context A Context.
    083     * @param filename A String with the filename of the template.
    084     * @param out A OutputStream where we will write the process template as
    085     *        a String.
    086     * @throws TurbineException Any exception thrown while processing will be
    087     *         wrapped into a TurbineException and rethrown.
    088     */
    089    void handleRequest(Context context, String filename, OutputStream out)
    090            throws TurbineException;
    091
    092    /**
    093     * Process the request and fill in the template with the values
    094     * you set in the Context.
    095     *
    096     * @param context A Context.
    097     * @param filename A String with the filename of the template.
    098     * @param writer A Writer where we will write the process template as
    099     *        a String.
    100     * @throws TurbineException Any exception thrown while processing will be
    101     *         wrapped into a TurbineException and rethrown.
    102     */
    103    void handleRequest(Context context, String filename, Writer writer)
    104            throws TurbineException;
    105
    106    /**
    107     * Create an empty WebContext object.
    108     *
    109     * @return An empty WebContext object.
    110     */
    111    Context getContext();
    112
    113    /**
    114     * This method returns a new, empty Context object.
    115     *
    116     * @return A WebContext.
    117     */
    118    Context getNewContext();
    119
    120    /**
    121     * Create a Context from the PipelineData object. Adds a pointer to
    122     * the PipelineData object to the Context so that PipelineData is available in
    123     * the templates.
    124     *
    125     * @param pipelineData The Turbine PipelineData object.
    126     * @return A clone of the Context needed by Velocity.
    127     */
    128    Context getContext(PipelineData pipelineData);
    129
    130    /**
    131     * Performs post-request actions (releases context
    132     * tools back to the object pool).
    133     *
    134     * @param context a Velocity Context
    135     */
    136    void requestFinished(Context context);
    137}