基于 Restlet 机制扩展领域资源

SuperMap iServer 提供了 Restlet、JAX-RS 两种机制，方便将领域功能发布为 REST 资源。其中，有关 Restlet 机制的简介参见：REST 服务发布机制。

• 定义 REST 资源
  • 资源基类
  • 获取服务组件
  • 定义 HTML 表述
  • 资源配置
  • 示例
• 扩展表述生成器
• 扩展参数解析器

定义 REST 资源

资源基类

在 SuperMap iServer Restlet 机制的 REST 实现框架中，最高层的资源类是 ResourceBase，所有的资源实现类都直接或间接地继承于它，例如 SuperMap iServer 已提供的所有的资源的实现类。

在扩展 REST 资源的时候，需要继承 ResourceBase 或它的子类，SuperMap iServer 在最终实现类和 ResourceBase 类之间抽象出了许多抽象类，标志不同类型的资源，这为扩展 REST 资源的开发提供了极大方便，可以根据欲扩展的资源的功能去寻找合适的抽象类进行扩展。

有关 SuperMap iServer 中， REST 资源抽象类的情况，请参见 JavaDoc 文档：com.supermap.services.rest.resources 包。

以 SimpleAlgorithmResultResourceBase 抽象类为例，若继承该类进行资源实现，需要实现如下抽象方法：

注意：资源实现类要添加 @Component 注记，来表明该资源关联的服务组件，如：

@Component(interfaceClass = Temperature.class)

获取服务组件

SuperMap iServer 中，服务组件通过相匹配的服务接口发布为 Web 服务，在资源实现类中，通过服务接口上下文获取服务组件，从而获取相应的 GIS 功能。

ResourceBase 提供了 getInterfaceContext() 接口，资源实现类可直接使用，获取服务接口上下文，从而获取服务组件，代码片段如下：

                InterfaceContext interfacecontext=super.getInterfaceContext();
                List<FirstComponent> firstComponents=interfacecontext.getComponents(FirstComponent.class);
                FirstComponent firstComponent=firstComponents.get(0);

定义 HTML 表述

自定义的 REST 资源默认支持的表述格式有：xml、json、rjson，在定义了 FreeMarker 模板后，还支持 HTML 表述。

FreeMarker 是基于模板生成文本输出的通用工具。在 SuperMap iServer 的 REST 框架下，资源的 *.ftl 模板文件中的 ${resource.content.*} 表示表述结果的字段。在 Restlet 机制下，文件名必须跟资源的配置项 ID 一致。*.ftl 文件需要放在 Jar 包:///templates 目录下。

SuperMap iServer 提供了一些变量供用户在制作*.ftl 模板时使用，从而获取资源信息，参见：iServer 提供的 FreeMarker 变量。

资源配置

首先，可通过配置文件说明了解“模块配置文件”和“资源配置文件”两个概念。领域模块发布为 REST 资源时，需要建立这两个文件。这两个文件都打在 Jar 包里，实现扩展模块的即插即用，方便系统管理员配置。

模块配置文件位于 Jar:///META-INF/extensions/services/rest 位置；

资源配置文件位置由模块配置文件中的 resourceFiles 项指定。

资源配置可跟资源实现类、FreeMarker 模板，打成一个 Jar 包。Jar 包放到 %SuperMap iServer_HOME%/webapps/iserver/WEB-INF/lib 目录下，启动 SuperMap iServer 服务即可。

示例

参见  %SuperMap iServer_HOME%/samples/code/Temprature_Restlet 示例工程，该示范代码基于 Restlet 机制扩展实现的天气查询服务，使用方法请参考工程目录下 readme.txt 中的介绍。

扩展表述生成器

自定义的 REST 资源默认支持的表述格式有：xml、json、rjson，在定义了 FreeMarker 模板后，还支持 HTML 表述。可对此进行扩展，使领域资源支持更多的表述格式。

在 SuperMap iServer 的 REST 实现框架中，提供了 com.supermap.services.rest.encoders.Encoder 抽象类用于表述生成器，所有的表述生成器都继承自该类。例如，在 SuperMap iServer 中已提供的 ImageEncoder、JsonEncoder、SceneEncoder、StreamEncoder、TemplateEncoder、XMLEncoder 等。

用户对表述生成器进行扩展，既可以继承 Encoder 抽象类，对其中的抽象方法进行实现，也可以继承现有的表述生成器类，改写其中的方法。其中，重要的方法如下表所示：

继承 Encoder 抽象类（或其子类），实现（或重写）上表中的两个方法，就可以实现一个自定义的表述生成器。

扩展过程与现有 REST 资源扩展中的扩展表述生成器一致，参见：扩展一个表述生成器。

注意：资源响应的媒体类型由 HTTP 请求的 URI 后缀决定，参见：URI 后缀与媒体类型的对应关系。

扩展参数解析器

SuperMap iServer 默认的参数传递格式为 json，还支持 xml 参数格式。

参数的类型由 HTTP 请求中的 X-RequestEntity-ContentType 请求头和 X-UrlEntity-ContentType 请求头标识，分别标识请求体中的参数的类型和 URI 中的参数的类型。当指定为 application/xml 时，表明 HTTP 请求中的参数是按 xml 格式组织的，SuperMap iServer 就会按 xml 格式去解析参数；不指定时默认采用 json 格式去解析参数。

在 SuperMap iServer 的 REST 实现框架中，提供了 com.supermap.services.rest.decoders.Decoder 抽象类用于参数解析器，所有的参数解析器都继承自该类。例如，在 SuperMap iServer 中已提供的 JsonDecoder、XMLDecoder 等。

用户扩展新的参数解析器，既可以继承 Decoder 抽象类，对其中的抽象方法进行实现，也可以继承现有的参数解析器类，改写其中的方法。其中，重要的方法如下表所示，详请参见 JavaDoc 文档：

继承 Decoder 抽象类（或其子类），实现（或重写）上表中的方法，就可以实现一个自定义的参数解析器。

扩展过程与现有 REST 资源扩展中的扩展参数解析器一致，参见：扩展一个参数解析器。