JAX-RS Application on the root context – how can it be done?

by

It’s probably not so much a bug as a limitation of the Servlet spec. The details of how a JAX-RS @ApplicationPath is handled is implementation specific, and I can’t speak for all implementations, but I’d guess the typical approach is to simply use it as a servlet URL pattern. Taking a look at Jersey’s ServletContainerInitializer implementation as one example, you’ll find that the addServletWithApplication() method is responsible for creating the servlet and mapping to handle requests, and you can see that it does, indeed, use the path from the @ApplicationPath as the Jersey ServletContainer’s mapped path.

Unfortunately, since time immemorial, the Servlet spec has allowed only a small handful of ways of mapping servlets to URL paths. The current options with Servlet 3.0, given in Section 12.2 of the spec–sadly only available as a PDF, so not linkable by section–are:

  • /.../* where the initial /... is zero or more path elements
  • *.<ext> where <ext> is some extension to match
  • the empty string, which maps only to the empty path/context root
  • /, the single slash, which indicates the “default” servlet in the context, which handles anything that doesn’t match anything else
  • any other string, which is treated as a literal value to match

The same section of the spec also has specific rules for the order in which the matching rules should apply, but the short version is this: to make your resource class answer requests at the context root, you have to use either / or /* as the path. If you use /, then you’re replacing the container’s default servlet, which would normally be responsible for handling static resources. If you use /*, then you’re making it too greedy and saying it should match everything all the time, and the default servlet will never be invoked.

So if we accept that we’re inside the box determined by the limitations of servlet URL patterns, our options are fairly limited. Here are the ones I can think of:

1) Use @ApplicationPath("https://stackoverflow.com/"), and explicitly map your static resources by name or by extension to the container’s default servlet (named “default” in Tomcat and Jetty, not sure about others). In a web.xml, it would look like

<!-- All html files at any path -->
<servlet-mapping>   
    <servlet-name>default</servlet-name>
    <url-pattern>*.html</url-pattern>
</servlet-mapping>
<!-- Specifically index.html at the root -->
<servlet-mapping>   
    <servlet-name>default</servlet-name>
    <url-pattern>/index.html</url-pattern>
</servlet-mapping>

or with a ServletContextInitializer, like

public class MyInitializer implements ServletContainerInitializer {
    public void onStartup(Set<Class<?>> c, ServletContext ctx) {
        ctx.getServletRegistration("default").addMapping("*.html");
        ctx.getServletRegistration("default").addMapping("/index.html");
    }
}

Because of the way the matching rules are written, an extension pattern wins over the default servlet, so you’d only need to add a mapping per static file extension as long as there’s no overlap between those and any “extensions” that might occur in your API. This is pretty close to the undesirable option mentioned in the forum post you linked, and I just mention it for completeness and to add the ServletContextInitializer part.

2) Leave your API mapped to /rest/*, and use a Filter to identify requests for the API and forward them to that path. This way, you break out of the servlet URL pattern box and can match URLs any way you want. For example, assuming that all your REST calls are to paths that either begin with “/foo” or are exactly “/bar” and all other requests should go to static resources, then something like:

import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.regex.Pattern;

@WebFilter(urlPatterns = "/*")
public class PathingFilter implements Filter {
    Pattern[] restPatterns = new Pattern[] {
            Pattern.compile("/foo.*"),
            Pattern.compile("/bar"),
    };

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
            FilterChain chain) throws IOException, ServletException {
        if (request instanceof HttpServletRequest) {
            String path = ((HttpServletRequest) request).getServletPath();
            for (Pattern pattern : restPatterns) {
                if (pattern.matcher(path).matches()) {
                    String newPath = "/rest/" + path;
                    request.getRequestDispatcher(newPath)
                        .forward(request, response);
                    return;
                }
            }
        }
        chain.doFilter(request, response);
    }

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {}

    @Override
    public void destroy() {}
}

With the above, you essentially translate requests as follows:

http://example.org/foo          -> http://example.org/rest/foo
http://example.org/foox         -> http://example.org/rest/foox
http://example.org/foo/anything -> http://example.org/rest/foo/anything
http://example.org/bar          -> http://example.org/rest/bar
http://example.org/bart         -> http://example.org/bart
http://example.org/index.html   -> http://example.org/index.html

3) Realize that the previous option is basically URL rewriting and use an existing implementation, such as Apache’s mod_rewrite, the Tuckey rewrite filter, or ocpsoft Rewrite.

Leave a Comment

tech