rest

JAX-RS Annotations Explained

In this example we shall learn some important JAX-RS annotations. To understand this tutorial, following is the prerequisite knowledge required:

  1. Basic knowledge of how to use annotations
  2. Basic REST Architecture

1. JAX-RS Annotations

1.1 @Path

@Path annotation defines the URI or the relative path of the JAX-RS method. Following is the sample usage of @Path annotation.

PathAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.javacodegeeks.examples.rest.entites.Author;

public class PathAnnotation {

	@GET
	@Produces("application/xml")
	@Path("javacodegeeks/authors")
	public List getAuthors() {
		// TODO: Code for returning list of authors
		return null;
	}
}

1.2 @PathParam

This annotation is used to bind the parameter passed in the URI to the parameter in the REST method. Following is the example usage of @PathParam annotation.

PathParamAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

import com.javacodegeeks.examples.rest.entites.Author;

public class PathParamAnnotation {
	@GET
	@Produces("application/json")
	@Path("javacodegeeks/authors/{id}")
	public Author getAuthor(@PathParam("id") int id) {
		// TODO: Code for returning author by id
		return null;
	}
}

In the above code snippet parameter in curly braces is mapped to method parameter using @PathParam annotation.

1.3 @GET

@GET annotation specifies that the HTTP GET request shall be served by this method. Following is the example usage.

GetAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.javacodegeeks.examples.rest.entites.Author;

public class GetAnnotation {
	@GET
	@Produces("application/xml")
	@Path("javacodegeeks/authors")
	public List getAuthors() {
		// TODO: Code for returning list of authors
		return null;
	}
}

1.4 @POST

@POST annotation specifies that the HTTP POST request shall be served by this method. Following is the example usage.

PostAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;

import com.javacodegeeks.examples.rest.entites.Author;

public class PostAnnotation {
	@POST
	@Consumes("application/json")
	public void addAuthor(Author contact) {
		//TODO: Code to store author
	}
}

1.5 @PUT

@PUT annotation corresponds to HTTP PUT method. Following is the sample usage of @PUT annotation.

PutAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import javax.ws.rs.Consumes;
import javax.ws.rs.PUT;

import com.javacodegeeks.examples.rest.entites.Author;

public class PutAnnotation {
	@PUT
	@Consumes("application/json")
	public void updateAuthor(Author contact) {
		//TODO: Code to update or add author
	}
}

1.6 @DELETE

@DELETE annotation corresponds to HTTP DELETE method. Following is the sample usage of @DELETE annotation.

DeleteAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import javax.ws.rs.DELETE;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

public class DeleteAnnotation {
	@DELETE
	@Path("javacodegeeks/authors/{id}")
	public void deleteAuthor(@PathParam("id") int id) {
		//TODO: Delete author with id passed as PathParam
	}
}

1.7 @Consumes

@Consumes annotation defines the MIME media type of resource sent by client which a REST method consumes. Following is the sample usage of @Consumes annotation.

ConsumesAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;

import com.javacodegeeks.examples.rest.entites.Author;

public class HeadAnnotation {
	@POST
	@Consumes("application/json")
	public void addAuthor(Author contact) {
		//TODO: Code to store author
	}
}

In the above code snippet, REST method is consuming resource having MIME type JSON.

1.8 @Produces

@Produces annotation specifies the MIME media type of resource that is sent back to client as a return response of REST method. Following is the sample usage of @Produces annotation.

ProducesAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.javacodegeeks.examples.rest.entites.Author;

public class ProducesAnnotation {
	@GET
	@Produces("application/json")
	@Path("javacodegeeks/authors")
	public List getAuthors() {
		// TODO: Code for returning list of authors
		return null;
	}
}

In the above code snippet, REST method is returning response having MIME type JSON.

1.9 @QueryParam

@QueryParam annotation is used to extract out query parameters from the request URI. Following is the sample usage of @QueryParam annotation.

QueryParamAnnotation.java

package com.javacodegeeks.examples.rest.annotations;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

import com.javacodegeeks.examples.rest.entites.Author;

public class QueryParamAnnotation {
	@GET
	@Produces("application/json")
	@Path("javacodegeeks/authors")
	public List getAuthor(@QueryParam("name") String name, @QueryParam("age") int age) {
		// TODO: Calculate and return list of authors which match the criteria
		// of age and name
		return null;
	}
}

2. Download the source code

This tutorial explained some of the  most important JAX-RS annotations.

Download
You can download the full source code of this example here: JAX-RS Annotations Explained

Saurabh Arora

Saurabh graduated with an engineering degree in Information Technology from YMCA Institute of Engineering, India. He is SCJP, OCWCD certified and currently working as Technical Lead with one of the biggest service based firms and is involved in projects extensively using Java and JEE technologies. He has worked in E-Commerce, Banking and Telecom domain.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Inline Feedbacks
View all comments
Back to top button