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

<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.

3. 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>

where we assumed your used mvn archetype created project value for  groupId was org.example.

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

4. 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	Example value	Default value	Description
hst-configuration	hst-configuration.xml	hst-configuration.xml	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.

 

5. Configuration for HST Container

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

 

NOTE: 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.

 

' /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:

1. Java system properties
2. Any configuration file specified by either ' hst-configuration' or ' hst-config-properties' servlet context init parameter.
3. ${catalina.base}/conf/hst.properties  if exists.
4. 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:

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

Also, the properties configuration file path configured by servlet context parameter can be defined like the following example:

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

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

<?xml version="1.0" ?>
<configuration>
  <!-- Includes all system properties -->
  <system/>
  <!-- Includes external properties files -->
  <properties fileName='${catalina.base}/conf/hst-config-1.properties'/>
  <properties fileName='${catalina.base}/conf/hst-config-2.properties'/>
</configuration>

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

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.