Course – LS (cat=REST)

Get started with Spring and Spring Boot, through the reference Learn Spring course:


1. Introduction

Jersey is a popular Java framework for creating RESTful web services.

In this tutorial, we’ll explore how to read different request parameter types via a simple Jersey project.

2. Project Setup

Using Maven archetypes, we’ll be able to generate a working project for our article:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2
  -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false
  -DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example

The generated Jersey project will run on top of a Grizzly container.

Now, by default, the endpoint for our app will be http://localhost:8080/myapp.

Let’s add an items resource, which we’ll use for our experiments:

public class ItemsController {
    // our endpoints are defined here

Note, by the way, that Jersey also works great with Spring controllers.

3. Annotated Parameters Types

So, before we actually read any request parameters, let’s clarify a few rules. The allowed types of parameters are:

  • Primitive types, like float and char
  • Types that have a constructor with a single String argument
  • Types that have either a fromString or valueOf static method; for those, a single String argument is mandatory
  • Collections – like List, Set, and SortedSet – of the types described above

Also, we can register an implementation of the ParamConverterProvider JAX-RS extension SPI. The return type must be a ParamConverter instance capable of a conversion from a String to a type.

We can resolve cookie values in our Jersey methods using the @CookieParam annotation:

public String jsessionid(@CookieParam("JSESSIONId") String jsessionId) {
    return "Cookie parameter value is [" + jsessionId+ "]";
If we start up our container, we can cURL this endpoint to see the response:
> curl --cookie "JSESSIONID=5BDA743FEBD1BAEFED12ECE124330923" http://localhost:8080/myapp/items
Cookie parameter value is [5BDA743FEBD1BAEFED12ECE124330923]

5. Headers

Or, we can resolve HTTP headers with the @HeaderParam annotation:

public String contentType(@HeaderParam("Content-Type") String contentType) {
    return "Header parameter value is [" + contentType+ "]";

Let’s test again:

> curl --header "Content-Type: text/html" http://localhost:8080/myapp/items
Header parameter value is [text/html]

6. Path Parameters

Especially with RESTful APIs, it’s common to include information in the path.

We can extract path elements with @PathParam:

public String itemId(@PathParam("id") Integer id) {
    return "Path parameter value is [" + id + "]";

Let’s send another curl command with the value 3:

> curl http://localhost:8080/myapp/items/3
Path parameter value is [3]

7. Query Parameters

We commonly use query parameters in RESTful APIs for optional information.

To read such values we can use the @QueryParam annotation:

public String itemName(@QueryParam("name") String name) {
    return "Query parameter value is [" + name + "]";

So, now we can test with curl, like before:

> curl http://localhost:8080/myapp/items?name=Toaster
Query parameter value if [Toaster]

8. Form Parameters

For reading parameters from a form submission, we’ll use the @FormParam annotation:
public String itemShipment(@FormParam("deliveryAddress") String deliveryAddress, 
  @FormParam("quantity") Long quantity) {
    return "Form parameters are [deliveryAddress=" + deliveryAddress+ ", quantity=" + quantity + "]";

We also need to set the proper Content-Type to mimic the form submission action. Let’s set the form parameters using the -d flag:

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  -d 'deliveryAddress=Washington nr 4&quantity=5' \
Form parameters are [deliveryAddress=Washington nr 4, quantity=5]

9. Matrix Parameters

A matrix parameter is a more flexible query parameter as they can be added anywhere in the URL.

For example, in http://localhost:8080/myapp;name=value/items, the matrix parameter is name.

To read such values, we can use the available @MatrixParam annotation:

public String itemColors(@MatrixParam("colors") List<String> colors) {
    return "Matrix parameter values are " + Arrays.toString(colors.toArray());

And now we’ll test again our the endpoint:

> curl http://localhost:8080/myapp/items;colors=blue,red
Matrix parameter values are [blue,red]

10. Bean Parameters

Finally, we’ll check how to combine request parameters using bean parameters. To clarify, a bean parameter is actually an object that combines different types of request parameters.

We’ll use a header parameter, a path and a form one in here:

public class ItemOrder {
    private String coupon;

    private Long itemId;

    private Double total;

    //getter and setter

    public String toString() {
        return "ItemOrder {coupon=" + coupon + ", itemId=" + itemId + ", total=" + total + '}';

Also, to get such a combination of parameters, we’ll use the @BeanParam annotation:

public String itemOrder(@BeanParam ItemOrder itemOrder) {
    return itemOrder.toString();

In the curl command, we’ve added those three types of parameters and we’ll end up with a single ItemOrder object:

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  --header 'coupon:FREE10p' \
  -d total=70 \
ItemOrder {coupon=FREE10p, itemId=28711, total=70}

11. Conclusion

To sum it up, we’ve created a simple setup for a Jersey project to help us explore how to read different parameters from a request using Jersey.

The implementation of all these snippets is available over on Github.

Course – LS (cat=REST)

Get started with Spring and Spring Boot, through the Learn Spring course :

res – REST (eBook) (cat=REST)
Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.