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