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    }