book

RESTful Java with JAX-RS

by Bill Burke

November 2009

Intermediate to advanced

310 pages

7h 42m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Author’s NoteWho Should Read This BookHow This Book Is OrganizedPart I, REST and the JAX-RS StandardPart II, JAX-RS WorkbookConventions Used in This BookUsing Code ExamplesWe’d Like to Hear from YouSafari® Books OnlineAcknowledgments
REST and the Rebirth of HTTPRESTful Architectural PrinciplesAddressabilityThe Uniform, Constrained InterfaceWhy Is the Uniform Interface Important?Representation-OrientedCommunicate StatelesslyHATEOASThe engine of application stateWrapping Up
The Object ModelModel the URIsDefining the Data FormatRead and Update FormatCommon link elementThe detailsCreate FormatAssigning HTTP MethodsBrowsing All Orders, Customers, or ProductsObtaining Individual Orders, Customers, or ProductsCreating an Order, Customer, or ProductCreating with PUTCreating with POSTUpdating an Order, Customer, or ProductRemoving an Order, Customer, or ProductCancelling an OrderOverloading the meaning of DELETEStates versus operationsWrapping Up
Developing a JAX-RS RESTful ServiceCustomer: The Data ClassCustomerResource: Our JAX-RS ServiceCreating customersRetrieving customersUpdating a customerUtility methodsJAX-RS and Java InterfacesInheritanceDeploying Our ServiceDeployment Within a Servlet ContainerWrapping Up
Binding HTTP MethodsHTTP Method Extensions@PathBinding URIs@Path ExpressionsTemplate parametersRegular expressionsPrecedence rulesEncodingMatrix ParametersSubresource LocatorsFull Dynamic DispatchingWrapping Up
The Basics@PathParamMore Than One Path ParameterScope of Path ParametersPathSegment and Matrix ParametersMatching with multiple PathSegmentsProgrammatic URI Information@MatrixParam@QueryParamProgrammatic Query Parameter Information@FormParam@HeaderParamRaw Headers@CookieParamCommon FunctionalityAutomatic Java Type ConversionPrimitive type conversionJava object conversionCollectionsConversion failures@DefaultValue@EncodedWrapping Up
Built-in Content Marshallingjavax.ws.rs.core.StreamingOutputjava.io.InputStream, java.io.Readerjava.io.Filebyte[]String, char[]MultivaluedMap<String, String> and Form Inputjavax.xml.transform.SourceJAXBIntro to JAXBJAXB JAX-RS HandlersManaging your own JAXBContexts with ContextResolversJAXB and JSONXML to JSON using BadgerFishJSON and JSON SchemaCustom MarshallingMessageBodyWriterAdding pretty printingPluggable JAXBContexts using ContextResolversMessageBodyReaderLife Cycle and EnvironmentWrapping Up
Default Response CodesSuccessful ResponsesError ResponsesComplex ResponsesReturning CookiesThe Status Enumjavax.ws.rs.core.GenericEntityException Handlingjavax.ws.rs.WebApplicationExceptionException MappingWrapping Up

Conneg ExplainedPreference OrderingLanguage NegotiationEncoding NegotiationJAX-RS and ConnegMethod DispatchingLeveraging Conneg with JAXBComplex NegotiationViewing Accept headersVariant processingNegotiation by URI PatternsLeveraging Content NegotiationCreating New Media TypesFlexible SchemasWrapping Up
HATEOAS and Web ServicesAtom LinksAdvantages of Using HATEOAS with Web ServicesLocation transparencyDecoupling interaction detailsReduced state transition errorsW3C standardized relationshipsLink Headers Versus Atom LinksHATEOAS and JAX-RSBuilding URIs with UriBuilderRelative URIs with UriInfoWrapping Up
CachingHTTP CachingExpires HeaderCache-ControlRevalidation and Conditional GETsLast-ModifiedETagJAX-RS and conditional GETsConcurrencyJAX-RS and Conditional UpdatesWrapping Up
DeploymentThe Application ClassDeployment Within a JAX-RS-Unaware ContainerDeployment Within a JAX-RS-Aware ContainerDeployment Within Java EE 6ConfigurationOlder Java EE ContainersWithin Java EE 6 ContainersEJB IntegrationSpring IntegrationWrapping Up
AuthenticationBasic AuthenticationDigest AuthenticationClient Certificate AuthenticationAuthorizationAuthentication and Authorization in JAX-RSEnforcing EncryptionAuthorization AnnotationsProgrammatic SecurityWrapping Up
java.net.URLCachingAuthenticationClient Certificate authenticationAdvantages and DisadvantagesApache HttpClientAuthenticationClient Certificate authenticationAdvantages and DisadvantagesRESTEasy Client FrameworkAuthenticationAdvantages and DisadvantagesRESTEasy Client ProxiesAdvantages and DisadvantagesWrapping Up
JerseyEmbeddable JerseyClient APIWADLData FormatsAtomJSONMIME multipartModel, View, and ControllerComponent IntegrationApache CXFAggregating Request Parameters into BeansConverting Request Parameters into Custom TypesStatic Resolution of SubresourcesClient APISupporting Services Without JAX-RS AnnotationsIntercepting Requests and ResponsesPromoting XSLT and XPath As First-Class CitizensSupport for Suspended InvocationsSupport for Multipart FormatsIntegration with Distributed OSGi RISupport for WADLComponent IntegrationJBoss RESTEasyEmbedded ContainerAsynchronous HTTPInterceptor FrameworkClient “Browser” CacheServer-Side CachingGZIP CompressionData FormatsAtomMultipartComponent IntegrationWrapping Up
Installing RESTEasy and the ExamplesExample Requirements and StructureCode Directory StructureEnvironment Setup
Build and Run the Example ProgramDeconstructing pom.xmlRunning the BuildExamining the Source Code
Example ex04_1: HTTP Method ExtensionBuild and Run the Example ProgramThe Server CodeThe Client CodeExample ex04_2: @Path with ExpressionsBuild and Run the Example ProgramThe Server CodeThe Client CodeExample ex04_3: Subresource LocatorsBuild and Run the Example ProgramThe Server CodeThe Client Code
Example ex05_1: Injecting URI InformationThe Server CodeThe Client CodeBuild and Run the Example ProgramExample ex05_2: Forms and CookiesThe Server CodeServer ConfigurationBuild and Run the Example Program
Example ex06_1: Using JAXBThe Client CodeChanges to pom.xmlBuild and Run the Example ProgramExample ex06_2: Creating a Content HandlerThe Content Handler CodeThe Resource ClassThe Application ClassThe Client CodeBuild and Run the Example Program
Example ex07_1: ExceptionMapperThe Client CodeBuild and Run the Example Program
Example ex08_1: Conneg with JAX-RSThe Client CodeBuild and Run the Example ProgramExample ex08_2: Conneg via URL PatternsThe Server CodeBuild and Run the Example Program
Example ex09_1: Atom LinksThe Server CodeThe Client CodeBuild and Run the Example ProgramExample ex09_2: Link HeadersThe Server CodeOrderResourceStoreResourceThe Client CodeBuild and Run the Example Program
Example ex10_1: Caching and Concurrent UpdatesThe Server CodeThe Client CodeBuild and Run the Example Program
Example ex11_1: EJB and JAX-RSProject StructureThe EJB ProjectThe EJB codeThe ExceptionMappersThe WAR ProjectThe EAR ProjectBuild and Run the Example ProgramExample ex11_2: Spring and JAX-RSBuild and Run the Example Program

Content preview from RESTful Java with JAX-RS

Chapter 15. Workbook Introduction

Reading a book on a new technology gives you a nice foundation to build on, but you cannot truly understand and appreciate a new technology until you see it in action. The following workbook chapters were designed to be a companion to the main chapters of this book. Their goal is to provide step-by-step instructions for installing, configuring, and running various JAX-RS examples found throughout this book with the JBoss RESTEasy framework.

This chapter focuses on downloading and installing RESTEasy and the workbook examples. Following this, each workbook chapter corresponds to a specific chapter in the book. For example, if you are reading Chapter 3 on writing your first JAX-RS service, use Chapter 16 of the workbook to develop and run the examples shown in that chapter with RESTEasy.

This workbook is based on the production release of JBoss RESTEasy JAX-RS 1.2. I picked RESTEasy as the JAX-RS framework for the workbook for no other reason than I am the project lead for it and I know it backward and forward. That said, I took great care to ensure you can easily port the examples to other JAX-RS implementations.

Installing RESTEasy and the Examples

The workbook examples are embedded within the RESTEasy distribution so that as future versions of RESTEasy are released, the workbook examples will be updated along with that release. (I discovered that having a separate download for the workbook examples causes various problems—users can get confused about ...