Core :: Server 12.0.6 · org.eclipse.jetty.server.handler.TryPathsHandler

Inspired by nginx's try_files functionality.

This handler can be configured with a list of rewrite URI paths. The special token $path represents the current request pathInContext (the portion after the context path).

Typical example of how this handler can be configured is the following:

TryPathsHandler tryPathsHandler = new TryPathsHandler();
tryPathsHandler.setPaths("/maintenance.html", "$path", "/index.php?p=$path");

PathMappingsHandler pathMappingsHandler = new PathMappingsHandler();
tryPathsHandler.setHandler(pathMappingsHandler);

pathMappingsHandler.addMapping(new ServletPathSpec("*.php"), new PHPHandler());
pathMappingsHandler.addMapping(new ServletPathSpec("/"), new ResourceHandler());

For a request such as /context/path/to/resource.ext:

This handler rewrites the request pathInContext to /maintenance.html and forwards the request to the next handler, where it matches the / mapping, hitting the ResourceHandler that serves the file if it exists.
Otherwise, this handler rewrites the request pathInContext to /path/to/resource.ext and forwards the request to the next handler, where it matches the / mapping, hitting the ResourceHandler that serves the file if it exists.
Otherwise, this handler rewrites the request pathInContext to /index.php?p=/path/to/resource.ext and forwards the request to the next handler, where it matches the *.php mapping, hitting the PHPHandler.

The original path and query may be stored as request attributes, under the names specified by setOriginalPathAttribute(String) and setOriginalQueryAttribute(String).

Field Summary

Modifier and Type	Field and Description
private static final Logger	LOG Hides org.eclipse.jetty.server.Handler.Abstract.LOG.
private String	originalPathAttribute
private String	originalQueryAttribute
private List<String>	paths

Constructor Summary

Access	Constructor and Description
public	TryPathsHandler()
public	TryPathsHandler(Handler handler)

Method Summary

Modifier and Type	Method and Description
public String	Returns: the attribute name of the original request path getOriginalPathAttribute() Get the attribute name of the original request path.
public String	Returns: the attribute name of the original request query getOriginalQueryAttribute() Get the attribute name of the original request query.
public List<String>	Returns: the rewrite URI paths getPaths()
public boolean	handle(Request the HTTP request to handle request, Response the HTTP response to handle response, Callback the callback to complete when the handling is complete callback) Overrides org.eclipse.jetty.server.Handler.Wrapper.handle. Implements org.eclipse.jetty.server.Request.Handler.handle. Invoked to handle the passed HTTP request and response.
private String	interpolate(Request request, String value)
public void	setOriginalPathAttribute(String the attribute name of the original request path originalPathAttribute) Sets the request attribute name to use to retrieve the original request path.
public void	setOriginalQueryAttribute(String the attribute name of the original request query originalQueryAttribute) Sets the request attribute name to use to retrieve the original request query.
public void	setPaths(List<String> the rewrite URI paths paths) Sets a list of rewrite URI paths.
private Request	tryPath(Request wrapped, String newPathQuery)

Inherited from org.eclipse.jetty.server.Handler.Wrapper:: getHandler getInvocationType setHandler

Field Detail

LOG	back to summary
private static final Logger LOG Hides org.eclipse.jetty.server.Handler.Abstract.LOG.

originalPathAttribute	back to summary
private String originalPathAttribute

originalQueryAttribute	back to summary
private String originalQueryAttribute

paths	back to summary
private List<String> paths

Constructor Detail

TryPathsHandler	back to summary
public TryPathsHandler()

TryPathsHandler	back to summary
public TryPathsHandler(Handler handler)

Method Detail

getOriginalPathAttribute	back to summary
public String getOriginalPathAttribute() Get the attribute name of the original request path. Returns:String the attribute name of the original request path

getOriginalPathAttribute

back to summary

public String getOriginalPathAttribute()

Get the attribute name of the original request path.

Returns:String: the attribute name of the original request path

getOriginalQueryAttribute	back to summary
public String getOriginalQueryAttribute() Get the attribute name of the original request query. Returns:String the attribute name of the original request query

getOriginalQueryAttribute

back to summary

public String getOriginalQueryAttribute()

Get the attribute name of the original request query.

Returns:String: the attribute name of the original request query

getPaths	back to summary
public List<String> getPaths() Returns:List<String> the rewrite URI paths

handle back to summary

handle	back to summary
public boolean handle(Request request, Response response, Callback callback) throws Exception Overrides org.eclipse.jetty.server.Handler.Wrapper.handle. Implements org.eclipse.jetty.server.Request.Handler.handle. Doc from org.eclipse.jetty.server.Request.Handler.handle. Invoked to handle the passed HTTP request and response. The request is accepted by returning true, then handling must be concluded by completing the passed callback. The handling may be asynchronous, i.e. this method may return true and complete the given callback later, possibly from a different thread. If this method returns false, then the callback must not be invoked and any mutation on the response reversed. Exceptions thrown by this method may be subsequently handled by an error `Request.Handler`, if present, otherwise a default HTTP 500 error is generated and the callback completed while writing the error response. The simplest implementation is: public boolean handle(Request request, Response response, Callback callback) { callback.succeeded(); return true; } A HelloWorld implementation is: public boolean handle(Request request, Response response, Callback callback) { response.write(true, ByteBuffer.wrap("Hello World\n".getBytes(StandardCharsets.UTF_8)), callback); return true; } Parameters request:Request the HTTP request to handle response:Response the HTTP response to handle callback:Callback the callback to complete when the handling is complete Returns:boolean True if and only if the request will be handled, a response generated and the callback eventually called. This may occur within the scope of the call to this method, or asynchronously some time later. If false is returned, then this method must not generate a response, nor complete the callback. Annotations @Override Exceptions Exception: if there is a failure during the handling. Catchers cannot assume that the callback will be called and thus should attempt to complete the request as if a false had been returned.

public boolean handle(Request request, Response response, Callback callback) throws Exception

Overrides org.eclipse.jetty.server.Handler.Wrapper.handle.

Implements org.eclipse.jetty.server.Request.Handler.handle.

Doc from org.eclipse.jetty.server.Request.Handler.handle.

Invoked to handle the passed HTTP request and response.

The request is accepted by returning true, then handling must be concluded by completing the passed callback. The handling may be asynchronous, i.e. this method may return true and complete the given callback later, possibly from a different thread. If this method returns false, then the callback must not be invoked and any mutation on the response reversed.

Exceptions thrown by this method may be subsequently handled by an error Request.Handler, if present, otherwise a default HTTP 500 error is generated and the callback completed while writing the error response.

The simplest implementation is:

public boolean handle(Request request, Response response, Callback callback)
{
    callback.succeeded();
    return true;
}

A HelloWorld implementation is:

public boolean handle(Request request, Response response, Callback callback)
{
    response.write(true, ByteBuffer.wrap("Hello World\n".getBytes(StandardCharsets.UTF_8)), callback);
    return true;
}

Parameters

request:Request: the HTTP request to handle
response:Response: the HTTP response to handle
callback:Callback: the callback to complete when the handling is complete

Returns:boolean

True if and only if the request will be handled, a response generated and the callback eventually called. This may occur within the scope of the call to this method, or asynchronously some time later. If false is returned, then this method must not generate a response, nor complete the callback.

Annotations

@Override

Exceptions

Exception:: if there is a failure during the handling. Catchers cannot assume that the callback will be called and thus should attempt to complete the request as if a false had been returned.

interpolate	back to summary
private String interpolate(Request request, String value)

setOriginalPathAttribute	back to summary
public void setOriginalPathAttribute(String originalPathAttribute) Sets the request attribute name to use to retrieve the original request path. Parameters originalPathAttribute:String the attribute name of the original request path

setOriginalPathAttribute

back to summary

public void setOriginalPathAttribute(String originalPathAttribute)

Sets the request attribute name to use to retrieve the original request path.

Parameters

originalPathAttribute:String: the attribute name of the original request path

setOriginalQueryAttribute	back to summary
public void setOriginalQueryAttribute(String originalQueryAttribute) Sets the request attribute name to use to retrieve the original request query. Parameters originalQueryAttribute:String the attribute name of the original request query

setOriginalQueryAttribute

back to summary

public void setOriginalQueryAttribute(String originalQueryAttribute)

Sets the request attribute name to use to retrieve the original request query.

Parameters

originalQueryAttribute:String: the attribute name of the original request query

setPaths back to summary

setPaths	back to summary
public void setPaths(List<String> paths) Sets a list of rewrite URI paths. The special token `$path` represents the current request `pathInContext` (the portion after the context path). Parameters paths:List<String> the rewrite URI paths

public void setPaths(List<String> paths)

Sets a list of rewrite URI paths.

The special token $path represents the current request pathInContext (the portion after the context path).

Parameters

paths:List<String>: the rewrite URI paths

tryPath	back to summary
private Request tryPath(Request wrapped, String newPathQuery)

public Class TryPathsHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail