Handler Configuration Parameter Summary

AclSwitchHandler

Simple access control hander based on url prefixes or regexps.

authName
The name of the request.props entry to find a white-space delimited list of url prefixes or regular expression patterns. (defaults to "roles"). If the items in the list don't start with "/", then the url prefix is prepended (only for prefix matching).
prefix, suffix, glob, match
Sepcify the URL that triggers this handler. (See MatchString).
redirect
Name of the url to re-direct to if permission is denied. If not specified, a simple message is sent to the client.
useRegexp
If provided, the list of credentials is interpreted as regular expressions, otherwise url prefixes are used.

BSLTemplate

The BSLTemplate takes an HTML document with embedded "BSL" markup tags in it and evaluates those special tags to produce a standard HTML document.

basematchelist.
The list of matches (e.g. "1 2 3 ...").
basematches
The number of times the regular expression was matched.
basesubmatches.
The number of sub-expressions for this regular expression.
debug
If this configuration parameter is present, this template replaces the BSL 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 BSL tags are completely eliminated from the HTML document rather than changed into comments.

BasicAuthHandler

The BasicAuthHandler obtains a Session ID by performing "basic" authentication, using either the "Authorization" or the "Proxy-Authorization" headers.

authenticate
If specified, this is the response header that will be sent in the HTTP error response if the user is not authenticated.

If this string is "", then this handler will authenticate the request if the authorization header is present, but will not send an HTTP error message if the request could not be authenticated. This is useful if the web developer wants to do something more complex (such as invoking an arbitrary set of handlers) instead of just sending a simple error message if the request was not authenticated. In this case, the web developer can determine that the request was not authenticated because no Session ID will be present in the request properties.

authorization
If specified, this is the request header that will contain the "basic" authentication string, instead of the "Authorization" or "Proxy-Authorization" header implied by code.
code
The type of authentication to perform. The default value is 401.

The value 401 corresponds to standard "basic" authentication. The "Authorization" request header is supposed to contain the authentication string. If the request was not authenticated, the "WWW-Authenticate" header is sent in the HTTP error response to cause the browser to prompt the client to authenticate.

The value 407 corresponds to "basic" proxy/firewall authentication. The "Proxy-Authorization" request header is supposed to contain the authentication string. If the request was not authenticated, the "Proxy-Authenticate" header is sent in the HTTP error response to cause the browser to prompt the client to authenticate.

Any other value may also be specified. Whatever the value, it will be returned as the HTTP result code of the error message.

ident
The ident argument to SessionManager.getSession(java.lang.Object, java.lang.Object, java.lang.Class) to get the table of valid sessions. The default value is "authorized". If ident is of the form ident:session, then the session portion is used as the session argument to SessionManager.get(). Otherwise the session argument is NULL. This table may be manipulated with the SetTemplate, using the "ident" namespace and "session" for the SetTemplate "sessionTable" parameter.
mapFile
If specified, this is the initial Session ID file. This is expected to be a java properties file, whose keys are the authentication tokens, and whose values are the Session IDs that are inserted into the request properties.

The keys in the file are basic authentication (base64) tokens with any trailing "=" characters changed to "!".

message
The body of the HTTP authentication error message. This will be displayed by the browser if the client chooses not to authenticate. The default value is "". Patterns of the form ${xxx} are replaced with the value of the xxx entry of request.props.
prefix, suffix, glob, match
Sepcify the URL that triggers this handler.
realm
The "realm" of the HTTP authentication error message. This is a string that the browser is supposed to present to the client when asking the client the authenticate. It provides a human-friendly name describing who wants the authentication.
session
The name of the request property that the Session ID will be stored in, to be passed to downstream handlers. The default value is "SessionID".

BeanShellHandler

The BeanShellHandler permits handlers to be written in "beanshell".

debug
If this configuration parameter is present, the script is re-read on each request, and a new interperter is created and initialized. The call to init is deferred until request time, and called before each call to respond.

This allows beanshell scripts to be debugged interatively from scratch.

root
The script directory, if the script is a relative file name. If the "root" property under the prefix is not found, the global "root" property is used. If the global "root" property is not found, the current directory is used.
script
The name of the BeanShell script to use as the handler. Normally, the script is read only once. (defaults to prefix.bsh)

BeanShellServerTemplate

The BeanShellServerTemplate looks for one of the starting tags <server language="beanshell">, <beanshell>, or <bsh> in an HTML page and treats the following data up to the corresponding ending tag ( </server>, </beanshell>, or </bsh>) as a BeanShell script to evaluate.

debug
If this configuration parameter is present, this class replaces the starting and ending 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 starting and ending tags are completely eliminated from the HTML document rather than changed into comments.
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.
script
The name of the BeanShell script to evaluate when the interpreter is created. This script is only evaluated when the interpreter 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.

BrazilServlet

This is the Brazil Toolkit Servlet Adapter.

context_path
The servlet context path
servlet_container
The name of the servlet container
servlet_name
The servlet's name
url.servlet
The original URL requested by the client.

CacheManager

This SessionManager associates an object with a Session ID to give Handlers the ability to maintain state that lasts for the duration of a session instead of just for the duration of a request.

size
The max number of entries in each table (defaults to 1000).
tables
The number of Hashtables in the pool (defaults to 6)

CertHandler

Handler for issuing A netscape certificate.

cert
The file name containing the CA certificate
id
If set, The the request property "id" MUST be set in order to generate a cert. This allows upstream handlers to do authentication before a cert is issued.
prefix
The url prefix for this handler to generate a cert

CgiHandler

Handler for implementing cgi/1.1 interface.

custom
set to "true" to enable custom environment variables. If set, all server properties starting with this handler's prefix are placed into the environment with the name: CONFIG_name, where name is the property key, in upper case, with the prefix removed. This allows cgi scripts to be customized in the server's configuration file.
prefix
The prefix for all cgi files (e.g. /cgi-bin)
root
The document root for cgi files
suffix
The suffix for cgi files (defaults to .cgi)

ChainHandler

Allows multiple handlers to be invoked sequentially for a single HTTP request.

exitOnError
If set, the server's initFailure will set any of the handlers fail to initialize. No handler prefix is required.
handlers
A list of Handler names that will be invoked in the given order to handle the request. These are considered the "wrapped" handlers. These handlers will all be initialized at startup by init(sunlabs.brazil.server.Server, java.lang.String). For each name in the list, the property name.class is examined to determine which class to use for this handler. Then name is used as the prefix in the handler's init() method.
prefix
If set, All url's must start with this, or the request will be ignored
report
If set, this property will be set to the name of the handler that handled the request (e.g. returned true).

ChainSawHandler

Variant of the chain handler for doing standard logging.

flush
The number of requests between flushes to the file
logFile
The name of the file to write the logs to.

ChangedTemplate

This Template adds an icon to HREFs to indicate when the file being referred to is new, changed, or unchanged with respect to the user's session.

always
If this property is present, the ChangedTemplate always rewrites the HREFs, instead of just when they appear within the <changed> and </changed> tags.
changed
The HTML to substitute into the document if the HREF refers to a file that has changed since the last time it was accessed by the user. If absent, the HREF for changed files will not be rewritten.
fileName
A request property containing the full path name of the current file, used to keep track of the last time that file was accessed by the current user. A Handler or other code may set this property if it wishes the file to be tracked.
new
The HTML to substitute into the document if the HREF refers to a file that has never been accessed by the user. If absent, the HREF for new files will not be rewritten.
root
The root of the document hierarchy. An HREF must resolve to a file in this hierarchy so its last-modified time can be checked. If the file does not exist, the HREF will not be rewritten.
unchanged
The HTML to substitute into the document if the HREF refers to a file that has not changed since the last time it was accessed by the user. If absent, the HREF for unchanged files will not be rewritten.

ChownHandler

Handler for changing the group and owner of the server.

groupName
The name of the group to run as
userName
name of the user to run as

ConfigFileHandler

Handler for manipulating per-user session state that can be represented as ASCII name/value pairs.

default
The default properties file to "seed" session properties
glob
Properties that match this "glob" pattern may be set using the "set" pattern. If this property is specified, the "default" property is optional.
name
The name of the config file. the first "%" is replaced by the current SessionID.
noContent
a url, matching the "set" pattern that causes a "204 no content" to be returned to the client (experimental).
prefix
The URL prefix required for all documents
root
The document root (no properties prefix required). If the "name" or "default" properties don't start with a "/", this is used as the current directory.
set
The url pattern to match setting properties. Currently, it must also match "prefix".

ContentTemplate

Template class for extracting content out of remote html pages.

all
The entire content
bodyArgs
The attributes to the body tag, if any
content-length
The document content length, as fetched from the origin server
content
The body, delimited by content.../content>. The text inside multiple <content> ... </content> pairs are concatenated together.
last-modified
The document last modified time (if any) in std format
link-[rel ]
Every link tag "rel" and "href"
meta-[name ]
Every meta tag "name" and "content"
prepend
Prepend this string to the property names define above, that are populated by this template. (defaults to "").
referer
The user agent referrer (if any)
script
All "<script>"..."</script>" tags found in the document head
style
All "<style">..."</style"> tags found in the document head
title
The document title
user-agent
The origin user agent

CookieFilter

The CookieFilter keeps a record of all the browser cookies associated with a given session.

admin
A URL prefix that causes status information to be placed in the request properties.
nosession
The name of the session to use if no session id is found. defaults to "common".
session
The request property to find the session id. Defaults to "SessionID"

CookieSessionHandler

Handler for creating browser sessions using cookies.

cookie
the name of the cookie to use (defaults to "cookie").
exist
If specified, this means that the Session ID corresponding to the cookie value must already exist in the SessionManager. Normally, if the cookie was not present, a new cookie is automatically created.
map
If specified, the ident argument to SessionManager.getSession(java.lang.Object, java.lang.Object, java.lang.Class) to get the table of valid cookies, used to map the cookie value to a Session ID. By default, the Session ID stored in the request is the cookie value itself.
persist
If set, cookies persist across browser sessions
prefix, suffix, glob, match
Specify the URL that triggers this handler (See MatchString).

If prefix is specified, it is also used to instruct the client to limit the scope of the browser cookie. to that prefix.

session
The name of the request property that the Session ID will be stored in, to be passed to downstream handler. The default value is "SessionID". If the property already exists, and is not empty, no action will be taken.

CopyContentFilter

Filter to save content (of an entire site) to a disk file.

directoryName
The root in the file system to save the content in

DeCommentTemplate

Template class for removing comments from html pages.

disable
if true, disable comment removal. This is checked at each request.

DebugTemplate

Template class for printing stuff to stderr (for template debugging).

debug
If this configuration parameter is true, debugging is enabled.

DefaultFileHandler

Handler for appending a url ending with '/' into the appropriate url based on a default file in the file system.

defaults
The names of the default files to search for in the directory implied by the URL. The first one that exists will cause its name to be appended to the URL. Defaults to "index.html".
DirectoryName
This property is set if the URL represents a valid directory in the document root.
fileName
This property is set to the name of the default file, if one was found.
root
The document root to look for files. If none is found with our prefix, then "root" is examined. Defaults to ".".

DeferredHandler

Wrap another handler, deferring its initialization until request time.

[handler.class]
The name of the handler class.
[handler.prefix]
Used to trigger the configuration
handler
The token representing the handler to conditionally configure. This is used as the handler's prefix
requires
The names of classes required to be resolvable before configuring the handler

DelayHandler

Handler or template for adding a delay into a response.

delay
The delay, in ms (defaults to 1000).
prefix, suffix, match, glob
Specify which url's to process.

DialogHandler

Sample handler for popping up a dialog box on the server.

default
The message to appear in the dialog box. Defaults to Request from Client.
denied
The message to appear in the "permission denied" spot.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).

DigestAuthHandler

Perform digest authentication.

allowBogusIE
Internet Explorer does not use the query parameters as part of the "uri" calculation. This is a bug (and a security risk, as it allows replay attacts to other than the url requested). If this variable is set, then it allows IE to work in this case.
credentials
A java-properties format file of credentials. The keys are the users, the values are either the "A1" values described above, or the user's password.
isDynamic
If set (to anything), when authentication for a user is requested that is not in the credentials table and the credentials table has changed since last read, the table is re-read, in case the user has been added since the credentials were loaded.
prefix, suffix, glob, match
Specify which url's this handler applies to.
realm
The string presented to the user for validation. This must also match any "digested" passwords.
username
If the user was validated, this field is filled out by the handler.

DirectoryHandler

This is a bare-bones handler for providing directory listings for web servers.

delim
The delimeter separating the file names. Defaults to a single space.
DirectoryName
This property is set by the FileHandler if the URL it was passed resolves to a directory, but no index file (e.g. index.html) was found.
mime.xxx
Only documents ending in ".xxx" are considered. more than on mime.xxx parameters may be specified.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
setProps
If present, no content is returned. Instead, The properties "Directories" and "Files" are set in the request properties, so the format of the output may be generated dynamically. [Note: This feature is deprecated, use the DirectoryTemplate instead].

DirectoryTemplate

Put current directory information (based on the URL) into the request properties.

[prepend.Directories]
List of sub-directories in current directory is set by this template.
[prepend.Files ]
List of files with valid suffixes in current directory. is set by this template.
debug
if set, a comment is emitted indicating where the file-list entitiy was encountered.
delimiter
Delimiter character to separate entries, defaults to " ".
directory
The directory to use instead of the one implied by the URL. If it starts with "/", then it is resolved relative to the document root, otherwise it is resolved relative to the directory implied by the URL. The document root is found in the porperty "[prefix].root", or in "root", or (if neither exists), the current directory of the server.
DirectoryName
If set (usually by an upstream handler, such as the FileHandler, or TemplateHandler), this is used as the directory name instead of deriving it from the URL.
mime.xxx
An indication that suffix "xxx" is valid. Only valid file names are returned.
prepend
String to prepend to the properties "Directories" and "Files" That contain the directory and file lists respectively. Defaults to the Templates properties prefix.
select
Specifies a "glob" pattern to restrict the names of files and directories returned. The form "![pattern]" selects the inverse of the glob pattern.
stats
If specified, then for each file, the properties: [prepend].[file].mod and [prepend].[file].size are set, containing the file last modified time (seconds since epoch) and size (bytes) respectively.

DynamicConfigHandler

The DynamicConfigHandler allows the user to change the configuration of the server and its handlers on the fly.

config
URLs beginning with this prefix can be used to upload or download new configuration properties to this handler, which will also dynamically change which sub-handler is installed. This property belongs to the DynamicConfigHandler and is not changed when new properties are uploaded. The default is "/config/".

Properties may be uploaded by sending them as "name=value" pairs in the body of a POST or in the "?" query parameters. The URL for uploading properties is "config/set".

The current set of properties may be retrieved from this handler by sending the URL "config/get"

handler
The name of the initial sub-handler that this DynamicConfigHandler will use to process requests. When new properties are uploaded, the sub-handler will be replaced with whatever is specified in the newly uploaded handler property.
prefix
Only URLs beginning with this string will be redirected to the sub-handler. This property belongs to the DynamicConfigHandler and is not changed when new properties are uploaded. The default is "/".

ExecFilter

Filter to Run all content through an external process filter.

command
The command to exec. The content is supplied as stdin, and the filtered output is expected on stdout. ${...} substitutions Are done at each filter invocation.
error
If the command failed, this property will contain the error message. If the command generated output on stderr, this property will contain the output.
newType
This property, if set, is used as the new content type. It is evaluated for ${...} at each conversion.
type
This property is set to the content type of the content just before command is evaluated.
types
A regular expression that matches the content types for the content we wish to filter

ExecTemplate

template to exec a program, and return its arguments into request properties .

code
The exit code for the program.
error
The error message, if something went wrong.
stderr
The standard error output produced by the program, converted to a String using the default encoding.
stdout
The standard output produced by the program, converted to a String using the default encoding.

ExpContentTemplate

Allow extracted content to be filtered through regular expressions.

extract
A regular expression to match the extracted content
replace
A regular expression substitution string used to replace the content, if the expression matched.
urlPrefix
A prefix the url must match to be considered for rewriting

ExprPropsHandler

The ExprPropsHandler installs an expression evaluator as a "smart properties" into the current request object, enabling arithmetic and logical expression evaluation in property name lookups.

prefix, suffix, glob, match
Only URL's that match are allowed. (See MatchString).

FileHandler

Standard handler for fetching static files.

default
The document to deliver if the URL ends in "/". (defaults to index.html.)
getOnly
If defined, only "GET" requests will be processed. By default, all request types are handled. (Note: this is the inverse of the previous policy, defined by the undocumented "allow" parameter).
mime
property for mime type For each file suffix .XX, the property mime.XX is used to determine the mime type. If no property exists, the document will not be delivered.
prefix
Only url's that start with this are allowed. defaults to "". The prefix is removed from the url before looking it up in the file system. So, if prefix is /foo then the the file [root]/foo/bar.html will be delivered in response to the url /bar.html.
root
property for document root (.) Since the document root is common to many handlers, if no root property is found with the supplied prefix, then the root property with the empty prefix ("") is used instead. This allows many handlers to share the common property.

FilterHandler

The FilterHandler captures the output of another Handler and allows the ouput to be modified.

exitOnError
If set, the server's initFailure will set any of the filters fail to initialize. No handler prefix is required.
filters
A list of Filter names. The filters are applied in the specified order to the output of the wrapped handler.
handler
The name of the Handler whose output will be captured and then filtered. This is called the "wrapped handler".
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).

GenericProxyHandler

Handler for implementing a virtual web site.

headers
A list of white space delimited tokens that refer to additional HTTP headers that are added onto the polled request. For each token the server properties [token].name and [token].value define a new http header.
host
name of host site to proxy to.
port
Host port to proxy to (defaults to 80).
prefix
URL prefix must match
proxyHost
Which proxy host to use (if any) to contact "host".
proxyPort
The proxy's port (defaults to 80)

GroovyServerTemplate

The GroovyServerTemplate looks for each <groovy> tag in an HTML page and treats the following data up to the next </groovy>) tag as a groovy script to evaluate.

debug
If this configuration parameter is present, this class replaces the <groovy> and </groovy> 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 <groovy> and </groovy> are completely eliminated from the HTML document rather than changed into comments.
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.
script
The name of the Groovy 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.

HighlightTemplate

Template class for highlighting text that matches a regular expression.

exit
If set, the template "init" method will return false, and no further processing will take place. This is useful if this template is used by itself.
highlight
A regular expression that with match any text between entities.
matchCase
If specifies, matches are case sensitive. The default is to ignore case when matching.
mustHighlight
If not set, the entire document is surrounded by implicit highlight tags. If set no highlighting will take place until an actual highlight tag is present.
options
the set of name=value options that will be added to the starting tag of the tag pair, above. The default is "color=red".
substitute
The string to substitute for the matched text. This is for advanced uses. If specified, the values for tag and options are ignored. The default is: <${tag} ${options}>&</${tag}> The format of the string is a regular expression substitution string, which supports ${} style variable substitutions from the request properties.
tag
the html/xml tag pair that will be added before and after all text maching "highlight", above. The default is "<font> ..... </font>

HistoryFilter

The HistoryFilter is both a Handler and a Filter that keeps a record of all pages visited by a given session.

admin
URLs beginning with this prefix cause the HistoryFilter to store the history information for the current Session in the request properties
filter
If specified, then this is a Regexp pattern to match against the "Content-Type" of the result. Setting this also implies that the HistoryFilter will be invoked as a Filter and not a Handler. The default value is "", which indicates that the "Content-Type" is not examined and that this HistoryFilter will be invoked as a Handler.
nosession
The Session ID to use if the Session ID was not specified. The default value is "common".
prefix
This handler will only process URLs beginning with this string. The default value is "", which matches all URLs.
session
The name of the request property that holds the Session ID. The default value is "SessionID".

HomeDirHandler

Handler for converting ~username queries.

home
The mount-point for home directories, defaults to "/home/".
prefix
The url prefix used to identify home directory queries. Defaults to "/~".
root
The name of the root property to set. Defaults to "root".
subdir
Name of the directory in the user's home directory that represents the user's "doc root"

JavaScriptTemplate

The JavaScriptTemplate looks for each <server language="javascript"> (or <javascript>) tag in an HTML page and treats the following data up to the next </server> (or </javascript>) tag as a JavaScript script to evaluate.

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.
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.
script
The name of the JavaScript script to evaluate when the interpreter is created. This script is 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.

JunkBusterHandler

Remove junk images from web pages.

host
The regular expression matching url's to reject. If the expression starts with a '@', it interpreted as a file name (minus the @) that contains a new-line separated list of regular exporessions. See Regexp for more information on regular expressions.
image
The file to contain the replacement image.

LDAPTemplate

The LDAPTemplate is invoked to process LDAP tags embedded in a document.

attributes
The space-delimited list of attribute names to return from the LDAP "dn" or "search" operation. If empty or unspecified, all attributes for the record are returned. Not all records in the LDAP database have the same attributes. Defaults to "".

authenticate
The Distinguished Name used for authenticating to the LDAP server, if necessary. Defaults to "". This would be a good option to specify in the configuration file rather than in the LDAP tag.

base
The Distinguished Name of the base record that forms the root of the search tree in the LDAP database. Used only with the "search" option. Defaults to "". This would be a good option to specify in the configuration file rather than in the LDAP tag.

dn
The Distinguished Name (DN) to lookup in the LDAP server. The format of a DN is described in RFC-1779. The "dn" and "search" options are mutually exclusive. When "dn" is specified, only zero or one result will be returned from the LDAP database. The result (if any) will be stored in the request properties as follows:
 <ldap dn="uid=6105,ou=people,o=WebAuth" prefix=name>
 <property name.dn>
 <property name.cn>
 <property name.sn>
 <property name.objectclass>
etc. The property name.dn is the DN that was found. Other properties will be defined as shown, based on the attributes present in the LDAP record.

host
The hostname of the LDAP server, of the form "host" or "host:port" if the server is not running on the standard LDAP port. Defaults to "". This would be a good option to specify in the configuration file rather than in the LDAP tag.

password
The password sent when the "authenticate" option is used. Defaults to "".
prefix
The string prefix for the property names that will be stored in the request properties to hold the results. If not specified, defaults to the prefix of this template as specified in the configuration file.

scope
The scope of the LDAP search, one of Used only with the "search" option. Defaults to "sub". This would be a good option to specify in the configuration file rather than in the LDAP tag.

search
The search filter to use when searching the LDAP server. The format of a search filter is described in RFC-1558. The "search" and "dn" options are mutually exclusive. When "search" is specified, zero or more results will be returned from the LDAP database. The results will be stored in the request properties as follows:
 <ldap search="(givenname=scott)" prefix=name>
 <property name.rows>
 <property name.rowcount>
 
 <property name.0.dn>
 <property name.0.cn>
 <property name.0.mail>

 <property name.1.dn>
 <property name.1.cn>
 <property name.1.pager>
etc. The property name.rows is set to the list of record indices found, and can be used by the BSL tag <foreach name=x property=name.rows> to iterate over all records. Other properties will be defined for each of the records found as shown, based on the attributes present in the each of the LDAP records.

LogHandler

Handler for logging information about requests.

fileName
The name of the file to log the output to. If the file already exists, data is appended to it. If the file is removed, a new one is created.
format
The format of the output string. Embedded strings of the form "%X" are replaced, based on the following values for "X": Defaults to "%u;%t:%d:%b".
handler
The name of the handler to wrap. This can either be the token for the class, or the class name itself.
headers
If specified This string is tacked onto the end of the "props" string. Entries in the HTTPrequest headers may be included using ${...} substitutions.
props
If specified This string is tacked onto the end of the "format" string. Entries in the Request Properties may be included using ${...} substitutions.
title
if present, this is output as the first line of the file

MD5Filter

Filter to compute the MD5 checksum of the content, and generate the appropriate "Content-MD5" http header.

prefix, suffix, glob, match
Specify the URLs that trigger this filter (See MatchString).

MacroTemplate

Template class for defining macros.

init
The name of the file (or resource) to read a default set of macro definitions from. If an absolute path isn't specified, the file is taken relative to the document root. The default macros are kept in the SessionManager on a per-server basis. All macros defined in the "init" file are global. All markup in this file outside of a macro definition is ignored. If "subst" is present as an attribute of a macro definition in this file, then all ${...} are evaluated relative to "server.props" before the macro is defined.
subst
If specified, then any tags that are not processed by any templates will have all ${..} contructs in attribute values substituted. This subsumes the function of the "SubstAllTemplate".

MatchString

Utility class for handlers to determine, based on the URL, if the current request should be processed.

glob
The glob pattern the url must match. If defined, this overrides both prefix and suffix.
ignoreCase
If present and match is defined, this causes the regular expression match to be case insensitive. By default, case counts.
match
The reqular expression pattern the url must match. If defined, this overrides glob.
prefix
The url prefix the url must match (defaults to "/").
suffix
The url suffix the url must match (defaults to "").

ModifiedTemplate

Template class for computing last-modified times for content that is processed through templates.

debug
If this configuration parameter is present, modified tag is replaced by a comment. Otherwise it is removed from the document.

MultiHostHandler

The MultiHostHandler allows the user to handle a set of host names that are all running on the same IP address.

prefix.handler
The main handler for the server with the given prefix. If this property is not specified, it defaults to the FileHandler.
prefix.host
Each server is started with a given prefix. The property prefix.host specifies a Glob pattern for a virtual hostname the server will be expected to handle. If this property is not specified, the server's virtual hostname will just be prefix. If multiple host patterns could match a given "Host:" header, the first match in the "servers" list matches first.
prefix.log
The log level for the server with the given prefix. If this property is not specified, it defaults to the log level of the parent server.
servers
The list of prefixes for the other servers. Each server will be initialized from the main server.props with the specified prefix. In this way, the configuration parameters for all the sub-servers can be stored in the same Properties object.

MultipartSetTemplate

Version of the SetTemplate that reflects form/multipart data in Request.props.

noEncode
If present, no encoding is performed on file uploads.
query
If present, The form data is translated from form/multipart and placed into the request properties, prefixed by the value of query.
saveName=name
The name to use to save the file. May contain ${...} substitutions. The variables ${fileName}, ${fieldName) and ${prefix} may be used here as "special" variables to make creating a file name easier. saveNamedefaults to: ${prefix}-${fieldName}-${fileName}
savePattern=[glob pattern ]
If set, then the form is scanned for field names that match glob pattern. If a match is found, then the next form element of type file is saved to a file in the document root instead of being loaded as a property. The name of the file is specified by the value of the saveName entry.

NoImageTemplate

Sample template class for removing all images from a web page, and replacing them with their alt strings.

template
The text used to replace the image. The first "%" will contain the image "alt" string, if any.

NotFoundHandler

Handler for returning "file not found" errors back to the client.

fileName
The name of the file to send for missing files. Defaults to "notfound.html"
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
root
The location of the document root for locating the default "not found" file (also looks using prefix of "").
type
The file type, defaults to text/html

PlainFilter

Filter to turn text/plain into html.

template
The string to use as an html template. The string should contain a single "%", which is replaced by the text/plain content. The default stuff the content between <pre>...</pre>.

PollHandler

Handler for periodically polling another web site, whose results are (optionally) added to the server's properties.

count.attempts
The total number of polls attemped.
count.errors
The total number of poll failures.
error.at
The poll attempt # for the last failure.
error.msg
The message describing the last failure.
error.time
The timestamp of the last failure.
fast
If set, don't wait "interval" before 1st poll.
format
a date format specifier to use for matching "match" patterns. Defaults to "EE-MM-dd-HH-mm".
headers
A list of white space delimited tokens that refer to additional HTTP headers that are added onto the polled request. For each token the server properties [token].name and [token].value define a new http header.
interval
The interval (in seconds) to fetch the url. Defaults to 10 seconds. If match is specified, this is the interval used to check for a time/date match. At each "interval", the current time format is computed, based on "format", below. If the computed format has not changed since the previous poll, then no poll is done. The interval is recalculated after each poll.
match
If specified, a regular expression that must match the current time for this URL to run. The format to match is specified by the "format" parameter, below. "EEE-dd-HH-mm" (eg: Thu-Dec, 14, 14:12 pm).
namespace
The namespace to use to store the properties to. If the sessionTable (see below)parameter is identical to the sessionTable parameter of the SetTemplate, then this specifies the namespace parameter that may be used with the SetTemplate "namespace" parameter to obtain the extracted data. Defaults to the "prepend" parameter.
post
The "post" data, if any. ${...} are evaluates as per url above.
prepend
The string to prepend to the properties. If not supplied no properties are loaded.
proxy
If specified, connect through a proxy. This should be in the form host:port, or host it the desired port is 80.
sessionTable
The name of the SessionManager table to use for storing values. By default, properties are stored in server.props. The value should match the sessionTable used by the SetTemplate to allow values obtained by this handler to be accessable from within templates.

If the sessionTable is set, the namespace value is used to name the table (e.g. the namespace specified by SetTemplate. If no namespace parameter is given, then prepend is used as the namespace parameter.

timestamp
The timestamp for the last successful poll.
url
The fully qualified URL to fetch periodically. any ${...} constructs are evaluated at each poll, with the values in the server properties object.

PropertiesCacheManager

A version of the CacheManager that saves out any session state that is either a "java properties" object, or implements "Saveable" into a directory in the filesystem, one file per entry, then restores them on server startup.

defer
If set, the saved session information is not reconstructed upon startup. Only the list of sessions is read in; the session information is restored only when needed.
filePrefix
A prefix pattern to use for all session files. Defaults to the handler prefix.
match
A glob pattern that matches the url (or url?query if a query is used. Defaults to "*?*save=true".
storeDir
The directory to use to store the state files. It is created as needed when the state is saved. Defalts to "store".

PropertiesHandler

Handler for returning selected request properties as a text/plain document in java properties format.

comment
Comment to put on output (defaults to select).
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
select
Glob pattern to match properties selected (Defaults to *). This is re-examined at every request.
type
Type of output to generate (defaults to text/plain).

PropsTemplate

[Deprecated, use the the SetTemplate.

headers
The mime headers are placed into the request object, prefixed by the value assigned to "headers". The values: url, query, method, and version are copied from the request object into the properties. The clients IP address is saved in the "address" property.
query
The query parameters are placed into the request object, prefixed by the value assigned to "query".
url.orig
If set and "headers" are requested, this value is used as the url instead of the one in request.url.

ProxyHandler

Handler for implementing a web proxy.

auth
The value of the proxy-authenticate header (if any) sent to the upstream proxy
proxyHost
If specified, the name of the upstream proxy
proxyPort
The up stream proxys port, if a proxyHost is specified (defaults to 80)
useproxy
The name of the SocketFactory class to use for this handler. If additional properties are required to set up the SocketFactory, it should be configured as a handler instead. This is here for convenience only.

ProxyPropertiesHandler

Obtain properties format content from remote websites, and add it to the current request properties.

prepend
The prefix that should be prepended to each property before it is inserted into the request properties
type
The document type for files to process as java properties (defaults to text/plain)
url
The url that should be used to fetch the remote content. If not specified, the curent url is used instead. Any ${...} constructs in the url are evaluated at each request.

PublishHandler

Handler for supporting publishing from Communicator.

prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
session
The the name of request property holding the session information to provide the credentials for posting. The default is "SessionID".

PushHandler

Skeleton Handler for uploading files using multipart/form-data.

prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).

PythonServerTemplate

The PythonServerTemplate looks for each <server language="python"> (or <python>) tag in an HTML page and treats the following data up to the next </server> (or </python>) tag as a python script to evaluate.

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.
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.
script
The name of the Python 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.

QueueTemplate

Template class for Managing simple Queues, allowing text communication among sessions.

age
Set how long the message has been q's (in seconds)
error
Something went wrong. Set an error message.
from
Set the (unauthenticated) sender.
items
Set the number of Q'd items.
message
Set The text of the next message in the queue.
sent
Set the timestamp (in sec) of when the item was q'd.

ReFilter

Filter to replace text content via a reqular expression substitution.

noCase
If set, case-insensitive matchins is performed.
oneOnly
If set, only replace the first match. by default, all matches are replaced.
re
The regular expression to match the content
sub
The replacement expression. If not specified, the matched content is deleted.

RePollHandler

Do regsub processing on content to extract properties.

encoding
The character set encoding to use when converting the request results to a string. Defaults to the default encoding.
prepend
The string to prepend to all properties. Extracted properties will contain the the "re" token as an additional prefix.
re.exp
The regular expression to search for.
re.flags
One or more ASCII flags to control how this "re" is processed. Consists of one or more of The following (defaults to "SFE"):. Characters not on this list are ignored.
re.key
The index of the sub-match (starting at 1) that will be used to name the row number portion of the property name instead of a counter. This is useful if one of the sub-matches will be unique for each matching pattern. This option is ignored if the "O" flag is specified, as there will be only one match so no "key" is required.
re.names
A white-space delimited set of tokens to use instead of numerical indices to name the properties. The first name in the list names the entire match, the remaining names name the sub-expressions. If there are more properties extracted than names provided, the "left over" properties will have numerical indeces. This implies 'E'.

If the name "X" is used, no property will be extracted for that match.

re.sub
The regular expression substitution pattern. If 'E' is specified, the substitution is done after the extraction.
re
the list of "re" tokens to process in order. Each "re" token has the following attributes:

ReplaceFilter

Filter to replace current content with a static form, or template.

debug
If set, the template is re-read each time. Otherwise a cached copy is used.
fileName
Name of the file to use as the form or template. The file is searched for as a Resource if not found in the filesystem.
root
The document root used to find the template file. If not found, "root" with no prefix is used instead.
type
Text subtype of content to filter. Defaults to "html"

ResourceHandler

Handler for serving documents out of the jar file.

default
The default file name for url references ending in /
mime.xxx
The mime type for suffix xxx.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
root
The document root path within the jar file

ResourceLimitHandler

Handler for server resource management.

file
The file name or resource of the html file to return if resources run low. Defaults to "busy.html".
memory
The minimum # of remaining bytes available to the vm
retry
The number of seconds to request the client wait before retrying the request.
threads
The Max number of active threads

RestartHandler

Restart the server when a sigHUP is received.

config
The name of the configuration file to use for this server. Relative paths are resolved relative to the current directory. If no file is specified, the server continues to use its existing configuration [which has presumably been modified in-place]. If a config file is specified and the config file hasn't changed, then no restart is done.
keep
If set, and a config file is specified, the existing configuration (server.props) is not cleared first.

RestrictClientHandler

Simple access control hander based on source ip addresses.

allow
The regular expression that matches the ip addresses of clients (in xxx.xxx.xxx.xxx format) that are permitted to access url's starting with prefix.
deny
The regular expression that matches the set of ip names that should be denied access. This is to make complying with silly EAR requirements easier. The use of this option implies a reverse DNS lookup, which could be expensive, as DNS names (and not ip addresses) are used for the comparison. Case insensitive matching is used.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
redirect
Name of the url to re-direct to if permission is denied. If not specified, a simple message is sent to the client.

RolesHandler

Handler for associating roles with an id.

mapFile
The absolute path to the java properties file containing the it to role mapping.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
roleName
The property to place the result of the id lookup into. Defaults to "roleName";
SessionID
The property to use to look up the id. Defaults to "SessionID".

SMTPHandler

Handler (or template) for Sending an email message via SMTP.

host
The mail host (e.g. listening on the SMTP port). Defaults to "localhost".
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).

SerialPersist

The SerialPersist class is a SessionManager that uses Java object serialization to make a persistent store of the session information for a server.

saveUrl
The name of a url that will cause the session information to be saved without terminating the server. WARNING! this has the side effect of removing non serializable elements from the session table, which can lead to disturbing behavior.
store
The name of the store file to hold the session information. The default value is "store".

SessionFilter

Filter to manage browser sessions using browser cookies or URL rewriting as needed.

cookie
The name of the cookie to use (defaults to "cookie"). If the name is "none", then no cookies are used. Instead, session rewriting will occur for every session.
cookiePrefix
The URL prefix for which the cookie applies. Defaults to "/".
persist
If set, cookies persist across browser sessions. If cookies are disabled, no persistence is available.
session
The name of the request property that the Session ID will be stored in, to be passed to downstream handler. The default value is "SessionID". If the session property is set, and not empty, then no processing is done.
suffix
A regular expression that matches url suffix we process. Defaults to html|xml|txt.

SetTemplate

Template (and handler) class for setting and getting values to and from the current (or other) request context.

autoImport
If set to "1", the namespace for the session is automatically imported. (defaults to "1");
debug
If set, the original tag is included in a comment, otherwise it is removed entirely.
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:

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.
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.
query
The query parameters are inserted into the request object, prefixed by the value assigned to "query".
querySet
If set, then properties may be set in query parameters, to the "handler" portion, but only if they match the glob pattern.
saveOk
This must be specified in order for the "namespace store" or "namespace load" functions to operate.
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.
sessionTable
The name of the SessionManager table to use for storing values. Defaults to the 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.
url.orig
If set and "headers" are requested, this value is used as the url instead of the one in request.url.

SimpleSessionHandler

Handler for creating browser sessions based on information found in the http request.

digest
If set, the "value" is replaced by the base64 encoding of the MD5 checksum of value.
extract
If specified, a string to use as the session-id. ${...} values will be searched for first in the HTTP header values, and then in the request properties.

In addition to the actual HTTP headers, the pseudo http headers ipaddress, url, method, and query are made available for ${...} substitutions.

force
If set (to anything), a session ID is set even if one already exists.
prefix, suffix, glob, match
Specify the URL that triggers this handler (See MatchString).
re
If specified, a regular expression that the extracted data must match. if it doesn't match, no session id is installed. The default is ".", which matches any non-empty string. If the first character is "!" then the sense of the match is inverted, But only for determining whether a match "succeeded" or not. no sub-matches may be used in computing the key value in this case.
session
The name of the request property that the Session ID will be stored in, to be passed to downstream handlers. The default value is "SessionID". If the property already exists, and is not empty, no session will be defined.
value
The value of the session ID. May contain & or (n=0,1,2...) constructs to substitute matched sub-expressions of re. The default is "&" , which uses the entire string "extract" as the session id.

SnarfTemplate

Template class for extracting content out of <snarf property=xxx> .

debug
If set, the snarf tags will be replaced by comments.
prepend
The string to prepend all properties with. Defaults to the handler's prefix.

SqlTemplate

Sample Template class for running SQL queries via jdbc and placing the results into the request properties for further processing.

driver
The name of the jdbc driver class for the desired database. Currently, only one driver may be specified. (e.g. prefix.driver=org.gjt.mm.mysql.Driver).
sqlPrefix
The properties prefix for any additional parameters that are required for this connection. For example:
		 prefix.sqlPrefix=params
		 params.user=my_name
		 params.password=xxx
		
All of the parameters are supplied to the jdbc connection at connection time.
url
The jdbc url used to establish a connection with the database. (e.g. prefix.url=jdbc:mysql://host/db?user=xxx&password=yyy).

SslHandler

Handler for installing SSL into the server.

certDir
The absolute pathname of the directory containing the server's certificates. The "main" in this class should generate a representitive sample (but doesn't). In the mean time, you can run "java CreateCertificates" with the Iaik jar in your path, to create a set of server test certificates in the certs directory.
certRequired
If set, the server will ask the user for a client cert.
fingerprint.*
The base64 encoded fingerprints of the clients certificates
issuer.*
Information about the certificate issuer.
owner.*
Information about the certificate owner.
session
The property to put the certificate serial number into. Defaults to "cert.id".

StunnelHandler

Handler to enable proper interaction with a protocol conversion gateway, by rewriting "redirect" directives properly.

protocol
The protocol to replace "http" with when redirection via a gateway (defaults to "https").
ssl
The regexp to match client ip addresses that are coming from ssl gateways (such as stunnel).

SubstPropsHandler

Handler that performs value conversions on ${.

[token.code ]
The name to match the "token" in the property name. The default is "[token]".
key
The regular expression substitution string used to represent the actual property name to filter. The default is \2
match
A regular expression that matches a property name that is a candidate for filtering. This expression should have at least 2 sets of ()'s in order to gather values for "key" and "token" below. The default value is ^([a-z]+)([^)]+)$
token
The regular expression substitution string used to represent the filter name or "token". The default is \1

Using the defaults for "match", "key", and "token", a property named "foo" would be represented as ${xxx(foo)} where "xxx" is the name of the conversion filter.

tokens
A witespace separated list of filter names or "token"s that map the conversion filters to conversion classes. For each token (e.g. foo), there should be a property of the form "foo.class" which specifies the name of the class that implements the filter, (and implements the Convert interface described below). Any additional properties (e.g. x, y, z) needed to initialize a filter should be present in the properties file as "foo.x, foo.y...".

SubstPropsHandler.Resub

Do a regexp substitution on a value.

match
A Regular expression that matches the string value.
sub
The regular expression substitution to perform. All occurances of "match" are substututed.

SupplyHandler

Sample Handler for dispatching different users to different url's based on a special http authentication header.

default
default map
header
http header (authentication)
mapFile
properties file
prefix
url prefix
realm
The authentication realm (basic)

TclFilter

Wrapper for writing FilterHandler filters in TCL.

script
The name of the TCL file sourced on startup. The init(sunlabs.brazil.server.Server, java.lang.String) parameters are made available as the global variables prefix and server.

TclHandler

Handler for writing handlers in tcl.

callback
The name of the TCL script to call at each request. Defaults to respond.
prefix, suffix, glob, match
Specify the URL that triggers this handler. (See MatchString).
script
The name of the TCL file sourced on startup. The init(sunlabs.brazil.server.Server, java.lang.String) parameters a make available as the global variables prefix and server.

TclRePollHandler

Post-process all "polled" properties with tcl code.

debug
If set, the "script" is sourced each time.
script
The name of the TCL script to call at each request. The interpreter is created with the following global variables. The script is "evaluted" once on startup. The tcl procedure "process" is called with the java properties object. Any modifications to that object are done here.

TclServerTemplate

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.

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

TemplateFilter

The TemplateFilter sends HTML content through an Html/XML parser to a set of Templates.

encoding
The charset encoding to use to represent the content as text. If none is specified, the default encoding is used.
outputEncoding
The character encoding to use to interpret the template results. If no "outputEncoding" is specified, then "encoding" is used. Once template processing is complete, the results are converted into a byte stream for transmission to the next filter, using "outputEncoding", if specified. If not specified then the default encoding is used.
session
The request property that contains the session ID. If no "session" property is found with the supplied prefix, then the global "session" property is used instead. The default value is "SessionID".
subtype
Restrict this template to only handle specified text sub-types. defaults to the empty string, which implies any text sub-type.
tagPrefix
If specified, all tag names defined for each template class are prefixed with tagPrefix. This parameter only takes effect if the tagPrefix option is not specified for an individual template.
templates
A list of template names. For each name in the list, the property name.class is examined to determine which class to use for each template. Then name is used as the prefix for other template specific properties if any. If name.class does not exist, then name is assumed to be the class name, and there are no template specific properties for the template. Methods in the template classes will be invoked to process the XML/HTML tags present in the content.

UrlMapperHandler

Handler for mapping or redirecting URLs.

export
If set, use this as a properties prefix, and set request properties for each sub-expression in "match". (E.g. [export]1 [export]2 ...).
ignoreCase
If set, the case of the expression is ignored.
match
The regexp to match a url. May contain constructs of the form ${xxx}, which are replaced by the value of request.props for the key xxx
redirect
If set, the request is redirected instead of being rewritten
replace
The url to replace it with. This may contain both regular expression sub-patterns, such as "", or variables of the form ${..} which are replaced with the equivalent request properties.
source
If set, then this string is used instead of the url as the source of the match. Variable substitution using ${xxx} is performed on source, which, if unset, defaults to "${url}". If set, the request properties "url", "host" and "user-agent" are set first. The source property is obtained at init time, but evaluated (for ${...}) at every request.

As an example, the configuration:
prefix.source=${user-agent}!${url}
prefix.match=Lynx.*!(.*)
prefix.replace=/text\1
could cause all browsers with "Lynx" in their user agent header to the "text" sub-directory.

UrlNavBarTemplate

Template class for dynamically generating a navigation bar by looking at portions of the url.

includeDir
Normally, if the URL refers to the directory ( e.g. it ends with a /), no nav bar entry is generated. If this property is set, the entry is generated.
prepend
Use as a prefix on the property name, instead of "NAV.".

VelocityFilter

A filter for processing markup that is a Velocity template.

script
The name of a BeanShell script file.
session
The name of the propery containing the session. The default session, if none is found, is "common".

VirtualHostHandler

Handler for managing virtual hosts using the same server configuration.

[prefix.[host]. ]
If the "mapping "property exists that matches the incoming "host" name, then that value is used instead of [host] to rewrite the "url" or "root".
default
If set, then all hosts for which no mappings are defined are mapped to the value of this property.
maproot
If set upon server startup, this handler changes the "root" property instead of the "url" property, by appending the "host" onto the document root, instead of prepending the "host" to the url.