RESTful Web Service - JAX-RS Annotations

RESTful Web Service - JAX-RS Annotations - Contents:

Annotation	Package Detail/Import statement
@GET	import javax.ws.rs.GET;
@Produces	import javax.ws.rs.Produces;
@Path	import javax.ws.rs.Path;
@PathParam	import javax.ws.rs.PathParam;
@QueryParam	import javax.ws.rs.QueryParam;
@POST	import javax.ws.rs.POST;
@Consumes	import javax.ws.rs.Consumes;
@FormParam	import javax.ws.rs.FormParam;
@PUT	import javax.ws.rs.PUT;
@DELETE	import javax.ws.rs.DELETE;

REST follows one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods. 

· To create a resource on the server, use POST.

· To retrieve a resource, use GET.

· To change the state of a resource or to update it, use PUT.

· To remove or delete a resource, use DELETE.

@GET

Annotate your Get request methods with @GET.

@GETpublic String getHTML() {   ... }

@Produces

@Produces annotation specifies the type of output this method (or web service) will produce.

@GET
@Produces("application/xml") 
public Contact getXML() {   ... } 

@GET@Produces("application/json") 
public Contact getJSON() {   ... }

@Path

@Path annotation specify the URL path on which this method will be invoked.

@GET
@Produces("application/xml") 
@Path("xml/{firstName}") 
public Contact getXML() {   ... }

@PathParam

We can bind REST-style URL parameters to method arguments using @PathParam annotation as shown below.

@GET
@Produces("application/xml") 
@Path("xml/{firstName}") 
public Contact getXML(@PathParam("firstName") String firstName) 
{   
   Contact contact = contactService.findByFirstName(firstName); 
   return contact;
} 

@GET
@Produces("application/json") 
@Path("json/{firstName}") 
public Contact getJSON(@PathParam("firstName") String firstName) 
{   
    Contact contact = contactService.findByFirstName(firstName);
    return contact; 
}

@QueryParam

Request parameters in query string can be accessed using @QueryParam annotation as shown below.

@GET@Produces("application/json") 
@Path("json/companyList") 
public CompanyList getJSON(@QueryParam("start") int start, @QueryParam("limit") int limit)
{   
   CompanyList list = new CompanyList(companyService.listCompanies(start, limit));
   return list;
}

@POST

Annotate POST request methods with @POST.

@POST
@Consumes("application/json") 
@Produces("application/json") 
public RestResponse<Contact> create(Contact contact) { ... }

@Consumes

The @Consumes annotation is used to specify the MIME media types a REST resource can consume.

@PUT
@Consumes("application/json") 
@Produces("application/json") 
@Path("{contactId}") 
public RestResponse<Contact> update(Contact contact) { ... }

@FormParam

The REST resources will usually consume XML/JSON for the complete Entity Bean. Sometimes, you may want to read parameters sent in POST requests directly and you can do that using @FormParam annotation. GET Request query parameters can be accessed using @QueryParam annotation.

@POST
public String save(@FormParam("firstName") String firstName,@FormParam("lastName") String lastName)
{
 ...
}

@PUT

Annotate PUT request methods with @PUT.

@PUT
@Consumes("application/json")
@Produces("application/json") 
@Path("{contactId}") 
public RestResponse<Contact> update(Contact contact) 
{ 
... 
}

@DELETE

Annotate DELETE request methods with @DELETE.

@DELETE
@Produces("application/json")
@Path("{contactId}")
public RestResponse<Contact> delete(@PathParam("contactId") int contactId) 
{
 ... 
}

References

1. Jersey JAX-RS Annotations: https://wikis.oracle.com/display/Jersey/Overview+of+JAX-RS+1.0+Features

参考地址： http://www.techferry.com/articles/RESTful-web-services-JAX-RS-annotations.html