在 RESTful 应用程序中定义资源的请求表示的参数
参数用来将附加信息传递和添加到请求。您可以使用参数作为 URL 的组成部分,也可以在头中使用参数。路径参数、矩阵参数、查询参数、头参数和 Cookie 参数对于将附加的信息传递给请求而言都非常有用。
关于此任务
存在多种参数类型。Java™ API for RESTful Web Services (JAX-RS) 使您能够使用注入的注释式参数轻松地访问所有类型的参数。
您可以使用任何基本 Java 基本类型(包括 java.lang.String)作为参数,也可以使用具有使用单一字符串或 valueOf(字符串)静态方法的构造函数的 Java 类型。另外,还可以使用 List、SortedSet 和 Set 接口,在这些接口中,通用类型是上面提到的其中一种类型,例如在参数可以具有多个值时使用的 Set。如果需要解析请求,请使用 String 作为参数类型,以便完成错误路径响应的基本检查和定制。
JAX-RS 提供了下列用于资源方法参数的注释,以指定可使用正确的参数值来调用资源方法。
- javax.ws.rs.PathParam 注释
路径参数是 URL 的组成部分。例如,URL 可以包含 /collection/{item},其中 {item} 用于标识集合中的项的路径参数。因为路径参数是 URL 的组成部分,所以对于标识请求而言至关重要。
如果 URL 包含参数,那么您可以使用 @javax.ws.rs.PathParam 所注释的参数;例如:
在此示例中,对 /bookstore/books/12345 的请求将值 12345 赋予 theBookId 变量。@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/ */ } }
- javax.ws.rs.MatrixParam 注释
矩阵参数是 URL 的组成部分。例如,如果 URL 包含路径段 /collection;itemID=itemIDValue,那么矩阵参数名是 itemID,并且值为 itemIDValue。
您可以使用注释式参数 @javax.ws.rs.MatrixParam 来读取矩阵参数;例如:
在此示例中,对 /bookstore/books;page=25;filter=test 的请求将调用 getBookCollectionInfo 参数,以便将 page 变量的值设置为 25,并将 filter 变量的值设置为 test。@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. */ } }
- javax.ws.rs.QueryParam 注释
查询参数通过名/值对追加到 URL 中的“?”之后。例如,如果 URL 是 http://example.com/collection?itemID=itemIDValue,那么查询参数名是 itemID,并且值为 itemIDValue。查询参数通常在您对 HTTP GET 请求进行过滤或翻页时使用。
您可以使用注释式参数 @javax.ws.rs.QueryParam 来读取查询参数;例如:
在此示例中,对 /bookstore/books;page=25;filter=test 的请求将调用 getBookCollectionInfo 参数,以便将 page 变量的值设置为 25,并将 filter 变量的值设置为 test。@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. */ } }
- javax.ws.rs.HeaderParam 注释
头参数是 HTTP 头。虽然存在预定义的 HTTP 头,但您还可以使用定制头。头通常包含客户机、中介或服务器的控制元数据信息。
如果必须读取 HTTP 请求头,请使用 @javax.ws.rs.HeaderParam 注释;例如:@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" */ } }
在此示例中,对 /bookstore/books/ 发出并且 Range HTTP 请求头值为 bytes=0-499 的请求将在 rangeValue 变量值为 bytes=0-499 的情况下调用方法。
- javax.ws.rs.CookieParam 注释
Cookie 参数是特殊的 HTTP 头。虽然 Cookie 与不支持 RESTful 的存储会话标识或有状态数据相关联,但 Cookie 可以包含无状态信息。
如果发送了 HTTP Cookie,例如 mycustomid=customvalue123,那么可以使用以下示例来检索 mycustomid 变量的值:@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. */ } }
- javax.ws.rs.FormParam 注释
从浏览器中提交介质类型为 application/x-www-form-urlencoded 的 HTML 表单时,将使用表单参数。表单参数和值在请求消息体中以类似于以下的格式进行编码:firstParameter=firstValue&secondParameter=secondValue。javax.ws.rs.FormParam 注释使您能够轻松地访问各个表单参数值。
如果提交了表单,并且实体值是 firstName=Bob&lastName=Smith,那么可以使用以下示例来检索表单参数的值:@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" */ } }
避免故障: 您可以使用单一非注释式参数来表示消息体,也可以使用多个 FormParam 注释式参数,但不能同时使用这两者。因为 FormParam 要求读取请求消息体,并且消息体以字符流表示,所以无法再次读取消息体。以下代码无效:
gotcha@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 */ } }
请选择下列其中一种方法来定义用于读取参数的变量。
过程
结果
资源方法已定义完毕,因此,您可以使用适当的参数值对其进行调用。