SuperMap iServer REST资源(Restlet)扩展机制简介

作者：MR

###iServer体系结构及扩展点
####iServer体系结构：

    iServer 服务框架是一个三层结构的体系，他们分别是 GIS 服务提供者，GIS 服务组件层和服务接口层。这种三层结构首先实现具体的 GIS 功能实体，再次通过第二层次的模块将 GIS 功能实体封装为粗粒度的组件，在功能实体与第二层的 GIS 服务组件以及 iServer 服务与客户端之间都是通过接口层规定的标准接口进行交互。目前 iServer 在每层中都相应提供一系列的模块，他们之间具有松耦合关系。在 iServer 服务框架中通过服务管理模块将三个层次中具有对应关系的模块进行集成，构建一系列的 GIS 服务。
#####GIS 服务组件
    GIS算法库。

#####GIS 服务提供者
    提供具体GIS服务内容。
#####GIS 服务接口
    访问GIS服务的接口。

#####其他
    除了 GIS 功能的组成模块之外，作为企业级的 GIS 服务器，SuperMap iServer 在系统体系结构上充分体现了它的服务器能力，主要包括：集群、缓存、管理、日志等。
    你可以从iServer管理页面找到这三层结构，要使用地得心应手也得需要了解这三层结构，这样就能完成很多个性化的配置了。
    详见：http://support.supermap.com.cn:8090/iserver/help/html/zh/Service_introduce/Architecture.htm
    各层次的交互关系：
    http://support.supermap.com.cn:8090/iserver/help/html/zh/Service_introduce/relationship.htm

###iServer扩展点
    使用iServer JAVA API 不是扩展iServer的方式，iServer的扩展主要有如下几种：

•	现有 REST 资源扩展
•	领域空间信息服务扩展
•	集群机制扩展
•	安全认证扩展
•	登录方式扩展
•	分布式切图切片格式扩展

详见：http://support.supermap.com.cn:8090/iserver/help/html/zh/DevelopGuide/Extend_iServer/Extend_iServer.htm

###基于 Restlet 机制扩展现有REST资源

    REST资源的扩展即扩展现有服务组件（或自己写的服务组件）基于Restlet 机制的服务资源。比如地图服务的map资源（比如：http://support.supermap.com.cn:8090/iserver/services/map-world/rest/maps/World）及其子资源；数据服务的datasources、featureResults资源（比如http://support.supermap.com.cn:8090/iserver/services/data-world/rest/data/featureResults）及其子资源等，总之即是基于Restlet 机制的服务组件整合的资源都包括再内。

    基于 Restlet 机制实现 REST 资源的模块有：地图模块、数据模块、交通网络分析模块、三维模块。提供的扩展形式如下：

•  扩展资源。使用 REST SDK，通过继承 SDK 中提供的抽象资源类，进行新资源的扩展。
•  扩展表述生成器。使 SuperMap iServer 服务器能将已有资源发布成新的表述格式。
•  扩展参数解析器。使 SuperMap iServer 服务器能够识别新的参数传递格式。
•  扩展 HTTP 请求处理器。可以定制 HTTP 请求在 SuperMap iServer 服务器中的处理过程。
•  扩展安全机制。使用户可以将自定义的安全机制配置到 SuperMap iServer 服务器上。

    客户端访问 SuperMap iServer REST 服务，一个 HTTP 请求在 SuperMap iServer 服务器端的流程如下图所示，其中，绿色的部分为扩展点：

    其中，通过 REST SDK 扩展的资源、通过领域组件发布而成的资源和 SuperMap iServer 服务器上原有的资源，都可以进行表述生成器、参数解析器、HTTP 请求处理器的扩展。
    REST 服务发布机制简述，参见：
http://support.supermap.com.cn:8090/iserver/help/html/zh/DevelopGuide/Extend_iServer/Extend_RESTlet/RestServiceProduce.htm

    简单解释：
    扩展资源即是具体实现业务功能，可以使用服务组件提供的方法、服务提供者提供的方法、超图java组件提供的方法、第三方类库以及自定义方法等。
    其他部分的扩展视需要进行，最常用的json(iServer默认支持跨域请求，要修改，需配置对应服务接口)、jsonp格式iServer默认已经支持，有其他需要才需要扩展，一般只需扩展资源即可。

###Restlet REST资源扩展实现方式
####实现需扩展的资源类
    资源的基类是：com.supermap.services.rest.resources. ResourceBase
    创建java工程，直接实现该类或继承它的子类就能实现不同资源层次的扩展，现有资源类型参考：

名称	资源实现的直接父类	对应的以实现的资源
简单算法资源	SimpleAlgorithmResultResourceBase	map 模块的 symbol、clearCache 等资源，data 模块的 statistic 等资源
简单算法资源	ImageResourceBase	entireImage、highlightImage、image、overview、tileImage 等资源
简单算法资源	MeasureResourceBase	area、distance 等资源
算法结果资源	AlgorithmResultResource	map 模块的 queryResults 等资源，data 模块的 featureResults 等资源
算法结果集资源	AlgorithmResultSetResource	map 模块的 queryResults 等资源，data 模块的 featureResults 等资源
目录资源	CatalogListResourceBase	map 模块的 maps、root、tempLayersSet、trackingLayers、domainComponents、domainComponentdata 等资源，data 模块的 data、datasources 等资源，networkanalyst 模块的 networkanalyst 等资源，3D 模块的 3D 、scenes、datas 等资源
静态资源	StaticResource	map 模块的 layers、map、templayers 等资源，networkanalyst 模块的 networkDataName 等资源

####实现对应资源后需要对资源进行配置，以让iServer能识别到。可以有如下两种方式：

    1.添加到外部 iserver-rest-resources.xml 文件（路径 %SuperMap iServer_HOME%/webapps/iserver/WEB-INF/iserver-rest-resources.xml）
    2. 添加到功能模块自己的 XML 配置文件，即插即用

    其中，1可参考iServer配置文件说明 ，2是推荐的方式，好处是即插即用，无需额外配置

    第二种资源配置的方式：

    在工程新建资源文件夹resource (source folder), 该文件夹下新建META-INF文件夹，参考资源配置说明创建相应文件夹和文件即可完成配置。

    比如扩展数据服务模块则在上述META-INF文件夹下创建文件夹：

/extensions/services/rest

    然后创建dataRest文件(无后缀)，该文件内容参考上面的资源配置说明

    完整路径：

Jar:///META-INF/extensions/services/rest/dataRest

    （可选）使资源支持html表述
    若要扩展的资源支持html表述（首先要支持GET方法），即浏览器访问该资源时返回的页面，需要在上述工程里创建的资源文件夹resources下创建templates文件夹，下面创建基于FreeMarker的html模板，文件名为：

{配置的资源ID}.ftl

比如：MyFunction.ftl

中文模板为：

{配置的资源ID}_zh_CN.ftl

    访问该页面默认会返回当前语言的对应模板，默认操作是GET；若资源还支持POST等方法，也可以自定义其他方法的页面模板，右边点击该HTTP方法时即可返回对应模板（否则使用默认）。POST操作的模板比如：

{配置的资源ID}_POST_zh_CN.ftl

    比如下面这个url点击右侧HTTP方法返回的页面是不同的
    http://support.supermap.com.cn:8090/iserver/services/data-world/rest/data/featureResults

    最后，将整个工程输出为jar文件，放到%SuperMap iServer_HOME%/webapps/iserver/WEB-INF/lib 目录下，重启iServer即可在对应的地方看到扩展的资源了。

    帮助文档一个扩展REST资源（Restlet机制）的示例：
    http://support.supermap.com.cn:8090/iserver/help/html/zh/DevelopGuide/Extend_iServer/Extend_RESTlet/extendSimpleAlgorithm.htm