52.2. 使用完整请求 URI

摘要

请求 URI 包含大量信息。大多数信息可以使用方法参数(如 第 47.2.2 节 “注入请求 URI 中的数据” 所述)来访问。但是,使用参数会强制对 URI 如何处理某些限制。使用参数访问 URI 的片段不提供对完整请求 URI 的资源访问权限。

您可以通过将 URI 上下文注入资源来提供对完整请求 URI 的访问权限。URI 作为 UriInfo 对象提供。UriInfo 界面以多种方式模拟 URI。它还可以将 URI 作为 UriBuilder 对象提供,允许您构建 URI 来返回到客户端。

:experimental:

52.2.1. 注入 URI 信息

概述

当作为 UriInfo 对象的类字段或方法参数使用 @Context 注释时,当前请求的 URI 上下文将注入到 UriInfo 对象中。

示例

将 URI 上下文注入类字段 显示通过注入 URI 上下文填充的字段的类。

将 URI 上下文注入类字段

import javax.ws.rs.core.Context;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.Path;
...
@Path("/monstersforhire/")
public class MonsterService
{
  @Context
  UriInfo requestURI;
  ...
}

52.2.2. 使用 URI

概述

使用 URI 上下文的一个主要优点是,它提供对服务的基本 URI 和所选资源的 URI 的路径片段的访问。此信息可用于许多目的,例如根据 URI 或计算 URI 做出处理决策,以作为响应的一部分返回。例如,如果请求的基本 URI 包含 .com 扩展,服务可能会决定使用美国资金,并且基本 URI 包含 .co.uk 扩展是否可能决定我们英国的 Pounds。

UriInfo 接口提供了访问 URI 的部分方法:

  • 基本 URI
  • 资源路径
  • 完整 URI

获取 Base URI

基础 URI 是发布该服务的根 URI。它不包含在 service 的 @Path 注释中指定的任何 URI 部分。例如,如果实施 例 47.5 “禁用 URI 解码” 中定义的资源的服务被发布到 http://fusesource.org,在 http://fusesource.org/montersforhire/nightstalker?12 基本 URI 中进行了请求将为 http://fusesource.org

表 52.2 “访问资源基本 URI 的方法” 描述返回基本 URI 的方法。

表 52.2. 访问资源基本 URI 的方法

方法Desription

URIgetBaseUri

将服务的基本 URI 返回为 URI 对象。

UriBuildergetBaseUriBuilder

将基础 URI 返回为 javax.ws.rs.core.UriBuilder 对象。UriBuilder 类对于为服务实施的其他资源创建 URI 很有用。

获取路径

请求 URI 的路径 部分是用来选择当前资源的 URI 的部分。它不包括基本 URI,但不包括 URI 中包含的任何 URI 模板变量和列表参数。

路径值取决于所选的资源。例如,在 获取资源路径 中定义的资源的路径将是:

  • rootPath/monstersforhire/
  • getterPath/mostersforhire/nightstalker

    GET 请求在 /monstersforhire/nightstalker 上进行。

  • putterPath/mostersforhire/911

    PUT 请求在 /monstersforhire/911 上进行。

获取资源路径

@Path("/monstersforhire/")
public class MonsterService
{
  @Context
  UriInfo rootUri;

  ...

  @GET
  public List<Monster> getMonsters(@Context UriInfo getUri)
  {
    String rootPath = rootUri.getPath();
    ...
  }

  @GET
  @Path("/{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @Context UriInfo getUri)
  {
    String getterPath = getUri.getPath();
    ...
  }

  @PUT
  @Path("/{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @Context UriInfo putUri)
  {
    String putterPath = putUri.getPath();
    ...
  }
  ...
}

表 52.3 “访问资源路径的方法” 描述返回资源路径的方法。

表 52.3. 访问资源路径的方法

方法Desription

字符串getPath

将资源的路径作为已解码的 URI 返回。

字符串getPath布尔值解码

返回资源的路径。指定 false 可禁用 URI 解码。

list<PathSegment&gt;getPathSegments

将解码的路径作为 javax.ws.rs.core.PathSegment 对象的列表返回。路径的每个部分(包括列表参数)都放入列表中的唯一条目。

例如,资源路径 box/round#tall 将导致列表,包括三个条目: 舍入tall

list<PathSegment&gt;getPathSegments布尔值解码

将路径返回为 javax.ws.rs.core.PathSegment 对象列表。路径的每个部分(包括列表参数)都放入列表中的唯一条目。指定 false 可禁用 URI 解码。

例如,资源路径 box#tall/round 的结果是带有三个条目的列表: tallround

获取完整请求 URI

表 52.4 “访问完整请求 URI 的方法” 描述返回完整请求 URI 的方法。您可以选择返回请求 URI 或资源的绝对路径。不同之处在于,请求 URI 包含附加到 URI 的任何查询参数,绝对路径不包含查询参数。

表 52.4. 访问完整请求 URI 的方法

方法Desription

URIgetRequestUri

返回完整的请求 URI,包括查询参数和列表参数,作为 java.net.URI 对象。

UriBuildergetRequestUriBuilder

返回完整的请求 URI,包括查询参数和列表参数,作为 javax.ws.rs.UriBuilder 对象。UriBuilder 类对于为服务实施的其他资源创建 URI 很有用。

URIgetAbsolutePath

返回完整的请求 URI,包括列表参数,作为 java.net.URI 对象。绝对路径不包括查询参数。

UriBuildergetAbsolutePathBuilder

返回完整请求 URI,包括列表参数,作为 javax.ws.rs.UriBuilder 对象。绝对路径不包括查询参数。

对于使用 URI http://fusesource.org/montersforhire/nightstalker?12 的请求,getRequestUri() 方法将返回 http://fusesource.org/montersforhire/nightstalker?12getAbsolutePath() 方法将返回 http://fusesource.org/montersforhire/nightstalker

52.2.3. 获取 URI 模板变量的值

概述

“设置路径”一节 所述,资源路径可以包含动态绑定到值的变量片段。通常,这些变量路径片段作为资源方法的参数使用,如 “从 URI 的路径获取数据”一节 所述。但是,您也可以通过 URI 上下文访问它们。

获取路径参数的方法

UriInfo 接口提供了两种方法,在 例 52.1 “从 URI 上下文返回路径参数的方法” 中显示,它会返回一个路径参数列表。

例 52.1. 从 URI 上下文返回路径参数的方法

MultivaluedMap<java.lang.String, java.lang.String&gt;getPathParametersMultivaluedMap<java.lang.String, java.lang.String&gt;getPathParametersbooleandecode

没有利用任何参数的 getPathParameters() 方法会自动解码路径参数。如果要禁用 URI 解码,请使用 getPathParameters(false)

值以模板标识符作为键存储在映射中。例如,如果资源的 URI 模板为 /{color}/box/{note},则返回的映射有两个条目,其键为 colornote

示例

例 52.2 “从 URI 上下文中提取路径参数” 显示使用 URI 上下文检索路径参数的代码。

例 52.2. 从 URI 上下文中提取路径参数

import javax.ws.rs.Path;
import javax.ws.rs.Get;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.core.MultivaluedMap;

@Path("/monstersforhire/")
public class MonsterService

  @GET
  @Path("/{type}/{size}")
  public Monster getMonster(@Context UriInfo uri)
  {
    MultivaluedMap paramMap = uri.getPathParameters();
    String type = paramMap.getFirst("type");
    String size = paramMap.getFirst("size");
  }
}