47.3. 参数转换器

概述

使用参数转换器时,可以将参数(字符串类型)注入 任何类型的 字段、bean 属性或资源方法参数。通过实施和绑定合适的参数转换,您可以扩展 JAX-RS 运行时,使它能够将参数 String 值转换为目标类型。

自动转换

参数作为 String 的实例接收,因此您可以将其直接注入到字段、bean 属性和 String 类型的方法参数。此外,JAX-RS 运行时还具备将参数字符串自动转换为以下类型的功能:

  1. 原语类型。
  2. 具有可接受单个 字符串 参数的构造器的类型。
  3. 具有名为 valueOf来自String 的静态方法类型,它带有一个 String 参数,该参数返回类型为实例。
  4. 如果 T 是 2 或 3 中描述的类型之一,请列出 & lt;T >、Set< T > 或 SortedSet <T>。

参数转换器

要将参数注入自动转换没有涵盖的类型,您可以为类型定义自定义 参数转换器。参数转换器是一种 JAX-RS 扩展,可让您定义从 String 转换到自定义类型,并在反向方向从自定义类型转换到 字符串

factory pattern

JAX-RS 参数转换器机制采用工厂模式。因此,您不必直接注册参数转换器,而是必须根据 需要注册参数转换器(类型、Java x.ws.rs.ext.ParamConverterProvider)。

ParamConverter 接口

javax.ws.rs.ext.ParamConverter 接口定义如下:

// Java
package javax.ws.rs.ext;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.ws.rs.DefaultValue;

public interface ParamConverter<T> {

    @Target({ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public static @interface Lazy {}

    public T fromString(String value);

    public String toString(T value);
}

要实现您自己的参数,您必须实现这个接口,覆盖 fromString 方法(将参数字符串转换为目标类型)和 toString 方法(将目标类型转换为字符串)。

ParamConverterProvider 接口

javax.ws.rs.ext.ParamConverterProvider 接口定义如下:

// Java
package javax.ws.rs.ext;

import java.lang.annotation.Annotation;
import java.lang.reflect.Type;

public interface ParamConverterProvider {
    public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation annotations[]);
}

要实施自己的 ParamConverterProvider 类,您必须实施这个接口,覆盖 getConverter 方法,它是一种工厂方法来创建 ParamConverter 实例。

绑定参数转换器供应商

要将参数转换器提供程序 绑定到 JAX-RS 运行时(使它可用于您的应用,您必须使用 @Provider 注释标注您的实施类),如下所示:

// Java
...
import javax.ws.rs.ext.ParamConverterProvider;
import javax.ws.rs.ext.Provider;

@Provider
public class TargetTypeProvider implements ParamConverterProvider {
    ...
}

此注解可确保您的参数转换器供应商会在部署的扫描阶段自动注册。

示例

以下示例演示了如何使用 ParamConverterProvider 和 ParamConverter(将参数字符串转换为 TargetType 类型)和 ParamConverter

// Java
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;

import javax.ws.rs.ext.ParamConverter;
import javax.ws.rs.ext.ParamConverterProvider;
import javax.ws.rs.ext.Provider;

@Provider
public class TargetTypeProvider implements ParamConverterProvider {

    @Override
    public <T> ParamConverter<T> getConverter(
        Class<T> rawType,
        Type genericType,
        Annotation[] annotations
    ) {
        if (rawType.getName().equals(TargetType.class.getName())) {
            return new ParamConverter<T>() {

                @Override
                public T fromString(String value) {
                    // Perform conversion of value
                    // ...
                    TargetType convertedValue = // ... ;
                    return convertedValue;
                }

                @Override
                public String toString(T value) {
                    if (value == null) { return null; }
                    // Assuming that TargetType.toString is defined
                    return value.toString();
                }
            };
        }
        return null;
    }

}

使用参数转换器

现在,您已为 TargetType 定义了参数转换器,可以直接将参数注入 TargetType 字段和参数,例如:

// Java
import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
...
@POST
public Response updatePost(@FormParam("target") TargetType target)
{
  ...
}

默认值的 lazy 转换

如果您为您的参数指定默认值(使用 @DefaultValue 注释),您可以选择默认值是否立即转换为目标类型(默认行为),还是只在需要时转换默认值(lazy conversion)。要选择 lazy conversion,将 @ParamConverter.Lazy 注解添加到目标类型。例如:

// Java
import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.ext.ParamConverter.Lazy;
...
@POST
public Response updatePost(
    @FormParam("target")
    @DefaultValue("default val")
    @ParamConverter.Lazy
    TargetType target)
{
  ...
}