Default Inherited Configuration

The Introduction of this chapter explained that the channel configuration for a channel example can be found at

+ hst:hst
   + hst:configurations
      + example           [hst:configuration]

Configuration inheritance explained how the example configuration can inherit from (and merge with) another configuration.

+ hst:hst
   + hst:configurations
      + example             [hst:configuration]
      |   - hst:inheritsfrom = ../common
      + common              [hst:configuration]

In addition, there is one default configuration from which every hst:configuration inherits implicitly, namely :

+ hst:hst
   + hst:configurations
       + hst:default

The hst:default is the implicitly inherited configuration and does not need to be included through the hst:inheritsfrom property.

Why is there a hst:default?

The hst:default node is the only fixed non-project-dependant name below hst:hst/hst:configuration. It is the configuration node to which the delivery tier (HST) and plugins can bootstrap their configuration.

By default, the delivery tier bootstraps sitemap items into hst:default that match requests for static webapp resources, webfiles, authentication requests, and repository binaries:

+ hst:hst
  + hst:configurations
    + hst:default
      + hst:sitemap
        + _any_.css
        + _any_.CSS
        + _any_.gif
        + _any_.GIF
        + _any_.ico
        + _any_.ICO
        + _any_.jpeg
        + _any_.JPEG
        + _any_.jpg
        + _any_.JPG
        + _any_.js
        + _any_.JS
        + _any_.pdf
        + _any_.PDF
        + _any_.png
        + _any_.PNG
        + _any_.svg
        + _any_.SVG
        + _any_.jsp
        + _any_.JSP
        + webfiles
        | + _default_
        |   + _any_
        login
        | + _any_
        + binaries
          + _any_

Note _any_ stands for ** matcher and _default_ for *.

As an example of a plugin using hst:default, the Sitemap Plugin bootstraps a sitemap.xml sitemap item into hst:default/hst:sitemap, resulting in the URL /sitemap.xml being directly available in every channel.

Another common use case is that a plugin or library feature bootstraps ready to use component catalog items into hst:default.

The Static Webapp Files Matchers

The static webapp files matchers are the _any_.css, _any_.CSS, _any_.gif  ...... _any_.JSP. They all have hst:containerresource = true:

/hst:hst/hst:configurations/hst:default/hst:sitemap
  + _any_.css
    - hst:containerresource = true

Each HTTP request, including those for static webapp resources, is matched against a sitemap item. A request, e.g. /css/style.css, matches _any_.css, after which the HST pipeline for container resources is executed, namely the ContainerResourcePipeline. The last valve in this pipeline is the containerResourceDispatchingValve which just forwards the request to the container servlet serving static webapp files.

It's possible to plug-in additional behavior in the ContainerResourcePipeline, such as an authentication check.

Nested sitemap structures can be used, for example for CSS files, where some CSS files are only served over HTTPS.

The default static webapp files matchers cover the most commonly used file extensions. Additional extensions can be bootstrapped into hst:default by the implementation project, if necessary.

A container resource sitemap item (item that has hst:containerresource = true) can only be configured in the hst:default sitemap, and not in other sitemaps. When a URL is created for a delivery tier link that matches a container resource sitemap item, the resulting link is relative to the webapp  (e.g. relative to /site) and not necessarily to the current channel (e.g. /site/fr/). A container resource sitemap item is by default also scheme agnostic, implying that it does not matter whether it is accessed over HTTP or HTTPS. If a matcher is only suited for a specific scheme, the property hst:schemeagnostic needs to be set to false.

The Webfiles Matcher

The webfiles matcher has been introduced to support Web Files. Including its properties, it is (should be) as follows:

/hst:hst/hst:configurations/hst:default/hst:sitemap
  + webfiles
    - hst:containerresource = true
    - hst:namedpipeline = WebFilePipeline
    - hst:refId = WEB-FILES-ID 
    + _default_
      + _any_
        - hst:parameternames = version
        - hst:parametervalues = ${1}
        - hst:relativecontentpath = ${2}

All URLs for webfiles are considered to be container resources as well. Their URLs are thus relative to the webapp and not relative to the currently matched channel. The webfiles sitemap item must contain  hst:refId = WEB-FILES-ID for web files to work. The _default_ matcher is to match the timestamp in the URL for web files. The _any_ matcher matches the web file location in the repository.

The Login Matcher

The login matcher catches all delivery tier authentication requests:

/hst:hst/hst:configurations/hst:default/hst:sitemap
  + login
    - hst:containerresource = true
    - hst:namedpipeline = PlainFilterChainInvokingPipeline
    - hst:scheme = https 
      + _any_

The Binaries Matcher

The binaries matcher is used to serve binaries from the repository. These include binaries from assets, gallery and document embedded binaries. The binaries matcher is by default bootstrapped as follows:

/hst:hst/hst:configurations/hst:default/hst:sitemap
  + binaries
    - hst:containerresource = true
    - hst:refId = BINARIES-PIPELINE-ID
      + _any_

The binaries matcher is a container resource, implying that one and the same binary used in two different channels on the same host (for example http://www.example.org and http://www.example.org/fr) will use one and the same URL to access the binary. The binaries matcher will delegate via the containerResourceDispatchingValve the request to the binaries servlet, which will serve the binary. In the CMS channel manager when viewing the preview of a channel, the preview of a binary will be served.