47.3. 参数转换器

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

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

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

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

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 方法（将目标类型转换为字符串）。

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)
{
  ...
}

如果您为您的参数指定默认值（使用 @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)
{
  ...
}