Reference Manual

Introduction

This document is the Weaver reference manual. It describes the following:

The overall structure of the Weaver Application Definition (WAD) file.
The standard XML tags available to the WAD file.
The expression language (EL) as used by Weaver.
Weaver's configuration files.
Deployment descriptor (web.xml) requirements.

For reference information about the Weaver classes most commonly used when writing a Weaver application see the javadoc.

WAD File Structure

The Weaver Application Definition (WAD) file defines the behavior of the Weaver controller. It is an XML file with the following basic structure:

weaver-app

information
load-beans
load-functions
application

init
destroy

session

init
destroy
time-out

main

dispatch
default
security

The following section describes the purpose of each of the execution tag sections:

Tag	Description
information	Declares properties of the application.
load-beans	Declares W-Beans to used by the application.
loads-functions	Declares functions to be used in the EL.
application/init	Called once for application initialisation.
application/destroy	Called once for application destruction.
session/init	Called once to initialise each session.
session/destroy	Called once on the destruction of each session.
session/time-out	Called when a session timeout is detected.
main/dispatch	Called to dispatch incoming requests to W-Bean classes.
main/default	Called when a request is not handled in the main/dispatch section.
main/security	Called when a session needs to be authenticated.

Declaration Tags

The <load-beans> Tag

The <load-beans> tag contains <bean> tags each of which associates a simple name with a W-Bean class name.

Attributes

None.

Sub-tags

Element	Description
bean	An association of a name with a W-Bean class name. The name can then be used by <call> tags.

The <bean> Tag

The <bean> tag associates a simple name with a W-Bean class name. The simple name may then be used in <call> tags.

Attributes

Attribute	EL	Required	Description
name	No	Yes	The name to be associated with the W-Bean class.
class	No	Yes	A fully qualified bean class name. The class must implement the com.oldlight.weaver.clientbinding.WeaverBean interface.

Sub-tags

None.

The <load-functions> Tag

The <load-functions> tag contains <function> tags, each of which declares a function that can be later used as part of an EL expression.

Attributes

None.

Sub-tags

Element	Description
function	Each <function> tag declares a function that may then be used in EL expressions.

The <function> Tag

The <function> tag associates a simple name to be used in EL expressions with a class and method implementing the function.

Attributes

Attribute	EL	Required	Description
name	No	Yes	The name of the function as it will appear in EL expressions.
class	No	Yes	The publicclass which implements the function. The function, as declared by the signature attribute, must be a public static member of that class.
signature	No	Yes	The return type, name and parameter profile of the function as it appears in the class declared by the class attribute. All class names must be fully qualified. e.g. java.util.List listFiles(java.lang.String).

Sub-tags

None.

The <information> Tag

The <information> tag declares properties of your application. Its attributes are used purely for display through the Administrative Console and are optional.

Attributes

Attribute	EL	Required	Description
version	No	No	A version number for your application.
date	No	No	The date of issue of this version of your application.
author-name	No	No	A contact name for the author of your application.
author-email	No	No	A contact email address for the author of your application.
vendor-name	No	No	The name of your company.
application-name	No	No	The name of your application.

Sub-tags

None.

The <import> Tag

The <import> tag includes other XML files in the WAD file. Each included file must be a well-formed XML document.

Attributes

Attribute	EL	Required	Description
file	No	Yes	Relative file name of the XML file to include.

Sub-tags

None.

Execution Tags

The <call> Tag

The <call> tag causes the named W-Bean to be executed.

Parameters may be passed to the bean by including <param> sub tags.

Attributes

Attribute	EL	Required	Description
name	No	Yes	The name of the bean to call. The bean must have been declared by a bean tag in the load-beans section.

Sub-tags

Element	Description
param	A parameter to pass to the bean.

The <param> Tag

The <param> tag is used to pass parameters to beans. Param values are made available as bean scoped attributes.

Attributes

Attribute	EL	Required	Description
name	No	Yes	The name of the parameter.
value	Yes	Yes	The value of the parameter.

Sub-tags

None.

The <if> Tag

The <if> tags provides support for the conditional execution of sub-tags.

Attributes

Attribute	EL	Required	Description
test	Yes	Yes	Sub-tags will be executed only if the test attribute evaluates to a true value according to the EL.

Sub-tags

Any.

The <session-control> Tag

The <session-control> tag manages user sessions. It may be used to initialise a session (if not already initialised), to destroy a session or to check for timeout.

Attributes

Attribute	EL	Required	Description
action	No	Yes	One of: init - to cause the session to be initialised if it is not already initialised; destroy - to cause the session to be destroyed; require - to require that the session is initialised. If the session is not initialised then the session/time-out section will be executed.

Sub-tags

None.

The <choose> Tag

The <choose> tag contains <when> tags and an optional <otherwise> tag. It implements exclusive conditional execution logic. The test EL expressions of each of the <when> tags are evaluated in turn. The sub-tags of the first to evaluate to true are executed and the rest of the <choose> is ignored. If none of the test conditions of the <when> sub-tags evaluate to true then, if an <otherwise> sub-tag is present, its contents are executed.

Attributes

None.

Sub-tags

Element	Description
when	The contents of the <when> tag are executed if it is the first in the surrounding <choose> whose test attribute evaluates to true.
otherwise	The contents of the <otherwise> tag is executed if none of the test conditions on the <when> tags have evaluated to true. The <otherwise> tag is optional.

The <when> Tag

The <when> tag is used inside <choose> tags. The first <when> tag within a given <choose> whose test attribute evaluates as an EL expression to true has its contents executed.

Attributes

Attribute	EL	Required	Description
test	Yes	Yes	An EL expression which is the gating condition for the execution of the contents of the <when> tag.

Sub-tags

Any.

The <otherwise> Tag

The <otherwise> tag is used inside <choose> tags. If none of the <when> tags are executed (because none of their test attributes evaluate to true) then the contents of the <otherwise> tag are executed.

Attributes

None.

Sub-tags

Any.

The <catch> Tag

The <catch> tag is used to handle exceptions raised by W-Bean calls in any of its sub-tags. Specifically any WeaverClientExceptions will be caught and optionally assigned to a scoped attribute.

Attributes

Attribute	EL	Required	Description
var	No	No	The name of the attribute to which to assign the WeaverClientException.
scope	No	No	The scope of the attribute to which to assign the WeaverClientException.

Sub-tags

Any.

The <set> Tag

The <set> tag sets the value of scoped attributes.

Attributes

Attribute	EL	Required	Description
var	No	Yes	The name of the attribute to set.
value	Yes	Yes	The value to set the attribute to.
scope	No	Yes	The scope of the attribute to set.

Sub-tags

None.

The <forward> Tag

The <forward> tag is used to forward a request. Typically the target of the forward is a JSP page.

Attributes

Attribute	EL	Required	Description
url	No	Yes	A path (which will be interpreted relative to the servlet context) to forward to.

Sub-tags

None.

The <auth> Tag

The <auth> tag handles user authentication.

Attributes

Attribute	EL	Required	Description
action	No	Yes	One of: required if the session is not authenticated for the given domain then the current execution state will be stored and the security section executed. Usually the security section will issue an authentication challenge to the user in the form of a login page; resume resume execution at the stored state after a successful authentication challenge and add the domain to those authenticated for the session. add add this session to those authenticated for the domain; remove remove this session from those authenticated for the domain.
domain	No	Yes	The name of the authentication domain.

Sub-tags

None.

The <out> Tag

The <out> tags sends output to the browser.

Attributes

Attribute	EL	Required	Description
value	Yes	Yes	The value to send back to the browser. The expression is evaluated and if the result is either a Reader or an InputStream then the its entire contents are read and returned to the browser. Otherwise toString is called on the result and its output is sent to the browser.

Sub-tags

None.

The <remove> Tag

The <remove> tag deletes a scoped attribute.

Attributes

Attribute	EL	Required	Description
var	No	Yes	The name of the attribute to remove.
scope	No	No	The scope from which the attribute is to be removed. If scope is not specified then the named attribute is removed from all scopes.

Sub-tags

None.

Values of the "scope" Attribute

The following table describes each of the possible values of the scope attribute used in the above tags. The mapping of scope names to Java objects is implemented by the WeaverAttributeUtil class. It is strongly recommended when implementing your own tags that take a scope attribute you should use this class to adhere to the convention.

Name	Object	Value
application	context.getApplicationContext()	An application scoped attribute.
servlet	context.getServletContext()	A servlet scoped attribute.
session	context.getSessionContext()	A session scoped attribute.
request	context.getRequestContext()	A request scoped attribute.
local	context.getLocalContext()	A locally scoped attribute.

The Expression Language

The Expression Language (EL) used in Weaver is identical to that specified for for JSP 2.0. Weaver shares some "scopes" with JSP 2.0 and adds some of its own. Those scopes that are shared have identical names in the Weaver EL and is the JSP EL and a value set in one may be accessed by the other.

The scopes used by Weaver are described in the following table.

Name - the name of the scope as it appears in the EL.
Weaver Bean - how to access the scope in Java via the WeaverExecution object supplied to a Weaver Bean.
View - Whether the context is shared with the View component (and so is available to the EL in JSP)
Servlet API - where the values are stored with w.r.t. the servlet API. This should indicate how to access values in a view component other than JSPs via the EL.

Scopes used by Weaver in the EL

Name	In-Bean	View	In Servlet API
localScope	WeaverExecutionContext.getLocalContext().getAttribute()	No	NA
localScope values persist for the length of processing a request, they are only available to the Controller and not to the view. They may be used in any Wad section.
requestScope	WeaverExecutionContext.getRequestContext().getAttribute()	Yes	HttpServletRequest.getAttribute()
requestScope values persist for the duration of a request. They are available to both the Controller and the View. They should only be used in sections that process an active request.
sessionScope	WeaverExecutionContext.getSessionContext().getAttribute()	Yes	HttpSession.getAttribute()
sessionScope values persist for the duration of a session. They are available to both the Controller and the View. They should only we used in sections where a session exists.
servletScope	WeaverExecutionContext.getServletContext().getAttribute()	No	NA
servletScope values a scoped to a particular Weaver servlet. If you have several Weaver servlets (that is several WeaverAppServlets and Wad files etc.) in a particular context servletScoped values in one may not be seen by any of the others.
applicationScope	WeaverExecutionContext.getApplicationContext().getAttribute()	Yes	ServletContext.getAttribute()
applicationScoped values are scoped to a particular Weaver applications. Values are shared by all Weaver servlets in a given context.
param	WeaverExecutionContext.getRequestContext().getParameter()	Yes	HttpServletRequest.getParameter()
param values are those supplied by the browser via HTTP GETs and POSTs. A single value is returned even when a given parameter name has multiple associated values.
paramValues	WeaverExecutionContext.getRequestContext().getParameterValues	Yes	HttpServletRequest.getParameterValues()
paramValues returns values supplied by the browser via HTTP GETs and POSTs. It is differentiated from the param scope by the fact that an array of all values of each param is returned.
contextInitParam	WeaverExecutionContext.getApplicationContext().getInitParameter()	Yes (via initParamScope)	ServletContext.getInitParameter()
init parameters read from the application context in the Web.xml file.
servletInitParam	WeaverExecutionContext.getServletContext().getInitParameter()	No	ServletConfig.getInitParameter(name)
init parameters read from the servlet section in the Web.xml file.
header	WeaverExecutionContext.getRequestContext().getHeader()	Yes	HttpServletRequest.getHeader()
HTTP headers, when a header has multiple values only the first is returned.
headerValues	WeaverExecutionContext.getRequestContext().getHeaders()	Yes	HttpServletRequest.getHeaders()
HTTP headers, all values of headers are returned.
uploadedFile	WeaverExecutionContext.getRequestContext().getUploadedFile()	No	NA
Uploaded files.

When Scope is Unspecified

If the scope is unspecified in an EL expression, then the scopes are searched in the order shown in the following:

localScope
requestScope
sessionScope
servletScope
applicationScope

Configuration Files

The Application Configuration File

The application configuration file (WEB-INF/application/conf/application.properties) contains context wide settings, as follows:

weaver.attribute_asserts_on: false weaver.upload_dir: /WEB-INF/application/uploads

The weaver.attribute_asserts_on property enables or to disables attribute assertions carried out by the com.oldlight.weaver.clientbinding.WeaverAttributeAssertion class.

The weaver.upload_dir property configures the temporary directory in which uploaded files are stored.

Always set the value of the weaver.attribute_asserts_on parameter to false in a production environment. Failure to do so will degrade performance.

Any property whose name begins property is used by Weaver to set the value of a system property. For example, to set the property that selects the SAX driver used to process XML files:

property.org.xml.sax.driver: org.apache.xerces.parsers.SAXParser

The name of the system property is formed by removing the property prefix from the name as it appears in the configuration file.

Finally the application configuration file contains logging settings. These are the standard settings of the Apache Log4j package that is used to implement Weaver logging. See the Log4j web site for further information.

The Per-Servlet Configuration File

Each Weaver based servlet has its own configuration file. This is made available to your servlet through the ServletContext.getConfigValue() method. The only setting acted on by Weaver itself is:

weaver.reload_if_modified: false

The value of weaver.reload_if_modified parameter determines whether modifications to the WAD file or configuration files should trigger an automatic application reload. Setting this parameter to true will degrade application performance. It exists purely for convenience during application development and should always be set to false in a production environment.

Always set the value of the weaver.reload_if_modified parameter to false in a production environment. Failure to do so will severely degrade performance.

The Web Application Deployment Descriptor (web.xml)

A section from a typical deployment descriptor (web.xml) for a Weaver based application follows.

The first listener is required by Weaver for session initialisation and destruction and the second is used by the Administrative Console.

Next comes Weaver's initialisation servlet. This must be loaded first (hence the <load-on-startup>1</load-on-startup> element.

Then comes the servlet that implements Weaver's Administrative Console.

This is followed by the declaration of the servlet(s) which implement your Weaver application(s).

Finally we have the servlet mapping for Weaver's administrative console and for your servlets.

... <listener> <listener-class> com.oldlight.weaver.interpreter.WeaverSessionListener </listener-class> </listener> <listener> <listener-class> com.oldlight.weaver.admin.WeaverStatisticsListener </listener-class> </listener> <servlet> <servlet-name>init</servlet-name> <servlet-class> com.oldlight.weaver.initservlet.WeaverInitServlet </servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet> <servlet-name>admin</servlet-name> <servlet-class> com.oldlight.weaver.appservlet.WeaverApplicationServlet </servlet-class> <load-on-startup>2</load-on-startup> </servlet> <servlet> <servlet-name>myapp</servlet-name> <servlet-class> com.oldlight.weaver.appservlet.WeaverApplicationServlet </servlet-class> <load-on-startup>3</load-on-startup> </servlet> <servlet-mapping> <servlet-name>init</servlet-name> <url-pattern>/init/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>admin</servlet-name> <url-pattern>/myapp/admin/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>myapp</servlet-name> <url-pattern>/myapp/*</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file>myapp</welcome-file> </welcome-file-list> <session-config> <session-timeout>10</session-timeout> </session-config> ...