RESTful Java with JAX-RS

Transcription

1 RESTful Java with JAX-RS Bill Burke TECHMiSCHE INFORMATIO N SEIBLIOTH EK UNIVERSITATSBiBLIQTHEK HANNOVER O'REILLY Beijing Cambridge Farnham Koln Sebastopol Taipei Tokyo

2 Table of Contents Foreword xiii Preface xv Parti. 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 10 HATEOAS 11 Wrapping Up 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 19 Obtaining Individual Orders, Customers, or Products 20 Creating an Order, Customer, or Product 21 Updating an Order, Customer, or Product 22 Removing an Order, Customer, or Product 23 Cancelling an Order 23 v

3 Wrapping Up 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 Deployment Within a Servlet Container 39 Wrapping Up HTTP Method and URI Matching 43 Binding HTTP Methods 43 HTTP Method Extensions 45 Binding URIs Expressions 46 Matrix Parameters 50 Subresource Locators 50 Full Dynamic Dispatching 52 Wrapping Up JAX-RS Injection 55 The Basics 56 More Than One Path Parameter 56 Scope of Path Parameters 57 PathSegment and Matrix Parameters 57 Programmatic URI Information 59 MatrixParam 60 Programmatic Query Parameter Information 62 Raw Headers 63 Common Functionality 65 Automatic Java Type Conversion 67 Encoded 68 Wrapping Up 69 vi Table of Contents

4 6. JAX-RS Content Handlers 71 Built-in Content Marshalling 71 j avax.ws.rs. core.streamingoutput 71 java.io.inputstream, java.io.reader 72 java.io.file 74 byte[] 74 String, char[] 75 MultivaluedMap<String, String> and Form Input 76 javax.xml.transform.source 76 JAXB 77 Intro to JAXB 77 JAXB JAX-RS Handlers 80 JAXB and JSON 82 JSON and JSON Schema 84 Custom Marshalling 86 MessageBodyWriter 86 MessageBodyReader 91 Life Cycle and Environment 92 Wrapping Up Response Codes, Complex Responses, and Exception Handling 95 Default Response Codes 95 Successful Responses 96 Error Responses 96 Complex Responses 97 Returning Cookies 99 The Status Enum 100 javax.ws.rs.core.genericentity 101 Exception Handling 102 j avax.ws. rs.web ApplicationException 102 Exception Mapping 103 Wrapping Up HTTP Content Negotiation 105 Conneg Explained 105 Preference Ordering 106 Language Negotiation 107 Encoding Negotiation 107 JAX-RS and Conneg 108 Method Dispatching 108 Leveraging Conneg with JAXB 109 Complex Negotiation 109 Negotiation by URI Patterns 114 Table of Contents vii

5 Leveraging Content Negotiation 115 Creating New Media Types 115 Flexible Schemas 116 Wrapping Up HATEOAS 119 HATEOAS and Web Services 120 Atom Links 120 Advantages of Using HATEOAS with Web Services 121 Link Headers Versus Atom Links 124 HATEOAS and JAX-RS 125 Building URIs with UriBuilder 125 Relative URIs with Urilnfo 127 Wrapping Up Scaling JAX-RS Applications 131 Caching 131 HTTP Caching 132 Expires Header 132 Cache-Control 133 Revalidation and Conditional GETs 135 Concurrency 138 JAX-RS and Conditional Updates 139 Wrapping Up Deployment and Integration 141 Deployment 141 The Application Class 142 Deployment Within a. JAX-RS-Unaware Container 143 Deployment Within a JAX-RS-Aware Container 144 Deployment Within Java EE Configuration 145 OlderJava EE Containers 145 Within Java EE 6 Containers 149 EJB Integration 149 Spring Integration 152 Wrapping Up Securing JAX-RS 155 Authentication 156 Basic Authentication 156 Digest Authentication 157 Client Certificate Authentication 158 viii Table of Contents

6 Authorization 159 Authentication and Authorization in JAX-RS 159 Enforcing Encryption 161 Authorization Annotations 162 Programmatic Security 163 Wrapping Up RESTful Java Clients 165 java.net.url 165 Caching 167 Authentication 167 Advantages and Disadvantages 169 Apache HttpClient 170 Authentication 172 Advantages and Disadvantages 173 RESTEasy Client Framework 174 Authentication 176 Advantages and Disadvantages 177 RESTEasy Client Proxies 177 Advantages and Disadvantages 178 Wrapping Up JAX-RS Implementations 179 Jersey 179 Embeddable Jersey 179 Client API 180 WADL 181 Data Formats 182 Model, View, and Controller 183 Component Integration 184 Apache CXF 185 Aggregating Request Parameters into Beans 185 Converting Request Parameters into Custom Types 186 Static Resolution of Subresources 187 Client API 187 Supporting Services Without JAX-RS Annotations 187 Intercepting Requests and Responses 187 Promoting XSLT and XPath As First-Class Citizens 188 Support for Suspended Invocations 188 Support for Multipart Formats 188 Integration with Distributed OSGi RI 188 Support for WADL 188 Component Integration 189 Table of Contents ix

7 JBoss RESTEasy 189 Embedded Container 189 Asynchronous HTTP 190 Interceptor Framework 191 Client "Browser" Cache 192 Server-Side Caching 192 GZIP Compression 192 Data Formats 192 Component Integration 194 Wrapping Up 194 Part II. JAX-RS Workbook 15. Workbook Introduction 197 Installing RESTEasy and the Examples 197 Example Requirements and Structure 199 Code Directory Structure 199 Environment Setup Examples for Chapter Build and Run the Example Program 201 Deconstructing pom.xml 202 Running the Build 206 Examining the Source Code Examples for Chapter Example ex04_l: HTTP Method Extension 211 Build and Run the Example Program 212 The Server Code 212 The Client Code 213 Example with Expressions 214 Build and Run the Example Program 214 The Server Code 214 The Client Code 215 Example ex04_3: Subresource Locators 216 Build and Run the Example Program 216 The Server Code 216 The Client Code Examples for Chapter Example ex05_t. Injecting URI Information 219 The Server Code 219 x Table of Contents

8 The Client Code 222 Build and Run the Example Program 222 Example ex05_2: Forms and Cookies 222 The Server Code 223 Server Configuration 224 Build and Run the Example Program Examples for Chapter Example ex06_l: Using JAXB 227 The Client Code 229 Changes to pom.xml 229 Build and Run the Example Program 230 Example ex06_2: Creating a Content Handler 230 The Content Handler Code 230 The Resource Class 232 The Application Class 232 The Client Code 233 Build and Run the Example Program Examples for Chapter Example ex07_l: ExceptionMapper 235 The Client Code 237 Build and Run the Example Program Examples for Chapter Example ex08_l; Conneg with JAX-RS 239 The Client Code 240 Build and Run the Example Program 241 Example ex08 2: Conneg via URL Patterns 241 The Server Code 241 Build and Run the Example Program Examples for Chapter Example ex09_l: Atom Links 243 The Server Code 244 The Client Code 248 Build and Run the Example Program 248 Example ex09_2: Link Headers 248 The Server Code 249 The Client Code 254 Build and Run the Example Program 257 Table of Contents xi

9 23. Examplesfor Chapter Example exlo_l: Caching and Concurrent Updates 259 The Server Code 259 The Client Code 262 Build and Run the Example Program Examples for Chapter Example exl 1_1: EJB and JAX-RS 265 Project Structure 265 The EJB Project 266 The WAR Project 272 The EAR Project 274 Build and Run the Example Program 277 Example exl 1_2: Spring and JAX-RS 278 Build and Run the Example Program 280 Index 281 xii Table of Contents