18.3. 使用模型定义 REST 服务
不含注解的 RESTful 服务
JAX-RS 模型架构使得定义 RESTful 服务成为可能，无需 注解 Java 类。也就是说，您可以使用模型模式在单独的 XML 文件中添加 @Path、@PathParam、@Consumes、@Produces 等注释，而是直接在 Java 类（或接口）中提供所有相关 REST 元数据。例如，当您无法修改实现服务的 Java 源时，这很有用。
模式 schema 示例
例 18.1 “JAX-RS Model Schema 示例” 显示为 BookStoreNoAnnotations 根资源类定义服务元数据的模型模式示例。
例 18.1. JAX-RS Model Schema 示例
<model xmlns="http://cxf.apache.org/jaxrs">
<resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore"
produces="application/json" consumes="application/json">
<operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml">
<param name="id" type="PATH"/>
</operation>
<operation name="getBookChapter" path="/books/{id}/chapter">
<param name="id" type="PATH"/>
</operation>
<operation name="updateBook" verb="PUT">
<param name="book" type="REQUEST_BODY"/>
</operation>
</resource>
<resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations">
<operation name="getItself" verb="GET"/>
<operation name="updateChapter" verb="PUT" consumes="application/xml">
<param name="content" type="REQUEST_BODY"/>
</operation>
</resource>
</model>命名空间
您用来定义模型模式的 XML 命名空间取决于是否在 Blueprint XML 中定义对应的 JAX-RS 端点，还是在 Spring XML 中定义。下表显示了要用于哪些 XML 语言的命名空间：
| XML 语言 | 命名空间 |
|---|---|
| 蓝图（Blueprint） | |
| Spring |
如何将模型模式附加到端点
要将模型模式定义并附加到端点，请执行以下步骤：
- 定义模型架构，使用您选择的注入平台(Blueprint XML 或 Spring XML)的适当 XML 命名空间。
将模型模式文件添加到您的项目的资源中，以便 schema 文件可在最终软件包(JAR、WAR 或 OSGi 捆绑包文件)中的 classpath 上可用。
注意另外，还可以使用端点的
jaxrs:model子元素直接将模型模式嵌入到 JAX-RS 端点中。-
将端点配置为使用模型模式，将端点的
modelRef属性设置为类路径上模型模式的位置（使用类路径 URL）。 -
如有必要，使用
jaxrs:serviceBeans元素明确实例化 root 资源。如果模型模式引用 root 资源类（而不是引用基本接口），您可以跳过此步骤。
引用类的模型模式配置
如果模型架构直接应用到根资源类，则不需要使用 jaxrs:serviceBeans 元素定义任何根资源 Bean，因为模型模式会自动实例化根资源 Bean。
例如，如果 customer-resources.xml 是一种模型模式，将元数据与客户资源类相关联，您可以按照如下所示实例化 customerService 服务端点：
<jaxrs:server id="customerService"
address="/customers"
modelRef="classpath:/org/example/schemas/customer-resources.xml" />引用接口的模型模式配置
如果模型架构适用于 Java 接口（这是 root 资源的基本接口），则必须使用端点中的 jaxrs:serviceBeans 元素实例化根资源类。
例如，假设 customer-interfaces.xml 是一种将元数据与客户接口关联的模型模式，您可以按照如下所示实例化 customerService 服务端点：
<jaxrs:server id="customerService"
address="/customers"
modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
<jaxrs:serviceBeans>
<ref component-id="serviceBean" />
</jaxrs:serviceBeans>
</jaxrs:server>
<bean id="serviceBean" class="service.CustomerService"/>Model Schema Reference
模型模式使用以下 XML 元素定义：
model-
模型架构的根元素。如果您需要引用模型模式（例如，使用
modelRef属性从 JAX-RS 端点），您应该设置此元素上的id属性。 model/resource资源元素用于将元数据与特定根资源类（或与对应的接口）关联。您可以在resource元素上定义以下属性：属性 描述 + name应用此资源模型的资源类（或对应接口）的名称。
+
path映射到此资源的 REST URL 路径的组件。
+
使用指定此资源使用的内容类型(Internet 介质类型)，如
application/xml或application/json。+
生成指定此资源生成的内容类型(Internet 介质类型)，如
application/xml或application/json。+
model/resource/operation操作元素用于将元数据与 Java 方法关联。您可以在操作元素上定义以下属性：属性 描述 + name应用此元素的 Java 方法的名称。
+
path映射到此方法的 REST URL 路径的组件。此属性值可以包含参数引用，例如：
path="/books/{id}/chapter"，其中{id}从路径中提取id参数的值。+
verb指定映射到此方法的 HTTP 动词。通常之一：
GET、POST、PUT或DELETE。如果没有指定 HTTP 动词，则假设 Java 方法是一种 子资源定位器，这将返回对子资源对象的引用（其中，必须使用资源元素提供子资源类）。+
使用指定此操作使用的内容类型(Internet 介质类型)，例如
application/xml或application/json。+
生成指定此操作生成的内容类型(Internet 介质类型)，例如
application/xml或application/json。+
oneway如果为
true，请将操作配置为 单向，表示不需要回复消息。默认值为false。+
model/resource/operation/param使用
param元素从 REST URL 中提取值并将其注入到方法参数之一中。您可以在param元素上定义以下属性：属性 描述 + name应用此元素的 Java 方法参数的名称。
+
type指定从 REST URL 或消息中提取参数值的方式。它可设置为以下值之一：
PATH,QUERY,MATRIX,HEADER,COOKIE,FORM,CONTEXT,REQUEST_BODY.+
defaultValue要注入参数的默认值，如果无法从 REST URL 或消息中提取值。
+
encoded如果为
true，则参数值使用 URI 编码格式注入（即使用%nn编码）。默认为false。例如，从 URL 路径中提取参数时，/name/Joe%20Bloggs的编码设为true时，该参数注入为Joe%20Bloggs; 否则，该参数将被注入为Joe Bloggs。+
