Parameters are used to pass and add additional information to a request. You can use parameters as part of the URL or in the headers. Path parameters, matrix parameters, query parameters, header parameters, and cookie parameters are useful for passing in additional information to a request.
Multiple parameter types exist. Java API for RESTful Web Services (JAX-RS) enables easy access to all the types of parameters using annotated injected parameters.
You can use any basic Java primitive type including java.lang.String as parameters, as well as Java types with a constructor that uses a single String or a valueOf(String) static method. Additionally, you can use List, SortedSet, and Set interfaces where the generic type is one of the previously mentioned types, such as a Set when a parameter can have multiple values. If you need to parse requests, then use String as the parameter type to enable you to complete basic inspection and customization of error path responses.
JAX-RS provides the following annotations to use on resource method parameters to specify that the resource method can be invoked with correct parameter values.
Path parameters are part of the URL. For example, the URL can include /collection/{item}, where {item} is a path parameter that identifies the item in the collection. Because path parameters are part of the URL, they are essential in identifying the request.
@javax.ws.rs.Path(“/bookstore/books/{bookId}”) public class BooksCollection { @javax.ws.rs.GET public String getSpecificBookInfo(@javax.ws.rs.PathParam(“bookId”) String theBookId) { /* theBookId would contain the next path segment after /bookstore/books/ */ } }In this example, requests to /bookstore/books/12345 assigns the value of 12345 to the theBookId variable.
Matrix parameters are part of the URL. For example, if the URL includes the path segment, /collection;itemID=itemIDValue, the matrix parameter name is itemID and itemIDValue is the value.
@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.MatrixParam(“page”) int page, @javax.ws.rs.MatrixParam(“filter”) String filter) { /* This statement uses the page and filter parameters. */ } }In this example, requests to/bookstore/books;page=25;filter=test invoke the getBookCollectionInfo parameter so that the value for the page variable is set to 25 and the value for filter variable is set to test.
Query parameters are appended to the URL after a “?” with name-value pairs. For instance, if the URL is http://example.com/collection?itemID=itemIDValue, the query parameter name is itemID and itemIDValue is the value. Query parameters are often used when filtering or paging through HTTP GET requests.
@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.QueryParam(“page”) int page, @javax.ws.rs.QueryParam(“filter”) String filter) { /* This statement uses the page and filter parameters. */ } }In this example, requests to/bookstore/books;page=25;filter=test invoke the getBookCollectionInfo parameter so that the value for the page variable is set to 25 and the value for filter variable is set to test.
Header parameters are HTTP headers. While there are pre-defined HTTP headers, you can also use custom headers. Headers often contain control metadata information for the client, intermediary, or server.
@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.HeaderParam(“Range”) String rangeValue) { /* The rangeValue variable contains the value of the HTTP request header "Range" */ } }
In this example, requests to /bookstore/books/ with a Range HTTP request header value of bytes=0-499 invokes the method with bytes=0-499 as the value for the rangeValue variable.
Cookie parameters are special HTTP headers. While cookies are associated with storing session identification or stateful data that is not accepted as RESTful, cookies can contain stateless information.
@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.CookieParam(“mycustomid”) String mycustomid) { /* The cookie value is passed to the mycustomid variable. */ } }
Form parameters are used when submitting a HTML form from a browser with a media type of application/x-www-form-urlencoded. The form parameters and values are encoded in the request message body in the form like the following: firstParameter=firstValue&secondParameter=secondValue. The javax.ws.rs.FormParam annotation enables easy access to individual form parameter values.
@javax.ws.rs.Path(“/customer”) public class Custommer { @javax.ws.rs.POST public String postCustomerInfo(@javax.ws.rs.FormParam(“firstName”) String firstName, @javax.ws.rs.FormParam("lastName") String lastName) { /* firstName would be "Bob" and secondName would be "Smith" */ } }
@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.POST public String postSpecificBookInfo(@javax.ws.rs.FormParam(“bookId”) String theBookId, String theRequestEntity) { /* This code is invalid. Can only use FormParam or a request entity parameter like "String theRequestEntity" and not both */ } }gotcha
Choose one of the following ways to define variables to read parameters.
Your resource methods are defined so that they can be invoked with appropriate parameter values.
In this information ...Related tasks
| IBM Redbooks, demos, education, and more(Index) |