[Up] |
Work in progressThis version may be updated without notice. |
Copyright © INRIA
This specification describes a Web optional module for
. This Web module provides tags, attributes, functions and predefined properties related to Web applications.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.
The following specifications are part of the technologies.
1 The Web module
2 Web concepts
3 Use cases
4 Web module reference
4.1 Elements
4.2 Foreign attributes
4.3 Predefined properties
4.4 Extended XPath functions
4.5 Data types
A Glossary
B Related specifications
C Lists
C.1 Examples listD for the Web module
C.2 Figures list
This
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 engine. How the engines are cooperating is out of the scope of this specification.Most Web concepts are represented in properties stored in the data set.
thanks toThe 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 :
According to the underlying Web engine used, the Web application may endorse a set of informations accessible with $web:application property ; additionally, parameters used to initialize the Web application are also accessible.
with theThe $web:application property can be referred in any 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.
When a service is invoked, the mapping (<web:mapping>) that matches the request's URL is called with the following properties :
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".
A Web application | |
---|---|
The following active sheet defines a service of a Web application <?xml version="1.0" encoding="iso-8859-1"?> 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 accessible with http://www.acme.org/foo/, this service might serves :
|
<web:mapping match="^/(.+)\.(xml|html)$" mime-type="application/xml"> <!-- ... --> </web:mapping>
If not known before :
<web:mapping match="^/(.*)$"> <xcl:attribute name="web:mime-type" referent="{ $web:response }" value="application/xml"/> <!-- ... --> </web:mapping>
<web:mapping match="^/(.+)\.(xml|html)$" mime-type=""> <!-- ... --> </web:mapping>
...will set the MIME type according to the extension.
If it doesn't depend on the extension :
<!-- a mapping that matches http://www.acme.org.myApp/query/foo?file=myFile.txt --> <web:mapping match="^/query/(.*)$"> <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>
<xcl:attribute name="web:character-encoding" referent="{ $web:response }" value="ISO-8859-1"/>
<xcl:append referent="{ $web:response }"> <xcl:item name="Cache-Control" value="no-cache"/> </xcl:append>
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>
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:version | $web:application $web:service $web:request $web:response $web:session $web:cookies $web:match | 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. |
Root element for an active sheet that stands for a Web service.
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.
[TODO: content definition]
Defines the initialization procedure.
unmarshal phase
Registers this action to the processor instance as the default procedure.
runtime phase
Run the subactions.
[TODO: content definition]
Handles an HTTP request.
runtime phase
Run the subactions.
[TODO: content definition]
Attributes runtime | hard-coded | both Name Type Value optional | default value match #adt:regexp A regular expression used to match the request's URL.
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 use to test 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, with the request http://www.foo.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. #xs:string It is possible to build other strings ; for example use="{$web:request/@web:full-path}" will produce /myApp/path/to/doc.html?param=value.
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.
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.
Invoke a service on the server.
Attributes runtime | hard-coded | both Name Type Value optional | default value path #xs:string The path to the service in the context of the current Web application.
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.
- 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.
Property type: #web:x-application $web:application is a reference to the Web application.
Property type: #web:x-service $web:service is a reference to the HTTP service.
Property type: #web:x-request $web:request is a reference to the HTTP request.
Property type: #web:x-response $web:response is a reference to the HTTP response.
Property type: #web:x-session $web:session is a reference to the HTTP session.
Property type: #adt:list of #web:x-cookie $web:cookie is a reference to the cookies.
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>.
Return: #xs:string Return the MIME type of a file.
Arguments 1 #io:x-file The file. Arguments 1 #xs:anyURI The URI of the file.
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.
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...
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:character-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. @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 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.
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: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. #adt:list of #web:x-cookie A list of cookies that has the same name. #web:x-cookie A new cookie to add to the list of cookies of that name.
Represents a session.
Operation read | write | rename | update | delete Type Value Comment type() #xs:QName #web:x-session This type 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: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.
[TODO]
This list is not exhaustive; it is a list of common modules usable by an engine that implements the
specifications that implementors may use. Additional modules are welcome.<asl:active-schema asl:version="1.0" target="web" schema-version="1.0" xml:lang="en" xmlns:web="http://ns.inria.org/active-tags/web" xmlns:asl="http://ns.inria.org/active-schema" xmlns:adt="http://ns.inria.org/active-datatypes" xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://www.w3.org/1999/xhtml" xmlns:at="http://ns.inria.org/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>