org.teatrove.tea.runtime
Interface Substitution

public interface Substitution

A block of code in a template that can be passed as a substitution to another template or to a function, must implement this interface. A function that defines its last parameter as a Substitution can receive a block of code from a template. To execute it, call substitute.

Substitution blocks can contain internal state information which may change when the called function returns. Therefore, Substitution objects should never be saved unless explicitly detached.

Functions that accept a Substitution appear to extend the template language itself. Condsider the following example, which implements a simple looping function:

 public void loop(int count, Substitution s) throws Exception {
     while (--count >= 0) {
         s.substitute();
     }
 }
 

The template might invoke this function as:

 loop (100) {
     "This message is printed 100 times\n"
 }
 

Author:

Brian S O'Neill

Method Summary

Substitution	detach() Returns a detached substitution that can be saved and re-used.
Object	getIdentifier() Returns an object that uniquely identifies this substitution block.
void	substitute() Causes the code substitution block to execute against its current output receiver.
void	substitute(Context context) Causes the code substitution block to execute against any context.

Method Detail

substitute

void substitute()
                throws Exception

Causes the code substitution block to execute against its current output receiver.

Throws:

UnsupportedOperationException - if this Substitution was detached.

Exception

substitute

void substitute(Context context)
                throws Exception

Causes the code substitution block to execute against any context.

Throws:

ClassCastException - if context is incompatible with this substitution.

Exception

getIdentifier

Object getIdentifier()

Returns an object that uniquely identifies this substitution block.

detach

Substitution detach()

Returns a detached substitution that can be saved and re-used. Detaching a substitution provides greater flexibilty when implementing template output caching strategies. One thread may execute the substitution while another thread may, upon timing out, output the previously cached output from this substitution.

When calling substitute, a context must be provided or else an UnsupportedOperationException is thrown. In order for multiple threads to safely execute this substitution, each must have its own detached instance.