apache > cocoon

- Home

# Host-Selector in Cocoon

## HostSelector

NAME | host
WHAT | The `HostSelector` component is used to select appropriate sitemap processing depending on `Host` header value.
TYPE | Selector, Sitemap Component
BLOCK | Core
CLASS | org.apache.cocoon.selection.HostSelector
SINCE | Cocoon 2.0
CACHEABLE | not applicable

## Description

The `HostSelector` tests the `Host` header field from the request against the test attribute of the selectors when clause.

## Usage

The `HostSelector` allows to define host specific sitemap processing. This way Cocoon can do multi-homed sitemap processing.

### Sitemap pipeline examples

The snippet below uses a `HostSelector` named `host`, and tests against symbolic host-sites which are configured in the `host` selector section.

    <map:select type="host">
      <map:when test="uk-site">
      ....
      </map:when>
      <map:when test="de-site">
      ...
      </map:when>
      ...
      <map:otherwise>
      ...
      </map:otherwise>
    </map:select>

### Sitemap component configuration example

The snippet below declares a `HostSelector` defining symbolic host-site names for some host domains.

    <map:selectors>
      <map:selector name="host"
        src="org.apache.cocoon.selection.HostSelector"
        logger="sitemap.selector.host"

        <host name="uk-site" value="foo.bar.uk"/>
        ...
        <host name="de-site" value="foo.bar.de"/>
        <host name="us-site" value="foo.bar.com"/>

      </map:selector>
      ...
    </map:selectors>

### Configuration

The configuration section of `HostSelector` specifies a mapping from host strings to symbolic host-site names.

Each host element specifies a name attribute holding the symbolic host-site name used in the test attribute expression. The attribute name contains a matchable substring of some real host header values.

It is allowed to specify for a host name more than one entry. This way a symbolic host-site name is matched by different host header substrings. The snippet belows will yield true for `test="central-europe"` if the host header contains `foo.bar.cz`, `foo.bar.at`, or `foo.bar.hu`.

    ...
      <host name="central-europe" value="foo.bar.cz"/>
      <host name="central-europe" value="foo.bar.at"/>
      <host name="central-europe" value="foo.bar.uk"/>
    ...

### Setup

Setting up a `HostSelector` includes choosing the `<map:when>` test expressions and a optional `<map:otherwise>` clause.

The test attribute of the `<map:when>` clause must match a host attribute name value. The value of the test attribute in a `<map:when>` clause must be declared in a `host` name attribute.

### Effect on Object Model and Sitemap Parameters

The `HostSelector` has no side effects on the object model or any sitemap parameters.

## Bugs/Caveats

The `HostSelector` adds the response header attribute `Vary` having value `Host` indicating that the response differ for different hosts. This information is particularly meaningful for a http-proxy server.

## History

28-12-02: initial creation

## See also

A general documentation about selectors is available at Matchers and Selectors.

For a detailed `Host` header documentation see RFC 2068, especially if Cocoon's run time environment is an http servlet environment.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).