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