Reload-on-Startup Initialization Items

Introduction

Goal

Reload a previously loaded repository initialization item.

Use Case

Normally repository initialization items are loaded only once. The "reload on startup" feature allows you to configure initialization items to be reloaded when the CMS is started after an upgrade. Initialize item instructions that can be reloaded are node type import instructions (hippo:nodetypesresource) and XML content import instructions (hippo:contentresource) except for those containing combine or overlay directives (see below). The reload is triggered only when the system detects a newer version of the initialization item then was loaded previously. This feature can help you deploy a new release of your project (e.g. containing document type modifications) in an existing environment.

A third initialize item type, resource bundle instructions (hippo:resourcebundles) is also reloadable. Resource bundle instructions, however, are always and automatically reloaded when bootstrapping is enabled, without the need to configure "reload on startup" or updating the version of the initialization item.  

Configure the Initialization Item to Reload on Startup

In the bootstrap module of your project locate the hippoecm-extension.xml file and the hippo:initializeitem you want to reload, then add the following property to it:

<sv:property sv:name="hippo:reloadonstartup" sv:type="Boolean">
   <sv:value>true</sv:value>
</sv:property>

Then, in order to let the system know when to reload the item add the hippo:version property:

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>2.23.02</sv:value>
</sv:property>

The hippo:version property can be any valid maven version number. The system will try to find the version number at which the initialization item was previously loaded. If it can't find it because it wasn't specified before, or it detects a version number that is lower than the current version number, it will reload the item.

Prevent Repetitive Manual Version Updating of Frequently Updated Items

To prevent frequent manual updates of the version number use Maven resource filtering. In the pom.xml file of a module containing a hippoecm-extension.xml file, add the following configuration in the <build> section.

<resources>
<resource>
 <directory>src/main/resources</directory>
<filtering>true</filtering>
<includes>
<include>**/hippoecm-extension.xml</include>
</includes>
</resource>
<resource>
 <directory>src/main/resources</directory>
 <excludes>
 <exclude>**/hippoecm-extension.xml</exclude>
</excludes>
 </resource>
 </resources>

The placeholders in the hippoecm-extension.xml containing a valid Maven property will be replaced:

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>${project.version}</sv:value>
</sv:property>

Reload of an Item in Consecutive Deployments of a SNAPSHOT Version

If a snapshot version is deployed on a regular basis, for example, a continuous or daily build, and the repository content is not restored at each deployment, items using the ${project.version} placeholder are not reloaded (because the version number has not been changed). To overcome this problem, replace the -SNAPSHOT part of the Maven version by a timestamp by adding the following configuration to the <build><plugins> section of your master pom.xml:

<plugin>
 <groupId>org.codehaus.groovy.maven</groupId>
 <artifactId>gmaven-plugin</artifactId>
 <version>1.0</version>
 <executions>
 <execution>
 <phase>validate</phase>
<goals>
 <goal>execute</goal>
 </goals>
 <configuration>
 <source>
 import java.text.MessageFormat
 version= "${project.version}"
 def vartimestamp = MessageFormat.format("{0,date,yyyyMMddHHmmss}", new Date())
reloadOnStartupVersion = version.replace("SNAPSHOT",vartimestamp)
 project.properties.setProperty('reloadonstartup.version', reloadOnStartupVersion)
 </source>
 </configuration>
 </execution>
</executions>
 </plugin>

In that case, the property placeholder should be ${reloadonstartup.version}.

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>${reloadonstartup.version}</sv:value>
</sv:property>

Same-Name Siblings and Renaming the Root Node of the Content Resource

The reload on startup feature tries to first remove the node at the document element of the content resource. For instance, if the content root was / and the document element of the content resource was <node name="foo"> it tries to remove /foo first before reimporting the content. There are two cases in which this strategy will fail to give you the results you desire. First, if there are two /foo nodes, which one to remove cannot be determined and reloading will fail with an error message being logged. The second case is when you rename the document element of the content resource. The system has no way of knowing what node was the one that was bootstrapped by an earlier version and it tries to remove the new node.

Thus beware of same-name siblings and renaming the root node of the content resource!

Combine and Overlay Enhanced System View XML Directives

When the content resource contains the enhanced System View XML combine or overlay directives (sometimes referred to as "Delta XML"), it means that this content resource is not the one responsible for the addition of the node pointed to by the document element. This in turn means that reload on startup cannot undo the changes previously done by the initialization item. Therefore the system is unable to reload such items.

Reloading of Downstream Items

Because the reload feature removes the context node and then reimports the xml, downstream items need to be reloaded as well. Downstream items are those items that bootstrap content below that context node. For instance, say we have an item that bootstraps the node /foo and another that bootstraps the node /foo/bar then the second item is downstream from the first. In this case when the item that bootstraps /foo is to be reloaded, the item that bootstraps /foo/bar must be reloaded as well. The system automatically determines which downstream items to reload.

How to Reload Document Types

A common usage of this feature is to reload changes made to document types. In this case you should add reloadonstartup to two initialization items:

• The initialization item that bootstraps the CND that contains the definition of all document types. It needs to be reloaded in case of new document type.

• The initialization item that bootstraps the definition and configuration for document editor. Editor template configuration needs to be reloaded in case of any modification in existing document type.