46.6. 资源选择方法

概述

给定 URI 可以映射到一个或多个资源方法。例如,URI customerservice/12/ma 可以与模板 @Path("customerservice/{id}")@Path("customerservice/{id}/{state}") 匹配。JAX-RS 指定与请求匹配的资源方法的详细算法。该算法将规范化 URI、HTTP 动词以及请求和响应实体的介质类型与资源类上的注解进行比较。

基本选择算法

JAX-RS 选择算法分为三个阶段:

  1. 确定根资源类。

    请求 URI 与带有 @Path 注释的所有类进行匹配。确定了 @Path 注释与请求 URI 匹配的类。

    如果资源类的 @Path 注释的值与整个请求 URI 匹配,则类的方法将用作输入到第三个阶段。

  2. 确定对象将处理请求。

    如果请求 URI 超过所选类 @Path 注释的值,则使用资源方法的 @Path 注释值来查找可以处理请求的子资源。

    如果一个或多个子资源方法与请求 URI 匹配,则这些方法将用作第三个阶段的输入。

    如果请求 URI 的唯一匹配项是子资源定位器,则由子资源定位器创建的对象的资源方法与请求 URI 匹配。此阶段会重复,直到子资源方法与请求 URI 匹配。

  3. 选择用于处理请求的资源方法。

    HTTP 动词注释与请求中的 HTTP 动词匹配的资源方法。另外,所选的资源方法必须接受请求实体正文的介质类型,并能够生成符合请求中指定的介质类型的响应。

从多个资源类中选择

选择算法的前两个阶段确定将处理请求的资源。在某些情况下,资源由资源类实施。在其他情况下,它由使用相同 URI 模板的一个或多个子资源实施。当有多个与请求 URI 匹配的资源时,首选资源类超过子资源。

如果在资源类和子资源间排序后,如果多个资源仍与请求 URI 匹配,则使用以下条件来选择单个资源:

  1. 首选使用其 URI 模板中的最多字面字符的资源。

    字面字符是不是模板变量一部分的字符。例如: /widgets/{id}/{color} 具有十个字面字符,/widgets/1/{color} 具有 eleven literal 字符。因此,请求 URI /widgets/1/red 将与 /widgets/1/{color} 作为其 URI 模板的资源匹配。

    注意

    尾部斜杠(/)计算为字面字符。因此,/joefred/ 优先于 /joefred

  2. 首选使用其 URI 模板中的大部分变量的资源。

    请求 URI /widgets/30/green 可以同时 /widgets/{id}/{color}/widgets/{amount}/。但是,将选择带有 URI 模板 /widgets/{id}/{color} 的资源,因为它有两个变量。

  3. 优先使用包含正则表达式的大多数变量的资源。

    请求 URI /widgets/30/green 可以和 /widgets/{number}/{color}/widgets/{id:.}/{color}* 匹配。但是,将选择带有 URI 模板 */widgets/{id:.}/{color} 的资源,因为它有一个包含正则表达式的变量。

从多个资源方法中选择

在很多情况下,选择一个与请求 URI 匹配的资源会导致单个资源方法可以处理请求。方法通过通过资源方法的 HTTP 动词与请求中指定的 HTTP 动词匹配来确定。除了具有适当的 HTTP 动词注释外,所选的方法还必须能够处理请求中包含的请求实体,并且能够生成请求元数据中指定的正确类型的响应。

注意

资源方法可以处理的请求实体的类型由 @Consumes 注释指定。资源方法生成的响应类型可使用 @Produces 注释指定。

当选择一个资源时,可以生成多个可以处理请求的方法,用于选择处理请求的资源方法:

  1. 优先选择资源方法而不是子资源。
  2. 优先使用子资源方法,而不是子资源定位器。
  3. 首选使用 @Consumes 注释中最常用的值的方法和 @Produces 注释。

    例如,具有注释 @Consumes("text/xml") 的方法优先于带有注释 @Consumes("text/*") 的方法。这两种方法都可以优先于不使用 @Consumes 注释的方法,或注解 @Consumes("\*/*")

  4. 最好与请求正文实体的内容类型匹配。

    注意

    请求正文实体的内容类型在 HTTP Content-Type 属性中指定。

  5. 最好与内容类型直接匹配作为响应的方法。

    注意

    HTTP Accept 属性中接受的内容类型作为响应指定。

自定义选择过程

在某些情况下,开发人员在选择多个资源类的方式中对算法有某种程度的限制。例如,如果一个给定资源类已匹配,如果此类没有匹配的资源方法,则算法将停止执行。它永远不会检查剩余的匹配资源类别。

Apache CXF 提供 org.apache.cxf.jaxrs.ext.ResourceComparator 接口,可用于自定义运行时如何处理多个匹配资源类。ResourceComparator 接口(在 例 46.9 “用于自定义资源选择的接口” 所示)必须具有需要实施的方法。其中一个比较两个资源类,另一个则比较两种资源方法。

例 46.9. 用于自定义资源选择的接口

package org.apache.cxf.jaxrs.ext;

import org.apache.cxf.jaxrs.model.ClassResourceInfo;
import org.apache.cxf.jaxrs.model.OperationResourceInfo;
import org.apache.cxf.message.Message;

public interface ResourceComparator
{
  int compare(ClassResourceInfo cri1,
              ClassResourceInfo cri2,
              Message message);

  int compare(OperationResourceInfo oper1,
              OperationResourceInfo oper2,
              Message message);
}

自定义实现选择两个资源之间的如下:

  • 如果第一个参数与第二个参数相比,返回 1
  • 如果第二个参数与第一个参数匹配,则返回 -1

如果返回 0, 则运行时将继续使用默认选择算法

您可以通过将 resourceComparator 子添加到服务的 jaxrs:server 元素,注册自定义资源Comparator 实施。