org.webmacro.util
Class WMEval

java.lang.Object
  extended byorg.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 rule over a number of different contexts. And, it can maintain a single context and evaluate different templates over the same context.

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.

A template, once parsed, can be preserved and made available using setRule() and getRule().

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

Note: All uses of the method assert(argList) should be converted to eval(argList) in anticipation of jdk 1.4.

Version:
2.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()
          Deprecated.  
 void eval(Context context)
          Evaluate the context supplied against the current rule.
 java.lang.String eval(Context context, java.lang.String templateResourceFile, java.lang.String outputFileName, boolean append, java.lang.String encoding)
          Evaluates the context using a file template sending the output to a disk file.
 java.lang.String eval(Context context, Template rule)
          Evaluate the supplied context and template and return the result as a as a string.
 void eval(Context context, Template rule, java.io.OutputStream out, java.lang.String encoding)
          Evaluate the supplied context and template to the provided output.
 java.lang.String eval(java.lang.String templateName)
          Evaluates the string template against the current context and returns the value.
 void eval(java.lang.String templateName, javax.servlet.http.HttpServletRequest req, 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.
 java.lang.String eval(java.lang.String templateName, java.io.OutputStream out)
          Evaluates the string template against the current context and returns the value.
 Context getCurrentContext()
          Gets the current context.
 Context getNewContext()
          Provides for a new context to be established.
 Template getRule()
          Obtain the parsed rule possibly for reuse in another run.
 Template init(java.io.InputStream unparsedRule)
          Initializes WMEval so that it can perform rule 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 setOutputStream(java.io.OutputStream out)
          Sets the output stream to be different than the default, System.out.
 void setParsedTemplate(Template parsedTemplate)
          Supplies the parsed rule directly.
 
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

init

public Template init(java.io.InputStream unparsedRule)
              throws java.lang.Exception
Initializes WMEval so that it can perform rule evaluation on multiple contexts. Init parses the rule supplied.

The argument to init() is the rule as a stream allowing the rule 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 rule, th current vm is able to resolve locations of other rules referenced within the supplied rule.

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

Parameters:
unparsedRule - The stream containing the top-level, unparsed rule.
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.


getCurrentContext

public Context getCurrentContext()
Gets the current context.


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

setParsedTemplate

public void setParsedTemplate(Template parsedTemplate)
Supplies the parsed rule directly.

Parameters:
parsedTemplate - The rule parsed possibly from a previous run.

getRule

public Template getRule()
Obtain the parsed rule possibly for reuse in another run.

Returns:
The rule parsed which can be resupplied in another run.

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 rule evaluation.

eval

public void eval()
          throws java.lang.Exception
Deprecated.  

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

Throws:
java.lang.Exception

eval

public void eval(Context context)
          throws java.lang.Exception
Evaluate the context supplied against the current rule.

Parameters:
context - The map containing the referents to assertable, rule-driven objects.
Throws:
java.lang.Exception

eval

public void eval(Context context,
                 Template rule,
                 java.io.OutputStream out,
                 java.lang.String encoding)
          throws java.lang.Exception
Evaluate the supplied context and template to the provided output.

Throws:
java.lang.Exception

eval

public java.lang.String eval(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 file is specified, the value is written out as well.

Parameters:
templateName - The name of the template.
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 void eval(java.lang.String templateName,
                 javax.servlet.http.HttpServletRequest req,
                 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.

Note: This method places "FastWriter" in the context so you can write out to the stream.

Parameters:
templateName - The name of the template.
Returns:
The output from the evaluated template
Throws:
javax.servlet.ServletException

eval

public java.lang.String eval(Context context,
                             Template rule)
                      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 templateResourceFile,
                             java.lang.String outputFileName,
                             boolean append,
                             java.lang.String encoding)
                      throws java.lang.Exception
Evaluates the context using a file template sending the output to a disk file.

Parameters:
context - The context to use.
templateResourceFile - The input template file in the resource path.
outputFileName - The absolute path to a file. If null, the context key OutputFileName must be present.
append - If true, the file will be opened for appending the output.
encoding - If null, the platform's encoding will be used.
Returns:
The output is also returned as a convenience.
Throws:
java.lang.Exception

destroy

public void destroy()
Free up resources when no longer needed.