org.webmacro.util
Class WMEval

java.lang.Object
  org.webmacro.util.WMEval

public class WMEval

extends java.lang.Object

WMEval encapsulates an instance of WebMacro for reuse in any java application.

Its main benefit are a number of convenience methods for evaluating a template and directing output either to a supplied output stream or to a file.

It can parse a single template stream and then evaluate that template over a number of different contexts. And, it can maintain a single context and evaluate different templates over the same context. Each time a context or a template is provided, it is retained as state.

The context can therefore be preserved over multiple "writes" of different templates.

The template stream can be any text stream but is often a rule stream containing wm script directives.

This helper class is useful for evaluating WebMacro templates for which flexibility in managing the evaluation options is key.

Version:

3.0

Author:

Lane Sharman

Field Summary

static java.lang.String

outputContextKey If an output file is not specified as an argument, it must be found in the context under this key.

Constructor Summary

WMEval()

WMEval(javax.servlet.Servlet servlet)
The constructor for WebMacro decorator in a servlet context.

Method Summary

void	destroy() Free up resources when no longer needed.
void	error(java.lang.String msg, java.lang.Exception e)
void	eval() Evaluates the context of this instance and the instance's current template and current output stream using UTF8.
java.lang.String	eval(Context context) Evaluate the context supplied against the current template.
java.lang.String	eval(Context context, java.lang.String templateName, java.io.OutputStream out) Evaluates the string template against the current context and returns the value.
java.lang.String	eval(Context context, java.lang.String templateName, java.io.OutputStream out, java.lang.String encoding) Evaluates the context using a file template sending the output to a disk file.
java.lang.String	eval(Context context, java.lang.String templateName, java.lang.String outputFileName, boolean append, java.lang.String encoding) Evaluates the current context for the input file and writes it to the output file.
java.lang.String	eval(Context context, Template template) Evaluate the supplied context and template and return the result as a as a string.
java.lang.String	eval(java.lang.String templateName) Evaluates the string template against the current context and returns the value.
java.lang.String	eval(WebContext context, java.lang.String templateName, javax.servlet.http.HttpServletResponse resp) Evaluates the string template against a new context and writes it to the http Response output stream using the proper encoding.
Context	getCurrentContext() Gets the current context.
Template	getCurrentTemplate() Gets the current template.
Log	getLog() Return the log associated with this instance of WMEval.
Context	getNewContext() Provides for a new context to be established.
WebContext	getNewContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
Settings	getSettings() Return the settings associated with this WebMacro instance.
Template	init(java.io.InputStream template) Initializes WMEval so that it can perform currentTemplate evaluation on multiple contexts.
Template	parseLocalTemplate(java.lang.String templateName) A convenience method to find and parse a template in the local template path.
void	setCurrentContext(Context c) Supplies a context to be parsed currentTemplate directly.
void	setCurrentTemplate(Template parsedTemplate) Supplies the parsed currentTemplate directly.
void	setOutputStream(java.io.OutputStream out) Sets the output stream to be different than the default, System.out.

Methods inherited from class java.lang.Object

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

Field Detail

outputContextKey

public static final java.lang.String outputContextKey

If an output file is not specified as an argument, it must be found in the context under this key.

See Also:

Constant Field Values

Constructor Detail

WMEval

public WMEval(javax.servlet.Servlet servlet)

The constructor for WebMacro decorator in a servlet context.

WMEval

public WMEval()

Method Detail

getSettings

public Settings getSettings()

Return the settings associated with this WebMacro instance.

getLog

public Log getLog()

Return the log associated with this instance of WMEval.

init

public Template init(java.io.InputStream template)
              throws java.lang.Exception

Initializes WMEval so that it can perform currentTemplate evaluation on multiple contexts. Init parses the currentTemplate supplied.

The argument to init() is the currentTemplate as a stream allowing the currentTemplate to come from pretty much anywhere such as a url, a file, or a db field.

Care must be given to the fact that in parsing the currentTemplate, th current vm is able to resolve locations of other currentTemplates referenced within the supplied currentTemplate.

Note, once this is complete, the parsed currentTemplate can be applied to successive new object contexts. In other words, the application context can assert new objects for currentTemplate application and remove others.

Parameters:

template - The stream containing the top-level, unparsed currentTemplate.

Throws:

java.lang.Exception

error

public void error(java.lang.String msg,
                  java.lang.Exception e)

getNewContext

public Context getNewContext()

Provides for a new context to be established.

getNewContext

public WebContext getNewContext(javax.servlet.http.HttpServletRequest req,
                                javax.servlet.http.HttpServletResponse resp)

getCurrentContext

public Context getCurrentContext()

Gets the current context.

getCurrentTemplate

public Template getCurrentTemplate()

Gets the current template.

parseLocalTemplate

public Template parseLocalTemplate(java.lang.String templateName)
                            throws java.lang.Exception

A convenience method to find and parse a template in the local template path.

Throws:

java.lang.Exception

setCurrentTemplate

public void setCurrentTemplate(Template parsedTemplate)

Supplies the parsed currentTemplate directly.

Parameters:

parsedTemplate - The currentTemplate parsed possibly from a previous run.

setCurrentContext

public void setCurrentContext(Context c)

Supplies a context to be parsed currentTemplate directly.

Parameters:

c - The context to be used for the evaluation.

setOutputStream

public void setOutputStream(java.io.OutputStream out)

Sets the output stream to be different than the default, System.out.

Parameters:

out - The new output stream for any output during currentTemplate evaluation.

eval

public void eval()
          throws java.lang.Exception

Evaluates the context of this instance and the instance's current template and current output stream using UTF8.

Throws:

java.lang.Exception

eval

public java.lang.String eval(Context context)
                      throws java.lang.Exception

Evaluate the context supplied against the current template.

Parameters:

context - The WebMacro context.

Throws:

java.lang.Exception

eval

public java.lang.String eval(Context context,
                             java.lang.String templateName,
                             java.io.OutputStream out)
                      throws java.lang.Exception

Evaluates the string template against the current context and returns the value. If an output stream is specified, the value is written out as well to this stream.

Parameters:

templateName - The name of the template.

out - An optional output stream.

Returns:

The output from the evaluated template

Throws:

java.lang.Exception

eval

public java.lang.String eval(java.lang.String templateName)
                      throws java.lang.Exception

Evaluates the string template against the current context and returns the value.

Parameters:

templateName - The name of the template.

Returns:

The output from the evaluated template

Throws:

java.lang.Exception

eval

public java.lang.String eval(WebContext context,
                             java.lang.String templateName,
                             javax.servlet.http.HttpServletResponse resp)
                      throws javax.servlet.ServletException

Evaluates the string template against a new context and writes it to the http Response output stream using the proper encoding.

This is an exceptionally useful method for a servlet to use to write out a template.

Parameters:

context - The WM context to use.

templateName - The name of the template.

resp - The servlet response from which the encoding will be derived.

Returns:

The output from the evaluated template.

Throws:

javax.servlet.ServletException

eval

public java.lang.String eval(Context context,
                             Template template)
                      throws java.lang.Exception

Evaluate the supplied context and template and return the result as a as a string.

Throws:

java.lang.Exception

eval

public java.lang.String eval(Context context,
                             java.lang.String templateName,
                             java.io.OutputStream out,
                             java.lang.String encoding)
                      throws java.lang.Exception

Evaluates the context using a file template sending the output to a disk file.

This method is the preferred method when an output stream is to be written as well as the value of the string is to be returned.

Parameters:

context - The context to use.

templateName - The input template file in the resource path.

out - The output stream. If null, an attempt will be made to locate the outputstream in the context using the output stream key if in the context. If no output stream can be resolved, the method does not throw an exception.

encoding - If null, the platform's encoding will be used.

Returns:

The output from the evaluation of the template.

Throws:

java.lang.Exception

eval

public java.lang.String eval(Context context,
                             java.lang.String templateName,
                             java.lang.String outputFileName,
                             boolean append,
                             java.lang.String encoding)
                      throws java.lang.Exception

Evaluates the current context for the input file and writes it to the output file.

Throws:

java.lang.Exception

destroy

public void destroy()

Free up resources when no longer needed.