Module com.aoapps.servlet.firewall.virtualhosts

Package com.aoapps.servlet.firewall.virtualhosts

Class VirtualHostManager

java.lang.Object

com.aoapps.servlet.firewall.virtualhosts.VirtualHostManager

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. aoindustries.com:/ -> domain=aoindustries.com, prefix=/
2. www.aoindustries.com:/ -> domain=aoindustries.com, prefix=/
3. semanticcms.com:/ -> domain=semanticcms.com, prefix=/
4. www.semanticcms.com:/ -> domain=semanticcms.com, prefix=/
5. pragmatickm.com:/ -> domain=pragmatickm.com, prefix=/
6. www.pragmatickm.com:/ -> domain=pragmatickm.com, prefix=/
7. aorepo.org:/ -> domain=aorepo.org, prefix=/
8. www.aorepo.org:/ -> domain=aorepo.org, prefix=/

The corresponding development environment would be:

1. localhost:/aoindustries.com/ -> domain=aoindustries.com, prefix=/
2. localhost:/semanticcms.com/ -> domain=semanticcms.com, prefix=/
3. localhost:/pragmatickm.com/ -> domain=pragmatickm.com, prefix=/
4. localhost:/aorepo.org/ -> domain=aorepo.org, 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	VirtualHostManager.Initializer	Creates the VirtualHostManager during application start-up.

Method Summary

Modifier and Type	Method	Description
static VirtualHostManager	getInstance(ServletContext servletContext)	Gets the VirtualHostManager for the given ServletContext, creating a new instance if not yet present.
VirtualHost	getVirtualHost(DomainName domain)	Finds the virtual host registered at the given domain.
Environment	newEnvironment(String name)	Creates a new, empty environment.
VirtualHost	newVirtualHost(DomainName domain, PartialURL canonicalPartialUrl, Rule... rules)	Creates a new virtual host.
VirtualHost	newVirtualHost(DomainName domain, PartialURL canonicalPartialUrl, Iterable<? extends Rule> rules)	Creates a new virtual host.
VirtualHost	newVirtualHost(DomainName domain, Rule... rules)	Creates a new virtual host.
VirtualHost	newVirtualHost(DomainName domain, Iterable<? extends Rule> rules)	Creates a new virtual host.
VirtualHostMatch	search(HttpServletRequest request)	Matches the given request to an environment and virtual host via HttpServletRequestFieldSource.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getInstance

public static VirtualHostManager getInstance(ServletContext servletContext)

Gets the VirtualHostManager for the given ServletContext, creating a new instance if not yet present.

newVirtualHost

public VirtualHost newVirtualHost(DomainName domain,
 PartialURL canonicalPartialUrl,
 Iterable<? extends Rule> rules)
                           throws IllegalStateException

Creates a new virtual host.

Parameters:

canonicalPartialUrl - When null, a canonical partial URL will be generated via VirtualHost.generateCanonicalPartialURL(com.aoapps.net.DomainName).

Throws:

IllegalStateException - If a virtual host already exists on the host's domain.

newVirtualHost

public VirtualHost newVirtualHost(DomainName domain,
 PartialURL canonicalPartialUrl,
 Rule... rules)
                           throws IllegalStateException

Creates a new virtual host.

Parameters:

canonicalPartialUrl - When null, a canonical partial URL will be generated via VirtualHost.generateCanonicalPartialURL(com.aoapps.net.DomainName).

Throws:

IllegalStateException - If a virtual host already exists on the host's domain.

newVirtualHost

public VirtualHost newVirtualHost(DomainName domain,
 Iterable<? extends Rule> rules)
                           throws IllegalStateException

Creates a new virtual host. Generates a default canonical partial URL as https://${domain}.

Throws:

IllegalStateException - If a virtual host already exists on the host's domain.

See Also:

• VirtualHost.generateCanonicalPartialURL(com.aoapps.net.DomainName)

newVirtualHost

public VirtualHost newVirtualHost(DomainName domain,
 Rule... rules)
                           throws IllegalStateException

Creates a new virtual host. Generates a default canonical partial URL as https://${domain}.

Throws:

IllegalStateException - If a virtual host already exists on the host's domain.

See Also:

• VirtualHost.generateCanonicalPartialURL(com.aoapps.net.DomainName)

getVirtualHost

public VirtualHost getVirtualHost(DomainName domain)

Finds the virtual host registered at the given domain.

See Also:

• newVirtualHost(com.aoapps.net.DomainName, com.aoapps.net.partialurl.PartialURL, java.lang.Iterable)
• newVirtualHost(com.aoapps.net.DomainName, com.aoapps.net.partialurl.PartialURL, com.aoapps.servlet.firewall.api.Rule...)
• newVirtualHost(com.aoapps.net.DomainName, java.lang.Iterable)
• newVirtualHost(com.aoapps.net.DomainName, com.aoapps.servlet.firewall.api.Rule...)

newEnvironment

public Environment newEnvironment(String name)
                           throws IllegalStateException

Creates a new, empty environment.

Throws:

IllegalStateException - If an environment already exists with this name.

search

public VirtualHostMatch search(HttpServletRequest request)
                        throws IOException,
ServletException

Matches the given request to an environment and virtual host via HttpServletRequestFieldSource.

Search the environments in the order added. Within each environment, searches the partial URLs in the order added.

Returns:

The match or null if no match found.

Throws:

ServletException - when a request value is incompatible with the self-validating types

IOException