Web applications are designed to handle incoming requests. URL mapping describes how to map the requested URLs to particular handlers or files.
In this document:
<url-mapping>
<default-prefix>forum</default-prefix>
<installed-size>5242880</installed-size>
<mapping url="/" path="htdocs"
xmlns:php="http://aps-standard.org/ns/1/php"
xmlns:mod-python="http://aps-standard.org/ns/1/mod-python">
<php:handler>
<php:extension>php</php:extension>
<php:extension>pinc</php:extension>
</php:handler>
<mapping url="upload">
<php:handler><php:disabled/></php:handler> <!-- Disabling PHP -->
<php:permissions writable="true"/>
</mapping>
<mapping url="stat" virtual="virtual">
<php:handler><php:disabled/></php:handler>
<mod-python:handler>com.example.StatHandler</mod-python:handler>
</mapping>
</mapping>
</url-mapping>
The example mapping describes three contexts: URLs starting from “/”, URLs starting from “/upload” and URLs starting from “/stat”. The first two are mapped to the file system, the third one is virtual (the mod_python aspect is not defined in this specification, so this is placed here just for illustrative purposes).
The default-prefix element defines a segment of a URL path component which should precede the service instance root by default. A controller is allowed to change it. The controller MUST normalize leading and trailing slashes of the default prefix when forming the final URL.
The site-root element defines the requirement of URL mapping to be on the root of a web site. A controller MUST place that URL mapping as the root mapping of the site. This element MUST appear only in the top level of the URL mapping root service.
A package may include a declaration of the approximate size of a single URL mapping instance, to help Controllers estimate the disk space resources needed for service provisioning. For this, the installed-size element should be specified with the declared size of an URL mapping instance size in bytes.
Mappings may be nested, and there MUST NOT be two mappings with such URLs that the first URL is the prefix of the second URL. In other words, the construction
<mapping url="/">
<mapping url="foo/bar"/>
<mapping url="foo/bar/baz"/>
</mapping>
is prohibited, and MUST be rewritten as
<mapping url="/">
<mapping url="foo/bar">
<mapping url="baz"/>
</mapping>
</mapping>
All url s in mappings are relative to the parent URL mapping. Absolute URLs are PROHIBITED in the url attributes except the root mapping where url value MUST be ‘/’.
The path attribute of mapping is always a path from the root of an archive to the directory inside the archive, it must not have the / character at the start.
If a mapping has an explicit path attribute, then the mapping is associated with the directory specified by this attribute. The association means that any URL which is in the scope of the given mapping (URLs in scopes of inner mappings are not in the scope of outer mapping) and is not handled by the handlers declared in the mapping needs to be served as the file from the directory specified.
If a mapping has neither an explicit path attribute nor a virtual attribute, then the directory associated with the given mapping is calculated from the directory associated with the parent mapping appending the relative URL that the given mapping has. E.g., for the following declarations
<mapping url="/" path="htdocs">
<mapping url="foo/bar">
<mapping url="baz"/>
<mapping url="quux" path="somedir"/>
</mapping>
</mapping>
mapping ‘/’ is associated with the htdocs/ directory, mapping ‘/foo/bar’ is associated with the htdocs/foo/bar directory, mapping ‘/foo/bar/baz’ is associated with the htdocs/foo/bar/baz directory, and mapping ‘/foo/bar/quux’ is associated with the htdocs/foo/bar/somedir directory.
If a mapping has an explicit virtual attribute equal to virtual, then the mapping is not associated with any directory, and requests to the URLs in the scope of this mapping must return a ‘Not found’ error, if not handled by the handlers declared in the given mapping.
If a mapping has an explicit virtual attribute equal to redirect, then a controller SHOULD configure an HTTP redirect to the URL denoted by href mapping child.
If a mapping has an explicit shared attribute equal to true, then a controller SHOULD share contents of the directory referred by this mapping between all instances of the version of an application.
If an outer mapping does not have an associated directory, then inner mappings without an explicit path element do not have an associated directory too.
If the whole application mapping is not virtual (meaning that there is at least one mapping without the virtual attribute), the root mapping MUST have the path attribute.
A controller MUST use mapping information for deployment and upgrade of application instance files. Files deployment MUST be driven by the URL mapping rules.
Aspects declare types of URL handlers, rules of how to process them. Rules regulating propagation of specific URL handlers to inner mappings are also declared in aspects.
A handler defined later overrides the former one. In the following example, all *.php files will be processed by the CGI handler.
<mapping url="users">
<php:handler>
<php:extension>php</php:extension>
</php:handler>
<cgi:handler>
<cgi:extension h:handler-type="php">php</cgi:extension>
</cgi:handler>
</mapping>
The URL Mapping provision method requires individual update of provisioned services. During update, application files will be overwritten. Any schema of files overwriting during upgrade is permitted, given that it satisfies the following requirements:
Thus, files expected to be modified during application work need to be created manually by the configuration scripts upon service provision.
During a patch, no changes in the mapping structure are allowed. A controller MUST leave the mapping as it was for the previous version of application. Mapping files MUST be replaced by new versions. File overwriting semantics is the same as for upgrade.