在 RESTful 应用程序中定义资源的请求表示的参数

参数用来将附加信息传递和添加到请求。您可以使用参数作为 URL 的组成部分,也可以在头中使用参数。路径参数、矩阵参数、查询参数、头参数和 Cookie 参数对于将附加的信息传递给请求而言都非常有用。

关于此任务

存在多种参数类型。Java™ API for RESTful Web Services (JAX-RS) 使您能够使用注入的注释式参数轻松地访问所有类型的参数。

您可以使用任何基本 Java 基本类型(包括 java.lang.String)作为参数,也可以使用具有使用单一字符串或 valueOf(字符串)静态方法的构造函数的 Java 类型。另外,还可以使用 ListSortedSetSet 接口,在这些接口中,通用类型是上面提到的其中一种类型,例如在参数可以具有多个值时使用的 Set。如果需要解析请求,请使用 String 作为参数类型,以便完成错误路径响应的基本检查和定制。

JAX-RS 提供了下列用于资源方法参数的注释,以指定可使用正确的参数值来调用资源方法。

javax.ws.rs.PathParam 注释

路径参数是 URL 的组成部分。例如,URL 可以包含 /collection/{item},其中 {item} 用于标识集合中的项的路径参数。因为路径参数是 URL 的组成部分,所以对于标识请求而言至关重要。

如果 URL 包含参数,那么您可以使用 @javax.ws.rs.PathParam 所注释的参数;例如:
@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/  */
    }
}
在此示例中,对 /bookstore/books/12345 的请求将值 12345 赋予 theBookId 变量。
javax.ws.rs.MatrixParam 注释

矩阵参数是 URL 的组成部分。例如,如果 URL 包含路径段 /collection;itemID=itemIDValue,那么矩阵参数名是 itemID,并且值为 itemIDValue

您可以使用注释式参数 @javax.ws.rs.MatrixParam 来读取矩阵参数;例如:
@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. */
    }
}
在此示例中,对 /bookstore/books;page=25;filter=test 的请求将调用 getBookCollectionInfo 参数,以便将 page 变量的值设置为 25,并将 filter 变量的值设置为 test
javax.ws.rs.QueryParam 注释

查询参数通过名/值对追加到 URL 中的“?”之后。例如,如果 URL 是 http://example.com/collection?itemID=itemIDValue,那么查询参数名是 itemID,并且值为 itemIDValue。查询参数通常在您对 HTTP GET 请求进行过滤或翻页时使用。

您可以使用注释式参数 @javax.ws.rs.QueryParam 来读取查询参数;例如:
@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. */
    }
}
在此示例中,对 /bookstore/books;page=25;filter=test 的请求将调用 getBookCollectionInfo 参数,以便将 page 变量的值设置为 25,并将 filter 变量的值设置为 test
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 要求读取请求消息体,并且消息体以字符流表示,所以无法再次读取消息体。以下代码无效:
@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

请选择下列其中一种方法来定义用于读取参数的变量。

过程

结果

资源方法已定义完毕,因此,您可以使用适当的参数值对其进行调用。

示例


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_parmexchdata
文件名:twbs_jaxrs_defresource_parmexchdata.html