Presentation is loading. Please wait.

Presentation is loading. Please wait.

Web Services with Apache CXF Part 3: REST Web Services Robert Thornton.

Similar presentations


Presentation on theme: "Web Services with Apache CXF Part 3: REST Web Services Robert Thornton."— Presentation transcript:

1 Web Services with Apache CXF Part 3: REST Web Services Robert Thornton

2 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)

3 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.

4 Web Services with Apache CXF REST Web Services Part 1: Introduction to REST

5 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.

6 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.

7 Introduction to REST The six characteristics of REST: 1.Uniform interface 2.Decoupled client-server interaction 3.Stateless 4.Cacheable 5.Layered 6.Extensible through code on demand (optional) * Services that do not conform to the above required contstraints are not strictly RESTful web services.

8 Web Services with Apache CXF REST Web Services Part 2: HTTP and REST

9 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.)

10 HTTP-REST Request Basics Sample Client Requests: A typical client GET request: A typical client POST request: GET /view?id=1 HTTP/1.1 User-Agent: Chrome Accept: application/json [CRLF] POST /save HTTP/1.1 User-Agent: IE Content-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)

11 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.)

12 HTTP-REST Response Basics Sample Server Responses: HTTP/1.1 200 OK Content-Type: text/html Content-Length: 1337 [CRLF] HTTP/1.1 500 Internal Server Error HTTP/1.1 201 Created Location: /view/7 [CRLF] Some message goes here. Response Status Response Headers Response Body (content) Response Status Response Header Response Body Response Status

13 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

14 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 protocolhost namepath to a resource query string

15 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.

16 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.

17 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)

18 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.

19 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.

20 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.

21 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.

22 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. Dont 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.

23 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.

24 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; @Controller public class HelloWebServiceRest { @GET public String sayHello() { return "Hello, World!"; }

25 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.

26 JAX-RS Basics Stack RS Namespace Usage: Element name: 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

27 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.

28 JAX-RS Basics An example WADL descriptor:

29 JAX-RS: Lab 1 Lab 1: Hello World with REST http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

30 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.

31 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.

32 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.

33 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.

34 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.

35 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 getItems( @PathParam("category") String category) { @PathParam("subcategory") String subcategory) { // @Path and @PathParam example }

36 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.

37 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.

38 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 editItems(List items) { // Does something and returns the modified list }

39 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 element of the configuration.

40 JAX-RS: Example PDF Export @Provider @Produces("application/pdf") public class PdfWriter implements MessageBodyWriter { 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 dont know yet } public void writeTo(MyCatalog mc, Class type, Type genericType, Annotation[] annot, MediaType mediaType, MultivaluedMap httpHeaders, OutputStream entityStream) throws IOException, WebApplicationException { // Use iText to generate PDF and write to entityStream }

41 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 element of the configuration.

42 JAX-RS: Example Spreadsheet Import @Provider @Consumes( "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet") public class SpreadSheetReader implements MessageBodyReader { 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 type, Type genericType, Annotation[] annot, MediaType mediaType, MultivaluedMap httpHeaders, InputStream entityStream) throws IOException, WebApplicationException { MyCatalog catalog = new MyCatalog() // Use Apache POI, to read the spreadsheet and extract its data return catalog; }

43 JAX-RS: Example Configuration The Stack RS namespace handler can be configured to use your own custom providers:

44 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.

45 JAX-RS: Lab 2 Lab 2: Using JAX-RS Annotations http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

46 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.

47 JAX-RS: Customizing the Response @Path("example") @Produces({"application/json", "application/xml"}) @Consumes({"application/json", "application/xml"}) public class ExampleRestService { @GET public List getItems() { // Return all items. return items; } @POST @Path("items") public Response editItems(List items) { //... Modify the list of items ResponseBuilder rb = Response.temporaryRedirect( URI.create(UriInfo.getBaseUri() + "example")); return rb.build(); // redirect to getItems() }

48 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

49 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 element of the configuration.

50 JAX-RS: Custom ExceptionMapper @Provider public class TimeoutExceptionMapper implements ExceptionMapper { 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(); }

51 JAX-RS: Lab 3 Lab 3: Custom Response and Exception Handling http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

52 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.

53 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


Download ppt "Web Services with Apache CXF Part 3: REST Web Services Robert Thornton."

Similar presentations


Ads by Google