46.5. 使用子资源

概述

服务可能需要由多个资源进行处理。例如,在订单处理服务最佳实践中,表示每个客户都将作为唯一资源进行处理。每个顺序也作为唯一资源进行处理。

使用 JAX-RS API,您可以将客户资源和订购资源 实施为子资源。子资源是一个通过根资源类访问的资源。它们通过将 @Path 注释添加到资源类的方法来定义。子资源可以通过以下两种方式之一实施:

指定子资源

sub-resources 通过减去带有 @Path 注释的方法来指定。子资源的 URI 构造如下:

  1. 将 sub-resource 的 @Path 注释的值附加到子资源的父资源 @Path 注释的值。

    父资源的 @Path 注释可能位于资源类中的方法上,该类返回包含子资源的类的对象。

  2. 重复上一步,直到到达 root 资源。
  3. 汇编 URI 附加到部署该服务的基本 URI 中。

例如,例 46.6 “order 子资源” 中显示的子资源的 URI 可以是 baseURI/customerservice/order/12

例 46.6. order 子资源

...
@Path("/customerservice/")
public class CustomerService
{
  ...
  @Path("/orders/{orderId}/")
  @GET
  public Order getOrder(@PathParam("orderId") String orderId)
  {
    ...
  }
}

子资源方法

子资源方法使用 @Path 注释和 HTTP 动词注释之一进行解码。子资源方法直接负责处理使用指定的 HTTP 动词对资源发出请求。

例 46.7 “子资源方法” 显示具有三个子资源方法的资源类:

  • getOrder() 处理对 URI 匹配 /customerservice/orders/{orderId}/ 的资源的 HTTP GET 请求。
  • updateOrder() 处理 URI 匹配 /customerservice/orders/{orderId}/ 的资源的 HTTP PUT 请求。
  • newOrder() 处理 /customerservice/orders/ 中资源的 HTTP POST 请求。

例 46.7. 子资源方法

...
@Path("/customerservice/")
public class CustomerService
{
  ...
  @Path("/orders/{orderId}/")
  @GET
  public Order getOrder(@PathParam("orderId") String orderId)
  {
    ...
  }

  @Path("/orders/{orderId}/")
  @PUT
  public Order updateOrder(@PathParam("orderId") String orderId,
                           Order order)
  {
    ...
  }

  @Path("/orders/")
  @POST
  public Order newOrder(Order order)
  {
    ...
  }
}
注意

具有相同 URI 模板的子资源方法等同于由子资源 locator 返回的资源类。

子资源 locators

子资源 locators 不使用其中一个 HTTP 动词注解来解码,而不直接处理子资源上的请求。相反,子资源 locator 返回可以处理请求的资源类的实例。

除了没有 HTTP 动词注解外,sub-resource locators 还没有任何实体参数。子资源 locator 方法使用的所有参数都必须使用 第 47 章 将信息传入资源类和方法 中描述的其中一个注解。

例 46.8 “sub-resource locator 返回特定类” 所示,子资源 locator 允许您将资源封装为可重复使用的类,而不是将所有方法放在一个超级类中。processOrder() 方法是一个子资源 locator。在与 URI 模板 /orders/{orderId}/ 匹配的 URI 上发出请求时,它会返回一个 Order 类的实例。Order 类具有 HTTP 动词注解分离的方法。PUT 请求由 updateOrder() 方法处理。

例 46.8. sub-resource locator 返回特定类

...
@Path("/customerservice/")
public class CustomerService
{
  ...
  @Path("/orders/{orderId}/")
  public Order processOrder(@PathParam("orderId") String orderId)
  {
    ...
  }

  ...
}

public class Order
{
  ...
  @GET
  public Order getOrder(@PathParam("orderId") String orderId)
  {
    ...
  }

  @PUT
  public Order updateOrder(@PathParam("orderId") String orderId,
                           Order order)
  {
    ...
  }

}

子资源 locators 在运行时处理,以便它们能够支持 polymorphism。子资源 locator 的返回值可以是通用 对象、抽象类或类层次结构的顶部。例如,如果您的服务需要处理 PayPal 排序和信用卡订购,则 processOrder() 方法的签名可能会保持不变。例 46.8 “sub-resource locator 返回特定类”您只需要实施两个类,即 ppOrderccOder,扩展 顺序 类。processOrder() 的实施会根据需要什么逻辑来实例化子资源所需的实现。