The cache manifest

Generating a cache manifest file

The application descriptor is an XML file that contains information about the web application structure. The cache-manifest section of an application descriptor file contains information needed to create the corresponding cache manifest. This section is divided into two subsections: cache and network. The cache subsection specifies the resources that should be added to the CACHE section of the cache manifest, i.e. should be cached by the browser for the offline use. The network subsection lists the resources that should be added to the NETWORK section of the cache manifest. Resources listed in this section will never be cached, i.e. requests to these resources will always bypass the cache.

Note that there can only be one application descriptor per web application, and all XDIME 2 files that are included in a web application that needs to be cached must contain a link to its application descriptor file.

Refer to the topic entitled The application descriptor and to the Offline Web Applications specification for more information.

MCS automatically generates the cache manifest while processing an XDIME 2 page that contains a link to an application descriptor file. All resources that can be used from within XDIME 2 pages can be cached, including images transcoded by MAP. MCS determines which resources, listed in the cache section of the application descriptor or referenced by the cached pages, must be cached by the target device and rewrites the references accordingly. In other words, only the assets that are suitable for the target device will be included in the CACHE section of the manifest (e.g. MCS will replace links to image policies with links to images matching the target device capabilities). It should be noted that if a resource is not listed in the application descriptor, it still can be cached if it is referenced from a cached XDIME file. The network section is processed differently. MCS copies all string values to the NETWORK section of the cache manifest unless it determines that a particular value should be replaced by the device specific asset. In order to allow MAP resources to be stored for the offline use it is necessary for them to appear to be accessible from the same host as the cache manifest file, and therefore MCS rewrites requests for MAP resources.

There are some limitations on the cache manifest functionality. Refer to the section entitled Constraints for more information.

Updating the cache manifest

Once a resource is stored in the application cache, the browser will never request it from the server until the cached item is de-cached or the cache manifest is invalidated. MCS assumes that the cache manifest and the resources it references do not change over the lifetime of the web application on the client. Please note that the device information is a part of a web application.

Constraints

The following restrictions/limitations apply:

• All policies and resources needed by an application must be available locally on the server on which the application is deployed. Therefore, remote resources, remote MCS policies and remote MCS projects cannot be used.

• XDIME 2 pages that are to be cached must be available as static files, i.e. no JSP or any other server-side dynamic technology is supported. Dynamic data must be available via resources that are always accessed from the network.

• Each application must correspond to an MCS project, i.e. it needs to have an mcs-project.xml file in its root directory.

• If the browser does not support HTML 5 cache manifest, then no link to the manifest will be added to a page but that will not prevent the application from working while online, it just will not be able to work offline.

In addition, the list of possible browser specific issues includes, but is not limited to:

• Most browsers set the cache storage limit to 5MB per application.

Example

Let's assume that the page.xdime page references two image policies: image1.mimg and image2.mimg, and that the image1.jpg and image2.jpg files represent the assets suitable for the target device.

<?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>/page.xdime</resource>
    </cache>
    <network>
      <resource>/script.js</resource>
    </network>
  </cache-manifest>
</app-descriptor>

In such a case, MCS will generate the following cache manifest:

CACHE MANIFEST
CACHE:
/mcs/page.xdime
/mcs/image1.jpg
/mcs/image2.jpg
NETWORK:
/mcs/script.js

Related topics

• The application descriptor
• Project configuration
• Offline Web Applications