sunlabs.brazil.template
Class SetTemplate

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

All Implemented Interfaces:

Serializable, Handler, TemplateInterface

Direct Known Subclasses:

MultipartSetTemplate

public class SetTemplate
extends Template
implements Serializable, Handler

Template (and handler) class for setting and getting values to and from the current (or other) request context. This class is used by the TemplateHandler. The following tags are processed by this class:

• <set name=.. [value=..] [namespace=..]>
• <get name=.. [default=..] [namespace=..] [max=nnn] [convert=html|url|none] [set=..]>
• <namespace name=.. [clear] [remove] [store=xxx] [load=xxx]>
• <import namespace=.. />
• <unimport namespace=.. />
• <tag [name=..]>
• </tag>

The tag<set> is processed with the following attributes:

name=value

The name of the entry to set in the request properties.

value=value

The value to store in the property. If this option is not specified, then the existing value for this property will be removed.

default=other

If default is specified and the specified value was the empty string "", then store this other value in the property instead. other is only evaluated in this case.

local

By default, variables are set (or removed from) a namespace that is persistent across all requests for the same session. If local is specified, the values only remain for the duration of the current request. [Deprecated - use namespace=local]

namespace

The namespace to use to set or delete the property. The default is namespace=${SessionID}, unless set is inside the scope of an enclosing namespace tag. Namespaces are used to define variable scopes that may be managed explicitly in template pages.

Two namespaces are treated specially:

• local
  may be used to set (or clear) values from request.props.
• server
  may be used to set (or clear) values from server.props, unless "noserver" is defined in which case hte "Server" namespace is not treated specially.

The <namespace>..</namespace> tag pairs are used to specify a default namespace other than the SessionId for the set and import tags or manipulate a namespace. When a namespace is in effect, the request property [prefix].namespace is set to the current namespace, where [prefix] is the RewriteContext.templatePrefix. This permits other templates (such as the ListTemplate) to use the current namespace setting. These tags don't nest.

attributes for namespace:

name=value

The default namespace to use for the set and import default namespace name.

clear

If set, namespace name is cleared.

remove

If set, namespace name is removed.

load=file_name

If specified, and the property saveOk is set, then the specified namespace will be saved loaded from a file in java properties format. Relative path names are resolved with respect to the document root.

store=file_name

If specified, and the property saveOk is set, then the specified namespace will be stored to a file in java properties format. Relative path names are resolved with respect to the document root.

When using load or store, the namespace names "local" and "server" are treated specially, referring to "request.props" and "server.props" respectively.

The tag<import> (and <unimport>) are processed with the following attributes:

namespace=value

The name/value pairs assiciated with the namespace are made available for the remainder of the page.

The "unimport" taq should probably be replaced by <import>

The "get" (formerly property) tag has the following attributes:

name

The name of the variable to get

namespace

The namespace to look in. By default, the variable is searched for in "request.props"

default

The value to use if no value matches "name".

convert

The conversion to perform on the value of the data before substitution: "html", "url", "lower, "trim", or "none" (the default). For "html", any special html syntax is escaped. For "url", the data will be suitable for transmission as an http URL. The "lower" and "trim" options convert to lowercase and remove leading and trailing whitespace, respectively.

max

The output is truncated to at most max characters.

If a single attribute is specified, with no "=", then is is taken to be the "name" parameter. Thus: <get foo> is equivalent to: <get name="foo">.

Request Properties:

sessionTable

The name of the SessionManager table to use for storing values. Defaults to the template handler's prefix. When configured in one server both as a handler and a template, the sessionTable should be set to the same value in both cases to get a useful result.

debug

If set, the original tag is included in a comment, otherwise it is removed entirely.

mustMatch

Set to a glob pattern that all names must match in order to be set. This may be used to prevent malicious html pages (what a concept) from changing inappropriate values.

noserver

The "server" namespace will no longer be mapped to server.props

noSet

If set, then the "set" tag will be disabled.

querySet

If set, then properties may be set in query parameters, to the "handler" portion, but only if they match the glob pattern.

autoImport

If set to "1", the namespace for the session is automatically imported. (defaults to "1");

imports

Defines a set of (white space delimited) namespaces that will automatically be imported at the beginning of each page. Each namespace name will be processed for ${...} substitutions before an import is attempted. If the namespace doesn't already exist, the import is ignored.

query

The query parameters are inserted into the request object, prefixed by the value assigned to "query".

headers

The mime headers are inserted into the request object, prefixed by the value assigned to "headers".

In addition, the following properties (prefixed with "headers") are also set:

• address The ip address of the client
• counter A monotonically increasing counter (# of client requests accepted since the server started).
• method The request method (typically GET or POST).
• protocol The client HTTP protocol level (for 1.0 or 1.1)
• query The current query data, if any.
• timestamp A timestamp (in ms since epoch) from when this request was first accepted.
• url The current url.
• hostname, hostport The name and port parts of the "host" header, if set.

url.orig

If set and "headers" are requested, this value is used as the url instead of the one in request.url.

Normally, any persistent properties held by the SetTemplate are chained onto the request.props when the init method is found. If this template is installed as an up-stream handler, then the persistent properties associated with the session are made available at that time.

When used as a handler, the following property is used:

session=value

The request property to find the session information in. Normally this should be the same as the session property used by the container calling this as a template.

saveOk

This must be specified in order for the "namespace store" or "namespace load" functions to operate.

See Also:

Serialized Form

Field Summary

Fields inherited from class sunlabs.brazil.template.Template

debug

Constructor Summary

SetTemplate()

Method Summary

boolean	doImport(RewriteContext hr) See if a remembered namespace is actually in use, and import it.
static File	file2path(Properties p, String prefix, String name) Convert a file name into a file object.
boolean	init(RewriteContext hr) Chain the session-id properties into the request chain, if there are any.
boolean	init(Server server, String prefix) Get the 2 SessionManager keys, "sessionTable" and "session" (SessionID).
static boolean	load(Properties p, RewriteContext hr, String name) load a namespace from a java properties file
boolean	respond(Request request) Chain a SessionManager entries onto the request properties, and optionally allow setting of request props from query parameters.
static boolean	store(Properties p, RewriteContext hr, String name, String title) Store a namespace into a java properties file
void	tag_get(RewriteContext hr) Replace the tag "get" with the value of the variable specified by the "name" attribute.
void	tag_import(RewriteContext hr) Import all the data from the named namespace.
void	tag_namespace(RewriteContext hr) Set the default namespace for "set" and "import".
void	tag_property(RewriteContext hr) Convert the html tag "property" in to the request's property DEPRECATED - use "get"
void	tag_set(RewriteContext hr) Set the value of a variable.
void	tag_slash_namespace(RewriteContext hr) Clear the default namespace for "set" and "import".
void	tag_slash_tag(RewriteContext hr) Insert a literal ">"
void	tag_tag(RewriteContext hr) Insert a literal "<".
void	tag_unimport(RewriteContext hr) Un-import a previously imported namespace.

Methods inherited from class sunlabs.brazil.template.Template

done

Methods inherited from class java.lang.Object

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

Constructor Detail

SetTemplate

public SetTemplate()

Method Detail

init

public boolean init(RewriteContext hr)

Chain the session-id properties into the request chain, if there are any. If "query" or "headers" are requested for "get", then add in those properties to request.props.

Specified by:

init in interface TemplateInterface

Overrides:

init in class Template

tag_set

public void tag_set(RewriteContext hr)

Set the value of a variable. Allow variable substitutions in the name and value. Don't create property tables needlessly.

Attributes:

name

The name of the variable to set

value

The value to set if to.

namespace

The namespace to look in. By default, the variable is set in the namespace associated with the current "SessionId".

local

A (deprecated) alias for "namespace=local", or the current request.props.

track

If true, all "set" operations are logged to stderr. This paramter may also be set in the configuration file to effect all "set" tags.

tag_property

public void tag_property(RewriteContext hr)

Convert the html tag "property" in to the request's property DEPRECATED - use "get"

tag_get

public void tag_get(RewriteContext hr)

Replace the tag "get" with the value of the variable specified by the "name" attribute.

Attributes:

name

The name of the variable to get

namespace

The namespace to look in. By default, the variable is searched for in "request.props". The namespace "server" is used to look in the server's namespace. The namespace "local" is a synonym for the default namespace.

default

The value to use if no value matches "name".

convert

The conversion to perform on the value of the data before substitution: "html", "url", or "none" (the default). For "html", any special html syntax is escaped. For "url", the data will be suitable for transmission as an http URL.

max

Truncate the String to at most max characters. Max must be at least one, and truncation occurs after any conversions.

set

The resultant value is placed into the request property named by the set attribute, and not inserted into the HTML stream. If none of "namespace", "convert", or "match" is used, then this simply copies the property from one name to another.

If a single attribute is specified, with no "=", then is is taken to be the "name" parameter. Thus: <get foo> is equivalent to: <get name="foo">.

tag_import

public void tag_import(RewriteContext hr)

Import all the data from the named namespace. The namespace associated with the session ID is imported automatically for backward compatibility. If the namespace doesn't exist, don't create it now, but remember it needs to be "Chained" if it is created on this page.

tag_unimport

public void tag_unimport(RewriteContext hr)

Un-import a previously imported namespace.

tag_namespace

public void tag_namespace(RewriteContext hr)

Set the default namespace for "set" and "import".

file2path

public static File file2path(Properties p,
                             String prefix,
                             String name)

Convert a file name into a file object. relative paths use are resolved relative to the document root

Parameters:

p - properties file to find the doc root in

prefix - the properties prefix for root

name - the name of the file

load

public static boolean load(Properties p,
                           RewriteContext hr,
                           String name)

load a namespace from a java properties file

store

public static boolean store(Properties p,
                            RewriteContext hr,
                            String name,
                            String title)

Store a namespace into a java properties file

tag_slash_namespace

public void tag_slash_namespace(RewriteContext hr)

Clear the default namespace for "set" and "import".

tag_tag

public void tag_tag(RewriteContext hr)

Insert a literal "<". Using the current scheme, there is no easy way to substitute into a tag parameter. So we'll invent a "magic" tag (called tag) that will allow us to create entities dynamically. Thus values can be substituted into entities by escaping the entity as in:

 <tag>a href=<property href></tag>
 

The [optional] attribute "name" may be used to specify the name of the tag, which will be emmitted just after the "<".

tag_slash_tag

public void tag_slash_tag(RewriteContext hr)

Insert a literal ">"

init

public boolean init(Server server,
                    String prefix)

Get the 2 SessionManager keys, "sessionTable" and "session" (SessionID).

Specified by:

init in interface Handler

Parameters:

server - The HTTP server that created this Handler. Typical Handlers will use Server.props to obtain run-time configuration information.

prefix - The handlers name. The string this Handler may prepend to all of the keys that it uses to extract configuration information from Server.props. This is set (by the Server and ChainHandler) to help avoid configuration parameter namespace collisions.

Returns:

true if this Handler initialized successfully, false otherwise. If false is returned, this Handler should not be used.

respond

public boolean respond(Request request)

Chain a SessionManager entries onto the request properties, and optionally allow setting of request props from query parameters. Only the session id table can be chained, and values (if any) are set in request.props (i.e. namespace=local)

Specified by:

respond in interface Handler

Parameters:

request - The Request object that represents the HTTP request.

Returns:

true if the request was handled. A request was handled if a response was supplied to the client, typically by calling Request.sendResponse() or Request.sendError.

doImport

public boolean doImport(RewriteContext hr)

See if a remembered namespace is actually in use, and import it. (This is a workaround). If some other template causes a namespace that was previously imported but empty to be created, then this tells us that it is now populated, and should be added to the chain. [a better implementation might have us register interest in a namespace, so we would be called automatically upon creation, instead of requiring the creator to know about us and make this call explicitly.]