Code Destine

In JAX-RS @MatrixParam annotation is used to bind matrix parameter value defined in the @Path ( URL ) expression to the method arguments.

Matrix parameters are a set of “name=value” pairs separated by a semi colon “;” in URI path, for example :-

URL :- <base URL>/books/query;from=10;to=100;orderBy=books

Let’s try to understand it with an example.

Example 1 :-

In this example of JAX-RS @MatrixParam, we will send two query parameters ( from and to ) in the @Path expression books/query. If we hit this URL <base URL>/books/query;from=10;to=100, The value 10 and 100 will get copy into @MatrixParam(“from”) int fromBook and @MatrixParam(“to”) int toBook variable.

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.MediaType;
import javax.ws.rs.core.Response;

@Path("books")
public class MatrixParamExample {

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   @Path("/query")
   public Response getListOfBooks(@MatrixParam("from") int fromBook,@MatrixParam("to") int toBook){  		
       return Response.status(200)
		      .entity("Books from " + fromBook + " to " + toBook).build();
   }
	
}

Result :-

Example 2 :-

In this example, we will send one parameter ( orderBy ) two times in the @Path expression books/query. If we hit this URL <base URL>/books/query;orderBy=books;orderBy=chapters, The values will get copy into @MatrixParam(“orderBy”) String orderBy variable as a List.

import java.util.List;

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.MediaType;
import javax.ws.rs.core.Response;

@Path("books")
public class MatrixParamExample {

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   @Path("/query")
   public Response getListOfBooksOrderBy(@MatrixParam("orderBy") List<String> orderBy) {
	String order = orderBy.stream().reduce( (x,y) -> x + " , " + y ).get();
	return Response.status(200)
 		       .entity("List of Books order by : " + order).build();
   }
	
}

Result :-

Example 3 :-

In this example, we will send two query parameters ( from and to ) in the @Path expression books/query. Here, @DefaultValue annotation is used, if values of matrix parameter are not sent in the URL. Then default values will be bind with the method arguments. 

import javax.ws.rs.DefaultValue;
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.MediaType;
import javax.ws.rs.core.Response;

@Path("books")
public class MatrixParamExample {

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   @Path("/query")
   public Response getListOfBooksDefaultValue(@DefaultValue("0") @MatrixParam("from") int fromBook,
   		    @DefaultValue("10") @MatrixParam("to") int toBook){
       return Response.status(200)
	 	      .entity("Books from " + fromBook + " to " + toBook).build();
   }
	
}

Result :-

References :-

1. @MatrixParam Java Docs
2. @DefaultValue Java Docs

That’s all for JAX-RS @MatrixParam with Example. If you liked it, please share your thoughts in comments section and share it with others too.