sunlabs.brazil.tcl
Class TclServerTemplate

java.lang.Object
  sunlabs.brazil.template.Template
      sunlabs.brazil.tcl.TclServerTemplate (view source)

All Implemented Interfaces:

TemplateInterface

public class TclServerTemplate
extends Template

The TclServerTemplate looks for each <server language="tcl"> (or <"tcl">) tag in an HTML page and treats the following data up to the next </server> tag as a Tcl script to evaluate. If the optional attribute eval is present, the all ${...} constructs are replaced using Format.subst(java.util.Dictionary, java.lang.String) before being passed to the Tcl interpreter.

The reason that Tcl scripts are included in an HTML page is usually to generate dynamic, server-side content. After running this template, everything between and including the <server> and </server> tags is replaced with the result of evaluating the Tcl script as follows:

• Anything printed to the standard output of the Tcl interpreter is added to the HTML document (for instance, puts "hello").
• Additionally, if the Tcl script returns a value, that value is added to the HTML document (for instance, return "bob").

Multiple puts and a final return can both be used within a single Tcl fragment.

All Tcl fragments within a given page are evaluated in the same Tcl interpreter. The Tcl interpreter actually lives for the entire duration of this Template object, so the user can implement persistence across requests.

The following configuration parameters are used to initialize this template.

script

The name of the Tcl script to evaluate when the interpreter is created. This script only evaluated when the interp is created, not on every request. The variables prefix and server are set before this file is evaluated, and are references to the parameters passed to a handler init method.

root

The document root, if the script is a relative file name. If the "root" property under the template prefix is not found, the global "root" property is used. If the global "root" property is not found, the current directory is used.

debug

If this configuration parameter is present, this class replaces the <server> and </server> tags with comments, so the user can keep track of where the dynamically generated content is coming from by examining the comments in the resultant HTML document. By default, the <server> and </server> are completely eliminated from the HTML document rather than changed into comments.

Before evaluating each HTML document, this class variables in the Tcl interpreter, which can be used to interact back with Java to do things like set the response headers:

request

Exposes the Request Java object. It is set anew at each request.

prefix

Exposes the handler prefix String.

server

Exposes the handler Server object.

SessionId

Exposes the session id for this interp, or "none".

If a serialized version of this object is reconstituted, the init method must be called again.

Constructor Summary

TclServerTemplate()

Method Summary

boolean	done(RewriteContext hr) Called after the HTML document has been processed.
boolean	init(RewriteContext hr) Defer setting up the interpreter until its first use.
boolean	setup(RewriteContext hr) Called at the first tcl code in the document TclServerTemplate is asked to process.
void	tag_server(RewriteContext hr) Processes the <server> tag.
void	tag_tcl(RewriteContext hr) Processes the <tcl> tag.

Methods inherited from class java.lang.Object

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

Constructor Detail

TclServerTemplate

public TclServerTemplate()

Method Detail

init

public boolean init(RewriteContext hr)

Defer setting up the interpreter until its first use. This way we don't initialize a tcl interp (a heavyweight operation) until its actually needed.

Specified by:

init in interface TemplateInterface

Overrides:

init in class Template

setup

public boolean setup(RewriteContext hr)

Called at the first tcl code in the document TclServerTemplate is asked to process.

Redirects the standard output of the Tcl interpreter to the resultant HTML document and exposes the Request object as a Tcl variable.

The first time this method is called, the initialization script is sourced into the interpreter, based on the configuration properties in the Request

Parameters:

hr - The request and associated HTML document that will be processed.

Returns:

true interpreter was successfully initialized false otherwise. About the only way that the initialization could fail would be

1. there was an error sourcing the initialization script.
2. if this class previously evaluated a Tcl fragment that redefined the scalar Tcl variables request or server as array variables.

If false is returned, an error message is logged.

done

public boolean done(RewriteContext hr)

Called after the HTML document has been processed.

Releases the resources allocated by init. This method should be called to ensure that the HtmlRewriter and all its attendant data structures are not preserved indefinitely (until the next request).

Specified by:

done in interface TemplateInterface

Overrides:

done in class Template

Parameters:

hr - The request and associated HTML document that was processed.

Returns:

true always, indicating that this document was successfully processed to completion.

tag_server

public void tag_server(RewriteContext hr)

Processes the <server> tag. Substitues the result of evaluating the following Tcl script into the resultant HTML document.

Note: Currently, there is no mechanism for other language interpreters to share the same server tag. Use the <tcl> tag instead.

Parameters:

hr - The request and associated HTML document that will be processed.

tag_tcl

public void tag_tcl(RewriteContext hr)

Processes the <tcl> tag. Substitues the result of evaluating the following Tcl script into the resultant HTML document.

Parameters:

hr - The request and associated HTML document that will be processed.