org.restlet.routing

Class Redirector

java.lang.Object

org.restlet.Restlet

org.restlet.routing.Redirector

All Implemented Interfaces:

Uniform

public class Redirector
extends Restlet

Rewrites URIs then redirects the call or the client to a new destination. There are various redirection modes that you can choose from: client-side redirections (MODE_CLIENT_FOUND, MODE_CLIENT_PERMANENT, MODE_CLIENT_SEE_OTHER, MODE_CLIENT_TEMPORARY) or server-side redirections, similar to a reverse proxy ( MODE_SERVER_OUTBOUND and MODE_SERVER_INBOUND).

When setting the redirection URIs, you can also used special URI variables to reuse most properties from the original request as well as URI template variables. For a complete list of properties, please see the Resolver class. For example "/target?referer={fi}" would redirect to the relative URI, inserting the referrer URI as a query parameter.

To create a reverse proxy, a typically configuration will use the MODE_SERVER_OUTBOUND constant and a target URI like "http://targetHost/targetRootPath/{rr}" to ensure that all child URIs are properly redirected as well, "rr" appending the remaining part of the current request URI that hasn't been routed yet.

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:

Template, User Guide - URI rewriting and redirection

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	headersCleaning Indicates if all headers of HTTP requests stored in the request's attributes, must be removed before the redirection.
protected int	mode The redirection mode.
static int	MODE_CLIENT_FOUND In this mode, the client is simply redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_FOUND status.
static int	MODE_CLIENT_PERMANENT In this mode, the client is permanently redirected to the URI generated from the target URI pattern, using the Status.REDIRECTION_PERMANENT status.
static int	MODE_CLIENT_SEE_OTHER In this mode, the client is simply redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_SEE_OTHER status.
static int	MODE_CLIENT_TEMPORARY In this mode, the client is temporarily redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_TEMPORARY status.
static int	MODE_SERVER_INBOUND In this mode, the call is sent to Context.getServerDispatcher().
static int	MODE_SERVER_OUTBOUND In this mode, the call is sent to Application.getOutboundRoot() or if null to Context.getClientDispatcher().
protected java.lang.String	targetTemplate The target URI pattern.

Constructor Summary

Constructors

Constructor and Description
Redirector(Context context, java.lang.String targetTemplate) Constructor for the client dispatcher mode.
Redirector(Context context, java.lang.String targetPattern, int mode) Constructor.

Method Summary

Modifier and Type	Method and Description
int	getMode() Returns the redirection mode.
protected Reference	getTargetRef(Request request, Response response) Returns the target reference to redirect to by automatically resolving URI template variables found using the Template class using the request and response as data models.
java.lang.String	getTargetTemplate() Returns the target URI pattern.
void	handle(Request request, Response response) Handles a call by redirecting using the selected redirection mode.
protected void	inboundServerRedirect(Reference targetRef, Request request, Response response) Redirects a given call to a target reference.
boolean	isHeadersCleaning() Indicates if the headers must be cleaned.
protected void	outboundServerRedirect(Reference targetRef, Request request, Response response) Redirects a given call to a target reference.
protected Representation	rewrite(Representation initialEntity) Optionally rewrites the response entity returned in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes.
protected void	rewrite(Request initialRequest) Optionally updates the request sent in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes.
protected void	rewrite(Response initialResponse) Optionally updates the response sent in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes.
void	rewriteLocation(Request request, Response response) Rewrite the location of the response, and the Location of the entity, if any.
protected void	serverRedirect(Restlet next, Reference targetRef, Request request, Response response) Redirects a given call on the server-side to a next Restlet with a given target reference.
void	setHeadersCleaning(boolean headersCleaning) Indicates if the headers must be cleaned.
void	setMode(int mode) Sets the redirection mode.
void	setTargetTemplate(java.lang.String targetTemplate) Sets the target URI pattern.

Methods inherited from class org.restlet.Restlet

createFinder, finalize, getApplication, getAuthor, getContext, getDescription, getFinderClass, getLogger, getName, getOwner, handle, handle, handle, isStarted, isStopped, setAuthor, setContext, setDescription, setFinderClass, setName, setOwner, start, stop

Methods inherited from class java.lang.Object

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

Field Detail

MODE_CLIENT_FOUND

public static final int MODE_CLIENT_FOUND

In this mode, the client is simply redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_FOUND status. Note: this is a client-side redirection.

See Also:

Status.REDIRECTION_FOUND, Constant Field Values

MODE_CLIENT_PERMANENT

public static final int MODE_CLIENT_PERMANENT

In this mode, the client is permanently redirected to the URI generated from the target URI pattern, using the Status.REDIRECTION_PERMANENT status. Note: this is a client-side redirection.

See Also:

Status.REDIRECTION_PERMANENT, Constant Field Values

MODE_CLIENT_SEE_OTHER

public static final int MODE_CLIENT_SEE_OTHER

In this mode, the client is simply redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_SEE_OTHER status. Note: this is a client-side redirection.

See Also:

Status.REDIRECTION_SEE_OTHER, Constant Field Values

MODE_CLIENT_TEMPORARY

public static final int MODE_CLIENT_TEMPORARY

In this mode, the client is temporarily redirected to the URI generated from the target URI pattern using the Status.REDIRECTION_TEMPORARY status. Note: this is a client-side redirection.

See Also:

Status.REDIRECTION_TEMPORARY, Constant Field Values

MODE_SERVER_INBOUND

public static final int MODE_SERVER_INBOUND

In this mode, the call is sent to Context.getServerDispatcher(). Once the selected client connector has completed the request handling, the response is normally returned to the client. In this case, you can view the Redirector as acting as a transparent proxy Restlet. Note: this is a server-side redirection.

Warning: remember to add the required connectors to the parent Component and to declare them in the list of required connectors on the Application.getConnectorService() property.

Note that in this mode, the headers of HTTP requests, stored in the request's attributes, are removed before dispatching. Also, when a HTTP response comes back the headers are also removed. You can control this behavior by setting the headersCleaning attribute or by overriding the rewrite(Request) or rewrite(Response).

See Also:

Context.getServerDispatcher(), Constant Field Values

MODE_SERVER_OUTBOUND

public static final int MODE_SERVER_OUTBOUND

In this mode, the call is sent to Application.getOutboundRoot() or if null to Context.getClientDispatcher(). Once the selected client connector has completed the request handling, the response is normally returned to the client. In this case, you can view the Redirector as acting as a transparent server-side proxy. Note: this is a server-side redirection.

Warning: remember to add the required connectors to the parent Component and to declare them in the list of required connectors on the Application.getConnectorService() property.

Note that in this mode, the headers of HTTP requests, stored in the request's attributes, are removed before dispatching. Also, when a HTTP response comes back the headers are also removed. You can control this behavior by setting the headersCleaning attribute or by overriding the rewrite(Request) or rewrite(Response).

See Also:

Application.getOutboundRoot(), Context.getClientDispatcher(), Constant Field Values

headersCleaning

protected volatile boolean headersCleaning

Indicates if all headers of HTTP requests stored in the request's attributes, must be removed before the redirection. If set to true, it removes all headers, otherwise it keeps only the extension (or non HTTP standard) headers

mode

protected volatile int mode

The redirection mode.

targetTemplate

protected volatile java.lang.String targetTemplate

The target URI pattern.

Constructor Detail

Redirector

public Redirector(Context context,
                  java.lang.String targetTemplate)

Constructor for the client dispatcher mode.

Parameters:

context - The context.

targetTemplate - The template to build the target URI.

See Also:

Template

Redirector

public Redirector(Context context,
                  java.lang.String targetPattern,
                  int mode)

Constructor.

Parameters:

context - The context.

targetPattern - The pattern to build the target URI (using StringTemplate syntax and the CallModel for variables).

mode - The redirection mode.

Method Detail

getMode

public int getMode()

Returns the redirection mode.

Returns:

The redirection mode.

getTargetRef

protected Reference getTargetRef(Request request,
                                 Response response)

Returns the target reference to redirect to by automatically resolving URI template variables found using the Template class using the request and response as data models.

Parameters:

request - The request to handle.

response - The response to update.

Returns:

The target reference to redirect to.

getTargetTemplate

public java.lang.String getTargetTemplate()

Returns the target URI pattern.

Returns:

The target URI pattern.

handle

public void handle(Request request,
                   Response response)

Handles a call by redirecting using the selected redirection mode.

Specified by:

handle in interface Uniform

Overrides:

handle in class Restlet

Parameters:

request - The request to handle.

response - The response to update.

inboundServerRedirect

protected void inboundServerRedirect(Reference targetRef,
                                     Request request,
                                     Response response)

Redirects a given call to a target reference. In the default implementation, the request HTTP headers, stored in the request's attributes, are removed before dispatching. After dispatching, the response HTTP headers are also removed to prevent conflicts with the main call.

Parameters:

targetRef - The target reference with URI variables resolved.

request - The request to handle.

response - The response to update.

isHeadersCleaning

public boolean isHeadersCleaning()

Indicates if the headers must be cleaned.

Returns:

True if the headers must be cleaned.

outboundServerRedirect

protected void outboundServerRedirect(Reference targetRef,
                                      Request request,
                                      Response response)

Redirects a given call to a target reference. In the default implementation, the request HTTP headers, stored in the request's attributes, are removed before dispatching. After dispatching, the response HTTP headers are also removed to prevent conflicts with the main call.

Parameters:

targetRef - The target reference with URI variables resolved.

request - The request to handle.

response - The response to update.

rewrite

protected Representation rewrite(Representation initialEntity)

Optionally rewrites the response entity returned in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes. By default, it just returns the initial entity without any modification.

Parameters:

initialEntity - The initial entity returned.

Returns:

The rewritten entity.

rewrite

protected void rewrite(Request initialRequest)

Optionally updates the request sent in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes. By default, it leverages the headersCleaning attribute in order to clean the headers: if set to true, it removes all headers, otherwise it keeps only the extension (or non HTTP standard) headers

Parameters:

initialRequest - The initial request returned.

rewrite

protected void rewrite(Response initialResponse)

Optionally updates the response sent in the MODE_SERVER_INBOUND and MODE_SERVER_OUTBOUND modes. By default, it leverages the headersCleaning attribute in order to clean the headers: if set to true, it removes all headers, otherwise it keeps only the extension (or non HTTP standard) headers

Parameters:

initialResponse - The initial response returned.

rewriteLocation

public void rewriteLocation(Request request,
                            Response response)

Rewrite the location of the response, and the Location of the entity, if any.

Parameters:

request - The request to handle.

response - The response to update.

serverRedirect

protected void serverRedirect(Restlet next,
                              Reference targetRef,
                              Request request,
                              Response response)

Redirects a given call on the server-side to a next Restlet with a given target reference. In the default implementation, the request HTTP headers, stored in the request's attributes, are removed before dispatching. After dispatching, the response HTTP headers are also removed to prevent conflicts with the main call.

Parameters:

next - The next Restlet to forward the call to.

targetRef - The target reference with URI variables resolved.

request - The request to handle.

response - The response to update.

setHeadersCleaning

public void setHeadersCleaning(boolean headersCleaning)

Indicates if the headers must be cleaned.

Parameters:

headersCleaning - True if the headers must be cleaned.

setMode

public void setMode(int mode)

Sets the redirection mode.

Parameters:

mode - The redirection mode.

setTargetTemplate

public void setTargetTemplate(java.lang.String targetTemplate)

Sets the target URI pattern.

Parameters:

targetTemplate - The target URI pattern.