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 projectsHstFilter 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:

Init parameter name

Required? 

Example value

Default value

Description

hst-configuration

No

${catalina.base}/conf/hst.xml

 

Commons-Configuration formatted XML configuration file for HST Container.

hst-config-properties

No

${catalina.base}/conf/hst-custom.properties

${catalina.base}/conf/hst.properties
  (in SITE application)
or
${catalina.base}/conf/platform.properties
   (in CMS or Platform application)

Java standard properties file for HST Container.

hst-system-properties-override No false true Whether or not to combine Java System properties first to override any properties in other Configurations.
Since v14.0, when the hst-config-properties context parameter is not specified, the default configuration properties file path is set to either ${catalina.base}/conf/hst.properties or ${catalina.base}/conf/platform.properties.
In case of Platform or CMS application, ${catalina.base}/conf/platform.properties is chosen. Otherwise (e.g, SITE application), ${catalina.base}/conf/hst.properties is chosen.
This allows to separate the configuration properties between CMS/Platform application and SITE application, also preventing unnecessary access from component code to any external service references or credentials that are supposed to be used in CMS/Platform application.
Note that a developer should never supply ${catalina.base}/conf/platform.properties or ${catalina.base}/conf/hst.properties : This is because environment specific properties should end up in these files. The non-environment specific properties should end up in the hst-config.properties below /cms/webapp/src/main/webapp/WEB-INF or /site/webapp/src/main/webapp/WEB-INF. Also see below the archetype created project setup

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.

Why combine those multiple files by default, not just using only either ${catalina.base}/conf/hst.properties or ${catalina.base}/conf/platform.properties?
If the Java System properties is not added first, then you won't be able to use property value expansion expressions in the configuration. Suppose you want to add a property like `my.secureapp.props = ${brc.appconfigpath}/mysecureapp.properties` using the property reference (i.e. ${brc.appconfigpath}) in the hst.properties. Without the Java System properties as the first child Configuration, you can't use the property value expansion expression in the next Configurations.
Also, as mentioned above, you might want to put different configuration set in different files separately. In that case, the combining Configurations through CompositeConfiguration is highly useful.

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.

In most cases, it is fine to keep all properties only in the default configuration files such as ${catalina.base}/conf/hst.properties or ${catalina.base}/conf/platform.properties. All the others are loaded optionally only when existing. If you don't have a good reason, you can ignore the context parameters but use the default configuration files only.

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.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?