Work in progress

This version may be updated without notice.

Web Specification

A Web module for Active Tags

Working Draft 12 june 2008

Abstract

This specification describes a Web optional module for Active Tags. This Web module provides tags, attributes, functions, predefined properties and data types related to Web applications.

Requirement levels

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Note that for reasons of style, these words are not capitalized in this document.

Active Tags specifications

The following specifications are part of the Active Tags technologies.

The Active Tags specification
The EXP specification
The XCL specification
The Active Schema Language specification
The Active Datatypes specification
The Active Catalog specification

1 The Web module
2 Web concepts

2.1 Application
2.2 Service
2.3 HTTP handling
2.4 The web URI scheme
2.5 Example

3 Use cases

3.1 Setting the MIME type of the HTTP response
3.2 Setting the character encoding of the HTTP response
3.3 Setting HTTP headers of the response
3.4 Using matchers
3.5 Cookies handling

4 Web module reference

4.1 Elements
4.2 Foreign attributes
4.3 Predefined properties
4.4 Extended XPath functions
4.5 Data types

Appendix

A Lists

A.1 Examples list

1 The Web module

This Active Tags module has been designed for basic Web support. It provides a high-level abstraction of a Web application. A Web application runs inside a Web engine that embeds an Active Tags engine. How the engines are cooperating is out of the scope of this specification.

2 Web concepts

Most Web concepts are represented in Active Tags thanks to typed properties stored in the data set.

2.1 Application

The Web application is the top level entry to a set of services related to the application. A Web application is mapped either at the server root, or just under the server root. Let's consider 3 Web applications available at http://www.example.com :

http://www.example.com/myApp/ : the "myApp" application
http://www.example.com/anotherApp/ : the "anotherApp" application
http://www.example.com/ : the root application ; every URL path that doesn't start with /myApp nor /anotherApp is mapped to the root application.

According to the underlying Web engine used, the Web application may endorse a set of informations accessible with Active Tags with the $web:application property ; additionally, parameters used to initialize the Web application are also accessible.

The $web:application property can be referred within any Active Tags service supplied by the Web application.

The Web application is in charge of the selection of the service to invoke. The selection of the service by the Web application is implementation dependant.

2.2 Service

Several services can be defined within a Web application. Each service of a Web application can be represented by an active sheet. How each service (active sheet) is bound to the Web application, and how it is invoked is implementation dependant.

The root element of such services is the <web:service> element that declares the mappings (<web:mapping>) used for handling HTTP requests.

The Web engine may also provide a set of initialization parameters with the $web:service property, which is accessible in the entire active sheet.

A service can also define an initialization phase (thanks to the <web:init> element) that will be performed once when the server starts. Its content is a convenient place to define shared properties.

2.3 HTTP handling

When a service is invoked by the Web application, the mapping (<web:mapping>) that matches the request's URL and the relevant HTTP method is invoked with the following properties :

property	type	usage
`$web:request`	`#web:x-request`	represents the HTTP request (note that one of its attribute contains the groups captured by the regular expression used for matching the incoming URL if relevant)
`$web:response`	`#web:x-response`	represents the HTTP response
`$web:session`	`#web:x-session`	represents an HTTP session
`$web:cookies`	`#web:x-cookies`	represent the set of HTTP cookies

The scope of these properties is global.

2.4 The `web` URI scheme

A Web application is often deployed to a target location not necessary known by developers, or that could be relocated ; the resources that depend on the location of a web application must be accessed in a neutral way (without the knowledge of the real path where the application is located). To do so, an implementation of this module must rely on a file system manager that accept the web URI scheme.

The web URI scheme is like the file URI scheme, except that the root file depends on the location where the Web application is effectively deployed. For convenience, the web URI scheme may be translated to a more classical file scheme. If necessary, this translation may be performed by a catalog.

For example, the following URI "web:///WEB-INF/xslt/xmlToHtml.xslt" could be resolved to the local file "file:///path/to/tomcat/webapps/myApp/WEB-INF/xslt/xmlToHtml.xslt".

2.5 Example

A Web application

	A Web application
The following active sheet defines an HTTP service of a Web application. <?xml version="1.0" encoding="iso-8859-1"?> <web:service xmlns:web="http://ns.inria.org/active-tags/web" xmlns:xcl="http://ns.inria.org/active-tags/xcl"> <!-- init phase run once when the server starts --> <web:init> <!-- define a shareable stylesheet : all concurrent HTTP request can use it safely --> <xcl:parse-stylesheet name="xmlToHtml" scope="shared" value="web:///WEB-INF/xslt/xmlToHtml.xslt"/> </web:init> <!-- Matches URL = http://www.example.com/myApp/this.xml --> <web:mapping match="^/this\.xml$"> <!-- simply return "$this" active-sheet --> <xcl:transform output="{ value( $web:response/@web:output ) }" source="{ $this }"/> </web:mapping> <!-- Matches URL = http://www.example.com/myApp/[whatever].html --> <web:mapping match="^/(.+).html$"> <!-- simply transform an XML file to HTML : -the name of the source file to transform is built with the URL part that matches the regular expression -the XSLT stylesheet is those parsed at the init phase -the output is the HTTP response stream sent back to the client --> <xcl:transform output="{ value( $web:response/@web:output ) }" source="web:///{ string( $web:request/@web:match ) }.xml" stylesheet="{ $xmlToHtml }"/> </web:mapping> </web:service> In this service, a stylesheet is parsed when the server starts. This stylesheet will be shared by all HTTP requests. Assuming that the Web application is hosted at `http://www.example.com/` and mapped to the path `/myApp/`, this service might serves : `http://www.example.com/myApp/this.xml` : the XML source of this service (the active sheet above). `http://www.example.com/myApp/document.html` : an HTML view of `myApp/document.xml`.

The following active sheet defines an HTTP service of a Web application.

<?xml version="1.0" encoding="iso-8859-1"?>
<web:service
    xmlns:web="http://ns.inria.org/active-tags/web"
    xmlns:xcl="http://ns.inria.org/active-tags/xcl">

    <!-- init phase run once when the server starts -->
    <web:init>
        <!-- define a shareable stylesheet :
             all concurrent HTTP request can use it safely
        -->
        <xcl:parse-stylesheet name="xmlToHtml" scope="shared" value="web:///WEB-INF/xslt/xmlToHtml.xslt"/>
    </web:init>

    <!-- Matches URL = http://www.example.com/myApp/this.xml -->
    <web:mapping match="^/this\.xml$">
        <!-- simply return "$this" active-sheet -->
        <xcl:transform output="{ value( $web:response/@web:output ) }" source="{ $this }"/>
    </web:mapping>

    <!-- Matches URL = http://www.example.com/myApp/[whatever].html -->
    <web:mapping match="^/(.+).html$">
        <!-- simply transform an XML file to HTML :
                 -the name of the source file to transform is built with
                      the URL part that matches the regular expression
                 -the XSLT stylesheet is those parsed at the init phase
                 -the output is the HTTP response stream sent back to
                      the client
        -->
        <xcl:transform output="{ value( $web:response/@web:output ) }"
 source="web:///{ string( $web:request/@web:match ) }.xml"
 stylesheet="{ $xmlToHtml }"/>
    </web:mapping>

</web:service>

In this service, a stylesheet is parsed when the server starts. This stylesheet will be shared by all HTTP requests.

Assuming that the Web application is hosted at http://www.example.com/ and mapped to the path /myApp/, this service might serves :

http://www.example.com/myApp/this.xml : the XML source of this service (the active sheet above).
http://www.example.com/myApp/document.html : an HTML view of myApp/document.xml.

3 Use cases

3.1 Setting the MIME type of the HTTP response

With a hard-coded value specified in the mapping :

  <web:mapping match="^/(.+)\.(xml|html)$" mime-type="application/xml">
    <!-- the MIME type of the response is those specified above -->
    <!-- ... -->
  </web:mapping>

If the MIME type is not known at designed-time, it can be set at runtime as an attribute of the HTTP response :

  <web:mapping match="^/(.*)$" mime-type="">
    <!-- the mapping above states that no MIME type is set so far -->
    <!-- the MIME type specified below is set as an attribute of the response -->
    <xcl:attribute name="web:mime-type" referent="{ $web:response }" value="application/xml"/>
    <!-- ... -->
  </web:mapping>

With a computed value :
```
  <web:mapping match="^/(.+)\.(xml|html)$">
    
    
  </web:mapping>
```
...will set the MIME type according to the extension of the URL matched ; in the above example, it can be "application/xml" if the extension is "xml", or "text/html" if the extension is "html". Specifying the empty string is not the same as not specifying the attribute : in the former case, the MIME type is not set.

If the MIME type doesn't depend on the extension of the URL, but rather on a parameter value, it can be set by using the web:mime-type() function :
```
  
  <web:mapping match="^/query/(.*)$" mime-type="">
    <io:file name="file" uri="web:///{ $web:request/file }"/>
    <xcl:attribute name="web:mime-type" referent="{ $web:response }"
 value="{ web:mime-type( $file ) }"/>
    
  </web:mapping>
```
How MIME types are bound to file extensions is implementation dependant.

3.2 Setting the character encoding of the HTTP response

The character encoding is also an attribute of the HTTP response.

    <xcl:attribute name="web:encoding" referent="{ $web:response }" value="ISO-8859-1"/>

3.3 Setting HTTP headers of the response

HTTP headers are children of the HTTP response.

    <xcl:append referent="{ $web:response }">
        <xcl:item name="Cache-Control" value="no-cache"/>
    </xcl:append>

3.4 Using matchers

The $web:request property is of the type #web:x-request that defines the @web:match attribute that contains the list of strings captured by the regular expression used in the mapping ; for convenience, each string captured is exposed as an unamed element (and accessible with the XPath joker "*") ; this facility makes this list not serializable as-is.

When there is a single captured string, the list can be processed as is.

For example, if the incoming URL http://www.example.com/myApp/document.html is matched by a mapping of the /myApp/ application that uses the regular expression ^/(.+).html$, it will be applied on the path /document.html and the part in bold will be captured. string( $web:request/@web:match ) will give the string "document".

    <!-- using a regular expression that captures a single string ;
         the string matched is in $web:request/@web:match -->
    <web:mapping match="^/(.+).html$" mime-type="text/html">
        <!-- simply transform an XML file to HTML -->
        <xcl:transform output="{ value( $web:response/@web:output ) }"
 source="web:///{ string( $web:request/@web:match ) }.xml"
 stylesheet="web:///WEB-INF/foo.xsl"/>
    </web:mapping>

If there are several groups captured, the list will contain several items. Each can be retrieved by specifying its position in the list :

    <!-- using a regular expression that captures 2 groups of string ;
         the groups of string matched are in $web:request/@web:match/* -->
    <web:mapping match="^/(.+[^/])/img/(.*)$">
        <!-- set the MIME type according to the extension of the file
                specified in the second group string -->
        <xcl:attribute name="web:mime-type" referent="{ $web:response }"
 value="{ web:mime-type( string( $web:request/@web:match/*[2] ) ) }"/>
        <!-- simply display the img -->
        <io:copy
 source="web:///img/{ string( $web:request/@web:match/*[1] ) }/{ string( $web:request/@web:match/*[2] ) }"
 target="{ value( $web:response/@web:output ) }"/>
    </web:mapping>

With the example above, the regular expression will match the request http://www.example.com/myApp/landscape/img/canyon.jpg and capture the two strings "landscape" and "canyon.jpg". The latter will serve to set the MIME type of the response. The body will be a copy of the file web:///img/landscape/canyon.jpg (that will be resolved relatively to the place where has been deployed the Web application on the server.)

3.5 Cookies handling

Cookies can be retrieved with $web:cookies (which contains the list of cookies sent by the client) and new ones can be created with <web:cookie> ; in both cases, the type of a single cookie is #web:x-cookie.

To send them back to the client, they have to be stored within the attributes of the $web:response :

    <xcl:append referent="{ $web:response }">
        <web:cookie comment="The user preferences" max-age="{ 60*60*24*365 }"
 name="userBackgroundColor" value="#FE80FE"/>
        <web:cookie comment="The user preferences" max-age="{ 60*60*24*365 }"
 name="userForegroundColor" value="{ string( $web:request/foregroundColor ) }"/>
    </xcl:append>

Once the HTTP response is send back to the client, on new requests the server will receive the cookies it had set before :

  <div
 style="background-color: { $web:cookie/userBackgroundColor } ; color: { $web:cookie/userForegroundColor }">
    <!-- we should test before if the cookies exist ! -->
  </div>

If several cookies that have the same name were sent, each can be retrieved individually :

    { string( $web:cookie/preferredSearchEngine[ 1 ]/@value ) }
    { string( $web:cookie/preferredSearchEngine[ 2 ]/@value ) }

4 Web module reference

Web namespace URI	:	`http://ns.inria.org/active-tags/web`
Usual prefix	:	`web`

Elements	Foreign attributes	Predefined properties	Extended functions	Data types
`<web:service>` `<web:init>` `<web:mapping>` `<web:flush>` `<web:clear>` `<web:invoke>` `<web:cookie>`	`@web:version`	`$web:application` `$web:service` `$web:request` `$web:response` `$web:session` `$web:cookies`	`web:mime-type()`	`#web:x-application` `#web:x-service` `#web:x-request` `#web:x-response` `#web:x-session` `#web:x-cookie`

	Must be an `adt:expression` that computes an object of the type expected.
	Must be a hard-coded value (litteral)
	Can be either a hard-coded value or an `adt:expression`
	This material may be missing
	Denotes a value to use by default
	Allows a read operation.
	Allows a write operation.
	Allows a rename operation.
	Allows an update operation.
	Allows a delete operation.

4.1 Elements

`<web:service>`

Root element for an active sheet that stands for a Web service.

A service is selected by an application in a way that is implementation dependant.

server initialization phase

The active sheet is unmarshalled when the Web engine starts.

If present, the <web:init> procedure is invoked.

HTTP handling phase

The Web engine selects the <web:mapping> procedure to invoke.

Attributes runtime | hard-coded | both
Name Type Value optional | default value

encoding #xs:string
If the request doesn't specify a character encoding, the default encoding used will be those specified in this attribute, if any.

Content : <web:init>, <web:mapping>+

Attributes	runtime \| hard-coded \| both
	Name	Type	Value	optional \| default value
	encoding	`#xs:string`	If the request doesn't specify a character encoding, the default encoding used will be those specified in this attribute, if any.

`<web:init>`

Defines the initialization procedure.

unmarshal phase

Registers this action to the processor instance as the default procedure.

runtime phase

Run the subactions.

Content : any

`<web:mapping>`

Handles an HTTP request. The first mapping that matches the incoming URL is invoked by the surrounding <web:service>.

runtime phase

Run the subactions.

Attributes runtime | hard-coded | both
Name Type Value optional | default value

match #adt:regexp
A regular expression used to match the request's URL. If groups of strings are captured by the regular expression, they will be available with $web:request/@web:match/*.

missing attribute
If missing, this procedure matches all URL with the method specified ; such mapping should be the last mapping defined in a service.

use
The string to test regarding the regular expression.

missing The test is made on the part of the request's URL from the application name up to the query string ; for example, if a Web application is mapped to /myApp/ at http://www.example.com/, then with the request http://www.example.com/myApp/path/to/doc.html?param=value, the regular expression is tested on /path/to/doc.html. Notice that the application name is excluded from the path, which make matchings insensible to the deployment location of the application ; if the Web application is mapped to /anotherApp/ or to the root /, the string to match remains the same.
#xs:string
It is possible to build other strings on which the regular expression will be applied ; for example use="{$web:request/@web:full-path}" will produce /myApp/path/to/doc.html?param=value (this time the mapping will be sensible to the path of the Web application).

method Indicates which HTTP method will be matched by this mapping. If specified, one or several of the values below may be specified.
missing attribute All HTTP methods are concerned.
#xs:string GET This mapping will be activated on HTTP GET requests.
POST This mapping will be activated on HTTP POST requests.
HEAD This mapping will be activated on HTTP HEAD requests.
PUT This mapping will be activated on HTTP PUT requests.
DELETE This mapping will be activated on HTTP DELETE requests.
OPTIONS This mapping will be activated on HTTP OPTIONS requests.
TRACE This mapping will be activated on HTTP TRACE requests.
#xs:string Several values from the above list, separated with blanks.

mime-type Specify how to set the MIME type to the HTTP response.
missing attribute No MIME type is set by default.
#xs:string '' Try to set the MIME type automatically according to the extension of the URL.
For example, if the URL is http://www.acme.org/index.html, the MIME type should be text/html.
The underlying implementation should define means to bind extensions to MIME types.
#xs:string Set the MIME type to the value specified.

Content : any

Attributes	runtime \| hard-coded \| both
	Name	Type	Value	optional \| default value
	match	`#adt:regexp`	A regular expression used to match the request's URL. If groups of strings are captured by the regular expression, they will be available with `$web:request/@web:match/*`.
missing attribute	If missing, this procedure matches all URL with the method specified ; such mapping should be the last mapping defined in a service.
	use	The string to test regarding the regular expression.
missing	The test is made on the part of the request's URL from the application name up to the query string ; for example, if a Web application is mapped to `/myApp/` at `http://www.example.com/`, then with the request `http://www.example.com/myApp/path/to/doc.html?param=value`, the regular expression is tested on `/path/to/doc.html`. Notice that the application name is excluded from the path, which make matchings insensible to the deployment location of the application ; if the Web application is mapped to `/anotherApp/` or to the root `/`, the string to match remains the same.
`#xs:string`	It is possible to build other strings on which the regular expression will be applied ; for example `use="{$web:request/@web:full-path}"` will produce `/myApp/path/to/doc.html?param=value` (this time the mapping will be sensible to the path of the Web application).
	method	Indicates which HTTP method will be matched by this mapping. If specified, one or several of the values below may be specified.
missing attribute	All HTTP methods are concerned.
`#xs:string`	GET	This mapping will be activated on HTTP GET requests.
POST	This mapping will be activated on HTTP POST requests.
HEAD	This mapping will be activated on HTTP HEAD requests.
PUT	This mapping will be activated on HTTP PUT requests.
DELETE	This mapping will be activated on HTTP DELETE requests.
OPTIONS	This mapping will be activated on HTTP OPTIONS requests.
TRACE	This mapping will be activated on HTTP TRACE requests.
`#xs:string`	Several values from the above list, separated with blanks.
	mime-type	Specify how to set the MIME type to the HTTP response.
missing attribute	No MIME type is set by default.
`#xs:string`	''	Try to set the MIME type automatically according to the extension of the URL. For example, if the URL is `http://www.acme.org/index.html`, the MIME type should be `text/html`. The underlying implementation should define means to bind extensions to MIME types.
`#xs:string`	Set the MIME type to the value specified.

`<web:flush>`

Forces any content in the buffer of the HTTP response to be written to the client.

`<web:clear>`

Clears the buffer of the HTTP response, and eventually the status code and headers.

Attributes runtime | hard-coded | both
Name Type Value optional | default value

clear-headers Indicates whether the status code and headers have to be cleared or not.
#xs:boolean true Clear all.
false Preserve the status code and headers.

Attributes	runtime \| hard-coded \| both
	Name	Type	Value	optional \| default value
	clear-headers	Indicates whether the status code and headers have to be cleared or not.
`#xs:boolean`	true	Clear all.
false	Preserve the status code and headers.

`<web:invoke>`

Invoke a service on the server.

Attributes runtime | hard-coded | both
Name Type Value optional | default value

path

mode Indicates whether the service must be included or forwarded.
#xs:string forward Forwards the request from a service to another resource (service, HTML file, etc) on the server.
include Includes the content of another resource (service, HTML file, etc) in the HTTP response.

Attributes	runtime \| hard-coded \| both
	Name	Type	Value	optional \| default value
	path
	mode	Indicates whether the service must be included or forwarded.
`#xs:string`	forward	Forwards the request from a service to another resource (service, HTML file, etc) on the server.
include	Includes the content of another resource (service, HTML file, etc) in the HTTP response.

`<web:cookie>`

Create a new #web:x-cookie and stores it in the current context. A cookie behaves like an attribute.

The cookies created have to be stored within the attributes of the $web:response.

Attributes runtime | hard-coded | both
Name Type Value optional | default value

name

value

comment

domain

path

max-age

is-secure Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.
#xs:boolean true Sends the cookie from the browser to the server only when using a secure protocol.
false Sent on any protocol.

version Sets the version of the cookie protocol this cookie complies with.
#xs:integer 0 Complies with the original Netscape cookie specification.
1 Complies with RFC 2109.

Attributes	runtime \| hard-coded \| both
	Name	Type	Value	optional \| default value
	name
	value
	comment
	domain
	path
	max-age
	is-secure	Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.
`#xs:boolean`	true	Sends the cookie from the browser to the server only when using a secure protocol.
false	Sent on any protocol.
	version	Sets the version of the cookie protocol this cookie complies with.
`#xs:integer`	0	Complies with the original Netscape cookie specification.
1	Complies with RFC 2109.

4.2 Foreign attributes

`@web:version`

Priority : 0

The version of the Web module to use. This attribute should be encountered before any Web element, but it takes precedence on the element inside which it is hosted.

4.3 Predefined properties

`$web:application`

Property type: #web:x-application

$web:application is a reference to the Web application.

`$web:service`

Property type: #web:x-service

$web:service is a reference to the HTTP service.

`$web:request`

Property type: #web:x-request

$web:request is a reference to the HTTP request.

`$web:response`

Property type: #web:x-response

$web:response is a reference to the HTTP response.

`$web:session`

Property type: #web:x-session

$web:session is a reference to the HTTP session. If no session exists, using this property will create a new one. To check if a session already exists, use $web:request/@web:has-session.

`$web:cookies`

Property type: #adt:list of #web:x-cookie

$web:cookie is a reference to the cookies.

4.4 Extended XPath functions

`web:mime-type()`

Return: #xs:string

Return the MIME type of a file. How the MIME type is resolved is implementation dependant ; it can be resolved thanks to some mappings of file extensions to MIME types, thanks to some heuristic that reads the content of the file, or thanks to a mix of both strategies.

Arguments
1 #io:x-file The file.
Arguments
1 #xs:anyURI The URI of the file.

Arguments
1	`#io:x-file`	The file.
Arguments
1	`#xs:anyURI`	The URI of the file.

4.5 Data types

`#web:x-application` type

Represents a Web application.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-application This type

name()
#xs:string The name of the application, if the underlying Web engine is naming applications.

child::

#adt:list of #adt:NItem Contains the init parameters (implementation dependant) used when the application is initialized. The init parameters are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the init parameter).

attribute::

#adt:map of #adt:NItem A set of attributes including those specified below (and that can't be removed). Other predefined attributes may have been set by the underlying Web engine. At runtime, additional attributes may be set, removed or updated, if they are not bound to a namespace URI.

@web:server-info

#xs:string Informations about the underlying Web engine.

@web:server-version

#xs:string The version of the underlying Web engine.

@web:application-path

#xs:string The path to the application, that either starts with "/", or is "".

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-application`	This type
`name()`
	`#xs:string`	The name of the application, if the underlying Web engine is naming applications.
`child::`
	`#adt:list` of `#adt:NItem`	Contains the init parameters (implementation dependant) used when the application is initialized. The init parameters are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the init parameter).
`attribute::`
	`#adt:map` of `#adt:NItem`	A set of attributes including those specified below (and that can't be removed). Other predefined attributes may have been set by the underlying Web engine. At runtime, additional attributes may be set, removed or updated, if they are not bound to a namespace URI.
`@web:server-info`
	`#xs:string`	Informations about the underlying Web engine.
`@web:server-version`
	`#xs:string`	The version of the underlying Web engine.
`@web:application-path`
	`#xs:string`	The path to the application, that either starts with "/", or is "".

`#web:x-service` type

Represents an HTTP service.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-service This type

name()
#xs:string The name of the service, if the underlying Web engine is naming services.

child::

#adt:list of #adt:NItem Contains the init parameters (implementation dependant) used when the service is initialized. The init parameters are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the init parameter).

attribute::

#adt:map of #xml:attribute A fixed set of attributes (see below).

@web:info

#xs:string Informations about the service, such as author, version...

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-service`	This type
`name()`
	`#xs:string`	The name of the service, if the underlying Web engine is naming services.
`child::`
	`#adt:list` of `#adt:NItem`	Contains the init parameters (implementation dependant) used when the service is initialized. The init parameters are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the init parameter).
`attribute::`
	`#adt:map` of `#xml:attribute`	A fixed set of attributes (see below).
`@web:info`
	`#xs:string`	Informations about the service, such as author, version...

`#web:x-request` type

Represents an HTTP request.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-request This type

name()
#xs:QName web:request The name of a request.

child::

#adt:list of #adt:NItem
Represent the parameters contained in the query string or posted form data. The parameters are contained in a list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the parameter) ; the list may contain duplicate names. Each value is either a #xs:string or a #io:x-file to upload (a file can be unwrapped from the parameter thanks to the value() function).
If parameters are sent with the POST method, the @web:input attribute won't be available : the parameters of the request body will be directly available within the child list. In order to not break the body input stream of the request, a special behaviour is implemented for files to upload : the child list will be fed progressively with the files to upload.
If several other parameters are following the first file to upload, only the file to upload will be available ; when its content is uploaded, @web:next-parameters indicates whether there are remainder parameters or not that will be appended to the child list until including the next file to upload and so on.
The input streams of the files to upload can be read once ; they are discarded when read or when accessing the next parameters.

attribute::

#adt:map of #adt:NItem A set of attributes including those specified below (and that can't be removed). Other predefined attributes may have been set by the underlying Web engine. Additional attributes may be set, removed or updated, if they are not bound to a namespace URI.

@web:next-parameters

#xs:int
Indicates whether more parameters are available within the children or not. It is relevant with the POST method with files to upload.
Reading the value of this attribute cause forwarding the body stream until the next file to upload. The number of parameters read is then returned. 0 means that no more parameters are available ; a strict positive value can be returned only with the POST method. Parameters that are read in the body are appended to the child list as one goes along.
Note that handling this attribute doesn't cause forwarding the body stream, only reading its value does (explicitely with the value() function or implicitely for example when the attribute is involved in an arithmetic operation). Note that this value should be read after having processed the file to upload, otherwise the file content will be discarded.

@web:encoding

#xs:string The name of the chararacter encoding if the request specifies one.

@web:content-length

#xs:integer The length of the request body, the same as the CGI variable CONTENT_LENGTH.

@web:mime-type

#xs:string The MIME type of the body of the request if known, the same as the value of the CGI variable CONTENT_TYPE.

@web:input

#io:input The body of the request. Available only if the body doesn't contain POST parameters.

@web:has-session

#xs:boolean Indicates whether a session is available or not.

@web:local-addr

#xs:string The IP address of the interface on which the request was received.

@web:local-host

#xs:string The host name that received the request.

@web:local-port

#xs:integer The IP port number of the interface on which the request was received.

@web:protocol

#xs:string The name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1 ; the value returned is the same as the value of the CGI variable SERVER_PROTOCOL.

@web:remote-addr

#xs:string The IP address of the client or last proxy that sent the request, the same as the value of the CGI variable REMOTE_ADDR.

@web:remote-host

#xs:string The fully qualified name of the client or the last proxy that sent the request if the underlying Web engine resolves the hostname, or the dotted-string form of the IP address ; the same as the value of the CGI variable REMOTE_HOST.

@web:remote-port

#xs:integer The IP source port of the client or last proxy that sent the request.

@web:scheme

#xs:string The name of the scheme used to make this request, for example, http or https.

@web:server-name

#xs:string The host name of the server to which the request was sent. It is the value of the part before ":" in the Host header, if any, or the resolved server name, or the server IP address.
Example : www.acme.org

@web:server-port

#xs:integer The port number to which the request was sent. It is the value of the part after ":" in the Host header, if any, or the server port where the client connection was accepted on.

@web:server

#xs:string The protocol, host name, and port of the server to which the request was sent.
Example : http://www.acme.org:8080

@web:is-secure

#xs:boolean Indicates whether this request was made using a secure channel, such as HTTPS.

@web:auth-type

#xs:string The name of the authentication scheme used ; the same as the value of the CGI variable AUTH_TYPE.

@web:application-path

#xs:string The path to the application, that either starts with "/", or is "" (for the root application).

@web:path

#xs:string The path of the request's URL from the protocol name up to the query string.
For example, with the request http://www.acme.org/path/to/doc.html?param=value, the path is /path/to/doc.html.

@web:full-path

#xs:string The path of the request's URL from the protocol name up to and including the query string.
For example, with the request http://www.acme.org/path/to/doc.html?param=value, the full path is /path/to/doc.html?param=value.

@web:url

#xs:string The full URL of the request, including the protocol, server name, port number, and path, but it does not include query string parameters.
For example, with the request http://www.acme.org/path/to/doc.html?param=value, the URL is http://www.acme.org/path/to/doc.html.

@web:full-url

#xs:string The full URL of the request, including the protocol, server name, port number, path, and the query string.
For example, with the request http://www.acme.org/path/to/doc.html?param=value, the full URL is the same.

@web:headers

#adt:list of #adt:NItem Represent the headers contained in this request. The headers are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the header) ; the list may contain duplicate names. Each header behave like an element.

@web:method

#xs:string The name of the HTTP method with which this request was made, for example, GET, POST, or PUT ; the same as the value of the CGI variable REQUEST_METHOD.

@web:path-info

#xs:string Any extra path information associated with the URL the client sent when it made this request ; the same as the value of the CGI variable PATH_INFO.

@web:path-translated

#xs:string Any extra path information translated to a real path ; the same as the value of the CGI variable PATH_TRANSLATED.
Example : /var/www/htdocs/path/to/doc.html

@web:query-string

#xs:string The query string that is contained in the request URL after the path ; the same as the value of the CGI variable QUERY_STRING.

@web:match

#adt:list of #adt:NItem The list of strings that has been captured by the regular expression used in a <web:mapping> (the empty list if not relevant). Each group of string is exposed as an unamed element, that is to say a named item which name is "".

@web:has-session

#xs:boolean Indicates whether a session is available. If no session is available, the predefined property $web:session will create a new one when invoked.

Precaution while handling parameters

As a request may handle several parameters that has the same name, it is recommended to use one of the following form when processing a single parameter :

value( $web:request/theParam )

$web:request/theParam[ 1 ]

value( $web:request/theParam[ 1 ] )

If more than 1 parameter was supplied whereas only 1 is expected, the parameters in excess would be ignored.

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-request`	This type
`name()`
	`#xs:QName`	web:request	The name of a request.
`child::`
	`#adt:list` of `#adt:NItem`	Represent the parameters contained in the query string or posted form data. The parameters are contained in a list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the parameter) ; the list may contain duplicate names. Each value is either a `#xs:string` or a `#io:x-file` to upload (a file can be unwrapped from the parameter thanks to the `value()` function). If parameters are sent with the POST method, the `@web:input` attribute won't be available : the parameters of the request body will be directly available within the child list. In order to not break the body input stream of the request, a special behaviour is implemented for files to upload : the child list will be fed progressively with the files to upload. If several other parameters are following the first file to upload, only the file to upload will be available ; when its content is uploaded, `@web:next-parameters` indicates whether there are remainder parameters or not that will be appended to the child list until including the next file to upload and so on. The input streams of the files to upload can be read once ; they are discarded when read or when accessing the next parameters.
`attribute::`
	`#adt:map` of `#adt:NItem`	A set of attributes including those specified below (and that can't be removed). Other predefined attributes may have been set by the underlying Web engine. Additional attributes may be set, removed or updated, if they are not bound to a namespace URI.
`@web:next-parameters`
	`#xs:int`	Indicates whether more parameters are available within the children or not. It is relevant with the POST method with files to upload. Reading the value of this attribute cause forwarding the body stream until the next file to upload. The number of parameters read is then returned. 0 means that no more parameters are available ; a strict positive value can be returned only with the POST method. Parameters that are read in the body are appended to the child list as one goes along. Note that handling this attribute doesn't cause forwarding the body stream, only reading its value does (explicitely with the `value()` function or implicitely for example when the attribute is involved in an arithmetic operation). Note that this value should be read after having processed the file to upload, otherwise the file content will be discarded.
`@web:encoding`
	`#xs:string`	The name of the chararacter encoding if the request specifies one.
`@web:content-length`
	`#xs:integer`	The length of the request body, the same as the CGI variable CONTENT_LENGTH.
`@web:mime-type`
	`#xs:string`	The MIME type of the body of the request if known, the same as the value of the CGI variable CONTENT_TYPE.
`@web:input`
	`#io:input`	The body of the request. Available only if the body doesn't contain POST parameters.
`@web:has-session`
	`#xs:boolean`	Indicates whether a session is available or not.
`@web:local-addr`
	`#xs:string`	The IP address of the interface on which the request was received.
`@web:local-host`
	`#xs:string`	The host name that received the request.
`@web:local-port`
	`#xs:integer`	The IP port number of the interface on which the request was received.
`@web:protocol`
	`#xs:string`	The name and version of the protocol the request uses in the form `protocol/majorVersion.minorVersion`, for example, `HTTP/1.1` ; the value returned is the same as the value of the CGI variable SERVER_PROTOCOL.
`@web:remote-addr`
	`#xs:string`	The IP address of the client or last proxy that sent the request, the same as the value of the CGI variable REMOTE_ADDR.
`@web:remote-host`
	`#xs:string`	The fully qualified name of the client or the last proxy that sent the request if the underlying Web engine resolves the hostname, or the dotted-string form of the IP address ; the same as the value of the CGI variable REMOTE_HOST.
`@web:remote-port`
	`#xs:integer`	The IP source port of the client or last proxy that sent the request.
`@web:scheme`
	`#xs:string`	The name of the scheme used to make this request, for example, `http` or `https`.
`@web:server-name`
	`#xs:string`	The host name of the server to which the request was sent. It is the value of the part before ":" in the Host header, if any, or the resolved server name, or the server IP address. Example : `www.acme.org`
`@web:server-port`
	`#xs:integer`	The port number to which the request was sent. It is the value of the part after ":" in the Host header, if any, or the server port where the client connection was accepted on.
`@web:server`
	`#xs:string`	The protocol, host name, and port of the server to which the request was sent. Example : `http://www.acme.org:8080`
`@web:is-secure`
	`#xs:boolean`	Indicates whether this request was made using a secure channel, such as HTTPS.
`@web:auth-type`
	`#xs:string`	The name of the authentication scheme used ; the same as the value of the CGI variable AUTH_TYPE.
`@web:application-path`
	`#xs:string`	The path to the application, that either starts with "/", or is "" (for the root application).
`@web:path`
	`#xs:string`	The path of the request's URL from the protocol name up to the query string. For example, with the request `http://www.acme.org/path/to/doc.html?param=value`, the path is `/path/to/doc.html`.
`@web:full-path`
	`#xs:string`	The path of the request's URL from the protocol name up to and including the query string. For example, with the request `http://www.acme.org/path/to/doc.html?param=value`, the full path is `/path/to/doc.html?param=value`.
`@web:url`
	`#xs:string`	The full URL of the request, including the protocol, server name, port number, and path, but it does not include query string parameters. For example, with the request `http://www.acme.org/path/to/doc.html?param=value`, the URL is `http://www.acme.org/path/to/doc.html`.
`@web:full-url`
	`#xs:string`	The full URL of the request, including the protocol, server name, port number, path, and the query string. For example, with the request `http://www.acme.org/path/to/doc.html?param=value`, the full URL is the same.
`@web:headers`
	`#adt:list` of `#adt:NItem`	Represent the headers contained in this request. The headers are contained in a fixed list of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the header) ; the list may contain duplicate names. Each header behave like an element.
`@web:method`
	`#xs:string`	The name of the HTTP method with which this request was made, for example, GET, POST, or PUT ; the same as the value of the CGI variable REQUEST_METHOD.
`@web:path-info`
	`#xs:string`	Any extra path information associated with the URL the client sent when it made this request ; the same as the value of the CGI variable PATH_INFO.
`@web:path-translated`
	`#xs:string`	Any extra path information translated to a real path ; the same as the value of the CGI variable PATH_TRANSLATED. Example : `/var/www/htdocs/path/to/doc.html`
`@web:query-string`
	`#xs:string`	The query string that is contained in the request URL after the path ; the same as the value of the CGI variable QUERY_STRING.
`@web:match`
	`#adt:list` of `#adt:NItem`	The list of strings that has been captured by the regular expression used in a `<web:mapping>` (the empty list if not relevant). Each group of string is exposed as an unamed element, that is to say a named item which name is "".
`@web:has-session`
	`#xs:boolean`	Indicates whether a session is available. If no session is available, the predefined property `$web:session` will create a new one when invoked.

`#web:x-response` type

Represents an HTTP response.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-response This type

name()
#xs:QName web:response The name of a response.

child::

Represent the HTTP headers of the response. The HTTP headers are contained in a list (by default, it is empty) of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the HTTP header) ; the list may contain duplicate names.

#adt:list of #adt:NItem A list of HTTP headers.

#adt:NItem A header name and its value.

attribute::

#adt:map of #adt:NItem A set of attributes including those specified below (and that can't be removed). Other attributes that are not bound to a namespace URI represent the cookies set to the HTTP response.

@web:encoding

#xs:string The name of the chararacter encoding of the HTTP response.

#xs:string The name of the chararacter encoding of the HTTP response.

@web:mime-type

#xs:string The MIME type of the HTTP response.

#xs:string The MIME type of the HTTP response.

@web:output

#io:output The output stream of the HTTP response.

@web:buffer-size

#xs:int The buffer size for the body of the HTTP response.

#xs:int The buffer size for the body of the HTTP response.

@web:status-code

The HTTP status code (200, 404, etc).

#xs:int The value is -1 until it is explicitely changed.

#xs:int The value to set to the HTTP status.

@a-cookie-name

a-cookie-name stands for any name not bound to a namespace URI. Once a cookie is added, it can't be neither removed nor updated. Several cookies that have the same name can be added safely.

#web:x-cookie A new cookie to add to this response.

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-response`	This type
`name()`
	`#xs:QName`	web:response	The name of a response.
`child::`
Represent the HTTP headers of the response. The HTTP headers are contained in a list (by default, it is empty) of values that have names. Each name in the list is a string not bound to a namespace URI (the name of the HTTP header) ; the list may contain duplicate names.
	`#adt:list` of `#adt:NItem`	A list of HTTP headers.
	`#adt:NItem`	A header name and its value.
`attribute::`
	`#adt:map` of `#adt:NItem`	A set of attributes including those specified below (and that can't be removed). Other attributes that are not bound to a namespace URI represent the cookies set to the HTTP response.
`@web:encoding`
	`#xs:string`	The name of the chararacter encoding of the HTTP response.
	`#xs:string`	The name of the chararacter encoding of the HTTP response.
`@web:mime-type`
	`#xs:string`	The MIME type of the HTTP response.
	`#xs:string`	The MIME type of the HTTP response.
`@web:output`
	`#io:output`	The output stream of the HTTP response.
`@web:buffer-size`
	`#xs:int`	The buffer size for the body of the HTTP response.
	`#xs:int`	The buffer size for the body of the HTTP response.
`@web:status-code`
The HTTP status code (200, 404, etc).
	`#xs:int`	The value is -1 until it is explicitely changed.
	`#xs:int`	The value to set to the HTTP status.
`@a-cookie-name`
a-cookie-name stands for any name not bound to a namespace URI. Once a cookie is added, it can't be neither removed nor updated. Several cookies that have the same name can be added safely.
	`#web:x-cookie`	A new cookie to add to this response.

`#web:x-session` type

Represents a session.

A session can be get with $web:session.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-session This type

name()
#xs:string Wrap the unique identifier assigned to this session which is implementation dependant within a QName. The QName given has no namespace URI and its local name might not be an XML NCName.

attribute::

#adt:map of #adt:NItem A set of attributes including those specified below (and that can't be removed). Other attributes that are not bound to a namespace URI represent the object stored in the session.

@web:creation-time

#xs:long The time when this session was created (number of milliseconds since midnight January 1, 1970 GMT).

@web:last-accessed-time

#xs:long The last time the client sent a request associated with this session (number of milliseconds since midnight January 1, 1970 GMT).

@web:max-inactive-interval

#xs:int The maximum time interval, in seconds, that this session will be keept open between client accesses.

#xs:int The maximum time interval, in seconds, that this session will be keept open between client accesses.

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-session`	This type
`name()`
	`#xs:string`	Wrap the unique identifier assigned to this session which is implementation dependant within a QName. The QName given has no namespace URI and its local name might not be an XML NCName.
`attribute::`
	`#adt:map` of `#adt:NItem`	A set of attributes including those specified below (and that can't be removed). Other attributes that are not bound to a namespace URI represent the object stored in the session.
`@web:creation-time`
	`#xs:long`	The time when this session was created (number of milliseconds since midnight January 1, 1970 GMT).
`@web:last-accessed-time`
	`#xs:long`	The last time the client sent a request associated with this session (number of milliseconds since midnight January 1, 1970 GMT).
`@web:max-inactive-interval`
	`#xs:int`	The maximum time interval, in seconds, that this session will be keept open between client accesses.
	`#xs:int`	The maximum time interval, in seconds, that this session will be keept open between client accesses.

`#web:x-cookie` type

Represents a Web cookie.

Operation read | write | rename | update | delete
Type Value Comment
type()
#xs:QName #web:x-cookie This type

name()
#xs:QName The name of the cookie.
#xs:QName The name of the cookie. The name must not be bound to a namespace URI.

child::

#xs:string The value of the cookie.

#xs:string The value of the cookie. Can't contain neither whitespaces nor any of [ ] ( ) = , " / ? @ : ;

attribute::

#adt:map of #adt:NItem The fixed set of attributes specified below (and that can't be removed).

@comment

#xs:string The purpose of the cookie.

#xs:string The purpose of the cookie.

@domain

#xs:string The domain of the cookie.

#xs:string The domain of the cookie.

@max-age

#xs:int The maximum age of the cookie, specified in seconds. By default, -1 indicating the cookie will persist until browser shutdown.

#xs:int The maximum age of the cookie, specified in seconds. By default, -1 indicating the cookie will persist until browser shutdown.

@path

#xs:string The path on the server to which the browser returns this cookie.

#xs:string The path on the server to which the browser returns this cookie.

@is-secure

#xs:boolean Indicates whether the browser is sending cookies only over a secure protocol or if the browser can send cookies using any protocol.

#xs:boolean Indicates whether the browser is sending cookies only over a secure protocol or if the browser can send cookies using any protocol.

@version

#xs:int The version of the protocol this cookie complies with. 0 if the cookie complies with the original Netscape specification; 1 if the cookie complies with RFC 2109

#xs:int The version of the protocol this cookie complies with. 0 if the cookie complies with the original Netscape specification; 1 if the cookie complies with RFC 2109

Operation	read \| write \| rename \| update \| delete
	Type	Value	Comment
`type()`
	`#xs:QName`	`#web:x-cookie`	This type
`name()`
	`#xs:QName`	The name of the cookie.
	`#xs:QName`	The name of the cookie. The name must not be bound to a namespace URI.
`child::`
	`#xs:string`	The value of the cookie.
	`#xs:string`	The value of the cookie. Can't contain neither whitespaces nor any of `[ ] ( ) = , " / ? @ : ;`
`attribute::`
	`#adt:map` of `#adt:NItem`	The fixed set of attributes specified below (and that can't be removed).
`@comment`
	`#xs:string`	The purpose of the cookie.
	`#xs:string`	The purpose of the cookie.
`@domain`
	`#xs:string`	The domain of the cookie.
	`#xs:string`	The domain of the cookie.
`@max-age`
	`#xs:int`	The maximum age of the cookie, specified in seconds. By default, -1 indicating the cookie will persist until browser shutdown.
	`#xs:int`	The maximum age of the cookie, specified in seconds. By default, -1 indicating the cookie will persist until browser shutdown.
`@path`
	`#xs:string`	The path on the server to which the browser returns this cookie.
	`#xs:string`	The path on the server to which the browser returns this cookie.
`@is-secure`
	`#xs:boolean`	Indicates whether the browser is sending cookies only over a secure protocol or if the browser can send cookies using any protocol.
	`#xs:boolean`	Indicates whether the browser is sending cookies only over a secure protocol or if the browser can send cookies using any protocol.
`@version`
	`#xs:int`	The version of the protocol this cookie complies with. 0 if the cookie complies with the original Netscape specification; 1 if the cookie complies with RFC 2109
	`#xs:int`	The version of the protocol this cookie complies with. 0 if the cookie complies with the original Netscape specification; 1 if the cookie complies with RFC 2109

Appendix

A Lists

A.1 Examples list

A Web application

Work in progress

Web Specification

A Web module for Active Tags

Working Draft 12 june 2008

Abstract

Requirement levels

Active Tags specifications

Table of contents

Appendix

1 The Web module

2 Web concepts

2.1 Application

2.2 Service

2.3 HTTP handling

2.4 The web URI scheme

2.5 Example

3 Use cases

3.1 Setting the MIME type of the HTTP response

3.2 Setting the character encoding of the HTTP response

3.3 Setting HTTP headers of the response

3.4 Using matchers

3.5 Cookies handling

4 Web module reference

4.1 Elements

server initialization phase

HTTP handling phase

unmarshal phase

runtime phase

runtime phase

4.2 Foreign attributes

4.3 Predefined properties

4.4 Extended XPath functions

4.5 Data types

#web:x-application type

#web:x-service type

#web:x-request type

Precaution while handling parameters

#web:x-response type

#web:x-session type

#web:x-cookie type

Appendix

A Lists

A.1 Examples list

2.4 The `web` URI scheme

`#web:x-application` type

`#web:x-service` type

`#web:x-request` type

`#web:x-response` type

`#web:x-session` type

`#web:x-cookie` type