RESTEasy tutorial part two: web parameters

In the first RESTEasy tutorial we have learnt the basics about REST Web services and we have tested a simple RESTful Web service. In this tutorial we will show how to inject web application elements (form parameters, query parameters and more) into a RESTful Web service.

You can use the following annotations to bind HTTP requests to a RESTful web service:

@FormParam

@PathParam

@QueryParam

@HeaderParam

@CookieParam

@MatrixParam

@BeanParam

Let's explore all the possible interactions.

@FormParam

The annotation @FormParam can be used to inject the parameters of a Web form into a RESTful Web service.resteasy tutorial

Here's an example: we are submitting a POST request containing two parameters email and password which are translated into the parameters "e" and "p" of the login method.

<form method="POST" action="login">


Email Address: <input type="text" name="email">
<br>
Password: <input type="text" name="password">
<input type="submit">

 
</form>

public class LoginService
{

 
  @Path("login")
  @POST
  @Consumes("application/x-www-form-urlencoded")
  public String login(@FormParam("email") String e, @FormParam("password") String p) {   
   return "Logged with " + e + " " + p;
  }

}

As an alternative, you can bind the parameters email and password at class level, which can be useful if you need to re-use the same parameters across different methods of the service.

public class User {
 
  @FormParam("email")
  private String email;
  @FormParam("password")
  private String password;

}

You would need to modify the REST method accordingly:

@POST
@Path("login")
 public String login(@Form User form) {
 return "Logged with " + form.email + " " + form.password;
 }

@PathParam

The @PathParam annotation binds the value of a path segment to a resource method parameter. For example, the following method would intercept an HTTP GET like http://server:port/login/12345 and convert the PathParam "12345" into the String "id"

public class LoginService
{


  @GET
  @Path("login/{zip}")
  public String login(@PathParam("zip") String id) {
   return "Id is " +id;
  }

}

As for @FormParam, you can embed the @PathParam declaration at class level, if you prefer.

@QueryParam

The @QueryParam annotation binds the value of a path segment to a resource method parameter. For example, the following method would intercept an HTTP GET like http://server:port/login?zip=12345 and inject the query parameter "zip" into the method parameter "zip"

public class LoginService
{

 @GET
 @Path("login/{zip}")
  public String login(@QueryParam("zip") String zip) {
   return "Id is " +id;
  }

}

QueryParam can be convenientely used with the DefaultValue annotation so that you can avoid a null pointer exception if no query parameter is passed.

@GET
@Path("login/{zip}")

public String login(@DefaultValue("11111") @QueryParam("zip") String zip) {
 return "Id is " +id;
 }

As for @FormParam, you can embed the @PathParam declaration at class level, if you prefer.

@HeaderParam

The @HeaderParam annotation extracts information from the HTTP header and binds it to a method parameter. Example:

@GET
public String callService(@HeaderParam("User-Agent") String whichBrowser) {
...
}

@CookieParam

The @CookieParam annotation reads an information stored as a cookie and binds it to a method parameter. Example:

@GET

public String callService(@CookieParam("JSESSIONID") String sessionid) {

...
 }

MultivaluedMap of Parameters

Another approach for retrieving the REST Parameters is by means of the @Context annotation which allows you to inject parameters as a javax.ws.rs.core.MultivaluedMap. Here is for example how to retrieve the list of Cookies:

@GET
public String get(@Context HttpHeaders hh) {
 
    MultivaluedMap<String, String> headerParameters = hh.getRequestHeaders();
    Map<String, Cookie> params = hh.getCookies();
 
}

In the next example, we are injecting the @Context to retrieve the Query and Path parameters:

@GET
public String get(@Context UriInfo ui) {
 
    MultivaluedMap<String, String> queryParameters = ui.getQueryParameters();
    MultivaluedMap<String, String> pathParameters = ui.getPathParameters();
 
}

Actually you can inject several other resources with @Context such as javax.ws.rs.core.UriInfo, javax.ws.rs.core.Request, javax.servlet.HttpServletRequest, javax.servlet.HttpServletResponse, javax.servlet.ServletConfig, javax.servlet.ServletContext, and javax.ws.rs.core.SecurityContext objects.

@MatrixParam

The @MatrixParam annotation can be used to bind an expression containing several property=value to a method parameter. For example, supposing you were to invoke an URL like: http://server:port/login;name=francesco;surname=marchioni

@GET

public String callService(@MatrixParam("name") String name,

                                @MatrixParam("surname") String surname) {

...
 }

@BeanParam

Finally, you can use the @BeanParam annotation to map all REST parameter in a Java class which works as a "parameter aggregator".
The JAX-RS runtime will instantiate the object and inject all it's fields and properties annotated with either one of the @XxxParam annotation (@PathParam, @FormParam ...) or the @Context annotation. For the POJO classes same instantiation and injection rules apply as in case of instantiation and injection of request-scoped root resource classes.

Here is an example:

 public class ParamBean {

   @HeaderParam("myHeader")
   private String header;

   @FormParam("myData")
   private String data;

   @PathParam("id")
   public void setResourceId(String id) {...}

   ...
 }

 @Path("myresources")
 public class MyResources {
   @POST
   @Path("{id}")
   public void post(@BeanParam ParamBean bean) {...}

   ...
 }
 

 



Follow us on Twitter