The application descriptor

The application descriptor is an XML file that contains information about the web application structure. MCS uses this information to generate the HTML 5 cache manifest for the entire application. Refer to the topic entitled The cache manifest for details about the cache manifest.

The application descriptor is an XML file that contains information about the web application structure. MCS uses this information to generate the HTML 5 cache manifest for the entire application. Refer to the topic entitled The cache manifest for details about the cache manifest.

Note:

This mechanism works only for web applications that were written using XDIME 2.

Note:

The application descriptor described in this article must not be mistaken with the application descriptor used by the prerenderer and builder CLI utilities.

Binding XDIME 2 pages to the application descriptor

The .mapd file extension identifies application descriptor files. The default content type of an application descriptor file is x-application/vnd.volantis.application-descriptor-file+xml. The extension and the content type are defined in the mime-mapping section of the web.xml file. Note that the encoding defined in the declaration line of the XML file will be used instead of the encoding defined in the HTTP response header.

An application descriptor file needs to be placed in the root application directory (i.e. in the topmost directory of the web application). Page authors can use the qualified-name value 'mcs:application' in the rel attribute of the link element to bind an application descriptor file to an XDIME 2 page. The href attribute of the link element must contain the name of the application descriptor file to use. Note that there can only be one application descriptor per web application.

The application descriptor XML schema

The following table lists the application descriptor configuration elements.

Element Description
app-descriptor The root element of the application descriptor file.
cache-manifest Contains information used to generate the HTML 5 cache manifest.
cache The list of resources that should be cached for the offline use.
network Contains resources that should be added to the NETWORK section of the cache manifest. The resources listed in that section will never be cached, i.e. requests to these resources will always bypass the cache.
resource The path to a resource. If the path starts with the '/' character, it is resolved against the web application context. Otherwise, the path is resolved against the location of the application descriptor file. Note that wildcards are not supported.

The related XML schema is following example. It can be used to validate application descriptor files.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.volantis.com/xmlns/2011/05/application-descriptor"
  targetNamespace="http://www.volantis.com/xmlns/2011/05/application-descriptor"
  elementFormDefault="qualified">
  <xs:simpleType name="CacheResourceType">
    <xs:restriction base="xs:token">
      <xs:pattern
        value="/?[a-zA-Z][\w_]+(((\.[\w_]+)?)|((/[\w_]+)*)((\.[\w_]+)|(\?[\w_]+=[\w_]+(&amp;[\w_]+=[\w_]+)*))?)?"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="NetworkResourceType">
    <xs:restriction base="xs:token">
      <xs:pattern
        value="\*|/?[a-zA-Z][\w_]+(((\.[\w_]+)?)|((/[\w_]+)*)((\.[\w_]+)|(\?[\w_]+=[\w_]+(&amp;[\w_]+=[\w_]+)*))?)?"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="CacheResourcesType">
    <xs:sequence>
      <xs:element name="resource" type="CacheResourceType" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="NetworkResourcesType">
    <xs:sequence>
      <xs:element name="resource" type="NetworkResourceType" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:element name="app-descriptor">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="cache-manifest">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="cache" minOccurs="0" type="CacheResourcesType"> </xs:element>
              <xs:element name="network" minOccurs="0" type="NetworkResourcesType"> </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example

The following application descriptor indicates that the index.xdime and /app/buy.xdime files and the assets defined by the header.mimg and background.mimg policies should be added to the CACHE section of the cache manifest, while the /assets/js/counter.js script and the assets specified by the /policies/images/logo.mimg and /policies/images/footer.mimg policies should be added to the NETWORK section of the cache manifest. Note that the resources referenced by both XDIME files (i.e. images, scripts, etc.) will also be added to the CACHE section of the cache manifest.

<?xml version="1.0" encoding="UTF-8"?>
<app-descriptor
  xmlns="http://www.volantis.com/xmlns/2011/05/application-descriptor"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.volantis.com/xmlns/2011/05/application-descriptor
  http://www.volantis.com/schema/project/mcs/application-descriptor.xsd">
  <cache-manifest>
    <cache>
      <resource>/index.xdime</resource>
      <resource>/app/buy.xdime</resource>
      <resource>/policies/images/header.mimg</resource>
      <resource>/policies/images/background.mimg</resource>
    </cache>
    <network>
      <resource>/assets/js/counter.js</resource>
      <resource>/policies/images/logo.mimg</resource>
      <resource>/policies/images/footer.mimg</resource>
    </network>
  </cache-manifest>
</app-descriptor>

Related topics