/
ExceptionMappers.xml
168 lines (154 loc) · 5.85 KB
/
ExceptionMappers.xml
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="ExceptionHandling">
<title>Exception Handling</title>
<sect1 id="ExceptionMappers">
<title>Exception Mappers</title>
<para>
ExceptionMappers are custom, application provided, components that can catch thrown application exceptions and
write specific HTTP responses. The are classes annotated with @Provider and that implement this interface
</para>
<para>
<programlisting>
package javax.ws.rs.ext;
import javax.ws.rs.core.Response;
/**
* Contract for a provider that maps Java exceptions to
* {@link javax.ws.rs.core.Response}. An implementation of this interface must
* be annotated with {@link Provider}.
*
* @see Provider
* @see javax.ws.rs.core.Response
*/
public interface ExceptionMapper<E>
{
/**
* Map an exception to a {@link javax.ws.rs.core.Response}.
*
* @param exception the exception to map to a response
* @return a response mapped from the supplied exception
*/
Response toResponse(E exception);
}
</programlisting>
</para>
<para>
When an application exception is thrown it will be caught by the JAX-RS runtime. JAX-RS will then scan registered
ExceptionMappers to see which one support marshalling the exception type thrown. Here is an example of
ExceptionMapper
</para>
<para>
<programlisting>
@Provider
public class EJBExceptionMapper implements ExceptionMapper<javax.ejb.EJBException>
{
Response toResponse(EJBException exception) {
return Response.status(500).build();
}
}
</programlisting>
</para>
<para>
You register ExceptionMappers the same way you do MessageBodyReader/Writers. By scanning, through the resteasy
provider context-param (if you're deploying via a WAR file), or programmatically through the
ResteasyProviderFactory class.
</para>
<para>
</para>
</sect1>
<sect1 id="builtinException">
<title>Resteasy Built-in Internally-Thrown Exceptions</title>
<para>Resteasy has a set of built-in exceptions that are thrown by it when it encounters errors during dispatching or marshalling. They all
revolve around specific HTTP error codes. You can find them in RESTEasy's javadoc under the package org.jboss.resteasy.spi. Here's
a list of them:</para>
<table frame="topbot">
<tgroup cols="3" rowsep="1" colsep="1">
<thead>
<row>
<entry>Exception</entry>
<entry>HTTP Code</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>BadRequestException</entry>
<entry>400</entry>
<entry>Bad Request. Request wasn't formatted correctly or problem processing request input.</entry>
</row>
<row>
<entry>UnauthorizedException</entry>
<entry>401</entry>
<entry>Unauthorized. Security exception thrown if you're using Resteasy's simple annotation-based role-based security</entry>
</row>
<row>
<entry>InternalServerErrorException</entry>
<entry>500</entry>
<entry>Internal Server Error.</entry>
</row>
<row>
<entry>MethodNotAllowedException</entry>
<entry>405</entry>
<entry>Method Not Allowed. There is no JAX-RS method for the resource that can handle the invoked HTTP operation.</entry>
</row>
<row>
<entry>NotAcceptableException</entry>
<entry>406</entry>
<entry>Not Acceptable. There is no JAX-RS method that can produce the media types listed in the Accept header.</entry>
</row>
<row>
<entry>NotFoundException</entry>
<entry>404</entry>
<entry>Not Found. There is no JAX-RS method that serves the request path/resource.</entry>
</row>
<row>
<entry>ReaderException</entry>
<entry>400</entry>
<entry>All exceptions thrown from MessageBodyReaders are wrapped within this exception. If there is no ExceptionMapper for the
wrapped exception or if the exception isn't a WebApplicationException, then resteasy will return a 400 code by default.</entry>
</row>
<row>
<entry>WriterException</entry>
<entry>500</entry>
<entry>All exceptions thrown from MessageBodyWriters are wrapped within this exception. If there is no ExceptionMapper for the
wrapped exception or if the exception isn't a WebApplicationException, then resteasy will return a 400 code by default.</entry>
</row>
<row>
<entry>o.j.r.plugins.providers.jaxb.JAXBUnmarshalException</entry>
<entry>400</entry>
<entry>The JAXB providers (XML and Jettison) throw this exception on reads. They may be wrapping JAXBExceptions. This class extends ReaderException</entry>
</row>
<row>
<entry>o.j.r.plugins.providers.jaxb.JAXBMarshalException</entry>
<entry>500</entry>
<entry>The JAXB providers (XML and Jettison) throw this exception on writes. They may be wrapping JAXBExceptions. This class extends WriterException</entry>
</row>
<row>
<entry>ApplicationException</entry>
<entry>N/A</entry>
<entry>This exception wraps all exceptions thrown from application code. It functions much in the same way as InvocationTargetException.
If there is an ExceptionMapper for wrapped exception, then that is used to handle the request.</entry>
</row>
<row>
<entry>Failure</entry>
<entry>N/A</entry>
<entry>Internal Resteasy. Not logged</entry>
</row>
<row>
<entry>LoggableFailure</entry>
<entry>N/A</entry>
<entry>Internal Resteasy error. Logged</entry>
</row>
<row>
<entry>DefaultOptionsMethodException</entry>
<entry>N/A</entry>
<entry>If the user invokes HTTP OPTIONS and no JAX-RS method for it, Resteasy provides a default behavior by throwing this exception</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="overring_resteasy_exceptions">
<title>Overriding Resteasy Builtin Exceptions</title>
<para>You may override Resteasy built-in exceptions by writing an ExceptionMapper for the exception. For that matter, you can write an ExceptionMapper
for any thrown exception including WebApplicationException</para>
</sect1>
</chapter>