JAX-RS introduction

JAX-RS--Java API for RESTful Web Services, is a standard defined by the SUN Microsystems, providing the Java programmers with a set of fixed interfaces (Java API) to develop RESTful WEB service applications, which helps avoid relying on the third-party framework. Meanwhile, JAX-RS, based on the POJO programming model, uses annotations to simplify the development and deployment of web service clients and endpoints. REST is a lightweight Web service architecture and JAX-RS regulates the interfaces for REST application development

The common JAX-RS implementation methods are as follows:

• Jersey--The JSR311 reference implementation released by the SUN Microsystems with the JSR311 release;

• CXF--The merging of XFire and Celtix

• RESTEasy--The JAX-RS project of JBoss

Jersey is the JSR311 implementation released by the SUN Microsystems with the JSR311 release; Under the support of SUN, the usability of Jersey is much better than that of the other two methods at present, and is used more widely. SuperMap iServer refers to Jersey for resource implementation.

Samples

Construct the root resource HelloWorldResource, which is a simple Web resource. Its URI is /helloworld and it supports the GET method and the representation in "text/plain". The 3 main elements of JSR311 consists of the resource URI, the HTTP request method and the output format. After the resource has been deployed as the corresponding Web service, you can access it through http://localhost:8090/helloworld.

package com.sun.ws.rest.samples.helloworld.resources;

import javax.ws.rs.GET;

import javax.ws.rs.Produces;

import javax.ws.rs.Path;

// The Java class can be located by URI "/helloworld", such as http://localhost:8090/helloworld

@Path("/helloworld")

public class HelloWorldResource {

   // Use the HTTP request method GET

   @GET

   // The Java method will return the value of the media type here.

   // The return type is "text/plain".

   @Produces("text/plain")

   public String getClichedMessage() {

       // Return the string.

       return "Hello World";

   }

}

Introduction of main annotations

JAX-RS provides a series of annotations, and encapsulates the resource classes and the corresponding methods into the Web resource. The main annotations are as follows:

• @Path, annotates the relative path of the resource class or the method;

• @GET, @PUT, @POST and @DELETE, annotate the HTTP request method type;

• @Produce, annotates the returned data format (MIME type), namely the type of the returned value of the method;

• @Consumes, annotates the acceptable request data format (MIME type), namely the parameter type decoded by the resource;

• @PathParam, @QueryParam, @HeaderParam, @CookieParam, @MatrixParam, and @FormParam, annotate the where of the HTTP request does the parameter of the methode come from. For example, @PathParam represents URL path, @QueryParam represents URL query parameter, @HeaderParam represents the header of the HTTP request, and @CookieParam represents the Cookie of the HTTP request.

Class-level annotations @Path and @Produces are applicable to each method, unless the method has its own @Path and @Produces.

Parameter passing method

There are two types of resource parameters: the URI query parameter annotated with @PathParam and the parameter in the request body annotated with @FormParam.

1. The URI query parameter is annotated with @PathParam, and userName is a URI parameter.

  1 @Path("/users/{username}")

  2 public class UserResource {

  3

  4     @GET

  5     @Produces("text/xml")

  6     public String getUser(@PathParam("username") String userName) {

  7         ...

  8     }

  9 }

2. The parameter in the request body is annotated with @FormParam. Taking the POST request as an example, its definition method is as follows. Parameter name is one of this type.

  1 @POST

  2 @Consumes("application/x-www-form-urlencoded")

  3 public void post(@FormParam("name") String name) {

  4     // Request the information

  5     }