org.apache.turbine.services.webmacro
Class TurbineWebMacroService

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.webmacro.TurbineWebMacroService

All Implemented Interfaces:

Initable, Service, TemplateEngineService, WebMacroService

public class TurbineWebMacroService

extends BaseTemplateEngineService

implements WebMacroService

This is a Service that can process WebMacro templates from within a Turbine Screen. Here's an example of how you might use it from a screen:
WebContext context = WebMacro.getContext(data);
context.put("message", "Hello from Turbine!");
String results = WebMacro.handleRequest(context,"helloWorld.wm");
data.getPage().getBody().addElement(results);


Multiple template paths are specified via the services.TurbineWebMacroService.templates property in the TurbineResources.properties file, specified as a single string delimited by the value of the System property path.separator (this is : on UNIX and ; on Windows).

Turbine does not use the default ResourceProvider for WebMacro ResourceEvents of type template. Instead, Turbine uses its own TurbineTemplateProvider implementation.

Version:

$Id$

Author:

Dave Bryson, Rafal Krzewski, Daniel Rall, Jason van Zyl

Field Summary

private org.webmacro.Broker	broker The broker used by WebMacro to retrieve resources.
protected static java.lang.String	DEFAULT_ENCODING The default encoding used by the WebMacro FastWriter.
private java.lang.String[]	templatePaths Paths where templates can be located.
private org.webmacro.servlet.WebContext	wcPrototype The context used as a factory.
private org.webmacro.WebMacro	wm The WebMacro engine.
private java.lang.String	WMProperties Webmacro properties file.
private java.lang.String	WMTemplateProvider WebMacro template provider.

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

configuration

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

name, properties, serviceBroker

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

initableBroker, isInitialized

Fields inherited from interface org.apache.turbine.services.webmacro.WebMacroService

SERVICE_NAME, WEBMACRO_CONTEXT

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

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

Constructor Summary

TurbineWebMacroService()

Method Summary

org.webmacro.servlet.WebContext	getContext() Create an empty WebContext object.
org.webmacro.servlet.WebContext	getContext(RunData data) Create a WebContext from the RunData object.
org.webmacro.Template	getTemplate(java.lang.String filename) Return a template from WebMacro.
java.lang.String	handleRequest(org.webmacro.servlet.WebContext wc, java.lang.String filename) Process the request and fill in the template with the values you set in the WebContext.
void	handleRequest(org.webmacro.servlet.WebContext wc, java.lang.String filename, org.webmacro.FastWriter writer) Process the request and fill in the template with the values you set in the WebContext.
void	handleRequest(org.webmacro.servlet.WebContext wc, java.lang.String filename, java.io.OutputStream out) Process the request and fill in the template with the values you set in the WebContext.
void	init(javax.servlet.ServletConfig unused) Performs early initialization of this service.
private void	initWebContext() This method must return a cloneable WebContext which can be cloned for use in responding to individual requests.
private void	initWebMacro() This method returns the WebMacro object which will be used to load, access, and manage the Broker.
void	shutdown() Shuts down the service, including its WebMacro engine.
boolean	templateExists(java.lang.String template) Determine whether 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, init

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, registerNatives, toString, wait, wait, wait

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

getConfiguration, getProperties, setName, setServiceBroker

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

getInit, init, init, setInitableBroker

Field Detail

DEFAULT_ENCODING

protected static final java.lang.String DEFAULT_ENCODING

The default encoding used by the WebMacro FastWriter.

We should encode the ouput byte stream as UTF-16 to achieve the fastest conversion back to Java characters, but for some reason this does not work (bug in FastWriter?). UTF-8 seems to work and is used as a fallback option.

wm

private org.webmacro.WebMacro wm

The WebMacro engine.

wcPrototype

private org.webmacro.servlet.WebContext wcPrototype

The context used as a factory.

broker

private org.webmacro.Broker broker

The broker used by WebMacro to retrieve resources.

templatePaths

private java.lang.String[] templatePaths

Paths where templates can be located.

WMProperties

private java.lang.String WMProperties

Webmacro properties file.

WMTemplateProvider

private java.lang.String WMTemplateProvider

WebMacro template provider.

Constructor Detail

TurbineWebMacroService

public TurbineWebMacroService()

Method Detail

init

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

Performs early initialization of this service.

Overrides:

init in class TurbineBaseService

Throws:

InitializationException - Caused by any initialization error.

shutdown

public void shutdown()

Shuts down the service, including its WebMacro engine.

Specified by:

shutdown in interface Initable

Overrides:

shutdown in class TurbineBaseService

getContext

public org.webmacro.servlet.WebContext getContext()

Create an empty WebContext object.

Specified by:

getContext in interface WebMacroService

Returns:

A new, empty context.

getContext

public org.webmacro.servlet.WebContext getContext(RunData data)

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

Specified by:

getContext in interface WebMacroService

Parameters:

data - The Turbine RunData object.

Returns:

A clone of the WebContext needed by WebMacro.

handleRequest

public java.lang.String handleRequest(org.webmacro.servlet.WebContext wc,
                                      java.lang.String filename)
                               throws TurbineException

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

Specified by:

handleRequest in interface WebMacroService

Parameters:

wc - 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.webmacro.servlet.WebContext wc,
                          java.lang.String filename,
                          java.io.OutputStream out)
                   throws java.lang.Exception

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

Specified by:

handleRequest in interface WebMacroService

Parameters:

wc - The populated context.

filename - The file name of the template.

out - A stream to write the processed template to.

Throws:

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

handleRequest

public void handleRequest(org.webmacro.servlet.WebContext wc,
                          java.lang.String filename,
                          org.webmacro.FastWriter writer)
                   throws java.lang.Exception

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

Specified by:

handleRequest in interface WebMacroService

Parameters:

wc - The populated context.

filename - The file name of the template.

writer - A writer to write the processed template with.

Throws:

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

getTemplate

public org.webmacro.Template getTemplate(java.lang.String filename)
                                  throws org.webmacro.NotFoundException

Return a template from WebMacro.

Specified by:

getTemplate in interface WebMacroService

Parameters:

filename - A String with the name of the template.

Returns:

A Template.

Throws:

org.webmacro.NotFoundException - The template could not be found.

initWebMacro

private void initWebMacro()
                   throws org.webmacro.InitException,
                          InitializationException

This method returns the WebMacro object which will be used to load, access, and manage the Broker. The WM first tries to locate the WebMacro properties file in the location specified by the 'services.WebmacroService.properties' key in the TurbineResource file. If the key is not set, it will search the classpath looking for the file.

Parameters:

config - A ServletConfig.

Throws:

org.webmacro.InitException - Thrown by WebMacro.

InitializationException - Thrown by Turbine.

initWebContext

private void initWebContext()
                     throws org.webmacro.InitException

This method must return a cloneable WebContext which can be cloned for use in responding to individual requests. Each incoming request will receive a clone of the returned object as its context. The default implementation is to return a new WebContext.

Throws:

InitException. -

templateExists

public boolean templateExists(java.lang.String template)

Determine whether a given template exists. This service currently only supports file base template hierarchies so we will use the utility methods provided by the template service to do the searching.

Overrides:

templateExists in class BaseTemplateEngineService

Parameters:

String - template

Returns:

boolean