@MatrixParam with example


What is @MatrixParam ?

It is the annotation defined in JAX-RS specification which is used to resolve the values passed in the URL with the Key-Value pair.

Each key value pair will be separated by semicolon(;)

This annotation will be used at the method argument level.

We should use the key with @MatrixParam annotation to resolve the actual value associated for that key.

Example:

http://sample.com/user;name=john

In this example, ‘name’ is passed as a key value pair.

For the above example, we can use @MatrixParam in method argument as below

(@MatrixParam(“name”) String name)

http://sample.com/user;name=john;age=45

In this example, “name” and “age” are passed as key value pairs.

For the above example, we can use @MatrixParam in method argument as below

(@MatrixParam(“name”) String name, @MatrixParam(“age”) String age)

Let’s see the complete example on this

Create a new Maven Web project in eclipse (Refer Rest service Hello World project for the same)

Project structure

Matrix_param_proj_structure

Step 1

Update pom.xml with below dependencies

  1. <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  2.   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  3.   <modelVersion>4.0.0</modelVersion>
  4.   <groupId>MatrixParam</groupId>
  5.   <artifactId>MatrixParam</artifactId>
  6.   <packaging>war</packaging>
  7.   <version>0.0.1-SNAPSHOT</version>
  8.   <name>MatrixParam Maven Webapp</name>
  9.   <url>http://maven.apache.org</url>
  10.   <dependencies>
  11.     <dependency>
  12.       <groupId>junit</groupId>
  13.       <artifactId>junit</artifactId>
  14.       <version>3.8.1</version>
  15.       <scope>test</scope>
  16.     </dependency>
  17.     <dependency>
  18.     <groupId>org.glassfish.jersey.containers</groupId>
  19.     <artifactId>jersey-container-servlet</artifactId>
  20.     <version>2.24</version>
  21. </dependency>
  22.   </dependencies>
  23.   <build>
  24.     <finalName>MatrixParam</finalName>
  25.   </build>
  26. </project>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>MatrixParam</groupId>
  <artifactId>MatrixParam</artifactId>
  <packaging>war</packaging>
  <version>0.0.1-SNAPSHOT</version>
  <name>MatrixParam Maven Webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet</artifactId>
    <version>2.24</version>
</dependency>
  </dependencies>
  <build>
    <finalName>MatrixParam</finalName>
  </build>
</project>

We have added dependencies for Jersey servlet and Junit in the above pom file.

Step 2

Update web.xml file with Jersey servlet container

  1. <!DOCTYPE web-app PUBLIC
  2.  "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  3.  "http://java.sun.com/dtd/web-app_2_3.dtd" >
  4.  
  5. <web-app>
  6.   <display-name>Archetype Created Web Application</display-name>
  7.   <servlet>
  8.         <servlet-name>jersey-serlvet</servlet-name>
  9.          <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
  10.         <init-param>
  11.             <param-name>jersey.config.server.provider.packages</param-name>
  12.             <param-value>com.kb.rest</param-value>
  13.         </init-param>
  14.         <load-on-startup>1</load-on-startup>
  15.     </servlet>
  16.  
  17.     <servlet-mapping>
  18.         <servlet-name>jersey-serlvet</servlet-name>
  19.         <url-pattern>/rest/*</url-pattern>
  20.     </servlet-mapping>
  21. </web-app>
<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
  <display-name>Archetype Created Web Application</display-name>
  <servlet>
		<servlet-name>jersey-serlvet</servlet-name>
		 <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
		<init-param>
			<param-name>jersey.config.server.provider.packages</param-name>
			<param-value>com.kb.rest</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>

	<servlet-mapping>
		<servlet-name>jersey-serlvet</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>
</web-app>

we have defined a special servlet called “jersey-serlvet” in web.xml and mapped it by the URL pattern /rest/*
Any request matching the above pattern will be handled by jersey Servlet.

Step 3

Create MatrixParamUserService as below

  1. package com.kb.rest;
  2.  
  3. import javax.ws.rs.GET;
  4. import javax.ws.rs.MatrixParam;
  5. import javax.ws.rs.Path;
  6. import javax.ws.rs.Produces;
  7. import javax.ws.rs.core.Response;
  8.  
  9. @Path("/user")
  10. public class MatrixParamUserService {
  11.    
  12.     @GET
  13.     @Produces("text/html")
  14.     public Response getUserByName(@MatrixParam("name") String name){
  15.            
  16.         String output =null;
  17.         //Service call to Get user Data based on id from DB
  18.         if(null !=name){
  19.          output ="user details for Name: "+name+ ", state : New jersey,Country:USA,age:45";
  20.         }
  21.         else{
  22.             output="Sorry user not found !";
  23.            
  24.         }
  25.        
  26.         return Response.status(200).entity(output).build();
  27.     }
  28.  
  29.     @Path("/details")
  30.     @GET
  31.     @Produces("text/html")
  32.     public Response getUserByNameAndAge(@MatrixParam("name") String name,@MatrixParam("age") String age){
  33.            
  34.         //Service call to Get user Data based on name and state from DB
  35.         String output ="user details : Name:John, state : New jersey,Country:USA,age:45";
  36.        
  37.         return Response.status(200).entity(output).build();
  38.     }
  39. }
package com.kb.rest;

import javax.ws.rs.GET;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("/user")
public class MatrixParamUserService {
	
	@GET
	@Produces("text/html")
	public Response getUserByName(@MatrixParam("name") String name){
			
		String output =null;
		//Service call to Get user Data based on id from DB
		if(null !=name){
		 output ="user details for Name: "+name+ ", state : New jersey,Country:USA,age:45";
		}
		else{
			output="Sorry user not found !";
			
		}
		
        return Response.status(200).entity(output).build();
	}

	@Path("/details")
	@GET
	@Produces("text/html")
	public Response getUserByNameAndAge(@MatrixParam("name") String name,@MatrixParam("age") String age){
			
		//Service call to Get user Data based on name and state from DB
		String output ="user details : Name:John, state : New jersey,Country:USA,age:45";
		
        return Response.status(200).entity(output).build();
	}
}

In this service, we have written 2 methods, one will get the user details based on “name” and other will get the user details based on “name” and “age”

In the first method,
We are passing “name” as a key value pair to get the user details.

In the second method,
We are passing name and age as a key value pairs to get the user details

Step 4

Build and deploy the project

Step 5

Let’s see the output

Access below URL
http://localhost:8080/MatrixParam/rest/user

Matrix_param_output_1

In the above URL request, we are not passing any matrix parameters and hence they will be null in the method and hence appropriate error message is shown.

Access below URL
http://localhost:8080/MatrixParam/rest/user;name=john

Matrix_param_output_2

Access below URL
http://localhost:8080/MatrixParam/rest/user/details;name=john;age=45

Matrix_param_output_3

Download this project MatrixParam.zip

About the Author

Raj
Founder of javainsimpleway.com
I love Java and open source technologies and very much passionate about software development.
I like to share my knowledge with others especially on technology 🙂
I have given all the examples as simple as possible to understand for the beginners.
All the code posted on my blog is developed,compiled and tested in my development environment.
If you find any mistakes or bugs, Please drop an email to kb.knowledge.sharing@gmail.com

Connect with me on Facebook for more updates

Share this article on