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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<chapter id="CDI">
<title>CDI Integration</title>
<para>This module provides integration with JSR-299 (Contexts and
Dependency Injection for the Java EE platform)
</para>
<section>
<title>Using CDI beans as JAX-RS components</title>
<para>
Both the JAX-RS and CDI specifications introduce their own
component
model. On the one hand, every class placed in a CDI archive that
fulfills a set of basic constraints is implicitly a CDI bean. On
the
other hand, explicit decoration of your Java class with
<code>@Path</code>
or
<code>@Provider</code>
is required for it to become a JAX-RS component.
Without the
integration code, annotating a class suitable for being a CDI bean
with
JAX-RS annotations leads into a faulty result (JAX-RS component
not managed by CDI)
The
resteasy-cdi module is a bridge that
allows
RESTEasy
to work with class
instances obtained from the CDI
container.
</para>
<para>
During a
web
service
invocation, resteasy-cdi asks the CDI
container
for the
managed
instance
of a JAX-RS component. Then, this
instance is
passed
to
RESTEasy.
If a
managed instance is not available for
some
reason (the
class is
placed
in a jar which is not a bean deployment
archive),
RESTEasy
falls back to
instantiating the class itself.
</para>
<para>
As a result, CDI services like injection, lifecycle management,
events, decoration and interceptor bindings can be used in JAX-RS
components.
</para>
</section>
<section>
<title>Default scopes</title>
<para>
A CDI bean that does not explicitly define a scope is
<code>@Dependent</code>
scoped by default.
This pseudo scope means that the bean adapts to the
lifecycle of
the bean it is
injected into. Normal scopes (request,
session,
application) are more suitable for JAX-RS components as they
designate component's lifecycle boundaries explicitly. Therefore, the
resteasy-cdi
module alters the default
scoping in
the following way:
</para>
<itemizedlist>
<listitem>
<para>
If a JAX-RS root resource does not define a scope
explicitly,
it is
bound to the Request scope.
</para>
</listitem>
<listitem>
<para>
If a JAX-RS Provider or
<code>javax.ws.rs.Application</code>
subclass
does not define a scope explicitly, it is bound to the
Application
scope.
</para>
</listitem>
</itemizedlist>
<warning>
<para>
Since the scope of all beans that do not declare a scope is
modified by resteasy-cdi, this affects session beans as well. As a
result, a conflict occurs if the scope of a stateless session bean
or singleton is changed automatically as the spec prohibits these
components to
be @RequestScoped.
Therefore, you
need to explicitly
define a scope
when using stateless session
beans or singletons. This
requirement is likely to
be removed in
future releases.
</para>
</warning>
</section>
<section>
<title>Configuration within WildFly</title>
<para>
CDI integration is provided with no additional configuration with WildFly.
</para>
</section>
<section>
<title>Configuration with different distributions</title>
<para>
Provided you have an
existing RESTEasy application, all that needs to
be done is to
add the
resteasy-cdi jar into your project's
<code>WEB-INF/lib</code>
directory.
When using
maven, this can be achieve by defining the
following
dependency.
<programlisting><![CDATA[<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-cdi</artifactId>
<version>${project.version}</version>
</dependency>]]></programlisting>
</para>
<para>
Furthermore, when running a pre-Servlet 3 container, the
following context parameter needs to be specified in web.xml. (This
is done
automatically via web-fragment in a Servlet 3 environment)
</para>
<programlisting language="xml"><![CDATA[<context-param>
<param-name>resteasy.injector.factory</param-name>
<param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
</context-param>]]></programlisting>
<para>
When deploying an application to a Servlet container that does not
support CDI out of the box
(Tomcat, Jetty, Google App Engine), a CDI implementation needs to be
added first.
<ulink
url="http://docs.jboss.org/weld/reference/latest/en-US/html/environments.html">Weld-servlet module
</ulink>
can be used for this purpose.
</para>
</section>
</chapter>
|
