JAX-RS @MatrixParam Example with RESTEasy 3

By Arvind Rai, June 05, 2016
On this page we will provide JAX-RS @MatrixParam example with RESTEasy 3. @MatrixParam binds the matrix parameter to a method parameter, class field or bean property in a REST web service to consume client request using matrix URI. @MatrixParam value will be same as the key of matrix parameter in matrix URI. @MatrixParam and @QueryParam can be used together. @MatrixParam will access matrix parameter and @QueryParam will access query string. Find the example of @MatrixParam using RESTEasy 3.

Matrix URI

A Matrix URI is separated by (;) and (=) in the way as given below.

/application/employee/detail;name=mohan;age=37

The above Matrix URL is equivalent to below Query String.

/application/employee/detail?name= mohan&age=37

The matrix URL can be written anywhere within the URI, not necessarily at the end of URI. All the below URIs are same.

1. /application/employee/detail;name=mohan;age=37
2. /application/employee;name=mohan;age=37/detail
3. /application/employee;name=mohan/detail;age=37

Query string cam also be used with matrix URI as give below.

/application/employee;name= mohan/fulldetail;age=37?location=Varanasi

@MatrixParam in RESTEasy 3 Service

To read matrix URI in JAX-RS, it provides @MatrixParam annotation. Here we are creating a REST web service using RESTEasy 3.
EmployeeService.java
package com.concretepage;
import java.util.HashMap;
import java.util.Map;
import javax.ws.rs.GET;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Response;
import org.jboss.resteasy.annotations.providers.jackson.Formatted;
@Path("/employee")
public class EmployeeService {
    @GET
    @Path("/detail")
    @Produces("application/json")
    @Formatted
    public Response detail(@MatrixParam("name") String name, @MatrixParam("age") Integer age) {
    	Map<String,String> map = new HashMap<String,String>();
    	map.put("name", name);
    	map.put("age", String.valueOf(age));
        return Response.ok(map).build();
    }
    @GET
    @Path("/fulldetail")
    @Produces("application/json")
    @Formatted
    public Response fulldetail(@MatrixParam("name") String name, @MatrixParam("age") Integer age,
    		@QueryParam("location") String location) {
    	Map<String,String> map = new HashMap<String,String>();
    	map.put("name", name);
    	map.put("age", String.valueOf(age));
    	map.put("location", location);
        return Response.ok(map).build();
    }    
 } 

JAX-RS Application Class

EmployeeApplication.java
package com.concretepage;
import java.util.HashSet;
import java.util.Set;
import javax.ws.rs.core.Application;
public class EmployeeApplication extends Application {
    private Set<Object> singletons = new HashSet<Object>();
    public EmployeeApplication() {
        singletons.add(new EmployeeService());
    }
    @Override
    public Set<Object> getSingletons() {
        return singletons;
    }
} 

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
                 http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <context-param>
        <param-name>resteasy.servlet.mapping.prefix</param-name>
        <param-value>/application</param-value>
    </context-param>
    <servlet>
        <servlet-name>RESTEasyService</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.concretepage.EmployeeApplication</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>RESTEasyService</servlet-name>
        <url-pattern>/application/*</url-pattern>
    </servlet-mapping>
</web-app> 

build.gradle
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'war'
archivesBaseName = 'concretepage'
version = '1' 
repositories {
    mavenCentral()
}
dependencies {
	compile 'org.jboss.resteasy:resteasy-jaxrs:3.0.10.Final'
	compile 'org.jboss.resteasy:resteasy-jackson2-provider:3.0.10.Final'
}  

Output

To run the application, create WAR file and deploy in tomcat. When we access any of the URL
1.
http://localhost:8080/concretepage-1/application/employee/detail;name=mohan;age=37
2.
http://localhost:8080/concretepage-1/application/employee;name=mohan;age=37/detail
3.
http://localhost:8080/concretepage-1/application/employee;name=mohan/detail;age=37

We will get output as given below.
{
  "name" : "mohan",
  "age" : "37"
} 
And when we run the URL with matrix URI and query string together using the URL
http://localhost:8080/concretepage-1/application/employee;name=mohan/fulldetail;age=37?location=varanasi

We will get the output as given below.
{
  "name" : "mohan",
  "location" : "varanasi",
  "age" : "37"
} 

References

Matrix URIs
URL matrix parameters vs. request parameters

Download Source Code

POSTED BY
ARVIND RAI
ARVIND RAI







©2024 concretepage.com | Privacy Policy | Contact Us