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

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.

Here's an example:

Here 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.

Here's the full example:

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

2. 

3.Email Address: <input type="text" name="email">

4.<br>

5.Password: <input type="text" name="password">

6.<input type="submit">

7. 

8.</form>

01.@Path("/")

02.public class LoginService

03.{

04. 

05. 

06.@Path("login")

07.@POST

08.public String login(@FormParam("email") String e, @FormParam("password") String p) {  

09.return "Logged with " + e + " " + p;

10.}

11.}

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.

1.public class User {

2. 

3.@FormParam("email")

4.private String email;

5.@FormParam("password")

6.private String password;

7. 

8.}

You would need to modify the REST method accordingly:

1.@POST

2.@Path("login")

3.public String login(@Form User form) {

4.return "Logged with " + form.email + " " + form.password;

5.}

@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"

01.@Path("/")

02.public class LoginService

03.{

04. 

05.@GET

06.@Path("login/{zip}")

07.public String login(@PathParam("zip") String id) {

08.return "Id is " +id;

09.}

10.}

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"

01.@Path("/")

02.public class LoginService

03.{

04. 

05.@GET

06.@Path("login/{zip}")

07.public String login(@QueryParam("zip") String zip) {

08.return "Id is " +id;

09.}

10. 

11.}

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

1.@GET

2.@Path("login/{zip}")

3.public String login(@DefaultValue("11111") @QueryParam("zip") String zip) {

4.return "Id is " +id;

5.}

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:

1.@GET

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

3....

4.}

@CookieParam

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

1.@GET

2.public String callService(@CookieParam("sessionid") String sessionid) {

3....

4.}

@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

1.@GET

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

3.@MatrixParam("surname") String surname) {

4....

5.}

<