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

Foreword

Marc Hadley

JAX-RS Specification Lead Sun Microsystems, Inc.Burlington, MA

REST is an architectural style that defines a set of constraints that, when applied to the architecture of a distributed system, induce desirable properties like loose coupling and horizontal scalability. RESTful web services are the result of applying these constraints to services that utilize web standards such as URIs, HTTP, XML, and JSON. Such services become part of the fabric of the Web and can take advantage of years of web engineering to satisfy their clients’ needs.

The Java API for RESTful web services (JAX-RS) is a new API that aims to make development of RESTful web services in Java simple and intuitive. The initial impetus for the API came from the observation that existing Java Web APIs were generally either:

Very low-level, leaving the developer to do a lot of repetitive and error-prone work such as URI parsing and content negotiation, or
Rather high-level and proscriptive, making it easy to build services that conform to a particular pattern but lacking the necessary flexibility to tackle more general problems.

A Java Specification Request (JSR 311) was filed with the Java Community Process (JCP) in January 2007 and approved unanimously in February. The expert group began work in April 2007 with the charter to design an API that was flexible, easy to use, and that encouraged developers to follow the REST style. The resulting API, finalized in October 2008, has already seen a remarkable ...