    001    package 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
    024    import java.io.OutputStream;
    025    import java.io.Writer;
    026
    027    import org.apache.turbine.pipeline.PipelineData;
    028    import org.apache.turbine.services.Service;
    029    import org.apache.turbine.util.RunData;
    030    import org.apache.turbine.util.TurbineException;
    031
    032    import org.apache.velocity.context.Context;
    033
    034    /**
    035     * Implementations of the VelocityService interface.
    036     *
    037     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    038     * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
    039     * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
    040     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    041     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    042     * @version $Id: VelocityService.java 615328 2008-01-25 20:25:05Z tv $
    043     */
    044    public interface VelocityService
    045            extends Service
    046    {
    047        /** The Service Name */
    048        String SERVICE_NAME = "VelocityService";
    049
    050        /** Key for storing the Context in the RunData object */
    051        String CONTEXT = "VELOCITY_CONTEXT";
    052
    053        /** The default extension of Velocity Pages */
    054        String VELOCITY_EXTENSION = "vm";
    055
    056        /** The Key for storing the RunData Object in the Context */
    057        String RUNDATA_KEY = "data";
    058
    059        /** The Key for storing the PipelineData Object in the Context */
    060        String PIPELINEDATA_KEY = "pipelineData";
    061
    062        /** Shall we catch Velocity Errors and report them? */
    063        String CATCH_ERRORS_KEY = "catch.errors";
    064
    065        /** Default: Yes */
    066        boolean CATCH_ERRORS_DEFAULT = true;
    067
    068        /**
    069         * Process the request and fill in the template with the values
    070         * you set in the Context.
    071         *
    072         * @param context A Context.
    073         * @param template A String with the filename of the template.
    074         * @return The process template as a String.
    075         * @exception Exception a generic exception.
    076         */
    077        String handleRequest(Context context, String template)
    078                throws Exception;
    079
    080        /**
    081         * Process the request and fill in the template with the values
    082         * you set in the Context.
    083         *
    084         * @param context A Context.
    085         * @param filename A String with the filename of the template.
    086         * @param out A OutputStream where we will write the process template as
    087         *        a String.
    088         * @throws TurbineException Any exception trown while processing will be
    089         *         wrapped into a TurbineException and rethrown.
    090         */
    091        void handleRequest(Context context, String filename, OutputStream out)
    092                throws TurbineException;
    093
    094        /**
    095         * Process the request and fill in the template with the values
    096         * you set in the Context.
    097         *
    098         * @param context A Context.
    099         * @param filename A String with the filename of the template.
    100         * @param writer A Writer where we will write the process template as
    101         *        a String.
    102         * @throws TurbineException Any exception trown while processing will be
    103         *         wrapped into a TurbineException and rethrown.
    104         */
    105        void handleRequest(Context context, String filename, Writer writer)
    106                throws TurbineException;
    107
    108        /**
    109         * Create an empty WebContext object.
    110         *
    111         * @return An empty WebContext object.
    112         */
    113        Context getContext();
    114
    115        /**
    116         * This method returns a new, empty Context object.
    117         *
    118         * @return A WebContext.
    119         */
    120        Context getNewContext();
    121
    122        /**
    123         * Create a Context from the RunData object.  Adds a pointer to
    124         * the RunData object to the Context so that RunData is available in
    125         * the templates.
    126         *
    127         * @param data The Turbine RunData object.
    128         * @return A clone of the Context needed by Velocity.
    129         */
    130        Context getContext(RunData data);
    131
    132        /**
    133         * Create a Context from the RunData object.  Adds a pointer to
    134         * the RunData object to the Context so that RunData is available in
    135         * the templates.
    136         *
    137         * @param data The Turbine RunData object.
    138         * @return A clone of the Context needed by Velocity.
    139         */
    140        Context getContext(PipelineData pipelineData);
    141
    142
    143
    144        /**
    145         * Performs post-request actions (releases context
    146         * tools back to the object pool).
    147         *
    148         * @param context a Velocity Context
    149         */
    150        void requestFinished(Context context);
    151    }