Table Of Contentwww.it-ebooks.info
www.it-ebooks.info
SECOND EDITION
RESTful Java with JAX-RS 2.0
Bill Burke
www.it-ebooks.info
RESTful Java with JAX-RS 2.0, Second Edition
by Bill Burke
Copyright © 2014 Bill Burke. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are
also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/
institutional sales department: 800-998-9938 or [email protected].
Editor: Meghan Blanchette Indexer: Ellen Troutman-Zaig
Production Editor: Melanie Yarbrough Cover Designer: Karen Montgomery
Copyeditor: Charles Roumeliotis Interior Designer: David Futato
Proofreader: Rachel Monaghan Illustrator: Rebecca Demarest
November 2013: Second Edition
Revision History for the Second Edition:
2013-11-11: First release
See http://oreilly.com/catalog/errata.csp?isbn=9781449361341 for release details.
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly
Media, Inc. RESTful Java with JAX-RS 2.0, Second Edition, the cover image of an Australian bee-eater, and
related trade dress are trademarks of O’Reilly Media, Inc.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trade‐
mark claim, the designations have been printed in caps or initial caps.
While every precaution has been taken in the preparation of this book, the publisher and author assume no
responsibility for errors or omissions, or for damages resulting from the use of the information contained
herein.
ISBN: 978-1-449-36134-1
[LSI]
www.it-ebooks.info
Table of Contents
Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Part I. REST and the JAX-RS Standard
1. Introduction to REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
REST and the Rebirth of HTTP 4
RESTful Architectural Principles 5
Addressability 6
The Uniform, Constrained Interface 7
Why Is the Uniform Interface Important? 9
Representation-Oriented 10
Communicate Statelessly 11
HATEOAS 11
Wrapping Up 13
2. Designing RESTful Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The Object Model 15
Model the URIs 16
Defining the Data Format 17
Read and Update Format 17
Create Format 19
Assigning HTTP Methods 19
Browsing All Orders, Customers, or Products 20
Obtaining Individual Orders, Customers, or Products 21
Creating an Order, Customer, or Product 21
Updating an Order, Customer, or Product 23
Removing an Order, Customer, or Product 24
Cancelling an Order 24
iii
www.it-ebooks.info
Wrapping Up 26
3. Your First JAX-RS Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Developing a JAX-RS RESTful Service 27
Customer: The Data Class 28
CustomerResource: Our JAX-RS Service 29
JAX-RS and Java Interfaces 35
Inheritance 37
Deploying Our Service 38
Writing a Client 40
Wrapping Up 42
4. HTTP Method and URI Matching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Binding HTTP Methods 43
HTTP Method Extensions 44
@Path 45
Binding URIs 45
@Path Expressions 46
Matrix Parameters 50
Subresource Locators 50
Full Dynamic Dispatching 52
Gotchas in Request Matching 53
Wrapping Up 55
5. JAX-RS Injection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
The Basics 57
@PathParam 58
More Than One Path Parameter 58
Scope of Path Parameters 59
PathSegment and Matrix Parameters 59
Programmatic URI Information 61
@MatrixParam 61
@QueryParam 62
Programmatic Query Parameter Information 63
@FormParam 63
@HeaderParam 64
Raw Headers 64
@CookieParam 65
@BeanParam 67
Common Functionality 68
Automatic Java Type Conversion 68
@DefaultValue 72
iv | Table of Contents
www.it-ebooks.info
@Encoded 72
Wrapping Up 73
6. JAX-RS Content Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Built-in Content Marshalling 75
javax.ws.rs.core.StreamingOutput 75
java.io.InputStream, java.io.Reader 76
java.io.File 78
byte[] 79
String, char[] 79
MultivaluedMap<String, String> and Form Input 80
javax.xml.transform.Source 80
JAXB 81
Intro to JAXB 81
JAXB JAX-RS Handlers 84
JAXB and JSON 87
JSON and JSON Schema 89
Custom Marshalling 91
MessageBodyWriter 91
MessageBodyReader 96
Life Cycle and Environment 97
Wrapping Up 98
7. Server Responses and Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Default Response Codes 99
Successful Responses 100
Error Responses 100
Complex Responses 101
Returning Cookies 104
The Status Enum 105
javax.ws.rs.core.GenericEntity 106
Exception Handling 106
javax.ws.rs.WebApplicationException 107
Exception Mapping 108
Exception Hierarchy 109
Wrapping Up 111
8. JAX-RS Client API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Client Introduction 113
Bootstrapping with ClientBuilder 114
Client and WebTarget 115
Building and Invoking Requests 116
Table of Contents | v
www.it-ebooks.info
Invocation 121
Exception Handling 122
Configuration Scopes 123
Wrapping Up 124
9. HTTP Content Negotiation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Conneg Explained 125
Preference Ordering 126
Language Negotiation 127
Encoding Negotiation 127
JAX-RS and Conneg 128
Method Dispatching 128
Leveraging Conneg with JAXB 129
Complex Negotiation 129
Negotiation by URI Patterns 134
Leveraging Content Negotiation 135
Creating New Media Types 136
Flexible Schemas 136
Wrapping Up 138
10. HATEOAS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
HATEOAS and Web Services 140
Atom Links 140
Advantages of Using HATEOAS with Web Services 141
Link Headers Versus Atom Links 144
HATEOAS and JAX-RS 145
Building URIs with UriBuilder 145
Relative URIs with UriInfo 148
Building Links and Link Headers 152
Writing Link Headers 154
Embedding Links in XML 154
Wrapping Up 155
11. Scaling JAX-RS Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Caching 157
HTTP Caching 158
Expires Header 158
Cache-Control 159
Revalidation and Conditional GETs 161
Concurrency 164
JAX-RS and Conditional Updates 165
vi | Table of Contents
www.it-ebooks.info
Wrapping Up 167
12. Filters and Interceptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Server-Side Filters 169
Server Request Filters 170
Server Response Filters 171
Reader and Writer Interceptors 172
Client-Side Filters 174
Deploying Filters and Interceptors 177
Ordering Filters and Interceptors 177
Per-JAX-RS Method Bindings 179
DynamicFeature 179
Name Bindings 181
DynamicFeature Versus @NameBinding 182
Exception Processing 183
Wrapping Up 183
13. Asynchronous JAX-RS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
AsyncInvoker Client API 185
Using Futures 185
Using Callbacks 189
Futures Versus Callbacks 191
Server Asynchronous Response Processing 191
AsyncResponse API 192
Exception Handling 194
Cancel 195
Status Methods 196
Timeouts 196
Callbacks 197
Use Cases for AsyncResponse 197
Wrapping Up 201
14. Deployment and Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Deployment 203
The Application Class 204
Deployment Within a JAX-RS-Aware Container 205
Deployment Within a JAX-RS-Unaware Container 207
Configuration 208
Basic Configuration 208
EJB Integration 211
Spring Integration 212
Table of Contents | vii
www.it-ebooks.info
Wrapping Up 214
15. Securing JAX-RS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Authentication 216
Basic Authentication 216
Digest Authentication 217
Client Certificate Authentication 219
Authorization 219
Authentication and Authorization in JAX-RS 219
Enforcing Encryption 221
Authorization Annotations 222
Programmatic Security 224
Client Security 225
Verifying the Server 226
OAuth 2.0 226
Signing and Encrypting Message Bodies 228
Digital Signatures 228
Encrypting Representations 232
Wrapping Up 233
16. Alternative Java Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
java.net.URL 235
Caching 237
Authentication 237
Advantages and Disadvantages 239
Apache HttpClient 240
Authentication 242
Advantages and Disadvantages 244
RESTEasy Client Proxies 244
Advantages and Disadvantages 245
Wrapping Up 245
Part II. JAX-RS Workbook
17. Workbook Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Installing RESTEasy and the Examples 249
Example Requirements and Structure 251
Code Directory Structure 251
Environment Setup 251
18. Examples for Chapter 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
viii | Table of Contents
www.it-ebooks.info
