HST-2 Container Configuration

Introduction

HstFilter behaves as HST Container frontend controller. Every request is processed by the HstFilter at first. If a request should be processed by one of HST Container Pipelines, then it gives the request processing to a chosen pipeline. Otherwise, it hands over to the servlet filter chain.

The HstContextLoaderListener initializes all the HST Container core components on initialization of site applications.

Configuring HstFilter

For archetype-created projects, HstFilter is by default configured in web.xml as follows:

<filter>
  <filter-name>HstFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.HstFilter</filter-class>
</filter>

<!-- SNIP -->

<filter-mapping>
  <filter-name>HstFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>

HstFilter should be mapped by the url-pattern, " /*" because it is responsible to find a proper mount on a request and decide if the request can be processed with pipelines or not.

Automatic Content Bean Scanning

To enable automatic content beans scanning, add a context-param to your web.xml, something like

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>classpath*:org/example/**/*.class
   ,classpath*:org/onehippo/**/*.class
   ,classpath*:com/onehippo/**/*.class
   ,classpath*:org/onehippo/forge/**/*.class
  </param-value>
</context-param>

assuming the value for groupId was org.example when the project was created from the archetype.

For a more verbose explanation, see Automatic Scanning for Content-Bean Annotated Classes.

Configuring HstContextLoaderListener

HstContextLoaderListener initializes HST Container core components such as session pools, event listener containers, site handler components, Guava EventBus, etc. on startup.

Configuration should be like this:

<listener>
  <listener-class>org.hippoecm.hst.site.container.HstContextLoaderListener</listener-class>
</listener>

You can configure the following servlet context parameters:

Basic Configuration for HST Container

When initializing HST Container, the HstContextLoaderListener finds and reads configuration file(s) to customize parameters.

1. How are Configuration File Paths Resolved?

The configuration file paths are resolved in the following way:

• If the configured file path starts with '/', then it is assumed that the file is a web resource under the specific servlet context. In other words, the configuration file is resolved by invoking javax.servlet.ServletContext#getResource(resourcePath) or javax.servlet.ServletContext#getRealPath(resourcePath).
  If the context relative web resource is not found, then the configuration file path (starting with '/') is assumed to be an absolute path.
• If the configured file path starts with 'file:', then the container reads the file by the file URL.
• If the configured file path doesn't start with '/' or 'file:', then it is assumed as a relative path from the current working directory.

2. Default Configuration Files

HST Container combines the following configuration resources as ordered child Configurations:

1. JVM System properties unless the hst-system-properties-override context parameter is explicitly set to false.
2. An XML file specified by the hst-configuration context parameter if found.
3. Java System properties file specified by the hst-config-properties context parameter if found. If the context parameter is not specified, then either ${catalina.base}/conf/hst.properties (in SITE application) or ${catalina.base}/conf/platform.properties (in CMS or Platform application) is used.
4. /WEB-INF/hst-configuration.xml if found. Otherwise /WEB-INF/hst-config.properties if existing.

HST Container looks up a property from the first child Configuration to next one until it finds values. So, the loading order determines the precedence. See the Javadoc of org.apache.commons.configuration.CompositeConfiguration for detail.

Suppose that you have ${catalina.base}/conf/hst.properties and /WEB-INF/hst-config.properties in your environment, then HST Container loads and combines (a) Java System properties, (b) ${catalina.base}/conf/hst.properties and (c) /WEB-INF/hst-config.properties. It looks up properties from the Java System properties first. If not found, it looks up from the next child Configuration, ${catalina.base}/conf/hst.properties. If not found again, it finally looks up the property from the last one, /WEB-INF/hst-config.properties.

Therefore, it is possible to decompose the sets of properties and put each set in a different configuration file. For example, developers might want to put some developer-specific configurations, which are never been updated by administrators, only in /WEB-INF/hst-config.properties. But for configurations that can be updated for a specific environment, you might want to keep them only in ${catalina.base}/conf/hst.properties.

3. Default Generated Configuration and SpringComponentManager.properties

The archetype-generated /WEB-INF/hst-config.properties is completely empty and contains only:

# this file is used to be able to override defaults from
# org/hippoecm/hst/site/container/SpringComponentManager.properties

It only serves to be able to override the default from the HST core SpringComponentManager.properties.

Advanced Configuration for HST Container

An XML configuration file can be configured by the hst-configuration context parameter like the following example:

<context-param>
  <param-name>hst-configuration</param-name>
  <param-value>${catalina.base}/conf/hst.xml</param-value>
</context-param>

If you want to combine some extra application specific configurations, you can include any extra properties files inside the XML file:

<?xml version="1.0" ?>
<configuration>
  <!-- Includes system properties regardless of hst-system-properties-override context param -->
  <system/>
  <!-- Include extra application specific properties files -->
  <properties fileName='${catalina.base}/conf/custom-app1.properties'/>
  <properties fileName='${catalina.base}/conf/custom-app2.properties'/>
</configuration>

In the above example, the XML file becomes a CompositeConfiguration as a child of the root Configuration of HST Container, and it results in adding three more descendant Configurations: Java System properties, custom-app1.properties and custom-app2.properties.

Now, suppose that you have ${catalina.base}/conf/hst.xml, ${catalina.base}/conf/hst.properties and /WEB-INF/hst-config.properties in your environment, then HST Container loads and combines (a) Java System properties, (b) ${catalina.base}/conf/custom-app1.properties, (c)${catalina.base}/conf/custom-app2.properties, (d) ${catalina.base}/conf/hst.properties and (e) /WEB-INF/hst-config.properties.

For details on Commons-Configuration XML Configuration, refer to http://commons.apache.org/configuration/userguide/user_guide.html.

The Archetype Created Project Setup

When creating a new project from the archetype, the /conf directory contains among others the following files:

hst-dev.properties
hst-platform.properties

In these property files developers typically configure local development environment specific properties, for example some ecommerce test configuration parameters. The hst-dev.properties and hst-platform.properties (and also for example log4j2-dev.xml) never end up in the dist (distribution) but are only present for local development. Developers should never add to /conf directory hst.properties or platform.properties files: these configuration files should always be provided by devops and are environment specific, and thus for example different for test / acct or production, hence can and should never be part of the dist. Developer can add environment-agnostic  properties to 

/cms/webapp/src/main/webapp/WEB-INF/hst-config.properties
/site/webapp/src/main/webapp/WEB-INF/hst-config.properties

Since these files will be part of the distribution.

Bloomreach Cloud Environment-Specific Configuration

On Bloomreach Cloud it's possible to set environment-specific configuration files, and therefore, it's also possible to make use of that mechanism to deploy different HST config files such as the platform.properties to different environments. A complete recipe for how to accomplish this is described in the Bloomreach Cloud docs linked above.