Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

2.7. 内容划分和提供程序

RESTEasy 可以自动托管和解封几个不同的消息正文。

Expand
表 2.1. 支持的介质类型和 Java 类型
介质类型Java 类型

application/* +xml,text/* +xml,application/* +json,application/* +fastinfoset,application/ atom+*

jakarta XML Binding 注解的类

application/* +xml,text/* +xml

org.w3c.dom.Document

* / *

java.lang.String

* / *

java.io.InputStream

text/plain

用于输出的原语、java.lang.String 或具有 String 构造器或静态 valueOf(String)方法的任何类型

* / *

javax.activation.DataSource

* / *

java.io.File

* / *

byte

application/x-www-form-urlencoded

javax.ws.rs.core.MultivaluedMap

2.7.1.1. 文本介质类型和字符集
复制链接

根据 Jakarta RESTful Web 服务规范，在编写响应时，实施必须遵循应用提供的字符集元数据。如果没有由应用程序指定字符集，或者应用程序指定了不支持的字符集，则实施必须使用 UTF-8 字符集。

相反，根据 HTTP 规范，发件人未提供显式 charset 参数时，将 文本 类型的媒体子类型定义为具有默认的 charset 值 ISO-8859-1。ISO-8859-1 或其子集以外的字符集中的数据必须使用适当的 charset 值进行标记。

如果没有通过资源或资源方法指定的字符集，RESTEasy 将 UTF-8 用作文本媒体类型的字符集。为此，RESTEasy 会将一个明确的 charset 参数添加到内容类型响应标头中。

要指定原始行为，其中 UTF-8 用于文本介质类型，但未附加显式 charset 参数，请将上下文参数 resteasy.add.charset 设置为 false。此参数的默认值为 true。

注意

文本介质类型包括：

  • 类型为 文本 和任何子类型的介质类型.
  • 类型为 application 和子类型（以 xml 开头的介质类型）这包括 application/xml-external-parsed-entity 和 application/xml-dtd。

2.7.2. 使用 @Provider 类构建内容
复制链接

Jakarta RESTful Web 服务规范允许您插入自己的请求/响应正文阅读器和作者。为此，您可以为类标上 @Provider，再为读取器指定 @Produces 类型和 @Consumes 类型。您还必须实施 MessageBodyReader/Writer 接口。

使用 @Provider 标注的客户端提供程序必须为 Jakarta RESTful Web Services 容器运行时的每个客户端实例注册，以处理注释。为了避免意外或重复的客户端供应商注册出现问题，系统属性 resteasy.client.providers.annotations.disabled 会禁用带有 @Provider 标注的客户端供应商的默认处理。

RESTEasy ServletContextLoader 会自动扫描标有 @Provider 的类的 WEB-INF/lib 和 class 目录，或者您可以在 web.xml 文件中手动配置它们。

2.7.3. 提供程序实用程序类
复制链接

javax.ws.rs.ext.Providers 是一个简单的可注入界面，允许您查找 MessageBodyReaders、Writers、 ContextResolvers 和 ExceptionMappers。它对于实施嵌入其他随机内容类型的多部分提供程序和内容类型非常有用。 

public interface Providers {
  <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType);
  <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType);
  <T extends="" throwable=""> ExceptionMapper<T> getExceptionMapper(Class<T> type);
  <T> ContextResolver<T> getContextResolver(Class<T> contextType, MediaType mediaType);
}
Copy to Clipboard Toggle word wrap

Providers 实例可以注入到 MessageBodyReader 或 Writers 中： 

@Provider
@Consumes("multipart/fixed")
public class MultipartProvider implements MessageBodyReader {

  private @Context Providers providers;
  ...
}
Copy to Clipboard Toggle word wrap

2.7.4. 配置文档强制
复制链接

XML 文档解析器受到 XXE(XML eXternal Entity)攻击，其中扩展外部实体会导致加载不安全的文件。例如，以下文档可能会导致加载 /etc/passwd 文件： 

<!--?xml version="1.0"?-->
<!DOCTYPE foo
[<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
<search>
 <user>bill</user>
 <file>&xxe;<file>
</search>
Copy to Clipboard Toggle word wrap

默认情况下，org.w3c.dom.Document 文档的 RESTEasy 内置 unmarshaller 不扩展外部实体。它将它们替换为空字符串。您可以将其配置为将外部实体替换为 DTD 中定义的值。这可以通过在 web.xml 文件中将 resteasy.document.expand.entity. references 上下文参数设置为 true 来实现。

示例：设置 resteasy.document.expand.entity.references 上下文参数

<context-param>
 <param-name>resteasy.document.expand.entity.references</param-name>
 <param-value>true</param-value>
</context-param>
Copy to Clipboard Toggle word wrap

另一种解决问题的方法是禁止 DTD，RESTEasy 默认这样做。可以通过将 resteasy.document.secure.disableDTDs 上下文参数设置为 false 来更改此行为。

示例：设置 resteasy.document.secure.disableDTDs Context Parameter

<context-param>
 <param-name>resteasy.document.secure.disableDTDs</param-name>
 <param-value>false</param-value>
</context-param>
Copy to Clipboard Toggle word wrap

当缓冲区被大型实体超额或太多属性时，文档也会受到 服务攻击的 Denial 服务攻击 的影响。例如，如果 DTD 定义了以下实体，则 &foo6 的扩展会导致 1,000,000 foos。 

<!--ENTITY foo 'foo'-->
<!--ENTITY foo1 '&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;'-->
<!--ENTITY foo2 '&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;'-->
<!--ENTITY foo3 '&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;'-->
<!--ENTITY foo4 '&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;'-->
<!--ENTITY foo5 '&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;'-->
<!--ENTITY foo6 '&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;'-->
Copy to Clipboard Toggle word wrap

默认情况下，RESTEasy 限制各个实体的扩展数和属性数量。确切的行为取决于底层解析器。可以通过将 resteasy.document.secure.process.feature 上下文参数设置为 false 来关闭限制。

示例：设置 resteasy.document.secure.process.feature Context Parameter

<context-param>
 <param-name>resteasy.document.secure.processing.feature</param-name>
 <param-value>false</param-value>
</context-param>
Copy to Clipboard Toggle word wrap

2.7.5. 使用 MapProvider
复制链接

您可以使用 MapProvider 接受并返回 Jakarta RESTful Web Services 资源映射。

示例：资源接受和返回映射

@Path("manipulateMap")
@POST
@Consumes("application/x-www-form-urlencoded")
@Produces("application/x-www-form-urlencoded")
public MultivaluedMap<String, String> manipulateMap(MultivaluedMap<String, String> map) {
  //do something
  return map;
}
Copy to Clipboard Toggle word wrap

您还可以使用 客户端发送和接收 map 到 Jakarta RESTful Web 服务资源。

示例： Client

MultivaluedMap<String, String> map = new MultivaluedHashMap<String, String>();

//add values to the map...

Response response = client.target(generateURL("/manipulateMap"))
                          .request(MediaType.APPLICATION_FORM_URLENCODED_TYPE)
                          .post(Entity.entity(map, MediaType.APPLICATION_FORM_URLENCODED_TYPE));

String data = response.readEntity(String.class);

//handle data...
Copy to Clipboard Toggle word wrap

2.7.6. 将基于字符串的注解转换为对象
复制链接

Jakarta RESTful Web Services @*Param 注释，包括 @QueryParam、@MatrixParam、@HeaderParam、@PathParam 和 @FormParam，在原始 HTTP 请求中以字符串形式表示。如果这些对象具有 valueOf(String) 静态方法或采用一个 String 参数的构造器，这些注入的参数可转换为对象。

如果您的类为 valueOf（） 方法或字符串构造器不存在或不适合 HTTP 请求，Jakarta RESTful Web 服务将提供 javax.ws.rs.ext.ParamConverterProvider 和 javax.ws.rs.ext.ParamConverter，以帮助将消息参数值转换为对应的自定义 Java 类型。ParamConverterProvider 必须通过编程方式在 Jakarta RESTful Web Services 运行时注册，必须标上 @Provider 注释，以便在提供商扫描阶段由 Jakarta RESTful Web Services 运行时自动发现。

例如：以下步骤演示了如何创建自定义 POJO 对象。从消息参数值（如 @QueryParam、@PathParam、@MatrixParam、@HeaderParam 转换为 POJO 对象的转换是通过实施 ParamConverter Provider 接口实现的。

  1. 创建自定义 POJO 类。 

    public class POJO {
  private String name;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}
    Copy to Clipboard Toggle word wrap

  2. 创建自定义 POJO Converter 类。 

    public class POJOConverter implements ParamConverter<POJO> {
  public POJO fromString(String str) {
    System.out.println("FROM STRNG: " + str);
    POJO pojo = new POJO();
    pojo.setName(str);
    return pojo;
  }

  public String toString(POJO value) {
    return value.getName();
  }
}
    Copy to Clipboard Toggle word wrap

  3. 创建自定义 POJO Converter Provider 类。 

    public class POJOConverterProvider implements ParamConverterProvider {
  @Override
  public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation[] annotations) {
    if (!POJO.class.equals(rawType)) return null;
    return (ParamConverter<T>)new POJOConverter();
  }
}
    Copy to Clipboard Toggle word wrap

  4. 创建自定义 MyResource 类。 

    @Path("/")
public class MyResource {
  @Path("{pojo}")
  @PUT
  public void put(@QueryParam("pojo") POJO q, @PathParam("pojo") POJO pp, @MatrixParam("pojo") POJO mp,
    @HeaderParam("pojo") POJO hp) {
    ...
  }
}
    Copy to Clipboard Toggle word wrap
扩展 ParamConverter 的功能

在 Jakarta RESTful Web 服务语义中，ParamConverter 转换代表单个对象的单个字符串。RESTEasy 扩展语义，以允许 ParamConverter 解析多个对象的字符串表示，并生成 List<T>、Set<T>、Sorted Set<T>、 数组 或任何其他多值数据结构。

例如，请考虑以下资源： 

@Path("queryParam")
public static class TestResource {
   @GET
   @Path("")
   public Response conversion(@QueryParam("q") List<String> list) {
      return Response.ok(stringify(list)).build();
   }
}

private static <T> String stringify(List<T> list) {
   StringBuffer sb = new StringBuffer();
   for (T s : list) {
      sb.append(s).append(',');
   }
   return sb.toString();
}
Copy to Clipboard Toggle word wrap

按照如下所示调用 TestResource，使用标准表示法： 

@Test
public void testQueryParamStandard() throws Exception {
   ResteasyClient client = new ResteasyClientBuilder().build();
   Invocation.Builder request = client.target("http://localhost:8081/queryParam?q=20161217&q=20161218&q=20161219").request();
   Response response = request.get();
   System.out.println("response: " + response.readEntity(String.class));
}
Copy to Clipboard Toggle word wrap

结果结果 ：20161217,20161218,20161219.

如果要使用用逗号分开的表示法，您可以添加： 

public static class MultiValuedParamConverterProvider implements ParamConverterProvider
   @SuppressWarnings("unchecked")
   @Override
   public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation[] annotations) {
      if (List.class.isAssignableFrom(rawType)) {
         return (ParamConverter<T>) new MultiValuedParamConverter();
      }
      return null;
   }
}

public static class MultiValuedParamConverter implements ParamConverter<List<?>> {
   @Override
   public List<?> fromString(String param) {
      if (param == null || param.trim().isEmpty()) {
         return null;
      }
      return parse(param.split(","));
   }

   @Override
   public String toString(List<?> list) {
      if (list == null || list.isEmpty()) {
         return null;
      }
      return stringify(list);
   }

   private static List<String> parse(String[] params) {
      List<String> list = new ArrayList<String>();
      for (String param : params) {
         list.add(param);
      }
      return list;
   }
}
Copy to Clipboard Toggle word wrap

现在，您可以按如下方式调用 TestResource: 

@Test
public void testQueryParamCustom() throws Exception {
   ResteasyClient client = new ResteasyClientBuilder().build();
   Invocation.Builder request = client.target("http://localhost:8081/queryParam?q=20161217,20161218,20161219").request();
   Response response = request.get();
   System.out.println("response: " + response.readEntity(String.class));
}
Copy to Clipboard Toggle word wrap

获得 回复：20161217,20161218,20161219.

在本例中，MultiValuedParamConverter.fromString（） 函数会创建并返回 aArrayList，以便可以重写 TestResource.conversion（） 功能： 

@Path("queryParam")
public static class TestResource {

   @GET
   @Path("")
   public Response conversion(@QueryParam("q") ArrayList<String> list) {
      return Response.ok(stringify(list)).build();
   }
}
Copy to Clipboard Toggle word wrap

另外，还可重写 MultiValuedParamConverter 以返回 LinkList，TestResource.conversion（）中的 参数列表可以是 List 或 LinkedList。

最后，请注意，此扩展也适用于数组。例如， 

public static class Foo {
    private String foo;
    public Foo(String foo) {
        this.foo = foo;
    }
    public String getFoo() {
        return foo;
    }
}

public static class FooArrayParamConverter implements ParamConverter < Foo[] > {
    @Override
    public Foo[] fromString(String value) {
        String[] ss = value.split(",");
        Foo[] fs = new Foo[ss.length];
        int i = 0;
        for (String s: ss) {
            fs[i++] = new Foo(s);
        }
        return fs;
    }

    @Override
    public String toString(Foo[] values) {
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < values.length; i++) {
            sb.append(values[i].getFoo()).append(",");
        }
        if (sb.length() > 0) {
            sb.deleteCharAt(sb.length() - 1);
        }
        return sb.toString();
    }
}

@Provider
public static class FooArrayParamConverterProvider implements ParamConverterProvider {
    @SuppressWarnings("unchecked")
    @Override
    public < T > ParamConverter < T > getConverter(Class < T > rawType, Type genericType, Annotation[] annotations) {
        if (rawType.equals(Foo[].class));
        return (ParamConverter < T > ) new FooArrayParamConverter();
    }
}

@Path("")
public static class ParamConverterResource {

    @GET
    @Path("test")
    public Response test(@QueryParam("foos") Foo[] foos) {
        return Response.ok(new FooArrayParamConverter().toString(foos)).build();
    }
}
Copy to Clipboard Toggle word wrap
java.util.Optional Parameter Types

RESTEasy 提供了多种额外的 java.util.Optional 参数类型。这些参数类型充当打包程序对象类型。它们允许用户输入可选类型参数，并使用 Optional.orElse（） 等方法取消所有 null 检查。 

@Path("/double")
@GET
public String optDouble(@QueryParam("value") OptionalDouble value) {
    return Double.toString(value.orElse(4242.0));
}
Copy to Clipboard Toggle word wrap

上例演示了 OptionalDouble 可用作参数类型。如果 @QueryParam 中未提供值，则将返回默认值。以下参数类型支持可选参数：

  • @QueryParam
  • @MatrixParam
  • @FormParam
  • @HeaderParam
  • @CookieParam

2.7.7. Serializable Provider
复制链接

从不受信任的来源对 Java 对象进行序列化是不安全的。因此，默认情况下会禁用 org.jboss.resteasy.plugins.providers.SerializableProvider。不建议使用此提供程序。

2.7.8. JSON 提供者
复制链接

2.7.8.1. RESTEasy Jackson2 中的 JsonFilter 支持
复制链接

JsonFilter 允许您为类添加 @JsonFilter 注释，从而促进动态过滤。以下示例定义了从 nameFilter 类映射到过滤器实例，然后在对实例序列化到 JSON 格式时过滤 bean 属性。 

@JsonFilter(value="nameFilter")
public class Jackson2Product {
    protected String name;
    protected int id;
    public Jackson2Product() {
    }
    public Jackson2Product(final int id, final String name) {
        this.id = id;
        this.name = name;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
}
Copy to Clipboard Toggle word wrap

@JsonFilter 注释资源组，以过滤出不应在 JSON 响应中序列化的属性。若要映射过滤器 ID 和实例，您必须创建另一个 Jackson 类，并将 ID 和过滤实例映射到此类，如下例中所示。 

public class ObjectFilterModifier extends ObjectWriterModifier {
	public ObjectFilterModifier() {
	}
	@Override
	public ObjectWriter modify(EndpointConfigBase<?> endpoint,
		MultivaluedMap<String, Object> httpHeaders, Object valueToWrite,
		ObjectWriter w, JsonGenerator jg) throws IOException {

		FilterProvider filterProvider = new SimpleFilterProvider().addFilter(
			"nameFilter",
			SimpleBeanPropertyFilter.filterOutAllExcept("name"));
		return w.with(filterProvider);
	}
}
Copy to Clipboard Toggle word wrap

在上面的示例中，方法 mod （） 负责过滤除 name 属性外的所有属性，然后再写入响应。要实现此目的，RESTEasy 必须了解此映射信息。您可以在 WriterInterceptor 或 servlet 过滤器中设置映射信息，如下例所示。

示例：使用 WriterInterceptor 设置 ObjectFilterModifier

@Provider
public class JsonFilterWriteInterceptor implements WriterInterceptor{

	private ObjectFilterModifier modifier = new ObjectFilterModifier();
	@Override
	public void aroundWriteTo(WriterInterceptorContext context)
		throws IOException, WebApplicationException {
	    	//set a threadlocal modifier
            ObjectWriterInjector.set(modifier);
                context.proceed();
	}

}
Copy to Clipboard Toggle word wrap

示例：使用 Servlet Filter 设置 ObjectFilterModifier

public class ObjectWriterModifierFilter implements Filter {
	private static ObjectFilterModifier modifier = new ObjectFilterModifier();

	@Override
	public void init(FilterConfig filterConfig) throws ServletException {
	}

	@Override
	public void doFilter(ServletRequest request, ServletResponse response,
		FilterChain chain) throws IOException, ServletException {
		    ObjectWriterInjector.set(modifier);
		    chain.doFilter(request, response);
	}

	@Override
	public void destroy() {
	}

}
Copy to Clipboard Toggle word wrap

现在，RESTEasy 可以从 ThreadLocal 变量获取 ObjectFilterModifier，并在写入响应前将其配置为修改 ObjectWriter。

2.7.8.2. JSON 序列化和持续时间对象
复制链接

注意

使用 RESTEasy 来序列化时间和持续时间对象，如 LocalDateTime、LocalDate 或 Duration 类，而无需配置 Jackson2 供应商会导致错误。

RESTEasy 支持使用 Jackson2 供应商的序列化时间和持续时间对象。以下示例演示了如何配置 Jackson2 供应商来激活序列化：

示例：为序列化配置 Jackson2 供应商

import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;

@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JacksonDatatypeJacksonProducer implements ContextResolver<ObjectMapper> {

    private final ObjectMapper json;

    public JacksonDatatypeJacksonProducer() throws Exception {
        this.json = JsonMapper.builder()
                .findAndAddModules()
                .build();
    }

    @Override
    public ObjectMapper getContext(Class<?> objectType) {
        return json;
    }
}
Copy to Clipboard Toggle word wrap

2.7.8.3. JSON Binding
复制链接

RESTEasy 同时支持 Jakarta JSON Binding 和 Jakarta JSON 处理。根据规范，jakarta JSON Binding 的实体提供商优先于所有类型的实体（ JsonValue 及其子类型除外）的 Jakarta JSON Processing。

resteasy-json-binding-provider 模块的 JsonBindingProvider 属性为 Jakarta JSON Binding 提供支持。为了满足 Jakarta RESTful Web Services 2.1 要求，JsonBindingProvider 提供商优先于其他供应商来处理 JSON 载荷，特别是 Jackson 有效负载。

对于相同的输入，Jackson 和 Jakarta JSON Binding 参考实施中的 JSON 输出可能会有所不同。因此，为了保持向后兼容性，您可以将 resteasy.preferJacksonOverJsonB 上下文属性设置为 true，并为当前部署禁用 JsonBindingProvider 配置。

JBoss EAP 支持通过设置同名的系统属性来为 resteasy.preferJacksonOverJsonB 上下文属性指定默认值。如果没有为上下文和系统属性设置值，它将扫描 Jackson 注解的 Jakarta RESTful Web Services 部署，并在找到任何这些注解时将属性设置为 true。

2.7.9. Jakarta XML Binding Providers
复制链接

2.7.9.1. Jakarta XML Binding 和 XML Provider
复制链接

RESTEasy 为 XML 提供 Jakarta XML Binding 供应商支持。

@XmlHeader 和 @Stylesheet

RESTEasy 提供使用 @org.jboss.resteasy.annotations.providers.jaxb.XmlHeader 注释设置 XML 标头。

示例：使用 @XmlHeader 注解

@XmlRootElement
public static class Thing {
   private String name;

   public String getName() {
      return name;
   }

   public void setName(String name) {
      this.name = name;
   }
}

@Path("/test")
public static class TestService {

   @GET
   @Path("/header")
   @Produces("application/xml")
   @XmlHeader("<?xml-stylesheet type='text/xsl' href='${baseuri}foo.xsl' ?>")
   public Thing get() {
      Thing thing = new Thing();
      thing.setName("bill");
      return thing;
   }
}
Copy to Clipboard Toggle word wrap

@XmlHeader 确保 XML 输出具有 XML 样式表标头。

RESTEasy 具有方便的样式表标头注释。

示例：使用 @Stylesheet 注解

@XmlRootElement
public static class Thing {
   private String name;

   public String getName() {
      return name;
   }

   public void setName(String name) {
      this.name = name;
   }
}

@Path("/test")
public static class TestService {

   @GET
   @Path("/stylesheet")
   @Produces("application/xml")
   @Stylesheet(type="text/css", href="${basepath}foo.xsl")
   @Junk
   public Thing getStyle() {
      Thing thing = new Thing();
      thing.setName("bill");
      return thing;
   }
}
Copy to Clipboard Toggle word wrap

2.7.9.2. Jakarta XML Binding 和 JSON Provider
复制链接

RESTEasy 允许您使用 JSON 提供程序将 Jakarta XML 绑定标注为 POJO 并从 JSON 中注释。此提供程序打包了 Jackson JSON 库以完成此任务。它具有基于 Java Bans 的模型和 API，类似于 Jakarta XML Binding。

Jackson 已包含 Jakarta RESTful Web 服务集成，但它已由 RESTEasy 扩展。若要将它包含在您的项目中，您需要更新 Maven 依赖项。

Jackson 的 Maven 依赖项

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jackson2-provider</artifactId>
    <version>${version.org.jboss.resteasy}</version>
    <scope>provided</scope>
</dependency>
Copy to Clipboard Toggle word wrap

注意

RESTEasy 的默认 JSON 提供程序是 Jackson2。早期版本的 JBoss EAP 包含 Jackson1 JSON 提供程序。有关将现有应用从 Jackson1 提供商迁移的更多详细信息，请参阅 JBoss EAP 迁移指南。如果您仍然要使用 Jackson1 提供程序，您必须 明确更新 Maven 依赖项来获取它。

注意

以前版本的 JBoss EAP 中 RESTEasy 的默认 JSON 提供程序是 Jettison，但现已在 JBoss EAP 7 中弃用。如需了解更多详细信息，请参阅 JBoss EAP 迁移指南。

JSON 提供程序示例

@XmlRootElement
public static class Thing {
  private String name;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}

@Path("/test")
public static class TestService {
  @GET
  @Path("/thing")
  @Produces("application/json")
  public Thing get() {
    Thing thing = new Thing();
    thing.setName("the thing");
    return thing;
  }
}
Copy to Clipboard Toggle word wrap

2.7.9.2.1. Java 8 的 Jackson 模块支持
复制链接

本节提供 Maven 依赖项，并演示如何在核心 Jackson 模块不需要 Java 8 运行时环境时注册支持 Java 8 功能所需的 Jackson 模块。Jackson 模块包括：

  • Java 8 数据类型
  • Java 8 日期/时间

添加以下 Maven 依赖项： 

<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jdk8</artifactId>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>
Copy to Clipboard Toggle word wrap

您可以使用 findAndRegisterModules（） 或 ObjectMapper.registerModule（） 找到并注册所有模块，如下例所示： 

ObjectMapper mapper = new ObjectMapper();
mapper.findAndRegisterModules();
Copy to Clipboard Toggle word wrap 
ObjectMapper mapper = new ObjectMapper()
   .registerModule(new ParameterNamesModule())
   .registerModule(new Jdk8Module())
   .registerModule(new JavaTimeModule());
Copy to Clipboard Toggle word wrap

示例：持续时间数据类型

@GET
@Path("/duration")
@Produces(MediaType.APPLICATION_JSON)
public Duration getDuration() {
    return Duration.ofSeconds(5, 6);
}
Copy to Clipboard Toggle word wrap

示例：可选数据类型

@GET
@Path("/optional/{nullParam}")
@Produces(MediaType.APPLICATION_JSON)
public Optional<String> getOptional(@PathParam("nullParam") boolean nullParameter) {
    return nullParameter ? Optional.<String>empty() : Optional.of("info@example.com");
}
Copy to Clipboard Toggle word wrap

您必须使用 ContextResolver 的自定义实施，才能在 RESTEasy 中使用这些 Jackson 模块。 

@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JacksonDatatypeJacksonProducer implements ContextResolver<ObjectMapper> {
    private final ObjectMapper json;
    public JacksonDatatypeJacksonProducer() throws Exception {
        this.json = new ObjectMapper()
                .findAndRegisterModules()
                .configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
                .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    }
    @Override
    public ObjectMapper getContext(Class<?> objectType) {
        return json;
    }
}
Copy to Clipboard Toggle word wrap
2.7.9.2.2. 切换默认的 Jackson 提供程序
复制链接

JBoss EAP 7 包含 Jackson 2.6.x 或更高版本，以及 resteasy-jackson2-provider，现在是默认的 Jackson 提供商。

若要切换到 JBoss EAP 上一发行版中包含的默认 resteasy-jackson-provider，请排除新提供程序并在 jboss-deployment-structure.xml 应用部署描述符文件中添加上述提供程序的依赖性。 

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
   <deployment>
       <exclusions>
           <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
       </exclusions>
       <dependencies>
           <module name="org.jboss.resteasy.resteasy-jackson-provider" services="import"/>
       </dependencies>
   </deployment>
</jboss-deployment-structure>
Copy to Clipboard Toggle word wrap

2.7.10. 创建 Jakarta XML Binding Decorators
复制链接

RESTEasy 的 Jakarta XML Binding 供应商提供了一种可插拔的方式来解码实例和 Unmarshaller 实例。您可以创建一个注解来触发某一实例或 Unmarshaller 实例，这可用于解码方法。

使用 RESTEasy 创建 Jakarta XML Binding Decorator

  1. 创建 Processor 类。

    1. 创建一个实现 DecoratorProcessor<Target, Annotation> 的类。目标是 Jakarta XML Binding¼er 或 Unmarshaller 类。该注释在第 2 步中创建。
    2. 给类标上 @DecorateTypes，再 声明解码器应解码的 MIME 类型。

    3. 在解码函数中设置属性或值。

      示例： Processor Class

      import org.jboss.resteasy.core.interception.DecoratorProcessor;
import org.jboss.resteasy.annotations.DecorateTypes;
import javax.xml.bind.Marshaller;
import javax.xml.bind.PropertyException;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.Produces;
import java.lang.annotation.Annotation;

@DecorateTypes({"text/*+xml", "application/*+xml"})
public class PrettyProcessor implements DecoratorProcessor<Marshaller, Pretty> {
    public Marshaller decorate(Marshaller target, Pretty annotation,
      Class type, Annotation[] annotations, MediaType mediaType) {
    target.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    }
}
      Copy to Clipboard Toggle word wrap

  2. 创建注解。

    1. 创建一个标有 @Decorator 注释的自定义接口。

    2. 声明 @Decorator 注释的处理器和目标。处理器在第 1 步中创建。目标是 Jakarta XML Binding¼ er 或 Unmarshaller 类。

      示例：带有 @Decorator 注解的自定义接口

      import org.jboss.resteasy.annotations.Decorator;

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Decorator(processor = PrettyProcessor.class, target = Marshaller.class)
public @interface Pretty {}
      Copy to Clipboard Toggle word wrap

  3. 将第 2 步中创建的注释添加到一个函数，以便在处理时对输入或输出进行解码。

您现在已创建了 Jakarta XML Binding decorator，可以在 Jakarta RESTful Web 服务中应用。

2.7.11. Jakarta RESTful Web 服务的多部分提供者
复制链接

多部分 MIME 格式用于传递嵌入在同一消息中的内容正文列表。多部分 MIME 格式的一个示例是 multipart/form-data MIME 类型。这通常在 Web 应用 HTML 表单文档中找到，通常用于上传文件。此 MIME 类型的格式 数据 格式与其他多部分格式相同，不同之处在于每个内嵌的内容都有相关联的名称。

RESTEasy 允许 multipart/form-data 和 multipart/* MIME 类型。RESTEasy 还提供了自定义 API，用于读取和写入多部分类型，以及托管任意 列表 （任何多部分类型）和 Map （仅限多部件/数据）对象。

重要

有许多框架通过过滤器和拦截器（如 Seam 中的 org.jboss.seam.web.MultipartFilter ）和 Spring 中的 org.springframework.web.multipart.MultipartResolver 自动进行多部分解析。但是，传入的多部分请求流只能被解析一次。使用多部分的 RESTEasy 用户应确保在 RESTEasy 获取流之前不会解析流。

2.7.11.1. 多部分数据输入
复制链接

在编写 Jakarta RESTful Web 服务时，RESTEasy 提供 org.jboss.resteasy.plugins.providers.multipart.MultipartInput 接口，以便您可以在任何多部分 MIME 类型中进行读取。 

package org.jboss.resteasy.plugins.providers.multipart;

public interface MultipartInput {

   List<InputPart> getParts();
   String getPreamble();

   // You must call close to delete any temporary files created
   // Otherwise they will be deleted on garbage collection or on JVM exit
   void close();
}

public interface InputPart {

   MultivaluedMap<String, String> getHeaders();
   String getBodyAsString();
   <T> T getBody(Class<T> type, Type genericType) throws IOException;
   <T> T getBody(org.jboss.resteasy.util.GenericType<T> type) throws IOException;
   MediaType getMediaType();
   boolean isContentTypeFromMessage();
}
Copy to Clipboard Toggle word wrap

MultipartInput 是一个简单界面，可让您访问多部分消息的每个部分。每个部分都由一个 InputPart 接口表示，每个部分都有一组与其关联的标头。您可以通过调用其中一个 getBody（） 方法来解译该部分。genericType 参数可以是 null，但必须设置 type 参数。RESTEasy 将根据部分的媒体类型以及您传递的类型信息查找 MessageBodyReader。

2.7.11.1.1. 多部分/混合输入
复制链接

示例： Unmarshalling 部分

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input) {
        List<Customer> customers = new ArrayList...;
        for (InputPart part : input.getParts()) {
            Customer cust = part.getBody(Customer.class, null);
            customers.add(cust);
        }
        input.close();
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

有时，您可能想要解译对通用类型的元数据敏感的正文部分。在这种情况下，您可以使用 org.jboss.resteasy.util.GenericType 类。

示例：将 Type Sensitive Unmarshalling a Generic Type Metadata

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input) {
        for (InputPart part : input.getParts()) {
            List<Customer> cust = part.getBody(new GenericType<List<Customer>>() {});
        }
        input.close();
    }
}
Copy to Clipboard Toggle word wrap

需要使用 GenericType，因为它是在运行时获取通用类型信息的唯一方法。

2.7.11.1.2. 多部分/mixed 和 java.util.List输入
复制链接

如果正文部分是统一的，您不必手动解译每个部分。您只需提供 java.util.List 作为您的输入参数。它的类型必须与 List 类型声明的 generic 参数解开。

示例：解压 客户列表

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(List<Customer> customers) {
        ...
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

2.7.11.1.3. 使用 multipart/form-data输入
复制链接

在编写 Jakarta RESTful Web 服务时，RESTEasy 提供了一个界面，允许您在 多部件/格式数据 MIME 类型中读取。多部分/格式数据 通常在 Web 应用 HTML 表单文档中找到，通常用于上传文件。form-data 格式与其他多部分格式相同，不同之处在于每个内嵌的内容都有相关联的名称。用于表单数据输入的界面为 org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput。

示例： MultipartFormDataInput Interface

public interface MultipartFormDataInput extends MultipartInput {

    @Deprecated
    Map<String, InputPart> getFormData();
    Map<String, List<InputPart>> getFormDataMap();
    <T> T getFormDataPart(String key, Class<T> rawType, Type genericType) throws IOException;
    <T> T getFormDataPart(String key, GenericType<T> type) throws IOException;
}
Copy to Clipboard Toggle word wrap

它的工作方式与 前面描述的 MultipartInput 基本相同。

2.7.11.1.4. 带有 multipart/form-data的 Java.util.Map
复制链接

使用表单数据时，如果正文部分是统一的，您不必手动分隔每个部分和每个部分。您只需将 java.util.Map 作为输入参数提供。它的类型必须与 List 类型声明的 generic 参数解开。

示例：解压 客户 对象的映射

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/form-data")
    public void put(Map<String, Customer> customers) {
        ...
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

2.7.11.2. 使用多部分数据的输出
复制链接

RESTEasy 提供了一个简单的 API 来输出多部分数据。 

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartOutput {

    public OutputPart addPart(Object entity, MediaType mediaType)
    public OutputPart addPart(Object entity, GenericType type, MediaType mediaType)
    public OutputPart addPart(Object entity, Class type, Type genericType, MediaType mediaType)
    public List<OutputPart> getParts()
    public String getBoundary()
    public void setBoundary(String boundary)
}

public class OutputPart {

    public MultivaluedMap<String, Object> getHeaders()
    public Object getEntity()
    public Class getType()
    public Type getGenericType()
    public MediaType getMediaType()
}
Copy to Clipboard Toggle word wrap

若要输出多部分数据，您需要创建一个 MultipartOutput 对象并调用 addPart（） 方法。RESTEasy 将自动查找 MessageBodyWriter 来托管您的实体对象。与 MultipartInput 类似，有时您可能会有对通用类型的元数据敏感的托管。在这种情况下，使用 GenericType。通常，传递对象及其 MediaType 应该足够。

示例：返回 多部分/混合 格式

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/mixed")
    public MultipartOutput get() {

        MultipartOutput output = new MultipartOutput();
        output.addPart(new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart(new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

2.7.11.2.1. 使用 java.util.List的多部分输出
复制链接

如果正文部分是统一的，您不必手动托管每个部分，甚至每个部分，甚至使用 MultipartOutput 对象。您可以提供 java.util.List，该类型必须具有正在捆绑的通用类型，并附带 List 类型声明的 generic 参数。您还必须使用 @PartType 注释给方法标注，以指定各个部分的媒体类型。

示例：返回 客户 对象 列表

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/mixed")
    @PartType("application/xml")
    public List<Customer> get(){
        ...
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

2.7.11.2.2. 带有 multipart/form-data的输出
复制链接

RESTEasy 提供了一个简单的 API 来输出 multipart/form-data。 

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartFormDataOutput extends MultipartOutput {

    public OutputPart addFormData(String key, Object entity, MediaType mediaType)
    public OutputPart addFormData(String key, Object entity, GenericType type, MediaType mediaType)
    public OutputPart addFormData(String key, Object entity, Class type, Type genericType, MediaType mediaType)
    public Map<String, OutputPart> getFormData()
}
Copy to Clipboard Toggle word wrap

要输出 multipart/form-data，您必须创建一个 MultipartFormDataOutput 对象并调用 addFormData（） 方法。RESTEasy 将自动查找 MessageBodyWriter 来托管您的实体对象。与 MultipartInput 类似，有时您可能会有对通用类型的元数据敏感的托管。在这种情况下，使用 GenericType。通常，传递对象及其 MediaType 应该足够。

示例：返回 multipart/form-data Format

@Path("/form")
public class MyService {

    @GET
    @Produces("multipart/form-data")
    public MultipartFormDataOutput get() {

        MultipartFormDataOutput output = new MultipartFormDataOutput();
        output.addPart("bill", new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart("monica", new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

如果正文部分是统一的，您不必手动托管每个部分或使用 MultipartFormDataOutput 对象。您只需提供一个 java.util.Map，该类型必须具有正在使用 Map 类型声明的 generic 参数的通用类型。您还必须使用 @PartType 注释给方法标注，以指定各个部分的媒体类型。

示例：返回 客户 对象的映射

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/form-data")
    @PartType("application/xml")
    public Map<String, Customer> get() {
        ...
    }
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

2.7.11.3. 将多部分表单映射到 POJO
复制链接

如果您对多部分/格式数据数据包有精确的了解，您可以将它们映射到 POJO 类或从 POJO 类中进行映射。这通过 org.jboss.resteasy.annotations.providers.multipart.MultipartForm 注释(@MultipartForm)和 Jakarta RESTful Web Services @FormParam 注释来实现。为此，您需要使用至少一个默认构造器定义 POJO，并使用 @FormParams 给其字段和/或属性标注。如果要创建输出，还必须使用 org.jboss.resteasy.annotations.providers.multipart.PartType( @PartType)标记这些 @FormParam s。

示例：将多组件表单映射到 POJO

public class CustomerProblemForm {

    @FormParam("customer")
    @PartType("application/xml")
    private Customer customer;

    @FormParam("problem")
    @PartType("text/plain")
    private String problem;

    public Customer getCustomer() { return customer; }
    public void setCustomer(Customer cust) { this.customer = cust; }
    public String getProblem() { return problem; }
    public void setProblem(String problem) { this.problem = problem; }
}
Copy to Clipboard Toggle word wrap

在定义了 POJO 类后，您可以使用它来表示 多部分/格式数据。

示例：提交 CustomerProblemForm

@Path("portal")
public interface CustomerPortal {

    @Path("issues/{id}")
    @Consumes("multipart/form-data")
    @PUT
    public void putProblem(@MultipartForm CustomerProblemForm,
                           @PathParam("id") int id);
}

// Somewhere using it:
{
    CustomerPortal portal = ProxyFactory.create(CustomerPortal.class, "http://example.com");
    CustomerProblemForm form = new CustomerProblemForm();
    form.setCustomer(...);
    form.setProblem(...);

    portal.putProblem(form, 333);
}
Copy to Clipboard Toggle word wrap

@MultipartForm 注释告知 RESTEasy 对象具有 @FormParam，并且应当从中托管。您还可以使用相同的对象来接收多部分数据。

示例：接收 客户ProblemForm

@Path("portal")
public class CustomerPortalServer {

    @Path("issues/{id})
    @Consumes("multipart/form-data")
    @PUT
    public void putIssue(@MultipartForm CustomerProblemForm,
                         @PathParam("id") int id) {
       ... write to database...
    }
}
Copy to Clipboard Toggle word wrap

2.7.11.4. XML-二进制优化打包(XOP)
复制链接

如果您有一个 Jakarta XML Binding 标注了 POJO，并且也包含一些二进制内容，您可以选择将其发送成不需要以任何方式（如 base64 或十六进制）对其进行编码。这可通过 XOP 实现，从而在仍然使用方便的 POJO 的同时加快传输速度。

RESTEasy 允许将 XOP 消息打包为 多部分/相关.

要配置 XOP，您首先需要一个带注解的 POJO 的 Jakarta XML Binding。

示例：jakarta XML Binding POJO

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public static class Xop {

    private Customer bill;
    private Customer monica;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private byte[] myBinary;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private DataHandler myDataHandler;

    // methods, other fields ...
}
Copy to Clipboard Toggle word wrap

注意

@XmlMimeType 告知 Jakarta XML 绑定二进制内容的 mime 类型。这不需要执行 XOP 打包，但如果您知道确切的类型，则建议对其进行设置。

在上面的 POJO myBinary 和 myDataHandler 中，将处理为二进制附件，而整个 XOP 对象将作为 XML 发送。代替二进制文件，将仅生成其引用。javax.activation.DataHandler 是最常用的类型。如果需要 java.io.InputStream 或 javax.activation.DataSource，您需要使用 DataHandler。Java.awt.Image 和 javax.xml.transform.SourceSome 也可用。

示例：使用 XOP 的客户端发送二进制内容

// our client interface:
@Path("mime")
public static interface MultipartClient {
    @Path("xop")
    @PUT
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXop(@XopWithMultipartRelated Xop bean);
}

// Somewhere using it:
{
    MultipartClient client = ProxyFactory.create(MultipartClient.class,
        "http://www.example.org");
    Xop xop = new Xop(new Customer("bill"), new Customer("monica"),
        "Hello Xop World!".getBytes("UTF-8"),
        new DataHandler(new ByteArrayDataSource("Hello Xop World!".getBytes("UTF-8"),
        MediaType.APPLICATION_OCTET_STREAM)));
    client.putXop(xop);
}
Copy to Clipboard Toggle word wrap

注意

上例假定 客户 类标有 Jakarta XML Binding。

@Consumes(MultipartConstants.MULTIPART_RELATED) 用于告知 RESTEasy，您要发送 多部分/相关 软件包，这是保存 XOP 消息的容器格式。@XopWithMultipartRelated 用于告知 RESTEasy，您想要发出 XOP 消息。

示例：用于接收 XOP 的 RESTEasy Server

@Path("/mime")
public class XopService {
    @PUT
    @Path("xop")
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXopWithMultipartRelated(@XopWithMultipartRelated Xop xop) {
        // do very important things here
    }
}
Copy to Clipboard Toggle word wrap

@consumes(MultipartConstants.MULTIPART_RELATED) 用于告知 RESTEasy，您希望读取 多部分/相关 包。@XopWithMultipartRelated 用于 告知 RESTEasy 想要读取 XOP 消息。您可以将 RESTEasy 服务器配置为以类似的方式生成 XOP 值，方法是添加 @Produces 注释并返回适当的类型。

2.7.11.5. 多部分消息覆盖默认回退内容类型
复制链接

默认情况下，如果部分 文本/plain 中不存在 Content-Type 标头；charset=us-ascii 用作回退。这由 MIME RFC 定义。但是，某些 Web 客户端（如许多浏览器）可能会为文件部分发送 Content-Type 标头，但不适用于 多部分/格式数据 请求中的所有字段。这可能会导致服务器端的字符编码和取消处理错误。RESTEasy 的 PreProcessInterceptor 基础架构可用于更正此问题。您可以使用它为每个请求动态定义另一个非 RFC 兼容回退值。

示例：将 * / *; charset=UTF-8 设置为默认 Fallback

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CONTENT_TYPE_PROPERTY, "*/*; charset=UTF-8");
        return null;
    }
}
Copy to Clipboard Toggle word wrap

2.7.11.6. 多部分消息的内容类型覆盖
复制链接

通过使用拦截器和 InputPart.DEFAULT_CONTENT_TYPE_PROPERTY 属性，您可以设置默认的 Content-Type。您还可以通过调用 org.jboss.resteasy.plugins.providers.multipart.InputPart.setMediaType（） 在任何输入部分中覆盖 Content- Type。

示例：覆盖 Content-Type

@POST
@Path("query")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.TEXT_PLAIN)
public Response setMediaType(MultipartInput input) throws IOException {

    List<InputPart> parts = input.getParts();
    InputPart part = parts.get(0);
    part.setMediaType(MediaType.valueOf("application/foo+xml"));
    String s = part.getBody(String.class, null);
    ...
}
Copy to Clipboard Toggle word wrap

2.7.11.7. 为多部分消息覆盖默认 Fallback charset
复制链接

在某些情况下，多部分消息的部分可能具有 Content-Type 标头且没有 charset 参数。如果设置了 InputPart.DEFAULT_CONTENT_TYPE_PROPERTY 属性，并且值具有 charset 参数，则该值将被附加到没有 charset 参数的现有 Content-Type 标头中。

您还可以使用 常量 InputPart.DEFAULT_CHARSET_PROPERTY(resteasy.provider.multipart.inputpart.defaultCharset)指定默认的 char set。

示例：指定默认 charset

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CHARSET_PROPERTY, "UTF-8");
        return null;
    }
}
Copy to Clipboard Toggle word wrap

注意

如果设置了 InputPart.DEFAULT_CONTENT_TYPE_PROPERTY 和 InputPart.DEFAULT_CHARSET_PROPERTY，则 InputPart.DEFAULT_CHARSET_PROPERTY 的值将覆盖 InputPart.DEFAULT_CONTY 的值中的任何 charset。

2.7.11.8. 使用 RESTEasy 客户端发送多部分实体
复制链接

除了配置多部分提供程序外，您还可以配置 RESTEasy 客户端来发送多部分数据。

使用 RESTEasy 客户端类

要在应用程序中使用 RESTEasy 客户端类，您必须将 Maven 依赖项添加到项目的 POM 文件中。

示例：Maven 依赖项

<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-client</artifactId>
  <version>${version.org.jboss.resteasy}</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-multipart-provider</artifactId>
  <version>${version.org.jboss.resteasy}</version>
  <scope>provided</scope>
</dependency>
Copy to Clipboard Toggle word wrap

使用 RESTEasy 客户端发送多部分数据

若要发送多部分数据，您必须首先配置 RESTEasy 客户端，并构建一个 org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataOutput 对象来包含您的多部分数据。然后，您可以使用客户端将该 MultipartFormDataOutput 对象作为 javax.ws.rs.core.GenericEntity 发送。

示例：RESTEasy Client

ResteasyClient client = new ResteasyClientBuilder().build();
ResteasyWebTarget target = client.target("http://foo.com/resource");

MultipartFormDataOutput formOutputData = new MultipartFormDataOutput();
formOutputData.addFormData("part1", "this is part 1", MediaType.TEXT_PLAIN);
formOutputData.addFormData("part2", "this is part 2", MediaType.TEXT_PLAIN);

GenericEntity<MultipartFormDataOutput> data = new GenericEntity<MultipartFormDataOutput>(formOutputData) { };

Response response = target.request().put(Entity.entity(data, MediaType.MULTIPART_FORM_DATA_TYPE));

response.close();
Copy to Clipboard Toggle word wrap

2.7.12. RESTEasy Atom 支持
复制链接

RESTEasy Atom API 和提供程序是 RESTEasy 定义为代表 Atom 的简单对象模型。API 的主要类位于 org.jboss.resteasy.plugins.providers.atom 软件包中。RESTEasy 使用 Jakarta XML Binding 来托管和卸载 API。提供程序基于 Jakarta XML Binding，不限于使用 XML 发送 Atom 对象。RESTEasy 能够被 Atom API 和供应商（包括 JSON）重复利用的所有 Jakarta XML Binding 提供程序。 

import org.jboss.resteasy.plugins.providers.atom.Content;
import org.jboss.resteasy.plugins.providers.atom.Entry;
import org.jboss.resteasy.plugins.providers.atom.Feed;
import org.jboss.resteasy.plugins.providers.atom.Link;
import org.jboss.resteasy.plugins.providers.atom.Person;

@Path("atom")
public class MyAtomService {

   @GET
   @Path("feed")
   @Produces("application/atom+xml")
   public Feed getFeed() throws URISyntaxException {
      Feed feed = new Feed();
      feed.setId(new URI("http://example.com/42"));
      feed.setTitle("My Feed");
      feed.setUpdated(new Date());
      Link link = new Link();
      link.setHref(new URI("http://localhost"));
      link.setRel("edit");
      feed.getLinks().add(link);
      feed.getAuthors().add(new Person("John Brown"));
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setType(MediaType.TEXT_HTML_TYPE);
      content.setText("Nothing much");
      entry.setContent(content);
      feed.getEntries().add(entry);
      return feed;
   }
}
Copy to Clipboard Toggle word wrap

org.jboss.resteasy.plugins.providers.atom.Content 类允许您解封和 marshal Jakarta XML Binding 注解为内容主体的对象。

示例：与客户进行输入

@XmlRootElement(namespace = "http://jboss.org/Customer")
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement
   private String name;

   public Customer() {
   }

   public Customer(String name) {
      this.name = name;
   }

   public String getName() {
      return name;
   }
}

@Path("atom")
public static class AtomServer {
   @GET
   @Path("entry")
   @Produces("application/atom+xml")
   public Entry getEntry() {
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setJAXBObject(new Customer("bill"));
      entry.setContent(content);
      return entry;
   }
}
Copy to Clipboard Toggle word wrap

Content.setJAXBObject（） 方法允许您将发送到 Jakarta XML Binding 的内容对象相应地指定为 marshal。如果您使用与 XML 不同的基本格式，即 application/atom+json，附加的 Jakarta XML Binding 对象会以相同的格式 marshalled。如果您有 Atom 文档作为输入，您也可以使用 Content. getJAXBObject(Class clazz) 方法从内容中提取 Jakarta XML Binding 对象。

示例：属性文档提取客户对象

@Path("atom")
public static class AtomServer {
   @PUT
   @Path("entry")
   @Produces("application/atom+xml")
   public void putCustomer(Entry entry) {
      Content content = entry.getContent();
      Customer cust = content.getJAXBObject(Customer.class);
   }
}
Copy to Clipboard Toggle word wrap

2.7.13. YAML 供应商
复制链接

警告

不支持 resteasy-yaml-provider 模块。不建议使用，因为 RESTEasy 用于取消托管的 SnakeYAML 库中存在安全问题。

RESTEasy 附带使用 SnakeYAML 库构建的 YAML 支持。

在 JBoss EAP 7.1 之前的版本中，YAML 提供程序设置默认启用，您只需要为 YAML 配置 Maven 依赖项，即可在应用中使用。自 JBoss EAP 7.1 起，默认情况下，YAML 提供程序是禁用的，应用中必须明确启用 YAML 提供程序。

启用 YAML 提供者

要在应用程序中启用 YAML 供应商，请按照以下步骤执行：

  1. 创建或更新名为 javax.ws.rs.ext.Providers 的文件。

  2. 将以下内容添加到 文件中： 

    org.jboss.resteasy.plugins.providers.YamlProvider
    Copy to Clipboard Toggle word wrap
  3. 将文件放到 WAR 或 JAR 文件的 META-INF/services/ 文件夹中。
YAML Provider Maven 依赖项

要在应用程序中使用 YAML 供应商，您必须将 snakeyaml JAR 依赖项添加到应用程序的项目 POM 文件中。

示例：YAML 的 Maven 依赖项

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-yaml-provider</artifactId>
    <version>${version.org.jboss.resteasy}</version>
    <scope>provided</scope>
</dependency>

<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>${version.org.yaml.snakeyaml}</version>
</dependency>
Copy to Clipboard Toggle word wrap

YAML 提供程序代码示例

YAML 供应商识别三种 mime 类型：

  • text/x-yaml
  • text/yaml
  • application/x-yaml

以下是如何在资源方法中使用 YAML 的示例。

示例：资源生成 YAML

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("/yaml")
public class YamlResource {

  @GET
  @Produces("text/x-yaml")
  public MyObject getMyObject() {
    return createMyObject();
  }
...
}
Copy to Clipboard Toggle word wrap

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部