You are previewing RESTful Java with JAX-RS.
O'Reilly logo
RESTful Java with JAX-RS

Book Description

Learn how to design and develop distributed web services in Java using RESTful architectural principals and the JAX-RS specification in Java EE 6. With this hands-on reference, you'll focus on implementation rather than theory, and discover why the RESTful method is far better than technologies like CORBA and SOAP. It's easy to get started with services based on the REST architecture. RESTful Java with JAX-RS includes a technical guide that explains REST and JAX-RS, how they work, and when to use them. With the RESTEasy workbook that follows, you get step-by-step instructions for installing, configuring, and running several working JAX-RS examples using the JBoss RESTEasy implementation of JAX-RS.

  • Work on the design of a distributed RESTful interface, and develop it in Java as a JAX-RS service

  • Dispatch HTTP requests in JAX-RS, and learn how to extract information from them

  • Deploy your web services within Java Enterprise Edition using the Application class, Default Component Model, EJB Integration, Spring Integration, and JPA

  • Discover several options for securing your web services

  • Learn how to implement RESTful design patterns using JAX-RS

  • Write RESTful clients in Java using libraries and frameworks such as java.net.URL, Apache HTTP Client, and RESTEasy Proxy

Table of Contents

  1. RESTful Java with JAX-RS
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. Foreword
    3. Preface
      1. Author’s Note
      2. Who Should Read This Book
      3. How This Book Is Organized
        1. Part I REST and the JAX-RS Standard
        2. Part IIJAX-RS Workbook
      4. Conventions Used in This Book
      5. Using Code Examples
      6. We’d Like to Hear from You
      7. Safari® Books Online
      8. Acknowledgments
    4. I. REST and the JAX-RS Standard
      1. 1. Introduction to REST
        1. REST and the Rebirth of HTTP
        2. RESTful Architectural Principles
          1. Addressability
          2. The Uniform, Constrained Interface
          3. Why Is the Uniform Interface Important?
          4. Representation-Oriented
          5. Communicate Statelessly
          6. HATEOAS
            1. The engine of application state
        3. Wrapping Up
      2. 2. Designing RESTful Services
        1. The Object Model
        2. Model the URIs
        3. Defining the Data Format
          1. Read and Update Format
            1. Common link element
            2. The details
          2. Create Format
        4. Assigning HTTP Methods
          1. Browsing All Orders, Customers, or Products
          2. Obtaining Individual Orders, Customers, or Products
          3. Creating an Order, Customer, or Product
            1. Creating with PUT
            2. Creating with POST
          4. Updating an Order, Customer, or Product
          5. Removing an Order, Customer, or Product
          6. Cancelling an Order
            1. Overloading the meaning of DELETE
            2. States versus operations
        5. Wrapping Up
      3. 3. Your First JAX-RS Service
        1. Developing a JAX-RS RESTful Service
          1. Customer: The Data Class
          2. CustomerResource: Our JAX-RS Service
            1. Creating customers
            2. Retrieving customers
            3. Updating a customer
            4. Utility methods
          3. JAX-RS and Java Interfaces
          4. Inheritance
        2. Deploying Our Service
          1. Deployment Within a Servlet Container
        3. Wrapping Up
      4. 4. HTTP Method and URI Matching
        1. Binding HTTP Methods
          1. HTTP Method Extensions
        2. @Path
          1. Binding URIs
          2. @Path Expressions
            1. Template parameters
            2. Regular expressions
            3. Precedence rules
            4. Encoding
          3. Matrix Parameters
        3. Subresource Locators
          1. Full Dynamic Dispatching
        4. Wrapping Up
      5. 5. JAX-RS Injection
        1. The Basics
        2. @PathParam
          1. More Than One Path Parameter
          2. Scope of Path Parameters
          3. PathSegment and Matrix Parameters
            1. Matching with multiple PathSegments
          4. Programmatic URI Information
        3. @MatrixParam
        4. @QueryParam
          1. Programmatic Query Parameter Information
        5. @FormParam
        6. @HeaderParam
          1. Raw Headers
        7. @CookieParam
        8. Common Functionality
          1. Automatic Java Type Conversion
            1. Primitive type conversion
            2. Java object conversion
            3. Collections
            4. Conversion failures
          2. @DefaultValue
          3. @Encoded
        9. Wrapping Up
      6. 6. JAX-RS Content Handlers
        1. Built-in Content Marshalling
          1. javax.ws.rs.core.StreamingOutput
          2. java.io.InputStream, java.io.Reader
          3. java.io.File
          4. byte[]
          5. String, char[]
          6. MultivaluedMap<String, String> and Form Input
          7. javax.xml.transform.Source
        2. JAXB
          1. Intro to JAXB
          2. JAXB JAX-RS Handlers
            1. Managing your own JAXBContexts with ContextResolvers
          3. JAXB and JSON
            1. XML to JSON using BadgerFish
          4. JSON and JSON Schema
        3. Custom Marshalling
          1. MessageBodyWriter
            1. Adding pretty printing
            2. Pluggable JAXBContexts using ContextResolvers
          2. MessageBodyReader
          3. Life Cycle and Environment
        4. Wrapping Up
      7. 7. Response Codes, Complex Responses, and Exception Handling
        1. Default Response Codes
          1. Successful Responses
          2. Error Responses
        2. Complex Responses
          1. Returning Cookies
          2. The Status Enum
          3. javax.ws.rs.core.GenericEntity
        3. Exception Handling
          1. javax.ws.rs.WebApplicationException
          2. Exception Mapping
        4. Wrapping Up
      8. 8. HTTP Content Negotiation
        1. Conneg Explained
          1. Preference Ordering
        2. Language Negotiation
        3. Encoding Negotiation
        4. JAX-RS and Conneg
          1. Method Dispatching
          2. Leveraging Conneg with JAXB
          3. Complex Negotiation
            1. Viewing Accept headers
            2. Variant processing
          4. Negotiation by URI Patterns
        5. Leveraging Content Negotiation
          1. Creating New Media Types
          2. Flexible Schemas
        6. Wrapping Up
      9. 9. HATEOAS
        1. HATEOAS and Web Services
          1. Atom Links
          2. Advantages of Using HATEOAS with Web Services
            1. Location transparency
            2. Decoupling interaction details
            3. Reduced state transition errors
            4. W3C standardized relationships
          3. Link Headers Versus Atom Links
        2. HATEOAS and JAX-RS
          1. Building URIs with UriBuilder
          2. Relative URIs with UriInfo
        3. Wrapping Up
      10. 10. Scaling JAX-RS Applications
        1. Caching
          1. HTTP Caching
          2. Expires Header
          3. Cache-Control
          4. Revalidation and Conditional GETs
            1. Last-Modified
            2. ETag
            3. JAX-RS and conditional GETs
        2. Concurrency
          1. JAX-RS and Conditional Updates
        3. Wrapping Up
      11. 11. Deployment and Integration
        1. Deployment
          1. The Application Class
          2. Deployment Within a JAX-RS-Unaware Container
          3. Deployment Within a JAX-RS-Aware Container
          4. Deployment Within Java EE 6
        2. Configuration
          1. Older Java EE Containers
          2. Within Java EE 6 Containers
        3. EJB Integration
        4. Spring Integration
        5. Wrapping Up
      12. 12. Securing JAX-RS
        1. Authentication
          1. Basic Authentication
          2. Digest Authentication
          3. Client Certificate Authentication
        2. Authorization
        3. Authentication and Authorization in JAX-RS
          1. Enforcing Encryption
          2. Authorization Annotations
          3. Programmatic Security
        4. Wrapping Up
      13. 13. RESTful Java Clients
        1. java.net.URL
          1. Caching
          2. Authentication
            1. Client Certificate authentication
          3. Advantages and Disadvantages
        2. Apache HttpClient
          1. Authentication
            1. Client Certificate authentication
          2. Advantages and Disadvantages
        3. RESTEasy Client Framework
          1. Authentication
          2. Advantages and Disadvantages
        4. RESTEasy Client Proxies
          1. Advantages and Disadvantages
        5. Wrapping Up
      14. 14. JAX-RS Implementations
        1. Jersey
          1. Embeddable Jersey
          2. Client API
          3. WADL
          4. Data Formats
            1. Atom
            2. JSON
            3. MIME multipart
          5. Model, View, and Controller
          6. Component Integration
        2. Apache CXF
          1. Aggregating Request Parameters into Beans
          2. Converting Request Parameters into Custom Types
          3. Static Resolution of Subresources
          4. Client API
          5. Supporting Services Without JAX-RS Annotations
          6. Intercepting Requests and Responses
          7. Promoting XSLT and XPath As First-Class Citizens
          8. Support for Suspended Invocations
          9. Support for Multipart Formats
          10. Integration with Distributed OSGi RI
          11. Support for WADL
          12. Component Integration
        3. JBoss RESTEasy
          1. Embedded Container
          2. Asynchronous HTTP
          3. Interceptor Framework
          4. Client “Browser” Cache
          5. Server-Side Caching
          6. GZIP Compression
          7. Data Formats
            1. Atom
            2. Multipart
          8. Component Integration
        4. Wrapping Up
    5. II. JAX-RS Workbook
      1. 15. Workbook Introduction
        1. Installing RESTEasy and the Examples
        2. Example Requirements and Structure
          1. Code Directory Structure
          2. Environment Setup
      2. 16. Examples for Chapter 3
        1. Build and Run the Example Program
          1. Deconstructing pom.xml
          2. Running the Build
        2. Examining the Source Code
      3. 17. Examples for Chapter 4
        1. Example ex04_1: HTTP Method Extension
          1. Build and Run the Example Program
          2. The Server Code
          3. The Client Code
        2. Example ex04_2: @Path with Expressions
          1. Build and Run the Example Program
          2. The Server Code
          3. The Client Code
        3. Example ex04_3: Subresource Locators
          1. Build and Run the Example Program
          2. The Server Code
          3. The Client Code
      4. 18. Examples for Chapter 5
        1. Example ex05_1: Injecting URI Information
          1. The Server Code
          2. The Client Code
          3. Build and Run the Example Program
        2. Example ex05_2: Forms and Cookies
          1. The Server Code
          2. Server Configuration
          3. Build and Run the Example Program
      5. 19. Examples for Chapter 6
        1. Example ex06_1: Using JAXB
          1. The Client Code
          2. Changes to pom.xml
          3. Build and Run the Example Program
        2. Example ex06_2: Creating a Content Handler
          1. The Content Handler Code
          2. The Resource Class
          3. The Application Class
          4. The Client Code
          5. Build and Run the Example Program
      6. 20. Examples for Chapter 7
        1. Example ex07_1: ExceptionMapper
          1. The Client Code
          2. Build and Run the Example Program
      7. 21. Examples for Chapter 8
        1. Example ex08_1: Conneg with JAX-RS
          1. The Client Code
          2. Build and Run the Example Program
        2. Example ex08_2: Conneg via URL Patterns
          1. The Server Code
          2. Build and Run the Example Program
      8. 22. Examples for Chapter 9
        1. Example ex09_1: Atom Links
          1. The Server Code
          2. The Client Code
          3. Build and Run the Example Program
        2. Example ex09_2: Link Headers
          1. The Server Code
            1. OrderResource
            2. StoreResource
          2. The Client Code
          3. Build and Run the Example Program
      9. 23. Examples for Chapter 10
        1. Example ex10_1: Caching and Concurrent Updates
          1. The Server Code
          2. The Client Code
          3. Build and Run the Example Program
      10. 24. Examples for Chapter 11
        1. Example ex11_1: EJB and JAX-RS
          1. Project Structure
          2. The EJB Project
            1. The EJB code
            2. The ExceptionMappers
          3. The WAR Project
          4. The EAR Project
          5. Build and Run the Example Program
        2. Example ex11_2: Spring and JAX-RS
          1. Build and Run the Example Program
    6. Index
    7. About the Author
    8. Colophon
    9. SPECIAL OFFER: Upgrade this ebook with O’Reilly