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$
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     * @throws 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}