基于 JAX-RS 机制扩展领域资源 |
SuperMap iServer 提供了 Restlet、JAX-RS 两种机制，方便将领域功能发布为 REST 资源。其中，有关 JAX-RS 机制请参见：JAX-RS 简介。
在 SuperMap iServer JAX-RS 机制的 REST 实现框架中，最高层的资源类是 com.supermap.services.rest.resources.JaxrsResourceBase，所有的资源实现类都直接或间接地继承于它。
com.supermap.services.rest.resources.JaxAlgorithResultSetResource<T> 对 JaxrsResourceBase 进一步实现，方便要求支持 POST 请求的资源的实现。
继承 JaxrsResourceBase 或 .JaxAlgorithResultSetResource<T>，按照 JAX-RS 标准定义资源即可。
注意：
@Path("/addressmatch")
// 申明该资源需要使用的业务组件
@Component(interfaceClass = com.supermap.services.components.AddressMatch.class)
public class AddressMatchResource extends JaxrsResourceBase {
...
}
SuperMap iServer 中，服务组件通过相匹配的服务接口发布为 Web 服务，在资源实现类中，通过服务接口上下文获取服务组件，从而获取相应的 GIS 功能。
JaxrsResourceBase 提供了 getInterfaceContext() 接口，资源实现类可直接使用，获取服务接口上下文，从而获取服务组件，代码片段如下：
InterfaceContext interfaceContext=super.getInterfaceContext(); List<Temperature> tempratureComponents=interfaceContext.getComponents(Temperature.class); Temperature tempratureComponent=tempratureComponents.get(0);
在 JAX-RS 机制的 REST 资源实现类中，SuperMap iServer 提供了@Template 注记指定 FreeMarker 模板，示例代码片段如下：
@GET
@Path("{cityname}")
@Template(name = "temperature.ftl")
public String getMapImageURI(
@PathParam("cityname") String cityname,
@Context HttpServletRequest request) {
...
}
FreeMarker 是基于模板生成文本输出的通用工具。*.ftl 可以跟资源实现类一起打的 Jar 中，*.ftl 文件需要放在 Jar 包:///templates 目录下。@Template 注记中 name 指定的即是*.ftl 文件的文件名。
SuperMap iServer 提供了一些变量供用户在制作*.ftl 模板时使用，从而获取资源信息，参见：iServer 提供的 FreeMarker 变量。
首先，可通过配置文件说明了解“模块配置文件”和“资源配置文件”两个概念。领域模块发布为 REST 资源时，需要建立这两个文件。这两个文件都打在 Jar 包里，实现扩展模块的即插即用，方便系统管理员配置。
模块配置文件位于 Jar:///META-INF/extensions/services/rest 位置；
资源配置文件位于 Jar 包中，位置由模块配置文件中的 resourceFiles 项指定。
资源配置可跟资源实现类、FreeMarker 模板，打成一个 Jar 包。Jar 包放到 %SuperMap iServer_HOME%/webapps/iserver/WEB-INF/lib 目录下，启动 SuperMap iServer 服务即可。
示例工程可在以下位置获取：%SuperMap iServer_HOME%\samples\code\DSSE_JSR。
示例说明参见：基于 JAX-RS 机制定义 REST 资源。
作为一个整体的工程文件，用户使用时需要把工程导入并编译后导出为 JAR 包（参见：dsse_jsr.jar），然后放在%SuperMap iServer_HOME%\webapps\iserver\WEB-INF\lib 下，并配置 服务配置文件（详见服务配置文件结构），启动 iServer 服务即可。
自定义的 REST 资源默认支持的表述格式有：xml、json、rjson，在通过 @Template 注记定义了 FreeMarker 模板后，还支持 HTML 表述。可对此进行扩展，使领域资源支持更多的表述格式。
JAX-RS 机制下，REST 资源表述生成器的扩展遵循 JAX-RS 标准。基于 javax.ws.rs.ext.MessageBodyWriter 实现，使用@Provider 标注来注册使用自定义的 MessageBodyProvider，并使用@Produces 指定媒体类型。
扩展过程跟现有 REST 资源扩展中的扩展表述生成器一致，参见：表述生成器扩展。
注意：资源响应的媒体类型由 HTTP 请求的 URI 后缀决定，参见：URI 后缀与媒体类型的对应关系。
自定义的 REST 资源默认支持的参数格式有：json。
JAX-RS 机制下，REST 资源表述生成器的扩展遵循 JAX-RS 标准。基于 javax.ws.rs.ext.MessageBodyReader 实现，通过@Provider 来标注使用自定义的 MessageBodyProvider，并使用@Consumes 指定媒体类型。
扩展过程跟现有 REST 资源扩展中的扩展表述生成器一致，参见：参数解析器扩展。
注意：资源响应的媒体类型由 HTTP 请求的 URI 后缀决定，参见：URI 后缀与媒体类型的对应关系。