org.apache.turbine.services.velocity
Class TurbineVelocityService

java.lang.Object
  org.apache.turbine.services.BaseInitable
      org.apache.turbine.services.BaseService
          org.apache.turbine.services.TurbineBaseService
              org.apache.turbine.services.template.BaseTemplateEngineService
                  org.apache.turbine.services.velocity.TurbineVelocityService

All Implemented Interfaces:

org.apache.velocity.app.event.EventHandler, Initable, org.apache.velocity.app.event.MethodExceptionEventHandler, Service, TemplateEngineService, VelocityService

public class TurbineVelocityService

extends BaseTemplateEngineService

implements VelocityService, org.apache.velocity.app.event.MethodExceptionEventHandler

This is a Service that can process Velocity templates from within a Turbine Screen. It is used in conjunction with the templating service as a Templating Engine for templates ending in "vm". It registers itself as translation engine with the template service and gets accessed from there. After configuring it in your properties, it should never be necessary to call methods from this service directly. Here's an example of how you might use it from a screen:
Context context = TurbineVelocity.getContext(data);
context.put("message", "Hello from Turbine!");
String results = TurbineVelocity.handleRequest(context,"helloWorld.vm");
data.getPage().getBody().addElement(results);


Version:

$Id: TurbineVelocityService.java 552336 2007-07-01 16:33:47Z tv $

Author:

Dave Bryson, Rafal Krzewski, Jason van Zyl, Sean Legassick, Daniel Rall, Henning P. Schmiedehausen

Nested Class Summary

Nested classes inherited from class org.apache.velocity.app.event.MethodExceptionEventHandler

org.apache.velocity.app.event.MethodExceptionEventHandler.MethodExceptionExecutor

Field Summary

Fields inherited from class org.apache.turbine.services.BaseService

name, serviceBroker

Fields inherited from class org.apache.turbine.services.BaseInitable

initableBroker, isInitialized

Fields inherited from interface org.apache.turbine.services.velocity.VelocityService

CATCH_ERRORS_DEFAULT, CATCH_ERRORS_KEY, CONTEXT, RUNDATA_KEY, SERVICE_NAME, VELOCITY_EXTENSION

Fields inherited from interface org.apache.turbine.services.template.TemplateEngineService

DEFAULT_ERROR_SCREEN, DEFAULT_LAYOUT, DEFAULT_LAYOUT_TEMPLATE, DEFAULT_NAVIGATION, DEFAULT_NAVIGATION_TEMPLATE, DEFAULT_PAGE, DEFAULT_SCREEN, DEFAULT_SCREEN_TEMPLATE, DEFAULT_TEMPLATE_EXTENSION, TEMPLATE_EXTENSIONS

Constructor Summary

TurbineVelocityService()

Method Summary

org.apache.commons.collections.ExtendedProperties	createVelocityProperties(org.apache.commons.configuration.Configuration conf) This method generates the Extended Properties object necessary for the initialization of Velocity.
org.apache.velocity.context.Context	getContext() Create a Context object that also contains the globalContext.
org.apache.velocity.context.Context	getContext(RunData data) Create a Context from the RunData object.
org.apache.velocity.context.Context	getNewContext() This method returns a new, empty Context object.
java.lang.String	handleRequest(org.apache.velocity.context.Context context, java.lang.String filename) Process the request and fill in the template with the values you set in the Context.
void	handleRequest(org.apache.velocity.context.Context context, java.lang.String filename, java.io.OutputStream output) Process the request and fill in the template with the values you set in the Context.
void	handleRequest(org.apache.velocity.context.Context context, java.lang.String filename, java.io.Writer writer) Process the request and fill in the template with the values you set in the Context.
void	init() Load all configured components and initialize them.
void	init(javax.servlet.ServletConfig config) Deprecated. use init() instead.
java.lang.Object	methodException(java.lang.Class clazz, java.lang.String method, java.lang.Exception e) MethodException Event Cartridge handler for Velocity.
void	requestFinished(org.apache.velocity.context.Context context) Performs post-request actions (releases context tools back to the object pool).
boolean	templateExists(java.lang.String template) Find out if a given template exists.

Methods inherited from class org.apache.turbine.services.template.BaseTemplateEngineService

getAssociatedFileExtensions, getTemplateEngineServiceConfiguration, initConfiguration, registerConfiguration

Methods inherited from class org.apache.turbine.services.TurbineBaseService

init, init, shutdown

Methods inherited from class org.apache.turbine.services.BaseService

getConfiguration, getName, getProperties, getServiceBroker, setName, setServiceBroker

Methods inherited from class org.apache.turbine.services.BaseInitable

getInit, getInitableBroker, setInit, setInitableBroker

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.turbine.services.Service

getConfiguration, getName, getProperties, setName, setServiceBroker

Methods inherited from interface org.apache.turbine.services.Initable

getInit, init, setInitableBroker, shutdown

Constructor Detail

TurbineVelocityService

public TurbineVelocityService()

Method Detail

init

public void init()
          throws InitializationException

Load all configured components and initialize them. This is a zero parameter variant which queries the Turbine Servlet for its config.

Specified by:

init in interface Initable

Overrides:

init in class TurbineBaseService

Throws:

InitializationException - Something went wrong in the init stage

init

public void init(javax.servlet.ServletConfig config)
          throws InitializationException

Deprecated. use init() instead.

Inits the service using servlet parameters to obtain path to the configuration file.

Overrides:

init in class TurbineBaseService

Parameters:

config - The ServletConfiguration from Turbine

Throws:

InitializationException - Something went wrong when starting up.

getContext

public org.apache.velocity.context.Context getContext()

Create a Context object that also contains the globalContext.

Specified by:

getContext in interface VelocityService

Returns:

A Context object.

getNewContext

public org.apache.velocity.context.Context getNewContext()

This method returns a new, empty Context object.

Specified by:

getNewContext in interface VelocityService

Returns:

A Context Object.

methodException

public java.lang.Object methodException(java.lang.Class clazz,
                                        java.lang.String method,
                                        java.lang.Exception e)
                                 throws java.lang.Exception

MethodException Event Cartridge handler for Velocity. It logs an execption thrown by the velocity processing on error level into the log file

Specified by:

methodException in interface org.apache.velocity.app.event.MethodExceptionEventHandler

Parameters:

clazz - The class that threw the exception

method - The Method name that threw the exception

e - The exception that would've been thrown

Returns:

A valid value to be used as Return value

Throws:

java.lang.Exception - We threw the exception further up

getContext

public org.apache.velocity.context.Context getContext(RunData data)

Create a Context from the RunData object. Adds a pointer to the RunData object to the VelocityContext so that RunData is available in the templates.

Specified by:

getContext in interface VelocityService

Parameters:

data - The Turbine RunData object.

Returns:

A clone of the WebContext needed by Velocity.

handleRequest

public java.lang.String handleRequest(org.apache.velocity.context.Context context,
                                      java.lang.String filename)
                               throws TurbineException

Process the request and fill in the template with the values you set in the Context.

Specified by:

handleRequest in interface VelocityService

Parameters:

context - The populated context.

filename - The file name of the template.

Returns:

The process template as a String.

Throws:

TurbineException - Any exception trown while processing will be wrapped into a TurbineException and rethrown.

handleRequest

public void handleRequest(org.apache.velocity.context.Context context,
                          java.lang.String filename,
                          java.io.OutputStream output)
                   throws TurbineException

Process the request and fill in the template with the values you set in the Context.

Specified by:

handleRequest in interface VelocityService

Parameters:

context - A Context.

filename - A String with the filename of the template.

output - A OutputStream where we will write the process template as a String.

Throws:

TurbineException - Any exception trown while processing will be wrapped into a TurbineException and rethrown.

handleRequest

public void handleRequest(org.apache.velocity.context.Context context,
                          java.lang.String filename,
                          java.io.Writer writer)
                   throws TurbineException

Process the request and fill in the template with the values you set in the Context.

Specified by:

handleRequest in interface VelocityService

Parameters:

context - A Context.

filename - A String with the filename of the template.

writer - A Writer where we will write the process template as a String.

Throws:

TurbineException - Any exception trown while processing will be wrapped into a TurbineException and rethrown.

createVelocityProperties

public org.apache.commons.collections.ExtendedProperties createVelocityProperties(org.apache.commons.configuration.Configuration conf)
                                                                           throws java.lang.Exception

This method generates the Extended Properties object necessary for the initialization of Velocity. It also converts the various resource loader pathes into webapp relative pathes. It also

Parameters:

conf - The Velocity Service configuration

Returns:

An ExtendedProperties Object for Velocity

Throws:

java.lang.Exception - If a problem occured while converting the properties.

templateExists

public boolean templateExists(java.lang.String template)

Find out if a given template exists. Velocity will do its own searching to determine whether a template exists or not.

Specified by:

templateExists in interface TemplateEngineService

Specified by:

templateExists in class BaseTemplateEngineService

Parameters:

template - String template to search for

Returns:

True if the template can be loaded by Velocity

See Also:

TemplateEngineService.templateExists(java.lang.String)

requestFinished

public void requestFinished(org.apache.velocity.context.Context context)

Performs post-request actions (releases context tools back to the object pool).

Specified by:

requestFinished in interface VelocityService

Parameters:

context - a Velocity Context