Project configuration

The default project

In the projects section in the mcs-config.xml it is necessary to create a single project using the default element. The example shows a single JDBC project. If the preload attribute is set to 'true' the project is loaded when MCS starts.

<projects>
  <default preload="true">
    <jdbc-policies name="myproject"/>
    <assets base-url="/[context_root]/">
      <audio-assets prefix-url="/audio/"/>
      <dynamic-visual-assets prefix-url="/dynvis/"/>
      <image-assets prefix-url="/images/"/>
      <script-assets prefix-url="/scripts/"/>
      <text-assets prefix-url="/text/"/>
    </assets>
    <generated-resources base-dir="myproject"/>
  </default>
</projects>

If this was a XML repository, you would use the directory attribute of the xml-policies element.

<xml-policies directory="[path-to]/[xml-repository]"/>

The assets element defines the URLs for policy variants and asset groups, and can be useful in specifying alternate locations for audio, image, and other files. These become the default URL prefixes for variants, to be used if asset groups are not specified in individual policies.

Portable projects

You can override the settings for the default project by placing a mcs-project.xml file either in the same directory as an XDIME page being processed, or somewhere on the path to it. MCS will traverse the directory hierarchy to the context root of your web application to find a file with this name, and if it fails to find one, it will use the URI and variant values in the default element.

Optionally, you can specify either an xml-repository, a jdbc-repository or none, and define a base URL for variants. Please note that if no policy source is specified, then MCS assumes that the policies are stored relative to the project location.

In XDIME 2, you may also choose to define a default layout and themes for the project. However there is no way to set comparable values in the default element. If the XDIME 2 page does not specify layout and theme bindings in rel and href attribute values on link elements, and there is no mcs-project.xml file, MCS will use a built in default layout, and the device style defaults will be used.

<project xmlns="http://www.volantis.com/xmlns/mcs/project"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  name="MyProject">
  <assets base-url="/assets"/>   
</project>

Portable projects are identified by their location. The location is a URL to the root directory of a portable project. For example, let's consider two projects with the following locations:

1. http://my.acme.com/projects/my/

2. http://other.foo.com/pages/

A policy with a URL of http://my.acme.com/projects/my/sub/icon.mimg belongs to the first project, a policy with a URL of http://other.foo.com/pages/main.mlyt belongs to the second project, but a policy with a URL of http://my.acme.com/projects/other/main.mthm belongs to neither.

Dynamic projects

Each XDIME resource belongs to a single project but an XDIME page processed by MCS can be constructed dynamically (e.g. using some server-side technology) from a number of different XDIME resources. That means that a page can contain a mixture of elements from different projects and therefore MCS has to track the projects separately for each element. If an XDIME page is constructed by a third party aggregation mechanism, then the aggregation mechanism is responsible for providing MCS with the required information. This can be achieved by placing the mcs:project attribute on any element within either XDIME 1 or XDIME 2. The contents of an mcs-project.xml file corresponding to a given element must be encoded into the mcs:project attribute using the "data" URL scheme, i.e.:

data:[<mediatype>][;base64],<data>

Please note that the media type must always be set to 'text/xml', no parameters are allowed and it must be encoded as base64. The standard XML rules apply for the determination of the applicable character set.

MCS uses the information encoded in the mcs:project attribute to construct mcs-project.xml. The contents of mcs-project.xml is created only for the first time when the project is created and for requests thereafter the project is cached and reused.

Dynamic projects have no location. They are identified by the project definition itself, i.e. dynamic projects with different definitions are treated as different projects. The identity of the project is determined by its definition, i.e. the result after loading the project. That means that the order of elements in the encoded XML is irrelevant, as are any white spaces, namespace prefixes, default values, etc.

Below is an example of the definition of a dynamic project. The base-url specifies the base URL for assets belonging to the enclosing project element. Both relative paths and absolute http: URLs are supported. For portable projects, relative URLs are resolved against the location of the project. For dynamic projects, relative URLs are resolved against the request context. If the attribute is not specified, then it defaults to '.', i.e. for portable projects, MCS assumes that assets are stored relative to the project location; for dynamic projects, MCS assumes that assets are stored relative to the request context.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://www.volantis.com/xmlns/mcs/project"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.volantis.com/xmlns/mcs/project
  http://www.volantis.com/schema/project/3-5/mcs-project.xsd">
  <xml-policies directory="file:/project/policies/"/>
  <assets base-url="http:/project/assets/"/>
  <default-layout>
    <policy>/defaults/layout.mlyt</policy>
  </default-layout>
  <themes>
    <policy>/defaults/structure.mthm</policy>
    <policy>/defaults/skin.mthm</policy>
  </themes>
  <policy-cache-partition size="50">
    <constraints>
      <cache>
        <time-to-live default="60"/>
      </cache>
    </constraints>
  </policy-cache-partition>
</project>

Encoding the previous mcs-project.xml file results in the following data URL:

data:text/xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0id
XRmLTgiPz4NCjxwcm9qZWN0IHhtbG5zPSJodHRwOi8vd3d3LnZvbGFud
GlzLmNvbS94bWxucy9tY3MvcHJvamVjdCINCiAgeG1sbnM6eHNpPSJodH
RwOi8vd3d3LnczLm9yZy8yMDAxL1hNTFNjaGVtYS1pbnN0YW5jZSINCiAg
eHNpOnNjaGVtYUxvY2F0aW9uPSJodHRwOi8vd3d3LnZvbGFudGlzLmNvb
S94bWxucy9tY3MvcHJvamVjdA0KICBodHRwOi8vd3d3LnZvbGFudGlzLm
NvbS9zY2hlbWEvcHJvamVjdC8zLTUvbWNzLXByb2plY3QueHNkIj4NCiAg
PHhtbC1wb2xpY2llcyBkaXJlY3Rvcnk9ImZpbGU6L3Byb2plY3QvcG9saWN
pZXMvIi8+DQogIDxhc3NldHMgYmFzZS11cmw9Imh0dHA6L3Byb2plY3Qv
YXNzZXRzLyIvPg0KICA8ZGVmYXVsdC1sYXlvdXQ+DQogICAgPHBvbGljeT
4vZGVmYXVsdHMvbGF5b3V0Lm1seXQ8L3BvbGljeT4NCiAgPC9kZWZhd
Wx0LWxheW91dD4NCiAgPHRoZW1lcz4NCiAgICA8cG9saWN5Pi9kZWZhd
Wx0cy9zdHJ1Y3R1cmUubXRobTwvcG9saWN5Pg0KICAgIDxwb2xpY3k+L
2RlZmF1bHRzL3NraW4ubXRobTwvcG9saWN5Pg0KICA8L3RoZW1lcz4NCi
AgPHBvbGljeS1jYWNoZS1wYXJ0aXRpb24gc2l6ZT0iNTAiPg0KICAgIDxjb25
zdHJhaW50cz4NCiAgICAgIDxjYWNoZT4NCiAgICAgICAgPHRpbWUtdG8tbG
l2ZSBkZWZhdWx0PSI2MCIvPg0KICAgICAgPC9jYWNoZT4NCiAgICA8L2Nvbn
N0cmFpbnRzPg0KICA8L3BvbGljeS1jYWNoZS1wYXJ0aXRpb24+DQo8L3By
b2plY3Q+

The project discovery process

Determining the project that applies to a given element is done as follows: if the mcs:project attribute has been specified on the element, then it defines a dynamic project that applies to the element. If not, then if the project on the parent element is a dynamic project, then the element will inherit that project. Otherwise, the project discovery process is performed and if a project is found, then that project applies to the current element. If the element has a parent, then it will inherit its project from the parent. If none succeeds, then the element will use the default local project.

Caching project specific policies

The mcs-project.xml file can also contain project specific cache settings that will optimize performance when MCS retrieves remote policies.

You can specify the overall cache size in the policy-cache-partition element, and define cache control constraints and defaults in the contained constraints element. Different constraints may also be applied to a number of type-partition elements that specify the configuration for one or more policy types with the same caching requirements.

You should regard the size attribute on a type-partition element as a rough indicator of the relative weighting that caches of the contained types should have at any given time. You should ensure the these values are not so low as to cause policies not to be cached. It is acceptable (for example) for each of the type values to be the same as the overall size.

The cache and retry elements have the boolean allow and default attributes. If the retry default is set to true, the interval and the max-count and retain elements set the parameters for retrying on a failed request over a remote connection. The time-to-live element sets the values that will invalidate the cache, and cause a request to be directed to the project repository. It is equivalent to the timeout attribute on the policy-cache element in the mcs-config.xml file. Both attributes can take an positive integer value or the keyword 'unlimited'.

The example defines a partition that can contain 100 policies, each of which can live for at most 1000 seconds but by default will only live for 50 seconds. Retry failed retrieval is allowed but is not on by default. Images and layouts by default will live for 500 seconds. Retry failed retrieval is on by default, and by default will retry 50 seconds after the most recent failed request up to 5 times, but can retry as often as 10 seconds apart and for as many as 10 times. The policy is retained during retry.

<policy-cache-partition size="100">     
  <constraints>
    <cache allow="true" default="true">
      <time-to-live maximum="1000" default="50"/>
      <retry allow="true" default="false"/>
    </cache>
  </constraints>
  <type-partition size="200">
    <type>image</type>
    <type>layout</type>
    <constraints>
      <cache allow="true" default="true">
        <time-to-live maximum="1000" default="500"/>
        <retry default="true">
          <interval minimum="10" default="50"/>
          <max-count maximum="10" default="5"/>
          <retain allow="true" default="false"/>
        </retry>
      </cache>
    </constraints>
  </type-partition>
</policy-cache-partition>

Related topics

• Configuring MCS
• projects
• Project configuration elements
• link
• The "data" URL scheme