HST-2 Container Configuration

1. 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 (or HstSiteConfigServlet, which is deprecated since 10.2) initializes all the HST Container core components on initialization of site applications.

2. Configuring HstFilter

HstFilter is by default for archetype created project configured in web.xml as follows:

Commons-Configuration formatted XML configuration file for HST Container.
If this init parameter does not exist or the configured file does not exist, then the " hst-config-properties" init parameter will be read and used.

hst-config-properties

hst-config.properties

hst-config.properties

Java standard properties file for HST Container.
If this init parameter is not configured, then /WEB-INF/hst-config.properties file will be used by default.

forceful.reinit

true

false

In most cases, this parameter can be just ignored.
If there are multiple site applications sharing one HST container, you can configure this parameter not to initialize the shared HST container twice or more.

Alternatively HstSiteConfigServlet can be configured instead as followings, however please note that this servlet is deprecated by HstContextLoaderListener since Hippo CMS 10.2. Please use HstContextLoaderListener if you use Hippo CMS 10.2 or newer.

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.

' /WEB-INF/hst-config.properties is used by default as configuration file. But, if you configure " hst-configuration" init parameter (as either servlet context init param or servlet config init param) with a Commons-Configurations formatted XML file, then you can do more sophisticated configurations. You can also configure ' hst-config-properties' init parameter (as either servlet context init param or servlet config init param) in order to use a properties configuration file in somewhere else.

NOTE: You can split configurations into multiple files. Any existing configuration files in the following locations are to be combined together by default, as resolved by the order:

Any configuration file specified by either hst-configuration or hst-config-properties servlet config init parameter (The default values are /WEB-INF/hst-configuration.xml and /WEB-INF/hst-config.properties).

So, for example, if you define ' default.repository.password = XXX' only in ' /WEB-INF/hst-config.properties', then ' default.repository.password' property value will be ' XXX'. But if you have the property in ${catalina.base}/conf/hst.properties like ' default.repository.password = YYY', then the ' default.repository.password' property value will be resolved to ' YYY'.
If you put ' -Ddefault.repository.password=ZZZ' in the command line, for instance, then the ' default.repository.password' property value will be resolved to ' ZZZ', instead.

This feature to allow properties overriding by multiple configuration files will make administrator change property values more easily because they don't have to copy every property but they can define only overriding properties in the overriding properties file instead.

The XML configuration file path configured by servlet context parameter can be defined like the following example:

However, because HST container loads the ${catalina.base}/conf/hst.properties if exists by default, you normally don't have to configure those servlet context init parameters any more. You can just define your overriding properties in ${catalina.base}/conf/hst.properties instead.

If you want to use XML configuration file instead, then here's an example configuration with an XML file (the default /WEB-INF/hst-configuration.xml, for instance):