Query param List of values java
RESTful Web Services Developer's Guide
Parameters of a resource method may be annotated with parameter-based annotations to extract information from a request. A previous example presented the use of the @PathParam parameter to extract a path parameter from the path component of the request URL that matched the path declared in @Path. There are six types of parameters you can extract for use in your resource class: query parameters, URI path parameters, form parameters, cookie parameters, header parameters, and matrix parameters. Query parameters are extracted from the request URI query parameters, and are specified by using the javax.ws.rs.QueryParam annotation in the method parameter arguments. The following example (from the sparklines sample application) demonstrates using @QueryParam to extract query parameters from the Query component of the request URL. @Path("smooth") @GET public Response smooth( @DefaultValue("2") @QueryParam("step") int step, @DefaultValue("true") @QueryParam("min-m") boolean hasMin, @DefaultValue("true") @QueryParam("max-m") boolean hasMax, @DefaultValue("true") @QueryParam("last-m") boolean hasLast, @DefaultValue("blue") @QueryParam("min-color") ColorParam minColor, @DefaultValue("green") @QueryParam("max-color") ColorParam maxColor, @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor ) { ... }If a query parameter "step" exists in the query component of the request URI, then the "step" value will be extracted and parsed as a 32–bit signed integer and assigned to the step method parameter. If "step" does not exist, then a default value of 2, as declared in the @DefaultValue annotation, will be assigned to the step method parameter. If the "step" value cannot be parsed as a 32–bit signed integer, then an HTTP 400 (Client Error) response is returned. User-defined Java types such as ColorParam may be used. The following code example shows how to implement this. public class ColorParam extends Color { public ColorParam(String s) { super(getRGB(s)); } private static int getRGB(String s) { if (s.charAt(0) == '#') { try { Color c = Color.decode("0x" + s.substring(1)); return c.getRGB(); } catch (NumberFormatException e) { throw new WebApplicationException(400); } } else { try { Field f = Color.class.getField(s); return ((Color)f.get(null)).getRGB(); } catch (Exception e) { throw new WebApplicationException(400); } } } }@QueryParam and @PathParam can only be used on the following Java types:
If @DefaultValue is not used in conjunction with @QueryParam, and the query parameter is not present in the request, then value will be an empty collection for List, Set, or SortedSet; null for other object types; and the Java-defined default for primitive types. URI path parameters are extracted from the request URI, and the parameter names correspond to the URI path template variable names specified in the @Path class-level annotation. URI parameters are specified using the javax.ws.rs.PathParam annotation in the method parameter arguments. The following example shows how to use @Path variables and the @PathParam annotation in a method: @Path("/{userName}") public class MyResourceBean { ... @GET public String printUserName(@PathParam("userName") String userId) { ... } }In the above snippet, the URI path template variable name userName is specified as a parameter to the printUserName method. The @PathParam annotation is set to the variable name userName. At runtime, before printUserName is called, the value of userName is extracted from the URI and cast to a String. The resulting String is then available to the method as the userId variable. If the URI path template variable cannot be cast to the specified type, the Jersey runtime returns an HTTP 400 Bad Request error to the client. If the @PathParam annotation cannot be cast to the specified type, the Jersey runtime returns an HTTP 404 Not Found error to the client. The @PathParam parameter and the other parameter-based annotations, @MatrixParam, @HeaderParam, @CookieParam, and @FormParam obey the same rules as @QueryParam. Cookie parameters (indicated by decorating the parameter with javax.ws.rs.CookieParam) extract information from the cookies declared in cookie-related HTTP headers. Header parameters (indicated by decorating the parameter with javax.ws.rs.HeaderParam) extracts information from the HTTP headers. Matrix parameters (indicated by decorating the parameter with javax.ws.rs.MatrixParam) extracts information from URL path segments. These parameters are beyond the scope of this tutorial. Form parameters (indicated by decorating the parameter with javax.ws.rs.FormParam) extract information from a request representation that is of the MIME media type application/x-www-form-urlencoded and conforms to the encoding specified by HTML forms, as described here. This parameter is very useful for extracting information that is POSTed by HTML forms. The following example extracts the form parameter named "name" from the POSTed form data. @POST @Consumes("application/x-www-form-urlencoded") public void post(@FormParam("name") String name) { // Store the message }If it is necessary to obtain a general map of parameter names to values, use code such as that shown in the following example , for query and path parameters. @GET public String get(@Context UriInfo ui) { MultivaluedMapOr code such as the following for header and cookie parameters: @GET public String get(@Context HttpHeaders hh) { MultivaluedMapIn general @Context can be used to obtain contextual Java types related to the request or response. For form parameters it is possible to do the following: @POST @Consumes("application/x-www-form-urlencoded") public void post(MultivaluedMap
Home » Java » JAX-RS (REST) » Jersey » JAX-RS @QueryParam Example by MemoryNotFound · Published March 16, 2016 · Updated February 12, 2018
Parameters and properties annotated with @CookieParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam are represented as strings in a raw HTTP request. The specification says that any of these injected parameters can be converted to an object if the object's class has a valueOf(String) static method or a constructor that takes one Stringparameter. In the following, for example, public static class Customer { private String name; public Customer(String name) { this.name = name; } public String getName() { return name; } } @Path("test") public static class TestResource { @GET @Path("") public Response test(@QueryParam("cust") Customer cust) { return Response.ok(cust.getName()).build(); } } @Test public void testQuery() throws Exception { Invocation.Builder request = ClientBuilder.newClient().target("http://localhost:8081/test?cust=Bill").request(); Response response = request.get(); ... }the query "?cust=Bill" will be transformed automatically to an instance of Customer with name == "Bill".
What if you have a class where valueOf()or this string constructor don't exist or are inappropriate for an HTTP request? JAX-RS 2.0 has the javax.ws.rs.ext.ParamConverterProvider to help in this situation. A ParamConverterProvider is a provider defined as follows: public interface ParamConverterProvider { publicwhere a ParamConverter is defined: public interface ParamConverterFor example, consider DateParamConverterProvider and DateParamConverter: @Provider public class DateParamConverterProvider implements ParamConverterProvider { @SuppressWarnings("unchecked") @Override publicSending a Date in the form of a query, e.g., "?date=20161217" will cause the string "20161217" to be converted to a Date on the server.
In addition to the JAX-RS javax.ws.rs.ext.ParamConverterProvider, RESTEasy also has its own org.jboss.resteasy.StringParameterUnmarshaller, defined public interface StringParameterUnmarshallerIt is similar to javax.ws.rs.ext.ParamConverter except that
For example, @Retention(RetentionPolicy.RUNTIME) @StringParameterUnmarshallerBinder(TestDateFormatter.class) public @interface TestDateFormat { String value(); } public static class TestDateFormatter implements StringParameterUnmarshallerNote that the annotation @StringParameterUnmarshallerBinder on the annotation @TestDateFormat binds the formatter TestDateFormatter to a parameter annotated with @TestDateFormat. In this example, TestDateFormatter is used to format the Date parameter. Note also that the parameter "MM-dd-yyyy" to @TestDateFormat is accessible from TestDateFormatter.setAnnotations().
For parameters and properties annotated with @CookieParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam, the JAX-RS specification [https://jcp.org/aboutJava/communityprocess/final/jsr339/index.html] allows conversion as defined in the Javadoc of the corresponding annotation. In general, the following types are supported:
Items 1, 3, and 4 have been discussed above, and item 2 is obvious. Note that item 5 allows for collections of parameters. How these collections are expressed in HTTP messages depends, by default, on the particular kind of parameter. In most cases, the notation for collections is based on convention rather than a specification.
For example, a multivalued query parameter is conventionally expressed like this: In this case, there is a query with name "q" and value {1, 2, 3}. This notation is further supported in JAX-RS by the method public MultivaluedMapin javax.ws.rs.core.UriInfo.
There is no specified syntax for collections derived from matrix parameters, but
RESTEasy adopts the convention that multiple instances of a matrix parameter with the same name are treated as a collection. For example, http://bluemonkeydiamond.com/sippycup;m=1;m=2;m=3is interpreted as a matrix parameter on path segment "sippycup" with name "m" and value {1, 2, 3}.
The HTTP 1.1 specification doesn't exactly specify that multiple components of a header value should be separated by commas, but commas are used in those headers that naturally use lists, e.g. Accept and Allow. Also, note that the method public MultivaluedMapin javax.ws.rs.core.HttpHeaders returns a MultivaluedMap. It is natural, then, for RESTEasy to treat x-header: a, b, cas mapping name "x-header" to set {a, b, c}.
The syntax for cookies is specified, but, unfortunately, it is specified in multiple competing specifications. Typically, multiple name=value cookie pairs are separated by ";". However, unlike the case with query and matrix parameters, there is no specified JAX-RS method that returns a collection of cookie values. Consequently, if two cookies with the same name are received on the server and directed to a collection typed parameter, RESTEasy will inject only the second one. Note, in fact, that the method public Mapin javax.ws.rs.core.HttpHeaders returns a Map rather than a MultivaluedMap.
Deriving a collection from path segments is somewhat less natural than it is for other parameters, but JAX-RS supports the injection of multiple javax.ws.rs.core.PathSegments. There are a couple of ways of obtaining multiple PathSegments. One is through the use of multiple path variables with the same name. For example, the result of calling testTwoSegmentsArray() and testTwoSegmentsList() in @Path("") public static class TestResource { @GET @Path("{segment}/{other}/{segment}/array") public Response getTwoSegmentsArray(@PathParam("segment") PathSegment[] segments) { System.out.println("array segments: " + segments.length); return Response.ok().build(); } @GET @Path("{segment}/{other}/{segment}/list") public Response getTwoSegmentsList(@PathParam("segment") Listis array segments: 2 list segments: 2An alternative is to use a wildcard template parameter. For example, the output of calling testWildcardArray() and testWildcardList() in @Path("") public static class TestResource { @GET @Path("{segments:.*}/array") public Response getWildcardArray(@PathParam("segments") PathSegment[] segments) { System.out.println("array segments: " + segments.length); return Response.ok().build(); } @GET @Path("{segments:.*}/list") public Response getWildcardList(@PathParam("segments") Listis array segments: 3 list segments: 3
In the JAX-RS semantics, a ParamConverter is supposed to convert a single String that represents an individual object. RESTEasy extends the semantics to allow a ParamConverter to parse the String representation of multiple objects and generate a List Calling TestResource as follows, using the standard notation, @Test public void testQueryParamStandard() throws Exception { Client client = ClientBuilder.newClient(); Invocation.Builder request = client.target("http://localhost:8081/queryParam?q=20161217&q=20161218&q=20161219").request(); Response response = request.get(); System.out.println("response: " + response.readEntity(String.class)); }results in response: 20161217,20161218,20161219,Suppose, instead, that we want to use a comma separated notation. We can add public static class MultiValuedParamConverterProvider implements ParamConverterProvider @SuppressWarnings("unchecked") @Override public
Now we can call and get response: 20161217,20161218,20161219,Note that in this case, MultiValuedParamConverter.fromString() creates and returns an ArrayList, so TestResource.conversion() could be rewritten @Path("queryParam") public static class TestResource { @GET @Path("") public Response conversion(@QueryParam("q") ArrayListOn the other hand, MultiValuedParamConverter could be rewritten to return a LinkList and the parameter list in TestResource.conversion() could be either a List or a LinkedList. Finally, note that this extension works for arrays as well. For example, public static class Foo { private String foo; public Foo(String foo) {this.foo = foo;} public String getFoo() {return foo;} } public static class FooArrayParamConverter implements ParamConverter
RESTEasy includes two built-in ParamConverters in the resteasy-jaxrs module, one for Collections: org.jboss.resteasy.plugins.providers.MultiValuedCollectionParamConverter,and one for arrays: org.jboss.resteasy.plugins.providers.MultiValuedArrayParamConverter,which implement the concepts in the previous section. In particular, MultiValued*ParamConverter.fromString() can transform a string representation coming over the network into a Collection or array, and MultiValued*ParamConverter.toString() can be used by a client side proxy to transform Collections or arrays into a string representation. String representations are determined by org.jboss.resteasy.annotations.Separator, a parameter annotation in the resteasy-core module: @Target({ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) public @interface Separator { public String value() default ""; }The value of Separator.value() is used to separate individual elements of a Collection or array. For example, a proxy implementing @Path("path/separator/multi/{p}") @GET public String pathMultiSeparator(@PathParam("p") @Separator("-") Listwill turn Listand "path/separator/multi/{p}" into ".../path/separator/multi/abc-xyz". On the server side, the RESTEasy runtime will turn "abc-xyz" back into a list consisting of elements "abc" and "xyz" for @Path("path/separator/multi/{p}") @GET public String pathMultiSeparator(@PathParam("p") @Separator("-") Listwhich will return "abc|xyz|". In fact, the value of the Separator annotations may be a more general regular expression, which is passed to String.split(). For example, "[-,;]" tells the server side to break up a string using either "-", ",", or ";". On the client side, a string will be created using the first element, "-" in this case. If a parameter is annotated with @Separator with no value, then the default value is The MultiValued*ParamConverters depend on existing facilities for handling the individual elements. On the server side, once it has parsed the incoming string into substrings, MultiValued*ParamConverter turns each substring into an Java object according to Section 3.2 "Fields and Bean Properties" of the JAX-RS specification. On the client side, MultiValued*ParamConverter turns a Java object into a string as follows: These ParamConverters are meant to be fairly general, but there are a number of restrictions: There are also some logical restrictions: These built-in ParamConverters have the lowest priority, so any user supplied ParamConverters will be tried first. |