<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Working with Annotations</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="annotations.html" title="Chapter&nbsp;13.&nbsp;Annotations"><link rel="prev" href="annotations.html" title="Chapter&nbsp;13.&nbsp;Annotations"><link rel="next" href="using-annotations-embedded.html" title="Using Annotations with Jetty Embedded"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Working with Annotations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="annotations.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;13.&nbsp;Annotations<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="using-annotations-embedded.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using-annotations"></a>Working with Annotations</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="using-annotations.html#_which_annotations_are_supported">Which Annotations Are Supported</a></span></dt><dt><span class="section"><a href="using-annotations.html#discoverable_introspectable_annotations">Discovered vs Introspected Annotations</a></span></dt><dt><span class="section"><a href="using-annotations.html#jars-scanned-for-annotations">Which Jar Files Are Scanned For Discovered Annotations</a></span></dt><dt><span class="section"><a href="using-annotations.html#_multi_threaded_annotation_scanning">Multi-threaded Annotation Scanning</a></span></dt><dt><span class="section"><a href="using-annotations.html#servlet-container-initializers">ServletContainerInitializers</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_which_annotations_are_supported"></a>Which Annotations Are Supported</h3></div></div></div><p>Jetty supports interpretation and application of the following annotations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">@Resource</li><li class="listitem">@Resources</li><li class="listitem">@PostConstruct</li><li class="listitem">@PreDestroy</li><li class="listitem">@DeclaredRoles</li><li class="listitem">@RunAs</li><li class="listitem">@MultipartConfig</li><li class="listitem">@WebServlet</li><li class="listitem">@WebFilter</li><li class="listitem">@WebListener</li><li class="listitem">@WebInitParam</li><li class="listitem">@ServletSecurity, @HttpConstraint, @HttpMethodConstraint</li><li class="listitem">@HandlesTypes (on ServletContainerInitializers)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="discoverable_introspectable_annotations"></a>Discovered vs Introspected Annotations</h3></div></div></div><p>Some types of annotation can be placed on any class, not necessarily just those with which the container interacts directly.
These type of annotations are referred to as "discovered" to indicate that the container must take proactive action to go out and find them.
The other type of annotation is call "introspected", meaning that they occur on classes with which the container interacts during their lifecycle (e.g. <code class="literal">javax.servlet.Servlet</code>, <code class="literal">javax.servlet.Filter</code>, &#8230;&#8203;etc.), and hence can be found by simple inspection of the class at that point.</p><p>Some examples of discovered annotations are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">@WebServlet</li><li class="listitem">@WebFilter</li><li class="listitem">@WebListener</li></ul></div><p>Some examples of introspected annotations are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">@PostConstruct</li><li class="listitem">@PreDestroy</li><li class="listitem">@Resource</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jars-scanned-for-annotations"></a>Which Jar Files Are Scanned For Discovered Annotations</h3></div></div></div><p>The web.xml file can contain the attribute <code class="literal">metadata-complete</code>.
If this is set to <code class="literal">true</code>, then <span class="emphasis"><em>no</em></span> scanning of discoverable annotations takes place.
However, scanning of classes may <span class="emphasis"><em>still</em></span> occur because of <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html" target="_top">javax.servlet.ServletContainerInitializer</a>s.
Classes implementing this interface are found by Jetty using the <a class="link" href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html" target="_top">javax.util.ServiceLoader</a> mechanism, and if one is present <span class="emphasis"><em>and</em></span> it includes the @HandlesTypes annotation, then Jetty must scan the class hierarchy of the web application.
This may be very time-consuming if you have many jars in the container&#8217;s path or in the webapp&#8217;s WEB-INF/lib.</p><p>If scanning is to take place - because either <code class="literal">metadata-complete</code> is <code class="literal">false</code> or missing, or because there are one or more <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html" target="_top">javax.servlet.ServletContainerIntializer</a>s with @HandlesTypes - then Jetty must consider both the container&#8217;s classpath and the webapp&#8217;s classpath.</p><p>By default, Jetty will <span class="emphasis"><em>not</em></span> scan any classes that are on the container&#8217;s classpath.
If you need to cause jars and classes that are on the container&#8217;s classpath to be scanned, then you can use the <a class="link" href="configuring-webapps.html#container-include-jar-pattern" title="org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern"><code class="literal">org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</code></a> context attribute to specify a pattern for jars and directories from the container&#8217;s classpath to scan.</p><p>By default Jetty will scan <span class="emphasis"><em>all</em></span>classes from <code class="literal">WEB-INF/classes</code> and all jars from <code class="literal">WEB-INF/lib</code> according to the order, if any, established by absolute or relative ordering clauses in web.xml.
If your webapp contains many jar files, you can significantly speed up deployment by omitting them from scanning.
To do this, use the <a class="link" href="configuring-webapps.html#web-inf-include-jar-pattern" title="org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern">org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern</a> context attribute to define the patterns of jars that you specifically want to be scanned.</p><p>Note that if you have configured an <a class="link" href="jetty-classloading.html#using-extra-classpath-method" title="Using the extraClasspath() method">extraClasspath</a> for the webapp, then it participates in the scanning process too.
Any classes dirs are treated the same for scanning purposes as if they were in WEB-INF/classes and jars are treated as if they were in WEB-INF/lib.</p><p>See also the next section on <a class="link" href="using-annotations.html#servlet-container-initializers" title="ServletContainerInitializers">ServletContainerInitializers</a> if you need to <a class="link" href="using-annotations.html#servlet-container-initializers" title="ServletContainerInitializers">control the order in which they are applied</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_multi_threaded_annotation_scanning"></a>Multi-threaded Annotation Scanning</h3></div></div></div><p><a class="link" href="using-annotations.html#jars-scanned-for-annotations" title="Which Jar Files Are Scanned For Discovered Annotations">If annotation scanning is to be performed</a>, by default Jetty will do it in a multi-threaded manner in order to complete it in the minimum amount of time.</p><p>If for some reason you don&#8217;t want multi-threaded scanning, you can configure Jetty to revert to single-threaded scanning.
There are several ways to configure this:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Set the context attribute <code class="literal">org.eclipse.jetty.annotations.multiThreaded</code> to <code class="literal">false</code></li><li class="listitem">Set the Server attribute <code class="literal">org.eclipse.jetty.annotations.multiThreaded</code> to <code class="literal">false</code></li><li class="listitem">Set the System property <code class="literal">org.eclipse.jetty.annotations.multiThreaded</code> to <code class="literal">false</code></li></ol></div><p>Method 1 will only affect the current webapp.
Method 2 will affect all webapps deployed to the same Server instance.
Method 3 will affect all webapps deployed in the same JVM.</p><p>By default, Jetty will wait a maximum of 60 seconds for all of the scanning threads to complete.
You can set this to a higher or lower number of seconds by doing one of the following:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Set the context attribute <code class="literal">org.eclipse.jetty.annotations.maxWait</code></li><li class="listitem">Set the Server attribute <code class="literal">org.eclipse.jetty.annotations.maxWait</code></li><li class="listitem">Set the System property <code class="literal">org.eclipse.jetty.annotations.maxWait</code></li></ol></div><p>Method 1 will only affect the current webapp.
Method 2 will affect all webapps deployed to the same Server instance.
Method 3 will affect all webapps deployed in the same JVM.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="servlet-container-initializers"></a>ServletContainerInitializers</h3></div></div></div><p>The <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html" target="_top">javax.servlet.ServletContainerInitializer</a> class can exist in: the container&#8217;s classpath, the webapp&#8217;s <code class="literal">WEB-INF/classes</code> directory, the webapp&#8217;s <code class="literal">WEB-INF/lib</code> jars, or any external <a class="link" href="jetty-classloading.html#using-extra-classpath-method" title="Using the extraClasspath() method">extraClasspath</a> that you have configured on the webapp.</p><p>The <a class="link" href="http://jcp.org/aboutJava/communityprocess/final/jsr340/" target="_top">Servlet Specification</a> does not define any order in which a <code class="literal">ServletContainerInitializer</code> must be called when the webapp starts.
By default Jetty will call them in the following order:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">ServletContainerInitializers from the container&#8217;s classpath</li><li class="listitem">ServletContainerInitializers from WEB-INF/classes</li><li class="listitem">ServletContainerInitializers from WEB-INF/lib jars <span class="emphasis"><em>in the order established in web.xml</em></span>, or in the order that the SCI is returned by the <a class="link" href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html" target="_top">javax.util.ServiceLoader</a> if there is <span class="emphasis"><em>no</em></span> ordering</li></ol></div><p>As is the case with annotation scanning, the <a class="link" href="jetty-classloading.html#using-extra-classpath-method" title="Using the extraClasspath() method">extraClasspath</a> is fully considered for <code class="literal">ServletContainerInitializer</code> callbacks. <code class="literal">ServletContainerInitializer</code> derived from a classes directory on the <code class="literal">extraClasspath</code> and jars from an <code class="literal">extraClasspath</code> for the webapp are called in step 2 and 3, respectively.</p><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>As of Jetty-9.4.4, unless the <code class="literal">web.xml</code> is version 3.0 or greater, only <code class="literal">ServletContainerInitializers</code> that are on the container classpath will be discovered.
Users wishing to use <code class="literal">ServletContainerInitializers</code> from within the webapp with older versions of <code class="literal">web.xml</code> must either upgrade their <code class="literal">web.xml</code> version, or call <code class="literal">WebAppContext.setConfigurationDiscovered(true)</code> either programmatically or in xml.
Upgrading the <code class="literal">web.xml</code> version is preferable.</p></div></blockquote></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_controlling_the_order_of_servletcontainerinitializer_invocation"></a>Controlling the order of ServletContainerInitializer invocation</h4></div></div></div><p>If you need <code class="literal">ServletContainerInitializer</code> classes called in a specific order that is different from that outlined above, you can use the context attribute <code class="literal">org.eclipse.jetty.containerInitializerOrder</code>.
Set them to a list of comma separated class names of <code class="literal">ServletContainerInitializers</code> in the order that you want them applied.
You may optionally use the wildcard character "<span class="strong"><strong>" *once</strong></span> in the list.
It will match all <code class="literal">ServletContainerInitializer</code> classed not explicitly named in the list.</p><p>Here is an example, setting the context attribute in code (although you can also do the <a class="link" href="quickstart-config-what.html#intro-jetty-configuration-webapps" title="Configuring Web Applications">same in xml</a>):</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
                     "org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer, com.acme.Foo.MySCI, *");</code></pre><p>In this example, we ensure that the <code class="literal">WebSocketServerContainerInitializer</code> is the very first <code class="literal">ServletContainerInitializer</code> that is called, followed by MySCI and then any other <code class="literal">ServletContainerInitializer</code> instances that were discovered but not yet called.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="excluding-scis"></a>Excluding ServletContainerInitializers</h4></div></div></div><p>By default, as according to the Servlet Specification, all <code class="literal">ServletContainerInitializer</code> that are discovered are invoked (see above for how to control the invocation order).
Sometimes, depending on your requirements, you may need to prevent some being called at all.</p><p>In this case, you can define the <code class="literal">org.eclipse.jetty.containerInitializerExclusionPattern</code> context attribute.
This is a regular expression that defines <a class="link" href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html" target="_top">patterns</a> of classnames that you want to exclude.
Here&#8217;s an example, setting the context attribute in code, although you may do exactly the <a class="link" href="quickstart-config-what.html#intro-jetty-configuration-webapps" title="Configuring Web Applications">same in xml</a>:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
                     "com.acme.*|com.corp.SlowContainerInitializer");</code></pre><p>In this example we exclude <span class="strong"><strong>all</strong></span> <code class="literal">ServletContainerInitializer</code> instances in the com.acme package, and the <code class="literal">SlowContainerInitializer</code>.</p><p>It is possible to use exclusion and ordering together to control <code class="literal">ServletContainerInitializer</code> invocation - the exclusions will be applied before the ordering.</p></div></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="annotations.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="annotations.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="using-annotations-embedded.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;13.&nbsp;Annotations&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Using Annotations with Jetty Embedded</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html>