Virtual host

This section describes the purpose and rules of virtual hosts and how ServletContext objects are related to virtual hosts.

1. Overview

Virtual hosts allow different web applications to be mapped with the same URL based on the Internet domain name. In other words, two or more domain names (for example, "www1.foo.com" and "www2.foo.com") can exist on a single web engine and use different web contexts.

In the context of web engines, web contexts and web applications are the same.

2. Web Engine and Virtual Hosts

This section describes the purpose and rules of virtual hosts and how ServletContext objects are related to virtual hosts.

Purpose

Virtual hosts allows mapping of different web applications to the same URL based on the domain name mapped to the virtual host. This allows service providers to provide multiple web sites on a single web engine. This is similar to the function that provides a virtual host through the Host header of HTTP 1.1.

A virtual host is a group of web contexts that can be configured on a web engine. Refer to Web Engine Components for more information about where the virtual host is positioned as a web engine component.

The following diagram shows how virtual hosts are used depending on their purposes.

figure basic idea behind virtual hosting

Virtual Host Usage Pattern

In the previous example, it appears that the same context path (/service) is being accessed through two different addresses. There is one server, but from the perspective of the clients, there appear to be two servers, "www.foo.com" and "www.bar.com".

The service provider can provide different services with the same "/service" address pattern. In the previous example, "www.foo.com" provides services in Korean and "www.bar.com" provides services in English.

Rules

The following rules apply when creating virtual hosts.

A virtual host must have its own name.

The name is used to refer to the virtual host in the configuration file and must be unique within the web engine.
One or more domain names and IP addresses can be mapped to a single virtual host.

JEUS calls this a host name. Note that the same host name cannot be mapped to different virtual hosts.
Web contexts with the same name cannot be deployed to different virtual hosts.

The Servlet standard state that a same web context cannot be shared by different virtual hosts.
Different web contexts with the same path can be deployed on different virtual hosts, but those with the same path cannot exist on the same virtual host.

The web context name is the application or module name that is defined in the Jakarta EE standard. The path is the context root or the context path that is defined in the web application. The web context names are managed for the purpose of deployment, and the web engine manages the context paths.

JEUS web engines have a default virtual host. When deploying a web context, if a virtual host is not set, the web context will be deployed to the default virtual host. The name of the default virtual host is 'DEFAULT_HOME'. This is a reserved word that cannot be used as another virtual host name.

2.1. ServletContext Object and Virtual Hosts

In the Servlet API, the jakarta.servlet.ServletContext.getContext(String contextPath) method returns the ServletContext object that is located in the "contextPath". This method returns the ServletContext that exists on the virtual host to which the ServletContext belongs. If the object does not exist on the virtual host, the default virtual host will be searched for.

3. Web Context Requests to Virtual Host

This section describes how to map URLs to web contexts on a virtual host.

The following example shows the relationships between a web engine, virtual hosts, and web contexts.

figure example of legal relationships between virtual host and contexts

Relationships between a Web Engine, Virtual Hosts, and Web Contexts

3.1. URL Matching Examples

The following describes the virtual hosts and web contexts that are mapped to URLs based on the previous figure, Relationships between a Web Engine, Virtual Hosts, and Web Contexts.

```
http://www.foo.com/ctx1/test.jsp
```
Matching virtual host

A

Matching web context name

ctx1
```
http://www.foo.com/ctx2/test.jsp
```
Matching virtual host

A

Matching web context name

ctx2
```
http://www.bar.com/ctx1/
```
Matching virtual host

B

Matching web context name

ctx1-1
```
http://www.bar2.com/ctx1/test.jsp
```
Matching virtual host

C

Matching web context name

None (404 Not Found)
```
http://www.foo2.com/ctx2/
```
Matching virtual host

C

Matching web context name

ctx2-2

Web context name and context path have different concepts. In general, they have the same value, but they are different when the services are distinguished by virtual host as in the previous example.

3.2. URL Matching Order

URLs are matched in the following order.

Match the host header domain name and port string with all registered virtual hosts. If there is a matching virtual host, the web context is searched within the virtual host.

Port information in the format of "IP:Port" can be mapped to a host name set in a virtual host. If port information exists, entire host headers (including ports) are matched.
If a web context cannot be found, search within the default virtual host.
If the web context does not exist in the default virtual host, a 404 Not Found error is thrown.

4. Configuring Virtual Hosts

Virtual hosts can be added, modified, and deleted in the console tool.

In the configuration examples of this section, "A", "B", and "C" are used as the host names for convenience. Use meaningful names in the production environment.

4.1. Add

Virtual hosts can be added in the console tool.

Using the Console Tool

To add a virtual host using the console tool, run the add-virtual-host command as follows:

add-virtual-host [-cluster <cluster-name> | -server <server-name>]
                 [-f, --forceLock]
                 <virtual-host-name>
                 -list <host-name-list>
                 [-tmin <The minimum number of threads>]
                 [-tmax <The maximum number of threads>]
                 [-tidle <max-idle-time>]
                 [-qs <max-queue-size>]

For more information about the command, refer to add-virtual-host in JEUS Reference Guide.

4.2. Modify

Virtual hosts can be modified in the console tool.

Using the Console Tool

To modify virtual hosts using the console tool, run the modify-virtual-host command. For more information about the command, refer to modify-virtual-host in JEUS Reference Guide.

modify-virtual-host [-cluster <cluster-name> | -server <server-name>]
                 [-f, --forceLock]
                 <virtual-host-name>
                 [-alhnl <access-log-enable-host-name-lookup> |
                 -aluse <use-access-log (true/false)> | -alf
                 <access-log-format> | -aluph
                 <access-log-use-parent-handler (true/false)> |
                 -alext <access-log-excluded-extensions>]
                 [-hnrm <host-name> | -hnadd <host-name>]
                 [-ast <attach-stacktrace-on-error>]
                 [-fhn <file-handler-name>]
                 [-fhp <file-handler-permission>]
                 [-tmin <The minimum number of threads>]
                 [-tmax <maximum-thread-num>]
                 [-tidle <max-idle-time>]

4.3. Delete

Virtual hosts can be added in the console tool.

Using the Console Tool

To delete virtual hosts using the console tool, run the remove-virtual-host command. For more information about the command, refer to remove-virtual-host in JEUS Reference Guide.

remove-virtual-host [-cluster <cluster-name> | -server <server-name>]
                 [-f, --forceLock]
                 <virtual-host-name>