robert thornton n.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
Robert Thornton PowerPoint Presentation
Download Presentation
Robert Thornton

Loading in 2 Seconds...

play fullscreen
1 / 53

Robert Thornton - PowerPoint PPT Presentation


  • 125 Views
  • Uploaded on

Web Services with Apache CXF Part 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

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Robert Thornton' - hinda


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
robert thornton

Web Services with Apache CXF

Part 3: REST Web Services

Robert Thornton

notes
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
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
Web Services with Apache CXF

REST Web Services

Part 1: Introduction to REST

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 rest1
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 rest2
Introduction to REST

The six characteristics of REST:

  • Uniform interface
  • Decoupled client-server interaction
  • Stateless
  • Cacheable
  • Layered
  • 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 cxf1
Web Services with Apache CXF

REST Web Services

Part 2: HTTP and REST

http rest request basics
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 basics1
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]

Requested Resource (path and query string)

Request Headers

(no request body)

POST /save HTTP/1.1

User-Agent: IE

Content-Type:application/x-www-form-urlencoded

[CRLF]

name=x&id=2

Requested Resource (typically no query string)

Request Headers

Request Body (e.g. form parameters)

http rest response basics
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 basics1
HTTP-REST Response Basics

Sample Server Responses:

HTTP/1.1 200 OK

Content-Type: text/html

Content-Length: 1337

[CRLF]

<html>

<!-- Some HTML Content. -->

</html>

Response Status

Response Headers

Response Body (content)

HTTP/1.1 500 Internal Server Error

Response Status

HTTP/1.1 201 Created

Location: /view/7

[CRLF]

Some message goes here.

Response Status

Response Header

Response Body

http rest vocabulary
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 vocabulary1
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

query string

protocol

host name

path to a resource

http and rest
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
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
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
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 framework1
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
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
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
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 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 basics1
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

packageorg.lds.tech.training.lab.ws;

importjavax.ws.rs.GET;

importorg.springframework.stereotype.Controller;

@Controller

publicclassHelloWebServiceRest{

@GET

publicString sayHello() {

return"Hello, World!";

}

}

jax rs basics2
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 basics3
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 basics4
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 basics5
JAX-RS Basics

An example WADL descriptor:

<applicationxmlns="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
JAX-RS: Lab 1

Lab 1: Hello World with REST

http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

jax rs annotations
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 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
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 annotation1
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
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
JAX-RS Annotations: Examples

@Path("example")

publicclassExampleWebServiceRest{

@GET

publicItem getItem(@QueryParam("itemId") Long id) {

// @QueryParam example

}

@POST

publicResponse editItem(@FormParam("itemId") Long id,

@FormParam("value") String value) {

// @FormParam example

}

@GET

@Path("{category}/{subcategory:[^/]*}")

publicList<Item> getItems(

@PathParam("category") String category) {

@PathParam("subcategory") String subcategory) {

// @Path and @PathParam example

}

}

jax rs annotations @produces
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
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 annotations1
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")

publicclassExampleRestService{

@POST

@Path("items")

@Produces({"application/json", "application/xml"})

@Consumes({"application/json", "application/xml"})

publicList<Item> editItems(List<Item> items) {

// Does something and returns the modified list

}

}

jax rs messagebodywriter
JAX-RS: MessageBodyWriter

To produce content in other formats (as output), do the following:

  • Implement javax.ws.rs.ext.MessageBodyWriterfor 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
JAX-RS: Example PDF Export

@Provider

@Produces("application/pdf")

publicclassPdfWriterimplementsMessageBodyWriter<MyCatalog> {

publicbooleanisWriteable(Class<?> type, Type genericType,

Annotation[] annotations, MediaType mediaType) {

returntrue; // true means I can write the type to PDF

}

publiclonggetSize(MyCatalog mc, Class<?> type, Type genericType,

Annotation[] annotations, MediaType mediaType) {

return -1; // Negative value means I don’t know yet

}

publicvoidwriteTo(MyCatalog mc, Class<?> type,

Type genericType, Annotation[] annot, MediaType mediaType,

MultivaluedMap<String, Object> httpHeaders,

OutputStream entityStream)

throwsIOException, WebApplicationException {

// Use iText to generate PDF and write to entityStream

}

}

jax rs messagebodyreader
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
JAX-RS: Example Spreadsheet Import

@Provider

@Consumes(

"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")

publicclassSpreadSheetReaderimplements MessageBodyReader<MyCatalog> {

publicbooleanisReadable(Class<?> type, Type genericType,

Annotation[] annotations, MediaType mediaType) {

returntrue; // true means I can read the type as a spreadsheet

}

publicMyCatalog readFrom(Class<MyCatalog> type,

Type genericType, Annotation[] annot, MediaType mediaType,

MultivaluedMap<String, String> httpHeaders,

InputStream entityStream)

throwsIOException, WebApplicationException {

MyCatalog catalog = new MyCatalog()

// Use Apache POI, to read the spreadsheet and extract its data

return catalog;

}

}

jax rs example configuration
JAX-RS: Example Configuration

The Stack RS namespace handler can be configured to use your own custom providers:

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

jax rs xml and json 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
JAX-RS: Lab 2

Lab 2: Using JAX-RS Annotations

http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

jax rs customizing the response
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 response1
JAX-RS: Customizing the Response

@Path("example")

@Produces({"application/json", "application/xml"})

@Consumes({"application/json", "application/xml"})

publicclassExampleRestService {

@GET

public List<Item> getItems() {

// Return all items.

return items;

}

@POST

@Path("items")

publicResponse 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
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
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
JAX-RS: Custom ExceptionMapper

@Provider

publicclassTimeoutExceptionMapper

implements ExceptionMapper<TimeoutException> {

publicResponse toResponse(TimeoutException exception) {

ResponseBuilder rb = Response.status(408); // Request timeout

// Call additional methods on the response builder

// to further customize the response

returnrb.build();

}

}

jax rs lab 3
JAX-RS: Lab 3

Lab 3: Custom Response and Exception Handling

http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_3

conclusion
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
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