1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<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-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="annotations.html" title="Chapter 12. Annotations"><link rel="prev" href="annotations.html" title="Chapter 12. 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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.2.11-SNAPSHOT</span></td><td style="width: 50%"><script type="text/javascript"> (function() {
var cx = '016459005284625897022:obd4lsai2ds';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script><gcse:search></gcse:search></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="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Chapter 12. Annotations<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="using-annotations-embedded.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
</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><dt><span class="section"><a href="using-annotations.html#d0e10971">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 Jars Are Scanned For Discovered Annotations</a></span></dt><dt><span class="section"><a href="using-annotations.html#d0e11123">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="d0e10971"></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" type="disc"><li class="listitem"><p>@Resource</p></li><li class="listitem"><p>@Resources</p></li><li class="listitem"><p>@PostConstruct</p></li><li class="listitem"><p>@PreDestroy</p></li><li class="listitem"><p>@DeclaredRoles</p></li><li class="listitem"><p>@RunAs</p></li><li class="listitem"><p>@MultipartConfig</p></li><li class="listitem"><p>@WebServlet</p></li><li class="listitem"><p>@WebFilter</p></li><li class="listitem"><p>@WebListener</p></li><li class="listitem"><p>@WebInitParam</p></li><li class="listitem"><p>@ServletSecurity, @HttpConstraint, @HttpMethodConstraint</p></li><li class="listitem"><p>@HandlesTypes (on ServletContainerInitializers)</p></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 classes, not
necessarily just those with which the container interacts directly. We
call these type of annotations "discovered" to indicate that the container
must take proactive action to go out and find them. The other type of
annotation we call "introspected", meaning that they occur on classes with
which the container interacts during their lifecycle (eg
javax.servlet.Servlet, javax.servlet.Filter etc), and hence can be found
by simple inspection of the class at that point.</p><p><a name="discovered_annotations"></a>Some examples of discovered
annotations are:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>@WebServlet</p></li><li class="listitem"><p>@WebFilter</p></li><li class="listitem"><p>@WebListener</p></li></ul></div><p>Some examples of introspected annotations are:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>@PostConstruct</p></li><li class="listitem"><p>@PreDestroy</p></li><li class="listitem"><p>@Resource</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jars-scanned-for-annotations"></a>Which Jars Are Scanned For Discovered Annotations</h3></div></div></div><p>The web.xml file can contain the attribute
<code class="code">metadata-complete</code>. If this is set to <code class="code">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's path or in the webapp's WEB-INF/lib.</p><p>If scanning is to take place - because either
<code class="code">metadata-complete</code> is <code class="code">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's
classpath and the webapp's classpath.</p><p>By default, Jetty will <span class="emphasis"><em>not</em></span> scan any classes
that are on the container's classpath. If you need to cause jars and
classes that are on the container'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">org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</a>
<a class="link" href="quickstart-config-what.html#context_attributes">context attribute</a> to specify a
pattern for jars and directories from the container's classpath to
scan.</p><p>By default, Jetty will scan <span class="emphasis"><em>all </em></span>classes from
<code class="code">WEB-INF/classes</code>, and all jars from <code class="code">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 jars, 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>
<a class="link" href="quickstart-config-what.html#context_attributes">context attribute</a> 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="d0e11123"></a>Multi-threaded Annotation Scanning</h3></div></div></div><p>Since jetty-9.1,<a class="link" href="using-annotations.html#jars-scanned-for-annotations" title="Which Jars 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't want to do it multi-threaded, you can
configure Jetty to revert to single-threaded scanning. You have several
ways to configure this:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>set the <a class="link" href="quickstart-config-what.html#context_attributes">context
attribute</a>
<code class="code">org.eclipse.jetty.annotations.multiThreaded</code> to
<code class="code">false</code></p></li><li class="listitem"><p>set the <a class="link" href="quickstart-config-what.html#server_attributes">Server
attribute</a>
<code class="code">org.eclipse.jetty.annotations.multiThreaded</code> to
<code class="code">false</code></p></li><li class="listitem"><p>set the System property
<code class="code">org.eclipse.jetty.annotations.multiThreaded</code> to
<code class="code">false</code></p></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"><p>set the <a class="link" href="quickstart-config-what.html#context_attributes">context
attribute</a>
<code class="code">org.eclipse.jetty.annotations.maxWait</code></p></li><li class="listitem"><p>set the <a class="link" href="quickstart-config-what.html#server_attributes">Server
attribute</a>
<code class="code">org.eclipse.jetty.annotations.maxWait</code></p></li><li class="listitem"><p>set the System property
<code class="code">org.eclipse.jetty.annotations.maxWait</code></p></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><a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html" target="_top">javax.servlet.ServletContainerInitializers</a>
can exist in: the container's classpath, the webapp's WEB-INF/classes
directory, the webapp's WEB-INF/lib 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 these
ServletContainerInitializers must be called when the webapp starts. Since
jetty-9.1, by default Jetty will call them in the following
order:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>ServletContainerInitializers from the container's
classpath</p></li><li class="listitem"><p>ServletContainerInitializers from WEB-INF/classes</p></li><li class="listitem"><p>ServletContainerInitializers from WEB-INF/lib jars i<span class="emphasis"><em>n
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</p></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 ServletContainerInitializer callbacks.
ServletContainerInitializers derived from a classes dir on the
extraClasspath and jars from an extraClasspath for the webapp are called
in step 2 and 3 respectively.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e11231"></a>Controlling the order of ServletContainerInitializer
invocation</h4></div></div></div><div class="section"><div class="titlepage"></div><p>If you need ServletContainerInitializers called in a specific
order that is different from that outlined above, then you can use the
<a class="link" href="quickstart-config-what.html#context_attributes">context attribute</a>
<code class="code">org.eclipse.jetty.containerInitializerOrder</code>. Set it to a
list of comma separated class names of ServletContainerInitializers in
the order that you want them applied. You may optionally use the
wildcard character "*" <span class="bold"><strong>once</strong></span> in the
list. It will match all ServletContainerInitializers not explicitly
named in the list. Here's 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><script type="syntaxhighlighter" class="brush: java;toolbar: false">
<![CDATA[WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
"org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer, com.acme.Foo.MySCI, *");]]>
</script><p>In this example, we ensure that the
WebSocketServerContainerInitializer is the very first
ServletContainerInitializer that is called, followed by MySCI and then
any other ServletContainerInitializers that were discovered but not
yet called.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e11253"></a>Excluding ServletContainerInitializers</h4></div></div></div><p>By default, as according to the Servlet Specification, all
ServletContainerInitializers that are discovered are invoked (see above
for how to control the invocation order). Sometimes, you may need to
prevent some being called at all.</p><p>In this case, you can define the
<code class="code">org.eclipse.jetty.containerInitializerExclusionPattern</code>
<a class="link" href="quickstart-config-what.html#context_attributes">context attribute</a>. 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'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><p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
<![CDATA[WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
"com.acme.*|com.corp.SlowContainerInitializer");]]>
</script>In
this example we exclude <span class="bold"><strong>all</strong></span>
ServletContainerInitializers in the com.acme package, and the
SlowContainerInitializer.</p><p>It is possible to use exclusion and ordering together to control
ServletContainerInitializer 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="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="annotations.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="using-annotations-embedded.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. Annotations </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top"> 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/jetty-project/jetty-documentation">Contribute to this documentation at
<span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-05-19T01:01:27+00:00)</i></span></div></p><script 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" type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1149868-7']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script></body></html>
|
