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

MODE_BEST_MATCH, MODE_CUSTOM, MODE_FIRST_MATCH, MODE_LAST_MATCH, MODE_NEXT_MATCH, MODE_RANDOM_MATCH

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
TemplateRoute	attach(Restlet target) Attaches a target Restlet to this router with an empty URI pattern.
TemplateRoute	attach(String uriPattern, Restlet target) Attaches a target Restlet to this router based on a given URI pattern.
TemplateRoute	attachDefault(Restlet defaultTarget) Attaches a Restlet to this router as the default target to invoke when no route matches.
protected void	checkContext(Restlet target) Checks the context and sets it if necessary.
Finder	createFinder(Class<? extends ServerResource> targetClass) Creates a new finder instance based on the "targetClass" property.
protected TemplateRoute	createRoute(String uriPattern, Restlet target, int matchingMode) Creates a new route for the given URI pattern, target and matching mode.
static Integer	getCurrent() Returns the virtual host code associated to the current thread.
String	getHostDomain() Returns the hostRef host domain to match.
String	getHostPort() Returns the hostRef host port to match.
String	getHostScheme() Returns the hostRef scheme to match.
static String	getIpAddress(String domain) Returns the IP address of a given domain name.
static String	getLocalHostAddress() Returns the local host IP address.
static String	getLocalHostName() Returns the local host name.
String	getResourceDomain() Returns the resourceRef host domain to match.
String	getResourcePort() Returns the resourceRef host port to match.
String	getResourceScheme() Returns the resourceRef scheme to match.
String	getServerAddress() Returns the listening server address.
String	getServerPort() Returns the listening server port.
void	setContext(Context parentContext) Sets the context.
static void	setCurrent(Integer code) Sets the virtual host code associated with the current thread.
void	setHostDomain(String hostDomain) Sets the hostRef host domain to match.
void	setHostPort(String hostPort) Sets the hostRef host port to match.
void	setHostScheme(String hostScheme) Sets the hostRef scheme to match.
void	setResourceDomain(String resourceDomain) Sets the resourceRef host domain to match.
void	setResourcePort(String resourcePort) Sets the resourceRef host port to match.
void	setResourceScheme(String resourceScheme) Sets the resourceRef scheme to match.
void	setServerAddress(String serverAddress) Sets the listening server address.
void	setServerPort(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, getDefaultRoute, getMatchingMode, getMaxAttempts, getNext, getRequiredScore, getRetryDelay, getRoutes, getRoutingMode, handle, logRoute, redirectPermanent, redirectSeeOther, redirectTemporary, setDefaultMatchingMode, setDefaultMatchingQuery, setDefaultRoute, setMaxAttempts, setRequiredScore, setRetryDelay, setRoutes, setRoutingMode, start, stop

Methods inherited from class org.restlet.Restlet

finalize, getApplication, getAuthor, getContext, getDescription, getFinderClass, getLogger, getName, getOwner, handle, handle, handle, isStarted, isStopped, setAuthor, setDescription, setFinderClass, 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 virtual host 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,
           String hostDomain,
           String hostPort,
           String hostScheme,
           String resourceDomain,
           String resourcePort,
           String resourceScheme,
           String serverAddress,
           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 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 String getIpAddress(String domain)

Returns the IP address of a given domain name.

Parameters:

domain - The domain name.

Returns:

The IP address.

getLocalHostAddress

public static String getLocalHostAddress()

Returns the local host IP address.

Returns:

The local host IP address.

getLocalHostName

public static String getLocalHostName()

Returns the local host name.

Returns:

The local host name.

setCurrent

public static void setCurrent(Integer code)

Sets the virtual host code associated with the current thread.

Parameters:

code - The thread's virtual host code.

attach

public TemplateRoute 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 TemplateRoute attach(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 TemplateRoute 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.

checkContext

protected void checkContext(Restlet target)

Checks the context and sets it if necessary.

Parameters:

target - The target Restlet.

createFinder

public Finder createFinder(Class<? extends ServerResource> 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 Restlet

Parameters:

targetClass - The target Resource class to attach.

Returns:

The new finder instance.

See Also:

Finder.createFinder(Class, Class, Context, Logger)

createRoute

protected TemplateRoute createRoute(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 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 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 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 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 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 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 String getServerAddress()

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

Returns:

The listening server address.

getServerPort

public String getServerPort()

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

Returns:

The listening server port.

setContext

public void setContext(Context parentContext)

Description copied from class: org.restlet.Restlet

Sets the context.

Overrides:

setContext in class Restlet

Parameters:

parentContext - The context.

setHostDomain

public void setHostDomain(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(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(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(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(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(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(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(String serverPort)

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

Parameters:

serverPort - The listening server port.