Embedded tomcat 7 servlet 3.0 annotations not working

Question

I have a stripped down test project which contains a Servlet version 3.0, declared with annotations like so:

    @WebServlet("/test")
public class TestServlet extends HttpServlet {

    private static final long serialVersionUID = -3010230838088656008L;

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException{
        response.getWriter().write("Test");
        response.getWriter().flush();
        response.getWriter().close();
    }
}

I also have a web.xml file like so:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">

      <servlet>
        <servlet-name>testServlet</servlet-name>
        <servlet-class>g1.TestServlet</servlet-class>
      </servlet>      

      <servlet-mapping>
        <servlet-name>testServlet</servlet-name>
        <url-pattern>/testWebXml</url-pattern>
      </servlet-mapping>

</web-app> 

I've tried to make a JUnit test using Embedded Tomcat 7. When I start the Embedded Tomcat I can only access the servlet via the url-pattern declared in web.xml (/testWebXml). If I try to access it via the url-pattern declared via annotation (/test) it sais 404 page not found.

Here's the code for my test:

    String webappDirLocation = "src/main/webapp/";
    Tomcat tomcat = new Tomcat();
    tomcat.setPort(8080);

    tomcat.addWebapp("/jerseyTest", new File(webappDirLocation).getAbsolutePath());

    tomcat.start();
    tomcat.getServer().await();

Just to make sure I've set up my project correctly, I've also installed an actual Tomcat 7 and deployed the war. This time, both web.xml declared url and annotation url for my servlet work ok.

So my question is: does anyone know how to make Embedded Tomcat 7 take into account my Servlet 3.0 annotations?

I should also state that it's a Maven project, and the pom.xml contains the following dependencies:

    <dependency>
        <groupId>org.apache.tomcat</groupId>
        <artifactId>tomcat-catalina</artifactId>
        <version>7.0.29</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.tomcat.embed</groupId>
        <artifactId>tomcat-embed-core</artifactId>
        <version>7.0.29</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.tomcat</groupId>
        <artifactId>tomcat-jasper</artifactId>
        <version>7.0.29</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.8.1</version>
        <scope>test</scope>
    </dependency>

== UPDATE ==

Here's an issue that seems similar to this (except the Servlet 3.0 annotation that is not working is on Listener, not Servlet), which has a suggested fix:

https://issues.apache.org/bugzilla/show_bug.cgi?id=53903

I've tried it and it didn't work:

Changed the Embedded Tomcat start code to:

String webappDirLocation = "src/main/webapp/";
Tomcat tomcat = new Tomcat();

tomcat.enableNaming();
tomcat.setPort(8080);


Context ctx = tomcat.addWebapp(tomcat.getHost(), "/embeddedTomcat", new File(webappDirLocation).getAbsolutePath());
((StandardJarScanner) ctx.getJarScanner()).setScanAllDirectories(true);

tomcat.start();

tomcat.getServer().await();

Other things I've tried, also without success:

• specifically setting metadata-complete="false" in web.xml "web-app" tag

• updating the Maven dependencies to version 7.0.30

• debugging the org.apache.catalina.startup.ContextConfig class. There's code there that checks for @WebServlet annotations, it's just that it never gets executed (line 2115). This may be a good way to get to the root of the issue, but the class is pretty big, and I don't have time to do this now. Maybe if someone would be willing to look how this class works, and under which conditions (config params) does it get to correctly check your project's classes for that annotation, it might get to a valid answer.

Solution 1

Well I finally solved it by looking in the Tomcat7 sources, namely in the unit tests that deal with EmbeddedTomcat and servlet 3.0 annotations.

Basically, you must start your Embedded Tomcat 7 like this to make it aware of your annotated classes:

String webappDirLocation = "src/main/webapp/";
Tomcat tomcat = new Tomcat();
tomcat.setPort(8080);

StandardContext ctx = (StandardContext) tomcat.addWebapp("/embeddedTomcat",
                new File(webappDirLocation).getAbsolutePath());

//declare an alternate location for your "WEB-INF/classes" dir:     
File additionWebInfClasses = new File("target/classes");
VirtualDirContext resources = new VirtualDirContext();
resources.setExtraResourcePaths("/WEB-INF/classes=" + additionWebInfClasses);
ctx.setResources(resources);

tomcat.start();
tomcat.getServer().await();

For the sake of clarity I should mention that this works for a standard Maven project where your "web resources" (such as static and dynamic pages, WEB-INF directory etc) are found in:

[your project's root dir]/src/main/webapp

and your classes get compiled into

[your project's root dir]/target/classes

(such that you'd have [your project's root dir]/target/classes/[some package]/SomeCompiledServletClass.class)

For other directories layouts, these locations need to be changed accordingly.

==== UPDATE: Embedded Tomcat 8 ====

Thanks to @kwak for noticing this.

The APIs have changed a bit, here how the above example changes when using Embedded Tomcat 8:

String webappDirLocation = "src/main/webapp/";
Tomcat tomcat = new Tomcat();
tomcat.setPort(8080);

StandardContext ctx = (StandardContext) tomcat.addWebapp("/embeddedTomcat",
                new File(webappDirLocation).getAbsolutePath());

//declare an alternate location for your "WEB-INF/classes" dir:     
File additionWebInfClasses = new File("target/classes");
WebResourceRoot resources = new StandardRoot(ctx);
resources.addPreResources(new DirResourceSet(resources, "/WEB-INF/classes", additionWebInfClasses.getAbsolutePath(), "/"));
ctx.setResources(resources);

tomcat.start();
tomcat.getServer().await();

Solution 2

    Tomcat tomcat = new Tomcat();
    tomcat.setPort(port);

    Context ctx = tomcat.addWebapp("/", new File(docBase).getAbsolutePath());
    StandardJarScanner scan = (StandardJarScanner) ctx.getJarScanner();
    scan.setScanClassPath(true);
    scan.setScanBootstrapClassPath(true); // just guessing here
    scan.setScanAllDirectories(true);
    scan.setScanAllFiles(true);

    tomcat.start();
    tomcat.getServer().await();

it works well for me using Tomcat Embed 7.0.90 from MVN

Comments

[Steve Perkins]

I too haven't been able to get a Servlet 3.0 (annotation-based) app working in embedded Tomcat 7. Works fine when I drop down to Servlet 2.5, and put my servlet in web.xml. I first tried using embedded Jetty 8... but after banging my head against a wall for a full day, I discovered that Servlet 3 annotations are only available when you use the "hightide" Jetty variant (which I couldn't get to work in embedded mode either).

[Steve Perkins]

Embedded Tomcat documentation is virtually non-existent. The Eclipse people have pretty-looking documentation for Jetty, but it is full of huge gaps (e.g. what is "hightide" and when to use it, how to embed version 8 with JSP support and annotation-based servlet config, etc). It feels like there is some fundamental piece of the puzzle missing for all of this stuff... I'm not sure that anyone IS using Servlet 3.0 with any of these embedded servlet engines right now.

[Steve Perkins]

Just a note on Shivan's example above... the issue is not that he is blending annotation-based config with web.xml-based config. Even when you remove the servlet and servlet mapping from web.xml, the annotation-declared mapping by itself still doesn't work either.

[Steve Perkins]

Interestingly enough, I HAVE gotten annotation-based Servlet 3.0 applications running in embedded Jetty 8 via the Maven Jetty plugin. So there must be SOME possible route to making all this work. However, that scenario is only running the server within a Maven build script... it isn't the same thing as programmatically embedding a Tomcat or Jetty instance inside an application and shipping it standalone.

[Shivan Dragon]

@StevePerkins: thanks for the input, however the idea here was to avoid Jetty and use Tomcat.

[jesse mcconnell]

"I discovered that Servlet 3 annotations are only available when you use the "hightide" Jetty variant (which I couldn't get to work in embedded mode either)." - this is not accurate, regardless if the goal is to not use jetty then the jetty tag ought to be removed, it is only mentioned in comments anyway

[Shivan Dragon]

@jessemcconnell I'm very sorry, I never ment to add that tag. Removed now.

[Vadzim]

See also @WebServlet annotation doesn't work with Tomcat 8

[Shivan Dragon]

You were on the right track, the "WEB-INF/classes" dir needed to be "aliased" somehow before starting Tomcat, however it wasn't very intuitive, I had to look up their unit tests to figure it out.

[caub]

VirtualDirContext is no longer in tomcat8 embedded

[Shivan Dragon]

@kwak thanks for noticing. Updated my answer to include tomcat8

[Benny Neugebauer]

@ShivanDragon - Thank you very much for your detailed solution! I just tested your solution on my embedded Tomcat 8.0.12 and it just works! Thank you so much! It saved me so many hours! +1

[Magno C]

This will work too: ((StandardJarScanner) ctx.getJarScanner()).setScanAllDirectories(true);

[Ace.Yin]

((StandardJarScanner) ctx.getJarScanner()).setScanAllDirectories(true); is really useful . one more comments: if the classes annotated by @WebFilter @WebServlet is packaged in a jar file, this line should be added into the embedded tomcat server class: DirResourceSet lib = DirResourceSet(this, "/WEB-INF/lib", Dir.LIBS.fullPath(), "/"); resources.addJarResources(lib);

[Michael]

@Ace.Yin what is "Dir.LIBS.fullPath()"...where is "Dir" coming from, do you have a fully qualified name of "Dir"? can only guess you have that statically imported...

[Michael]

Does someone have a full example on how to make tomcat read annotations when ran from within a local project and when running as a fatjar? This answer only appears to cover running from your local project.

[Ace.Yin]

@Michael, the Dir.LIBS.fullPath() is a static method which can get the full path where the app starts from. so you can use some path like "/your/application/absolute/path/where/your/jars/put". here are some example codes (in kotlin): val res = StandardRoot(ctx); res.addPreResources(DirResourceSet(res, "/WEB-INF/classes", "/usr/local/deployment/my-app/classes", "/")); res.addJarResources(DirResourceSet(res, "/WEB-INF/lib", /usr/local/deployment/my-app/libs", "/"));

[Michael]

@Ace.Yin can you provide the fully qualified name of the "Dir" class? That can't be resolved, which jar is it in? Or is it a class you have written?

[Ace.Yin]

@Michael, it's a class written by me, it just like a helper class, i use it to get the full path of "lib", "classes" directory.

[personal_cloud]

I have found that sometimes this solution works, but other times it leads to a mysterious exception

[user207421]

This solution will only work if the application as deployed is misconfigured so as to contain the target directory.