JAX-RS Specifications
JAX-RS: Java API for Restful web services
It’s a Java API specification which uses Java SE 5 annotations (JSR 311 specifications) for creating web services according to the REST architectural style.
Some of the annotations provided by JAX-RS to map java class as a web Resource are listed below
@Path
Specifies the relative Path of the resource.
This relative path should be specified by the client to invoke the Rest service.
@GET,@POST,@PUT,@DELETE etc specifies HTTP methods to request a resource.
Each HTTP method specifies the action to be performed with the Rest service.
@Produces
Specifies the MIME type or data representation that service is returning to the client
MIME type could be Json,xml,pdf etc.
Rest service can return data of specified MIME type to the client.
@Consumes
Specifies the MIME type or data representation that Service can accept from the client
MIME type could be Json,xml,pdf etc.
Rest service can only accept the data of specified MIME type.
Some of the annotations used at the method parameters to get the information from the request are listed below
@PathParam
This is used to bind the @Path variable value to the method parameter.
Example:
- @Path("/userInfo")
- public class RestServicePathParamExample {
- @GET
- @Path("{name}/{country}")
- @Produces("text/html")
- public Response getUserInfo(
- @PathParam("name") String name,
- @PathParam("country") String country) {
- String userDetails = User name -> "+name+", Country -> "+country+"";
- return Response.status(200).entity(userDetails).build();
- }
- }
@Path("/userInfo")
public class RestServicePathParamExample {
@GET
@Path("{name}/{country}")
@Produces("text/html")
public Response getUserInfo(
@PathParam("name") String name,
@PathParam("country") String country) {
String userDetails = User name -> "+name+", Country -> "+country+"";
return Response.status(200).entity(userDetails).build();
}
}we have retrieved name and country from Path url using @PathParam and setting them to the method parameter.
@QueryParam
This is used to bind the query parameter value to the method parameter
Query string will be in the URL after ? as below
?firstName=Ram&lastName=Raj
firstName and lastName in the query param can bind with method parameters as below
- @Path("/userInfo")
- public class RestServiceQueryParamExample {
- @GET
- @Path("/getData")
- @Produces("application/json")
- public Student getUserInfo(@QueryParam("firstName") String firstName,
- @QueryParam("lastName") String lastName) {
- User user = new User();
- user.setFirstName(firstName);
- user.setLastName(lastName);
- return user;
- }
- }
@Path("/userInfo")
public class RestServiceQueryParamExample {
@GET
@Path("/getData")
@Produces("application/json")
public Student getUserInfo(@QueryParam("firstName") String firstName,
@QueryParam("lastName") String lastName) {
User user = new User();
user.setFirstName(firstName);
user.setLastName(lastName);
return user;
}
} we have used @QueryParam to retrieve firstName and lastName from query string passed as part of URL.
@MatrixParam
This is used to bind the value of HTTP matrix parameter to the method parameter.
We can find Matrix parameters in the URL separated by semicolon.
Example:
firstName=Ram;lastName=Raj
- @Path("/userInfo")
- public class RestServiceMatrixParamExample {
- @GET
- @Path("/getData")
- @Produces("application/json")
- public Student getUserInfo(@MatrixParam("firstName") String firstName,
- @MatrixParam("lastName") String lastName) {
- User user = new User();
- user.setFirstName(firstName);
- user.setLastName(lastName);
- return user;
- }
- }
@Path("/userInfo")
public class RestServiceMatrixParamExample {
@GET
@Path("/getData")
@Produces("application/json")
public Student getUserInfo(@MatrixParam("firstName") String firstName,
@MatrixParam("lastName") String lastName) {
User user = new User();
user.setFirstName(firstName);
user.setLastName(lastName);
return user;
}
}We have used @MatrixParam to retrieve the values passed as Matrix parameters in the URL.
@HeaderParam
This is used to bind the header value to the method parameter.
Example:
- @Path("/userInfo")
- public class RestServiceHeaderParamExample {
- @GET
- @Path("/getData")
- @Produces("application/json")
- public Student getUserInfo(@HeaderParam("accessId") String accessId) {
- User user = new User();
- user.setFirstName(firstName);
- user.setLastName(lastName);
- user.setCredential(accessId);
- return user;
- }
- }
@Path("/userInfo")
public class RestServiceHeaderParamExample {
@GET
@Path("/getData")
@Produces("application/json")
public Student getUserInfo(@HeaderParam("accessId") String accessId) {
User user = new User();
user.setFirstName(firstName);
user.setLastName(lastName);
user.setCredential(accessId);
return user;
}
}Header parameter called accessId is retrieved using @HeaderParam and setting it to the method parameter
@CookieParam
This is used to bind the cookie value to the method parameter.
Cookie is mostly used to maintain the state between the client and server.
Example:
- @Path("/userInfo")
- public class RestServiceCookieParamExample {
- @GET
- @Path("/getData")
- @Produces("application/json")
- public Student getUserInfo(@CookieParam("userName") String userName) {
- User user = new User();
- user.setUserName(userName);
- return user;
- }
- }
@Path("/userInfo")
public class RestServiceCookieParamExample {
@GET
@Path("/getData")
@Produces("application/json")
public Student getUserInfo(@CookieParam("userName") String userName) {
User user = new User();
user.setUserName(userName);
return user;
}
}We have accessed the userName stored in cookie using @CookieParam and setting it to the method parameter.
These annotations are just the specification provided by JAX-RS which does not have any implementation by itself.
Some of the Implementations of these JAX-RS annotations are as below
Jersey
RestEasy
Restlet
Apache CXF
All the above implementations provide the libraries to support the JSR 311 specifications.
We can use any one of these implementations to develop the Rest web service
