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 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()
          The constructor which creates the environment for evaluating a rule.
 
Method Summary
 void assert()
          Deprecated.  
 void assert(Context context)
          Deprecated.  
 java.lang.String assert(Context context, Template rule)
          Evaluate the supplied context and template and return the result as a as a string.
 void assert(Context context, Template rule, java.io.OutputStream out, java.lang.String encoding)
          Deprecated.  
 void destroy()
          Free up resources when no longer needed.
 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.
 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.
Constructor Detail

WMEval

public WMEval()
The constructor which creates the environment for evaluating a rule.
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.

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.

setParsedTemplate

public void setParsedTemplate(Template parsedTemplate)
Supplies the parsed rule directly.
Parameters:
parsedRule - 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.

assert

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


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.

assert

public void assert(Context context)
            throws java.lang.Exception
Deprecated.  


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.

assert

public void assert(Context context,
                   Template rule,
                   java.io.OutputStream out,
                   java.lang.String encoding)
            throws java.lang.Exception
Deprecated.  


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.

assert

public java.lang.String assert(Context context,
                               Template rule)
                        throws java.lang.Exception
Evaluate the supplied context and template and return the result as a as a string.

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.

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.
inputTemplateFileName - 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.

destroy

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