org.restlet.routing

## Class VirtualHost

- java.lang.Object
- - org.restlet.Restlet
  - - org.restlet.routing.Router
    - - org.restlet.routing.VirtualHost

All Implemented Interfaces:
  Uniform

    public class VirtualHost
    extends Router

Router of calls from Server connectors to Restlets. The attached Restlets are typically Applications.
A virtual host is defined along three properties:

- request's `Request.getHostRef()`: the URI of the host that received the request. Note that the same IP address can correspond to multiple domain names and therefore receive request with different "hostRef" URIs.
- request's `Request.getResourceRef()`: the URI of the target resource of the request. If this reference is relative, then it is based on the "hostRef", otherwise it is maintained as received. This difference is useful for resources identified by URNs or for Web proxies or Web caches.
- response's `Response.getServerInfo()`: the information about the server connector receiving the requests such as it IP address and port number.

When creating a new instance, you can define Java regular expressions ( `Pattern`) that must match the domain name, port, scheme for references or IP address and port number for server information. The default values match everything.
Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
  Jerome Louvel
See Also:
  `Pattern`, Wikipedia - Virtual Hosting, Apache - Virtual Hosting

### Field Summary

### Fields inherited from class org.restlet.routing.Router

`BEST, CUSTOM, FIRST, LAST, MODE_BEST_MATCH, MODE_CUSTOM, MODE_FIRST_MATCH, MODE_LAST_MATCH, MODE_NEXT_MATCH, MODE_RANDOM_MATCH, NEXT, RANDOM`

### Constructor Summary

Constructors
Constructor and Description
`VirtualHost()` Constructor.
`VirtualHost(Context parentContext)` Constructor.
`VirtualHost(Context parentContext, java.lang.String hostDomain, java.lang.String hostPort, java.lang.String hostScheme, java.lang.String resourceDomain, java.lang.String resourcePort, java.lang.String resourceScheme, java.lang.String serverAddress, java.lang.String serverPort)` Constructor.

### Method Summary

Methods
`Route` `attach(Restlet target)` Attaches a target Restlet to this router with an empty URI pattern.
`Route` `attach(java.lang.String uriPattern, Restlet target)` Attaches a target Restlet to this router based on a given URI pattern.
`Route` `attachDefault(Restlet defaultTarget)` Attaches a Restlet to this router as the default target to invoke when no route matches.
`Finder` `createFinder(java.lang.Class<?> targetClass)` Creates a new finder instance based on the "targetClass" property.
`protected Route` `createRoute(java.lang.String uriPattern, Restlet target, int matchingMode)` Creates a new route for the given URI pattern, target and matching mode.
`static java.lang.Integer` `getCurrent()` Returns the virtual host code associated to the current thread.
`java.lang.String` `getHostDomain()` Returns the hostRef host domain to match.
`java.lang.String` `getHostPort()` Returns the hostRef host port to match.
`java.lang.String` `getHostScheme()` Returns the hostRef scheme to match.
`static java.lang.String` `getIpAddress(java.lang.String domain)` Returns the IP address of a given domain name.
`static java.lang.String` `getLocalHostAddress()` Returns the local host IP address.
`static java.lang.String` `getLocalHostName()` Returns the local host name.
`java.lang.String` `getResourceDomain()` Returns the resourceRef host domain to match.
`java.lang.String` `getResourcePort()` Returns the resourceRef host port to match.
`java.lang.String` `getResourceScheme()` Returns the resourceRef scheme to match.
`java.lang.String` `getServerAddress()` Returns the listening server address.
`java.lang.String` `getServerPort()` Returns the listening server port.
`static void` `setCurrent(java.lang.Integer code)` Sets the virtual host code associated with the current thread.
`void` `setHostDomain(java.lang.String hostDomain)` Sets the hostRef host domain to match.
`void` `setHostPort(java.lang.String hostPort)` Sets the hostRef host port to match.
`void` `setHostScheme(java.lang.String hostScheme)` Sets the hostRef scheme to match.
`void` `setResourceDomain(java.lang.String resourceDomain)` Sets the resourceRef host domain to match.
`void` `setResourcePort(java.lang.String resourcePort)` Sets the resourceRef host port to match.
`void` `setResourceScheme(java.lang.String resourceScheme)` Sets the resourceRef scheme to match.
`void` `setServerAddress(java.lang.String serverAddress)` Sets the listening server address.
`void` `setServerPort(java.lang.String serverPort)` Sets the listening server port.

### Methods inherited from class org.restlet.routing.Router

`attach, attach, attach, attach, attachDefault, createRoute, detach, detach, doHandle, getCustom, getDefaultMatchingMode, getDefaultMatchingQuery, getDefaultMatchQuery, getDefaultRoute, getFinderClass, getMatchingMode, getMaxAttempts, getNext, getRequiredScore, getRetryDelay, getRoutes, getRoutingMode, handle, logRoute, setDefaultMatchingMode, setDefaultMatchingQuery, setDefaultMatchQuery, setDefaultRoute, setFinderClass, setMaxAttempts, setRequiredScore, setRetryDelay, setRoutes, setRoutingMode, start, stop`

### Methods inherited from class org.restlet.Restlet

`finalize, getApplication, getAuthor, getContext, getDescription, getLogger, getName, getOwner, isStarted, isStopped, setAuthor, setContext, setDescription, setName, setOwner`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### VirtualHost

    public VirtualHost()

Constructor. Note that usage of this constructor is not recommended as the Router won't have a proper context set. In general you will prefer to use the other constructor and pass it the parent component's context.

#### VirtualHost

    public VirtualHost(Context parentContext)

Constructor. Accepts all incoming requests by default, use the set methods to restrict the matchable patterns.

Parameters:
  `parentContext` - The parent component's context.

#### VirtualHost

    public VirtualHost(Context parentContext,
               java.lang.String hostDomain,
               java.lang.String hostPort,
               java.lang.String hostScheme,
               java.lang.String resourceDomain,
               java.lang.String resourcePort,
               java.lang.String resourceScheme,
               java.lang.String serverAddress,
               java.lang.String serverPort)

Constructor.

Parameters:
  `parentContext` - The parent component's context.
  `hostDomain` - The hostRef host domain pattern to match.
  `hostPort` - The hostRef host port pattern to match.
  `hostScheme` - The hostRef scheme protocol pattern to match.
  `resourceDomain` - The resourceRef host domain pattern to match.
  `resourcePort` - The resourceRef host port pattern to match.
  `resourceScheme` - The resourceRef scheme protocol pattern to match.
  `serverAddress` - The listening server address pattern to match.
  `serverPort` - The listening server port pattern to match.
See Also:
  `Pattern`

### Method Detail

#### getCurrent

    public static java.lang.Integer getCurrent()

Returns the virtual host code associated to the current thread. This variable is stored internally as a thread local variable and updated each time a call is routed by a virtual host.

Returns:
  The current context.

#### getIpAddress

    public static java.lang.String getIpAddress(java.lang.String domain)

Returns the IP address of a given domain name.

Parameters:
  `domain` - The domain name.
Returns:
  The IP address.

#### getLocalHostAddress

    public static java.lang.String getLocalHostAddress()

Returns the local host IP address.

Returns:
  The local host IP address.

#### getLocalHostName

    public static java.lang.String getLocalHostName()

Returns the local host name.

Returns:
  The local host name.

#### setCurrent

    public static void setCurrent(java.lang.Integer code)

Sets the virtual host code associated with the current thread.

Parameters:
  `code` - The thread's virtual host code.

#### attach

    public Route attach(Restlet target)

Attaches a target Restlet to this router with an empty URI pattern. A new route will be added routing to the target when any call is received. In addition to super class behavior, this method will set the context of the target if it is empty by creating a protected context via the `Context.createChildContext()` method.

Overrides:
  `attach` in class `Router`
Parameters:
  `target` - The target Restlet to attach.
Returns:
  The created route.

#### attach

    public Route attach(java.lang.String uriPattern,
               Restlet target)

Attaches a target Restlet to this router based on a given URI pattern. A new route will be added routing to the target when calls with a URI matching the pattern will be received. In addition to super class behavior, this method will set the context of the target if it is empty by creating a protected context via the `Context.createChildContext()` method.

Overrides:
  `attach` in class `Router`
Parameters:
  `uriPattern` - The URI pattern that must match the relative part of the resource URI.
  `target` - The target Restlet to attach.
Returns:
  The created route.

#### attachDefault

    public Route attachDefault(Restlet defaultTarget)

Attaches a Restlet to this router as the default target to invoke when no route matches. It actually sets a default route that scores all calls to 1.0. In addition to super class behavior, this method will set the context of the target if it is empty by creating a protected context via the `Context.createChildContext()` method.

Overrides:
  `attachDefault` in class `Router`
Parameters:
  `defaultTarget` - The Restlet to use as the default target.
Returns:
  The created route.

#### createFinder

    public Finder createFinder(java.lang.Class<?> targetClass)

Creates a new finder instance based on the "targetClass" property. In addition to super class behavior, this method will set the context of the finder by creating a protected context via the `Context.createChildContext()` method.

Overrides:
  `createFinder` in class `Router`
Parameters:
  `targetClass` - The target Resource class to attach.
Returns:
  The new finder instance.

#### createRoute

    protected Route createRoute(java.lang.String uriPattern,
                    Restlet target,
                    int matchingMode)

Description copied from class: `Router`
Creates a new route for the given URI pattern, target and matching mode. The route will match the URI query string depending on the result of `Router.getDefaultMatchingQuery()`.

Overrides:
  `createRoute` in class `Router`
Parameters:
  `uriPattern` - The URI pattern that must match the relative part of the resource URI.
  `target` - The target Restlet to attach.
  `matchingMode` - The matching mode.
Returns:
  The created route.

#### getHostDomain

    public java.lang.String getHostDomain()

Returns the hostRef host domain to match. See the `Pattern` class for details on the syntax.

Returns:
  The hostRef host domain to match.

#### getHostPort

    public java.lang.String getHostPort()

Returns the hostRef host port to match. See the `Pattern` class for details on the syntax.

Returns:
  The hostRef host port to match.

#### getHostScheme

    public java.lang.String getHostScheme()

Returns the hostRef scheme to match. See the `Pattern` class for details on the syntax.

Returns:
  The hostRef scheme to match.

#### getResourceDomain

    public java.lang.String getResourceDomain()

Returns the resourceRef host domain to match. See the `Pattern` class for details on the syntax.

Returns:
  The resourceRef host domain to match.

#### getResourcePort

    public java.lang.String getResourcePort()

Returns the resourceRef host port to match. See the `Pattern` class for details on the syntax.

Returns:
  The resourceRef host port to match.

#### getResourceScheme

    public java.lang.String getResourceScheme()

Returns the resourceRef scheme to match. See the `Pattern` class for details on the syntax.

Returns:
  The resourceRef scheme to match.

#### getServerAddress

    public java.lang.String getServerAddress()

Returns the listening server address. See the `Pattern` class for details on the syntax.

Returns:
  The listening server address.

#### getServerPort

    public java.lang.String getServerPort()

Returns the listening server port. See the `Pattern` class for details on the syntax.

Returns:
  The listening server port.

#### setHostDomain

    public void setHostDomain(java.lang.String hostDomain)

Sets the hostRef host domain to match. See the `Pattern` class for details on the syntax.

Parameters:
  `hostDomain` - The hostRef host domain to match.

#### setHostPort

    public void setHostPort(java.lang.String hostPort)

Sets the hostRef host port to match. See the `Pattern` class for details on the syntax.

Parameters:
  `hostPort` - The hostRef host port to match.

#### setHostScheme

    public void setHostScheme(java.lang.String hostScheme)

Sets the hostRef scheme to match. See the `Pattern` class for details on the syntax.

Parameters:
  `hostScheme` - The hostRef scheme to match.

#### setResourceDomain

    public void setResourceDomain(java.lang.String resourceDomain)

Sets the resourceRef host domain to match. See the `Pattern` class for details on the syntax.

Parameters:
  `resourceDomain` - The resourceRef host domain to match.

#### setResourcePort

    public void setResourcePort(java.lang.String resourcePort)

Sets the resourceRef host port to match. See the `Pattern` class for details on the syntax.

Parameters:
  `resourcePort` - The resourceRef host port to match.

#### setResourceScheme

    public void setResourceScheme(java.lang.String resourceScheme)

Sets the resourceRef scheme to match. See the `Pattern` class for details on the syntax.

Parameters:
  `resourceScheme` - The resourceRef scheme to match.

#### setServerAddress

    public void setServerAddress(java.lang.String serverAddress)

Sets the listening server address. See the `Pattern` class for details on the syntax.

Parameters:
  `serverAddress` - The listening server address.

#### setServerPort

    public void setServerPort(java.lang.String serverPort)

Sets the listening server port. See the `Pattern` class for details on the syntax.

Parameters:
  `serverPort` - The listening server port.