18.3. 使用 Model Schema 定义 REST 服务
没有注解的 RESTful 服务
JAX-RS 模型架构使得可以在不注解 Java 类 的情况下 定义 RESTful 服务。也就是说，您不将 @Path、@PathParam、@Consumes、@Produces 等注释直接添加到 Java 类（或接口），您可以使用模型模式在单独的 XML 文件中提供所有相关 REST 元数据。例如，当您无法修改实施该服务的 Java 源时，这非常有用。
model 模式示例
例 18.1 “JAX-RS 模型架构示例” 显示了一个模型模式示例，它为 BookStoreNoAnnotations root 资源类定义服务元数据。
例 18.1. JAX-RS 模型架构示例
<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 或 Spring XML 中定义对应的 JAX-RS 端点。下表显示了哪个 XML 语言使用哪个命名空间：
| XML 语言 | Namespace |
|---|---|
| Blueprint | |
| Spring |
如何将模型模式附加到端点
要将模型模式定义并附加到端点，请执行以下步骤：
- 定义模型模式，使用适用于您选择的注入平台的适当 XML 命名空间（打印 XML 或 Spring XML）。
将模型架构文件添加到项目的资源中，以便在最终软件包(JAR、WAR 或 OSGi 捆绑包文件)中的 classpath 上提供 schema 文件。
注意或者，也可以使用端点的
jaxrs:model子元素直接将模型架构嵌入到 JAX-RS 端点中。-
通过将端点的
modelRef属性设置为类路径（使用 classpath URL）上模型模式的位置，将端点配置为使用模型模式。 -
如有必要，使用
jaxrs:serviceBeans元素显式实例化 root 资源。如果模型模式直接引用 root 资源类（而不是引用基本接口），您可以跳过这一步。
配置引用类的模型模式
如果模型模式直接应用到 root 资源类，则不需要使用 jaxrs:serviceBeans 元素定义任何根资源 Bean，因为模型模式会自动实例化 root 资源 Bean。
例如，如果 customer-resources.xml 是一个模型模式，它将元数据与客户资源类相关联，您可以按照以下方式实例化 customerService 服务端点：
<jaxrs:server id="customerService"
address="/customers"
modelRef="classpath:/org/example/schemas/customer-resources.xml" />配置引用接口的模型模式
如果模型模式适用于 Java 接口（这是 root 资源的基本接口），则必须使用端点中的 jaxrs:serviceBeans 元素实例化 root 资源类。
例如，如果 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"/>模型架构参考
模型模式使用以下 XML 元素定义：
model-
模型模式的根元素。如果您需要引用模型架构（例如，使用
modelRef属性从 JAX-RS 端点中），您应该在此元素上设置id属性。 model/resourceresource元素用于将元数据与特定根资源类（或与对应的接口）关联。您可以在resource元素上定义以下属性：属性 描述 + name应用此资源模型的资源类（或对应接口）的名称。
+
path映射到此资源的 REST URL 路径的组件。
+
使用指定此资源使用的内容类型(Internet 介质类型)，如
application/xml或application/json。+
生成指定此资源生成的内容类型(Internet 介质类型)，如
application/xml或application/json。+
model/resource/operationoperation元素用于将元数据与 Java 方法关联。您可以在operation元素上定义以下属性：属性 描述 + name应用此元素的 Java 方法的名称。
+
path映射到此方法的 REST URL 路径的组件。此属性值可以包含参数引用，例如：
path="/books/{id}/chapter"，其中{id}从路径中提取id参数的值。+
verb指定映射到此方法的 HTTP 动词。通常之一：
GET、POST、PUT或DELETE。如果没有指定 HTTP 动词，则假设 Java 方法是一个 子资源定位器，它会返回对子资源对象的引用（子资源类还必须使用resource元素提供元数据）。+
使用指定此操作使用的内容类型(Internet 介质类型)，如
application/xml或application/json。+
生成指定此操作生成的内容类型(Internet 介质类型)，如
application/xml或application/json。+
Oneway如果为
true，请将操作配置为 单向，即不需要回复消息。默认值为false。+
model/resource/operation/paramparam元素用于从 REST URL 中提取值，并将它注入到其中一个方法参数中。您可以在param元素中定义以下属性：属性 描述 + name应用此元素的 Java method 参数的名称。
+
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。+
