public final class VirtualHostManager extends Object
Manages the mapping of incoming requests to virtual host and the per-virtual-host virtual path.

Each virtual host is identified by a canonical domain. However, any number of hostnames may be routed to the virtual host. The hostnames do not necessarily have to include the domain, such as in development modes, but this will often be the case.

Multiple "environments" are supported, each of which is a different mapping of requests to virtual hosts. Links between hosts must consider the environment when choosing how to generate links to other virtual hosts.

Environments are matched in the order registered. This may be significant when there are ambiguities in the mapping.

An example of a production environment might be:

  1. ->, prefix=/
  2. ->, prefix=/
  3. ->, prefix=/
  4. ->, prefix=/
  5. ->, prefix=/
  6. ->, prefix=/
  7. ->, prefix=/
  8. ->, prefix=/

The corresponding development environment would be:

  1. localhost:/ ->, prefix=/
  2. localhost:/ ->, prefix=/
  3. localhost:/ ->, prefix=/
  4. localhost:/ ->, prefix=/

The resulting per-virtual-host paths are in a virtual space introduced by this API and not directly part of the standard Servlet API. How they are handled and mapped onto servlet container resources is up the application and not defined here.

It is possible, but not required, to configure a default host. When a default host is set, any request not matching the mappings will be assigned to this host. When there is no default host set, non-matching requests are never passed through virtual hosting lists of rules.

Among all the hostnames mapped to a virtual host, one may be specified as "canonical". By default, the first non-IP-address hostname is considered the canonical.

Per-virtual host, with a global default if unspecified per host, it is possible to canonicalize the host, which means 301 redirect requests to alternate hostnames to the primary. Requests to IP addresses will not be redirected. Also, only OPTIONS, GET, and HEAD requests are redirected. This allows a POST to not lose its content due to a redirect. When using 303 redirect after POST, this would then get redirected to the canonical hostname. TODO: 307 redirect for non-OPTIONS/HEAD/GET.

Virtual host rules are invoked before non-virtual-host rules. If the virtual rule rules result in a terminal action, the non-virtual-host rules are never performed.