com.go.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"
 }
 

Version:
15 , 01/05/03
Author:
Brian S O'Neill

Method Summary
 Substitution detach()
          Returns a detached substitution that can be saved and re-used.
 java.lang.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

public void substitute()
                throws java.lang.Exception
Causes the code substitution block to execute against its current output receiver.
Throws:
UnsupportedOperationException - if this Substitution was detached.

substitute

public void substitute(Context context)
                throws java.lang.Exception
Causes the code substitution block to execute against any context.
Throws:
java.lang.ClassCastException - if context is incompatible with this substitution.

getIdentifier

public java.lang.Object getIdentifier()
Returns an object that uniquely identifies this substitution block.

detach

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