Java EE 8 MVC: Working with query parameters

In the previous post about the new Java EE MVC Framework we had a detailed look on Controllers. In this and the following posts we will see how to access various types of request data in MVC Controllers.

Java EE MVC makes heavy use of JAX-RS and most of the things we will see in this and the next posts are JAX-RS features. So, if you are familiar with JAX-RS you probably will not learn much new in this post.

Query parameters

This post focuses on query parameters. If you read my Java EE MVC Getting started post you might already know the @QueryParam annotation. The most common use case of  @QueryParam is to map a query parameter to a controller method parameter.

For example:

@Controller
@Path("query-params")
public class QueryParamsController {

  @GET
  public String queryParams(@QueryParam("name") String name) {
    ...
  }
}

If we now send a HTTP GET request to

/query-params?name=john

the string "john" will be passed as name parameter to the method queryParams().

Type conversion

With @QueryParam query parameters can automatically be converted to various types.

For example:

public enum Role {
  admin, reporter, accountant
}

@Controller
@Path("query-params")
public class QueryParamsController {

  @GET
  public String queryParams(
      @QueryParam("id") long id,
      @QueryParam("name") String name,
      @QueryParam("role") Role role) {

    ...
  }
}

We can now send a request like this:

/query-params?id=42&name=john&role=admin

A query parameter can automatically converted to a type, if the target type matches one of the following rules:

• It is a primitive type
• The type has a constructor that accepts a single String argument
• The type has a static factory method named valueOf() or fromString() with a single String argument
• The type is List<T>, Set<T>; or SortedSet<T> where T matches one of the previous rules

In the previous example, the query parameter id is automatically converted to long. If the id parameter is missing or a conversion to long is not possible, an exception will be thrown. It is also possible to use Long instead of long. In this case, we get null passed to the controller method if the id parameter is missing.

Enums have a valueOf() method by default. So, the query parameter role can automatically be converted to the corresponding enum value.

Using @QueryParam on fields and methods

@QueryParam is not limited to method parameters. It is also possible to map query parameters to fields or methods, like the following example shows:

@Controller
@Path("query-params-fields")
public class QueryParamsFieldController {

  @QueryParam("id")
  private Long id;

  @QueryParam("role")
  private Role role;

  private String name;

  @QueryParam("name")
  public void setName(String name) {
    this.name = name;
  }
  
  @GET
  public String queryParams() {
    // use id, role and name
  }
}

If we now send a HTTP GET request to

/query-params-fields?name=john&id=42&role=reporter

the parameters are set to the fields id, role and name (via setName()) before queryParams() is called.

Do not forget that a new instance of the class is created for every request, so it is safe to have fields that contain request information.

Quick Summary

The @QueryParam annotation can be used to obtain query parameters. @QueryParam can be used on fields, methods and method parameters. Query parameters can be automatically converted to various types, as long as the target type is a primitive type, contains a String constructor or contains valueOf() or fromString() factory methods.

You can find the source code for all the shown examples on GitHub.

In the next post we will see how to work with path parameters.