Thursday, January 22, 2015

REST Web Service Tutorial-JAX-RS

Int his REST Web Service tutorial we will demonstrates how RESTful services are created using JAX-RS. We'll be using Tomcat as our primary application server. Java API for RESTful Web Services (JAX-RS), is a set if APIs to developer REST service.JAX-RS is part of the Java EE6, and make developers to develop REST web application easily.

What Are RESTful Web Services?
RESTful web services are built to work best on the Web. Representational State Transfer (REST) is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such asperformance, scalability, and modifiability, that enable services to work best on the Web. In the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs), typically links on the Web. The resources are acted upon by using a set of simple, well-defined operations. The REST architectural style constrains an architecture to a client/server architecture and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture style, clients and servers exchange representations of resources by using a standardized interface and protocol.

The following principles encourage RESTful applications to be simple, lightweight, and fast:
  • Resource identification through URI: A RESTful web service exposes a set of resources that identify the targets of the interaction with its clients. Resources are identified by URIs, which provide a global addressing space for resource and service discovery. See The @Path Annotation and URI Path Templates for more information.
  • Uniform interface: Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT,GET, POST, and DELETE. PUT creates a new resource, which can be then deleted by using DELETE. GET retrieves the current state of a resource in some representation. POST transfers a new state onto a resource. See Responding to HTTP Methods and Requests for more information.
  • Self-descriptive messages: Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and others. Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control. See Responding to HTTP Methods and Requests and Using Entity Providers to Map HTTP Response and Request Entity Bodies for more information.
  • Stateful interactions through hyperlinks: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies, and hidden form fields. State can be embedded in response messages to point to valid future states of the interaction. See Using Entity Providers to Map HTTP Response and Request Entity Bodies and “Building URIs” in the JAX-RS Overview document for more information.
RESTful web API HTTP methods
ResourceGETPUTPOSTDELETE
Collection URI, such ashttp://example.com/resources/List the URIs and perhaps other details of the collection's members.Replace the entire collection with another collection.Create a new entry in the collection. The new entry's URI is assigned automatically and is usually returned by the operation.Deletethe entire collection.
Element URI, such ashttp://example.com/resources/item17Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type.Replace the addressed member of the collection, or if it doesn't exist,create it.Not generally used. Treat the addressed member as a collection in its own right and create a new entry in it.Deletethe addressed member of the collection.

Creating a RESTful Root Resource Class
Root resource classes are POJOs that are either annotated with @Path or have at least one method annotated with @Path or arequest method designator, such as @GET, @PUT, @POST, or @DELETE. Resource methods are methods of a resource class annotated with a request method designator. This section explains how to use JAX-RS to annotate Java classes to createRESTful web services. 

Developing RESTful Web Services with JAX-RS
JAX-RS is a Java programming language API designed to make it easy to develop applications that use the REST architecture.
The JAX-RS API uses Java programming language annotations to simplify the development of RESTful web services. Developers decorate Java programming language class files with JAX-RS annotations to define resources and the actions that can be performed on those resources. JAX-RS annotations are runtime annotations; therefore, runtime reflection will generate the helper classes and artifacts for the resource. A Java EE application archive containing JAX-RS resource classes will have the resources configured, the helper classes and artifacts generated, and the resource exposed to clients by deploying the archive to a Java EE server.

Annotation
Description
@Path
The @Path annotation’s value is a relative URI
path indicating where the Java class will be hosted: for example, /helloworld.
You can also embed variables in the URIs to make a URI
path template. For example, you could ask for the name of a user
and pass it to the application as a variable in the URI: /helloworld/{username}.
@GET
The @GET annotation is a request method designator and corresponds to the similarly
named HTTP method. The Java method annotated with this request method designator will
process HTTP GET requests. The behavior of a resource is determined by the
HTTP method to which the resource is responding.
@POST
The @POST annotation is a
request method designator and corresponds to the similarly named HTTP method. The Java
method annotated with this request method designator will process HTTP POST requests. The
behavior of a resource is determined by the HTTP method to which the
resource is responding.
@PUT
The @PUT annotation is a request method designator and corresponds to
the similarly named HTTP method. The Java method annotated with this request method
designator will process HTTP PUT requests. The behavior of a resource is determined
by the HTTP method to which the resource is responding.
@DELETE
The @DELETE annotation
is a request method designator and corresponds to the similarly named HTTP method.
The Java method annotated with this request method designator will process HTTP DELETE
requests. The behavior of a resource is determined by the HTTP method to
which the resource is responding.
@HEAD
The @HEAD annotation is a request method designator and corresponds
to the similarly named HTTP method. The Java method annotated with this request
method designator will process HTTP HEAD requests. The behavior of a resource is
determined by the HTTP method to which the resource is responding.
@PathParam
The @PathParam
annotation is a type of parameter that you can extract for use in
your resource class. URI path parameters are extracted from the request URI, and
the parameter names correspond to the URI path template variable names specified in
the @Path class-level annotation.
@QueryParam
The @QueryParam annotation is a type of parameter that you can
extract for use in your resource class. Query parameters are extracted from the
request URI query parameters.
@Consumes
The @Consumes annotation is used to specify the MIME media
types of representations a resource can consume that were sent by the client.
@Produces
The @Produces annotation is used to specify the MIME media types of representations a
resource can produce and send back to the client: for example, "text/plain".
@Provider
The @Provider
annotation is used for anything that is of interest to the JAX-RS runtime,
such as MessageBodyReader and MessageBodyWriter. For HTTP requests, theMessageBodyReader is
used to map an HTTP request entity body to method parameters. On the
response side, a return value is mapped to an HTTP response entity body
by using a MessageBodyWriter. If the application needs to supply additional metadata, such
as HTTP headers or a different status code, a method can return a Response that wraps the entity and that can be built using Response.ResponseBuilder.
Posted by at No comments:

JAX-RS Jersey hello world example

I have written a number of posts on JAX-RS RESTEasy concepts and how to. Now I have started exploring Jersey which is another popular framework for making RESTFul applications. To start with, I am writing my hello world application in this post, which I will modify in next posts to show demos of other features Jersey provide.

Step 1) Make a eclipse web project using maven

Step 2) Update Jersey dependencies in pom.xml file

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.howtodoinjava</groupId>
  <artifactId>JerseyHelloWorld</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>JerseyHelloWorld Maven Webapp</name>
  <url>http://maven.apache.org</url>
  <repositories>
        <repository>
            <id>maven2-repository.java.net</id>
            <name>Java.net Repository for Maven</name>
            <url>http://download.java.net/maven/2/</url>
            <layout>default</layout>
        </repository>
    </repositories>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.sun.jersey</groupId>
        <artifactId>jersey-server</artifactId>
        <version>1.17.1</version>
    </dependency>
    <dependency>
        <groupId>com.sun.jersey</groupId>
        <artifactId>jersey-core</artifactId>
        <version>1.17.1</version>
    </dependency>
    <dependency>
        <groupId>com.sun.jersey</groupId>
        <artifactId>jersey-servlet</artifactId>
        <version>1.17.1</version>
    </dependency>
  </dependencies>
   
  <build>
    <finalName>JerseyHelloWorld</finalName>
        <plugins>
            <plugin>
              <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                  <source>1.6</source>
                  <target>1.6</target>
                </configuration>
            </plugin>
      </plugins>
  </build>
</project>

Step 3) Update web.xml file with servlet mapping to com.sun.jersey.spi.container.servlet.ServletContainer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >
<web-app>
  <display-name>Archetype Created Web Application</display-name>
   
  <servlet>
        <servlet-name>jersey-serlvet</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
             <param-name>com.sun.jersey.config.property.packages</param-name>
             <param-value>com.howtodoinjava.rest</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
  
    <servlet-mapping>
        <servlet-name>jersey-serlvet</servlet-name>
        <url-pattern>/rest-points/*</url-pattern>
    </servlet-mapping>
     
</web-app>

Step 4) Write first REST service class

The service class will look like exactly as RESTEasy because of common annotations used from JAX-RS.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package com.howtodoinjava.rest;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
@Path("/show-on-screen")
public class JerseyHelloWorldService
{
    @GET
    @Path("/{message}")
    public Response getMsg(@PathParam("message") String msg)
    {
        String output = "Message requested : " + msg;
        //Simply return the parameter passed as message
        return Response.status(200).entity(output).build();
    }
}
Posted by at No comments:
Subscribe to: Posts (Atom)