RESTful Web Services @QueryParam Example using JAX-RS and Jersey

@QueryParam Example

In this example we are going to develop a simple RESTful web service using JAX-RS and Jersey to extract query parameters from the request URL using the @QueryParam annotation.

This rest service uses the same methods we developed in the last tutorial, RESTful Web Services @PathParam Example, which calculates square root of a number by extracting the value from the path using @QueryParam annotation. The thing that differentiates this tutorial from the last is that we have also added a calcSumAllValues method that extracts a List of @QueryParam values from the request URL.

The basic format of Query parameters in request URL is:

As you can see from the above request URL, this particular web service call will pass in three parameters; first one is name with a value of Alex, age with a value of 22, and state with a value of Ohio.

@QueryParam can be used only on the following Java types:

• All primitive types except char
• All wrapper classes of primitive types except Character
• Any class with a constructor that accepts a single Stringargument
• Any class with the static method named valueOf(String) that accepts a single Stringargument
• Any class with a constructor that takes a single String as a parameter
• List<T>, Set<T>, or SortedSet<T>, where T matches the already listed criteria

Getting Started

In order to run this tutorial yourself, you will need the following:

• Java JDK 1.6 or greater
• Favorite IDE Spring Tool Suite (STS), Eclipse IDE or NetBeans (I happen to be using STS because it comes with a Tomcat server built-in)
• Tomcat 7 or greater or other popular container (Weblogic, Websphere, Glassfish, JBoss, VMWare vFabric, etc). For this tutorial I am using VMware vFabric tc Server Developer Edition which is essentially an enhanced Tomcat instance integrated with Spring STS
• Jersey JAX-RS
• log4J (for logging purposes)

Required Libraries

Copy all of the following jars to WebContent->WEB-INF->lib folder.

asm-3.1.jar
jersey-client-1.18.jar
jersey-core-1.18.jar
jersey-json-1.18.jar
jersey-server-1.18.jar
jersey-servlet-1.18.jar
jsr311-api-1.1.1.jar
log4j-1.2.17.jar

Complete Project Overview

I have added the project overview to give you a full view of the structure and show you all files contained in this sample project.

RESTful Web Service End Points

Using the @QueryParam in JAX-RS API

Single @QueryParam Parameter

In this example we show you how to extract a single query parameter from the request URL.

@GET
@Path("/squareroot")
@Produces(MediaType.TEXT_HTML)
public Response calcSqrt(@QueryParam("value") int value) {

  double answer = Math.sqrt(value);
  String msg = String.format("calcSqrt==> value: %d, answer: %10.4f", value, answer);
  logger.info(msg);
    
  return Response.status(200).entity(msg).build();
}

Multiple @QueryParam Parameters

In this example we show you how to extract a multiple query parameters from the request URL.

@GET
@Path("/add")
@Produces(MediaType.TEXT_HTML)
public Response calcAddTwoValues(@QueryParam("value1")  double value1, 
                                 @QueryParam("value2")  double value2) {

  double answer = value1 + value2;
  String msg = String.format("calcAddTwoValues==> value1: %10.4f, value2: %10.4f, answer: %10.4f", 
                              value1, value2, answer);
  logger.info(msg);
    
  return Response.status(200).entity(msg).build();
}

Using List, Set, SortedSet with @QueryParam Parameter

In this example we show you how to extract a List of @QueryParam values from the request URL. You could quite as easily use Set or Sorted as well. By using the List<Integer> values it will automatically be converted into the List collection for us.

@GET
@Path("/sum")
@Produces(MediaType.TEXT_HTML)
public Response calcSumAllValues(@QueryParam("values") List<Integer> values) {

  double answer = 0;
  for (int v: values) {
    answer += v;
  }
  String msg = String.format("calcSumAllValues==> values: %s, answer: %10.4f", 
                             values.toString(), answer);
  logger.info(msg);
    
  return Response.status(200).entity(msg).build();
}

Complete Program using @QueryParam

package com.avaldes;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.apache.log4j.Logger;

@Path("/calculate")
public class RestfulQueryParamExample {
  static Logger logger = Logger.getLogger(RestfulQueryParamExample.class);
  
  @GET
  @Path("/squareroot")
  @Produces(MediaType.TEXT_HTML)
  public Response calcSqrt(@QueryParam("value") int value) {

    double answer = Math.sqrt(value);
    String msg = String.format("calcSqrt==> value: %d, answer: %10.4f", value, answer);
    logger.info(msg);
    
    return Response.status(200).entity(msg).build();
  }
  
  @GET
  @Path("/add")
  @Produces(MediaType.TEXT_HTML)
  public Response calcAddTwoValues(@QueryParam("value1")  double value1, 
                                   @QueryParam("value2")  double value2) {

    double answer = value1 + value2;
    String msg = String.format("calcAddTwoValues==> value1: %10.4f, value2: %10.4f, answer: %10.4f", 
                  value1, value2, answer);
    logger.info(msg);
    
    return Response.status(200).entity(msg).build();
  }
  
  @GET
  @Path("/sub")
  @Produces(MediaType.TEXT_HTML)
  public Response calcSubTwoValues(@QueryParam("value1")  double value1, 
                                   @QueryParam("value2")  double value2) {

    double answer = value1 - value2;
    String msg = String.format("calcSubTwoValues==> value1: %10.4f, value2: %10.4f, answer: %10.4f", 
                  value1, value2, answer);
    logger.info(msg);
    
    return Response.status(200).entity(msg).build();
  }

  @GET
  @Path("/sum")
  @Produces(MediaType.TEXT_HTML)
  public Response calcSumAllValues(@QueryParam("values") List<Integer> values) {

    double answer = 0;
    for (int v: values) {
      answer += v;
    }
    String msg = String.format("calcSumAllValues==> values: %s, answer: %10.4f", 
                  values.toString(), answer);
    logger.info(msg);
    
    return Response.status(200).entity(msg).build();
  }
}

Web Deployment Descriptor (web.xml)

This is a pretty straight forward deployment descriptor file – only thing you need to add is the location of you java package in the Jersey ServletContainer entry as init-param. Please ensure you add it to the web.xml file as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
  <display-name>com.omega.rest</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>
  
  <servlet>
 
   <servlet-name>Jersey REST Service</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>com.sun.jersey.config.property.packages</param-name>
      <param-value>com.avaldes</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>Jersey REST Service</servlet-name>
    <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>
</web-app>

Testing out the Web Services

In this example, we add two numbers using the web service using multiple @QueryParam parameters.

This next example we calculate the sum of all values in a repeating list of values using @QueryParam parameter.

That’s It!

I hope you enjoyed this tutorial. It was certainly a lot of fun putting it together and testing it out. Please continue to share the love and like us so that we can continue bringing you quality tutorials. Happy Coding!!!

Please Share Us on Social Media