web services with apache cxf part 3: rest web services robert thornton
TRANSCRIPT
Web Services with Apache CXFPart 3: REST Web Services
Robert Thornton
Notes
• This is a training, NOT a presentation• Please ask questions• This is being recorded• https://tech.lds.org/wiki/Java_Stack_Training• Prerequisites:
– Maven, Spring– Web Application Development– CXF Training, Parts 1 and 2– Spring MVC, Part 2 (Recommended, but optional)
Objectives
At the end of this presentation, the participant will be able to:• Understand the basics of the HTTP protocol.• Understand how REST web services fit onto the HTTP protocol.• Understand how the JAX-RS APIs and annotations can be used to
develop REST web services.• Understand how CXF can be configured with Spring to produce
JAX-RS web services in a web application.• Understand how JAX-RS differs and compares to Spring MVC• Understand how to negotiate content in a JAX-RS service.• Understand how to handle responses and exceptions in a JAX-RS
service.
Web Services with Apache CXF
REST Web ServicesPart 1: Introduction to REST
Introduction to REST
REST stands for Representational State Transfer• It is an architectural pattern for developing web services
as opposed to a specification.• REST web services communicate over the HTTP
specification, using HTTP vocabulary:– Methods (GET, POST, etc.)– HTTP URI syntax (paths, parameters, etc.)– Media types (xml, json, html, plain text, etc)– HTTP Response codes.
Introduction to REST
• Representational– Clients possess the information necessary to identify,
modify, and/or delete a web resource.• State
– All resource state information is stored on the client.• Transfer
– Client state is passed from the client to the service through HTTP.
Introduction to REST
The six characteristics of REST:1. Uniform interface2. Decoupled client-server interaction3. Stateless4. Cacheable5. Layered6. Extensible through code on demand (optional)
* Services that do not conform to the above required contstraints are not strictly RESTful web services.
Web Services with Apache CXF
REST Web ServicesPart 2: HTTP and REST
HTTP-REST Request Basics
• The HTTP request is sent from the client.– Identifies the location of a resource.– Specifies the verb, or HTTP method to use when
accessing the resource.– Supplies optional request headers (name-value pairs)
that provide additional information the server may need when processing the request.
– Supplies an optional request body that identifies additional data to be uploaded to the server (e.g. form parameters, attachments, etc.)
HTTP-REST Request Basics
Sample Client Requests:• A typical client GET request:
• A typical client POST request:
GET /view?id=1 HTTP/1.1User-Agent: ChromeAccept: application/json[CRLF]
POST /save HTTP/1.1User-Agent: IEContent-Type: application/x-www-form-urlencoded[CRLF]name=x&id=2
Requested Resource (path and query string)
Request Headers
Request Body (e.g. form parameters)
Requested Resource (typically no query string)
Request Headers
(no request body)
HTTP-REST Response Basics
• The HTTP response is sent from the server.– Gives the status of the processed request.– Supplies response headers (name-value pairs) that
provide additional information about the response.– Supplies an optional response body that identifies
additional data to be downloaded to the client (html, xml, binary data, etc.)
HTTP-REST Response Basics
Sample Server Responses:HTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 1337[CRLF]<html> <!-- Some HTML Content. --></html>
HTTP/1.1 500 Internal Server Error
HTTP/1.1 201 CreatedLocation: /view/7[CRLF]Some message goes here.
Response Status
Response Headers
Response Body (content)
Response Status
Response Header
Response Body
Response Status
HTTP-REST Vocabulary
HTTP Methods supported by REST:• GET – Requests a resource at the request URL
– Should not contain a request body, as it will be discarded.– May be cached locally or on the server.– May produce a resource, but should not modify on it.
• POST – Submits information to the service for processing– Should typically return the new or modified resource.
• PUT – Add a new resource at the request URL• DELETE – Removes the resource at the request URL• OPTIONS – Indicates which methods are supported• HEAD – Returns meta information about the request URL
HTTP-REST Vocabulary
A typical HTTP REST URL:
• The protocol identifies the transport scheme that will be used to process and respond to the request.
• The host name identifies the server address of the resource.• The path and query string can be used to identify and customize
the accessed resource.
http://my.store.com/fruits/list?category=fruit&limit=20
protocol host name path to a resource query string
HTTP and REST
A REST service framework provides a controller for routing HTTP requests to a request handler according to:• The HTTP method used (e.g. GET, POST)• Supplied path information (e.g /service/listItems)• Query, form, and path parameters• Headers, cookies, etc.
Producing REST Services
REST services in Java web applications can be implemented in several ways:• As a plain Java Servlet
– Adequate for very simple REST services.– Requires a lot of “boiler plate” code for complex services.
• Using a REST service framework.– Eliminates the need to write “boilerplate” code.– Typically integrates with other technologies, such as Spring.
Java provides the JAX-RS specification for use by providers of REST service frameworks.
REST on the Java Stack
Although developers may implement REST web services however they choose, the Java Stack team is best equipped to support the following:• Apache CXF
– A JAX-RS web service framework• Spring MVC
– An MVC framework built upon the Spring Platform (does not implement the JAX-RS specification)
CXF Web Services Framework
Apache CXF is a robust framework designed specifically for producing and consuming web services:• It is open-source and free to use.• It supports several web service standards and JSR APIs.• It provides tooling and configuration for JAX-WS and
JAX-RS services.• It provides integration with the Spring Application
Framework, the core technology upon which most of the Java Stack is built.
CXF Web Services Framework
Apache CXF provides robust support for several web service patterns and specifications:• JSR APIs: JAX-WS, JAX-RS, JSR-181 annotations, SAAJ• WS-* specifications for web service interoperability.• Rich support support for message transports, protocol bindings,
content negotiation, data bindings, and so forth.• Flexible, lightweight deployment in a variety of web application
containers or stand-alone.• Tooling for code generation• Tools for WSDL and WADL publishing.
REST Services with JAX-RS
JAX-RS is a Java standard API for REST services:• Services are annotation driven• Provides support for data binding.• Provides advanced APIs for content negotiation.
CXF provides an implementation of JAX-RS:• Supports CXF filters, interceptors, and invokers to
customize and extend the service.• Configurable through Spring.• Integrates with security providers.
REST Services with Spring MVC
Spring MVC is a model-view-controller framework built upon the Spring Application Framework.• Annotation driven• Supports a RESTful pattern of routing requests to
web resources using HTTP vocabulary.• Not an implementation of the JAX-RS
specification.
JAX-RS or Spring MVC?
Some Guidelines for choosing your solution:• Both JAX-RS and Spring MVC can produce REST services.• Spring MVC is a web application framework that can be used as service
framework.– Provides better validation– Supports internationalization
• JAX-RS is a primarily a services framework.– Provides support for WADL generation– Can use CXF interceptors, filters, etc.
• Match the framework to the needs and purpose of the project.• Don’t mix both in same web application unless you need unique
features from each.– If your project needs both, consider separate web applications.
• Consult the Java Stack team.
JAX-RS Basics
JAX-RS applications consist of a hierarchy of resources:• Resources are served up by a CXF controller servlet.• Each REST resource is mapped to a request URI that is relative to
the CXF controller servlet path.• The relative path of each resource is mapped to a method on a
JAX-RS annotated service bean that returns the resource.• Service bean methods that return a resource must be annotated
with a single JAX-RS HTTP method annotation (e.g @GET)• Additional, optional annotations may be applied to the class, class
fields, and method parameters to customize the service API.• JAX-RS service beans form the “view” or public interface of your
REST web service application.
JAX-RS Basics
An example REST service class:
• At least one method must be annotated with an HTTP verb (e.g. @GET)• The @Controller annotation makes the class discoverable by Spring
package org.lds.tech.training.lab.ws;
import javax.ws.rs.GET;import org.springframework.stereotype.Controller;
@Controllerpublic class HelloWebServiceRest {
@GET public String sayHello() { return "Hello, World!"; }}
JAX-RS Basics
Example Spring configuration:• Example location: WEB-INF/example-servlet.xml
• A reference to the JAX-RS annotated service bean is passed to the Stack RS “produce” namespace handler.
• Multiple service beans may be supplied under the Stack RS “interfaces” element.
• Each bean will be scanned by CXF for annotated resources that can be served up RESTfully.
<stack-rs:produce> <stack-rs:interfaces> <ref bean="helloWebServiceRest"/> </stack-rs:interfaces> </stack-rs:produce>
JAX-RS Basics
Stack RS Namespace Usage:• Element name: <stack-rs:produce/>• Optional Attributes:
– secured – whether to secure the endpoint– extensions – whether to support the use of .xml and .json extensions– address – the relative address of the REST service– authentication-manager-ref
• Child elements:– interfaces – JAX-RS annotated service beans– providers – provider beans for content negotiation– in-interceptors– out-interceptors
JAX-RS Basics
The JAX-RS resource hierarchy is described using “Web Application Descriptor Language”, or WADL. Apache CXF generates a WADL descriptor to expose the following information about your service:• All the resources available through REST calls.• The relative path to each resource• The HTTP method required to access each resource.• How the HTTP response will represent, or format, each
resource.
JAX-RS Basics
An example WADL descriptor:<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <resources base="http://localhost:8080/example/Services/rest"> <resource path="/"> <method name="GET"> <response> <representation mediaType="application/octet-stream"> <param name="result" style="plain" type="xs:string"/> </representation> </response> </method> </resource> </resources></application>
JAX-RS: Lab 1
Lab 1: Hello World with RESThttp://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3
JAX-RS Annotations
JAX-RS Annotations customize many parts of the REST service:• They identify the HTTP method for accessing a resource.• They identify the relative path for accessing a resource.• They identify how query and form parameters, headers,
cookies and other pieces of the HTTP request message map to Java parameters and fields.
• They identify the available content types that can be consumed or produced for a resource.
JAX-RS Method Annotations
JAX-RS HTTP Method Annotations:@GET @POST@PUT @DELETE@OPTIONS @HEAD• Applied to a Java method to bind it to an HTTP method.• Only one HTTP annotation may be applied to a single Java
method.• Multiple Java methods may be given the same HTTP method
annotation, assuming they are bound to different paths.
JAX-RS @Path Annotation
• @Path annotations may be supplied to customize the request URI of resource.
• @Path on a class defines the base relative path for all resources supplied by that class.
• @Path on a Java class method defines the relative path for the resource bound to that method.
• @Path on a method is relative to any @Path on the class.• In the absence of @Path on the class or method, the
resource is defined to reside at the root of the service.• A leading forward slash (/) is unecessary as the path is
always relative.
JAX-RS: @Path Annotation
The @Path annotation supports the use of template parameters in the form:
{ name : regex }• The template parameter name is required.• The colon (:) followed by a regular expression is optional
and will default to the pattern: [^/]+• Multiple template parameters may be defined in a single
@Path.• Template parameter values will be injected into method
parameters annotated with @PathParam.
JAX-RS Parameter Annotations
• Common JAX-RS Parameter Annotations:– @QueryParam – maps to a query string parameter.– @FormParam – maps to a form POST parameter.– @PathParam – maps to a path segment.– @DefaultValue – supplies a default parameter value.
• Most often used on service methods to annotate input parameters.
• Can also be used on fields or field setter methods if the service bean has request scope.
• Additional parameter annotations are also available.– See the JAX-RS API documentation for details.
JAX-RS Annotations: Examples
@Path("example")public class ExampleWebServiceRest { @GET public Item getItem(@QueryParam("itemId") Long id) {
// @QueryParam example }
@POST public Response editItem(@FormParam("itemId") Long id, @FormParam("value") String value) {
// @FormParam example }
@GET @Path("{category}/{subcategory:[^/]*}") public List<Item> getItems( @PathParam("category") String category) { @PathParam("subcategory") String subcategory) {
// @Path and @PathParam example }}
JAX-RS Annotations: @Produces
@Produces• Used on a class or method to identify the content types
that can be produced by that resource class or method.• Method annotation overrides class annotation• If not specified, CXF assumes any type (*/*) can be
produced.• CXF responds with HTTP status “406 Not Acceptable” if
no appropriate method is found.
JAX-RS Annotations: @Consumes
@Consumes• Used on a class or method to identify the content types
that can be accepted by that resource class or method.• Method annotation overrides class annotation• If not specified, CXF assumes any type (*/*) is
acceptable.• CXF responds with HTTP status “406 Not Acceptable” if
no appropriate method is found.
JAX-RS Annotations
Examples of @Produces and @Consumes:
• The client submits JSON or XML content with the “Content-Type” header.
• The client requests either JSON or XML content through use of the HTTP “Accept” request header.
@Path("example")public class ExampleRestService {
@POST @Path("items") @Produces({"application/json", "application/xml"}) @Consumes({"application/json", "application/xml"}) public List<Item> editItems(List<Item> items) { // Does something and returns the modified list }}
JAX-RS: MessageBodyWriter
To produce content in other formats (as output), do the following:• Implement javax.ws.rs.ext.MessageBodyWriter for the Java
type that you want to write to the response.• Annotate the implementation with @Provider• Optionally annotate the implementation with @Produces to
restrict the content types for which it is suitable.• Configure an instance of your provider as a Spring bean.• Supply a reference to your bean under the <stack-
rs:providers> element of the <stack-rs:produce> configuration.
JAX-RS: Example PDF Export
@Provider@Produces("application/pdf")public class PdfWriter implements MessageBodyWriter<MyCatalog> {
public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) { return true; // true means I can write the type to PDF }
public long getSize(MyCatalog mc, Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
return -1; // Negative value means I don’t know yet }
public void writeTo(MyCatalog mc, Class<?> type, Type genericType, Annotation[] annot, MediaType mediaType, MultivaluedMap<String, Object> httpHeaders, OutputStream entityStream) throws IOException, WebApplicationException { // Use iText to generate PDF and write to entityStream }}
JAX-RS: MessageBodyReader
To consume content in other formats (as input), do the following:• Implement javax.ws.rs.ext.MessageBodyReader for the
type that you want to read from the request.• Annotate the implementation with @Provider• Optionally annotate the implementation with @Consumes
to restrict the content types for which it is suitable.• Configure an instance of your provider as a Spring bean.• Supply a reference to your bean under the <stack-
rs:providers> element of the <stack-rs:produce> configuration.
JAX-RS: Example Spreadsheet Import@Provider@Consumes("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")public class SpreadSheetReader implements MessageBodyReader<MyCatalog> {
public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
return true; // true means I can read the type as a spreadsheet }
public MyCatalog readFrom(Class<MyCatalog> type, Type genericType, Annotation[] annot, MediaType mediaType, MultivaluedMap<String, String> httpHeaders, InputStream entityStream) throws IOException, WebApplicationException { MyCatalog catalog = new MyCatalog() // Use Apache POI, to read the spreadsheet and extract its data return catalog; }}
JAX-RS: Example Configuration
<stack-rs:produce> <stack-rs:interfaces> <ref bean="catalogServiceRest"/> </stack-rs:interfaces> <stack-rs:providers> <ref bean="pdfWriter"/> <ref bean="xlsReader"/> </stack-rs:providers></stack-rs:produce>
The Stack RS namespace handler can be configured to use your own custom providers:
JAX-RS: XML and JSON Providers
• As a requirement of JAX-RS, CXF automatically provides support for reading and writing XML to and from JAXB annotated classes.
• CXF also provides built-in support for reading and writing JSON to and from JAXB annotated classes.– Default support uses Jettison as the JSON provider– The Stack RS namespace handler will automatically
configure Jackson as the JSON provider if it is on the classpath.
JAX-RS: Lab 2
Lab 2: Using JAX-RS Annotationshttp://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3
JAX-RS: Customizing the Response
There may be times when you need to customize the response from your JAX-RS service, for example:• To provide metadata instead of, or in addition to, the
response entity.• To supply a custom status code• To instruct CXF to perform a redirect.For these cases, JAX-RS provides the abstract Response class and the ResponseBuilder utility.• An example is provided on the following screen.
JAX-RS: Customizing the Response
@Path("example")@Produces({"application/json", "application/xml"})@Consumes({"application/json", "application/xml"})public class ExampleRestService {
@GET public List<Item> getItems() { // Return all items. return items; }
@POST @Path("items") public Response editItems(List<Item> items) { // ... Modify the list of items ResponseBuilder rb = Response.temporaryRedirect( URI.create(UriInfo.getBaseUri() + "example")); return rb.build(); // redirect to getItems() }}
JAX-RS: Exception Handling
By default, JAX-RS provides exception handling for its own javax.ws.rs.WebApplicationException.• Extends java.lang.RuntimeException• May be thrown by any resource method• Is converted by CXF into a Response object.Any other exception will result in HTTP status “500 Internal Server Error”
JAX-RS: Custom Exception Handling
Custom exception handling can be provided by doing the following:• Implement javax.ws.rs.ext.ExceptionMapper for the
exception type you want to handle.• Annotate the implementation class with @Provider• Configure an instance of your provider as a Spring bean.• Supply a reference to your bean under the <stack-
rs:providers> element of the <stack-rs:produce> configuration.
JAX-RS: Custom ExceptionMapper
@Providerpublic class TimeoutExceptionMapper implements ExceptionMapper<TimeoutException> {
public Response toResponse(TimeoutException exception) { ResponseBuilder rb = Response.status(408); // Request timeout // Call additional methods on the response builder // to further customize the response return rb.build(); }}
JAX-RS: Lab 3
Lab 3: Custom Response and Exception Handlinghttp://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3
Conclusion
JAX-RS is a flexible API for providing scalable web services.CXF, Spring and the Java Stack integrate to make developing and configuring REST services easy.Many aspects of the request, response, and exception handling can be customized through use of MessageBodyReader, MessageBodyWriter, ResponseBuilder, and ExceptionMapper.
Credit
Resources used to prepare this training:• http://cxf.apache.org• http://en.wikipedia.org/wiki/Representational_state_transfer• Java 6 API Documentation• Java Stack Documentation• W3C HTTP Method Specification• Spring MVC Training, Part 2, by Spencer Uresk