Work in progress This version may be updated without notice.

1 The Web module

This Active Tags module has been designed to provide 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 properties stored in the data set.

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 :

• /myApp : the "myApp" application
• /anotherApp : the "anotherApp" application
• / : the root application ; every URL 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 in any Active Tags service.

Service

A service defines mappings to handle HTTP requests with the <web:mapping> element. Each service of an application is represented by an active sheet. How each service (active sheet) is bound to the Web application is implementation dependant.

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 define an initialization phase thanks to the <web:init> element.

HTTP handling

When a service is invoked, the mapping (<web:mapping>) that matches the request's URL is called with the following properties :

• $web:request : represents the HTTP request
• $web:response : represents the HTTP response
• $web:match : represent the groups captured by the regular expression used for matching

The web URI scheme

A Web application is often deployed to a target location not necessary known by developers ; 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 "file:///path/to/tomcat/myWebapp/WEB-INF/xslt/xmlToHtml.xslt".

Example

<?xml version="1.0" encoding="iso-8859-1"?>

<web:service
    xmlns:web="http://www.inria.fr/xml/active-tags/web"
    xmlns:xcl="http://www.inria.fr/xml/active-tags/xcl">

    <web:init>
        <!-- define shareable stylesheets -->
        <xcl:parse-stylesheet name="xmlToHtml" scope="shared" value="web:///stylesheets/xmlToHtml.xslt"/>
    </web:init>

    <web:mapping match="^/this\.xml$" mime-type="application/xml">
        <!-- simply return this active-sheet -->
        <xcl:transform output="{ value( $web:response/@web:output ) }" source="{ $this }"/>
    </web:mapping>

    <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:///{ $web:match }.xml" stylesheet="{ $xmlToHtml }"/>
    </web:mapping>

</web:service>

3 Use cases

Using matchers

The $web:match property contains a list of strings matched by the regular expression used in the mapping ; in XPath, if a list contains a single item, it can be processed as is :

    <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:///{ $web:match }.xml" stylesheet="{ $xmlToHtml }"/>
    </web:mapping>

On the opposite, if a list contains several items, it must be processed by retrieving the nodes that compose the list (notice that the XPath wildcard * is not relevant because strings are not like XML elements) :

    <web:mapping match="^/(.+[^/])/img/(.*)$">
        <xcl:attribute name="web:mime-type" referent="{ $web:response }"
 value="{ web:mime-type( $web:match/node()[2] ) }"/>
        <!-- simply display the img -->
        <io:copy source="web:///img/{ $web:match/node()[1] }/{ $web:match/node()[2] }"
 target="{ value( $web:response/@web:output ) }"/>
    </web:mapping>

4 Web module reference

	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

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:match

Property type: adt:list of xs:string

$web:match contains a list of strings that has been captured by the regular expression used in a <web:mapping>.

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
string()
	xs:string		The string value of the application is its name, if the underlying Web engine is naming applications.
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:path
	xs:string		The path to the application, that either starts with "/", or is "".
@web:init-param
	adt:map of xml:attribute		A fixed set of attributes that are not bound to a namespace URI. They represent the parameters used when the application is initialized.

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
string()
	xs:string		The string value of the service is its name, if the underlying Web engine is naming services.
attribute::
	adt:map of xml:attribute		A fixed set of attributes including those specified below. Other attributes are not bound to a namespace URI and represent the parameters used when the service is initialized.
@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
child::
	adt:list of adt:NItem		Represent the parameters contained in the query string or posted form data. The 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 parameter) ; the list may contain duplicate names.
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:content-length
	xs:integer		The length of the request body, the same as the CGI variable CONTENT_LENGTH.
@web:input
	io:input		The body of the request.
@web:scheme
	xs:string		The name of the scheme used to make this request, for example, http or https.
@web:is-secure
	xs:boolean		Indicates whether this request was made using a secure channel, such as HTTPS.
@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 and with 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.
@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.

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/param )
• $web:request/param[ 1 ]
• value( $web:request/param[ 1 ] )

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

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
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:character-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: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.
@web:id
	xs:string		The unique identifier assigned to this 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

[TODO]

Appendix

A Glossary

B Related Active Tags specifications

This list is not exhaustive; it is a list of common modules usable by an engine that implements the Active Tags specifications that implementors may use. Additional modules are welcome.

C Lists

C.1 Examples list

• A Web application

C.2 Figures list

D Active Schema for the Web module

[schema.asl]

<asl:active-schema asl:version="1.0" target="web" schema-version="1.0" xml:lang="en"
    xmlns:web="http://www.inria.fr/xml/active-tags/web"
    xmlns:asl="http://www.inria.fr/xml/active-schema"
    xmlns:adt="http://www.inria.fr/xml/active-datatypes"
    xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:at="http://www.inria.fr/xml/active-tags/reference">

    <asl:element name="web:service" root="always">
        <asl:attribute id="asl:common-attribute" ref-ns="#other" min-occurs="0" max-occurs="unbounded"/>
        <asl:sequence>
            <asl:element ref-elem="web:init" min-occurs="0"/>
            <asl:element ref-elem="web:map" max-occurs="unbounded"/>
            <asl:element ref-elem="xcl:logic" min-occurs="0" max-occurs="unbounded">
                <asl:interim>
                    <!-- force <xcl:logic> to have a name -->
                    <asl:assert test="{ asl:element()/@name }">
                        <asl:desc id="web:procedureMustBeNamed-desc">
                            All logic procedure declared in a service must have a name.
                        </asl:desc>
                    </asl:assert>
                </asl:interim>
            </asl:element>
        </asl:sequence>
    </asl:element>

    <asl:element name="web:init">
        <asl:use ref-id="asl:common-attribute"/>
        <asl:sequence>
            <asl:element ref-ns="#other"/>
        </asl:sequence>
    </asl:element>

    <asl:element name="web:mapping">
        <asl:use ref-id="asl:common-attribute"/>
        <asl:attribute name="url-match"
 min-occurs="{ count( asl:element()/following-sibling::web:mapping[ 1 ] ) }">
            <asl:desc>
                The <at:attribute>url-match</at:attribute> attribute is mandatory
                except on the last <at:element>web:map</at:element> element.
            </asl:desc>
        </asl:attribute>
        <asl:sequence>
            <asl:element ref-ns="#other"/>
        </asl:sequence>
    </asl:element>

    <!-- TODO -->

</asl:active-schema>