sunlabs.brazil.template
Class SetTemplate
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.
Version: @(#)SetTemplate.java 2.15
Author: Stephen Uhler
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.]
public 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
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.
public boolean init(
Server server, String prefix)
Get the 2 SessionManager keys, "sessionTable" and "session" (SessionID).
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)
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">
.
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.
Set the default namespace for "set" and "import".
Convert the html tag "property" in to the request's property
DEPRECATED - use "get"
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.
Clear the default namespace for "set" and "import".
Insert a literal ">"
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 "<".
Un-import a previously imported namespace.