同样，在介绍MapGuide 服务器如何处理枚举资源操作之前，让我们首先来看看MapGuide 服务器用于处理服务请求和操作的类，图19‑9显示服务请求处理器类的类图，图19‑10显示了操作处理器类的类图。

图 19‑10 服务请求处理器类的类图

图 19‑11 操作处理器类的类图

MapGuide提供了资源服务、要素服务等多种服务，每种服务包含了大量操作。MapGuide为每种服务提供了一个服务请求处理器类，用于处理这些服务所提供的操作，例如MgResourceServiceHandler、MgFeatureServiceHanlder等。这些类都继承自IMgServiceHandler，并且实现了方法IMgServiceHandler::ProcessOperation(...)。MapGuide使用工厂类MgServiceHanlderFactory来创建一个服务请求处理器类的实例，给定一个服务ID，调用方法MgServiceHandlerFactory::GetHandler(...)可以创建对应的服务请求处理器类的实例。

对于服务中的每种操作，MapGuide也提供了相应的操作处理器类。从图19‑10可以看到，操作处理器类分为四个层次，最高一层是类IMgOperationHandler，它是所有操作处理类的基类，第二层是类MgServiceOperation，第三层是类MgXXXOperation，“XXX”代表服务名称，在这一层每种类型的服务都有一个对应的类，例如MgFeatureOperation、MgResourceOperation等，第四层为真正负责工作的操作处理器类，每种服务中的每个操作都有一个对应的操作处理器类，某种服务中操作处理器类都继承自同一个父类，例如MgEnumerateResource、MgSetResource都继承自MgResourceOperation。

接下来让我们看看MapGuide服务器如何处理枚举资源操作，这个操作流程的时序图如图 19‑11所示。

图 19‑12 MapGuide服务器处理枚举资源操作的时序图

1） 在线程池中找一个空闲的线程执行操作

MapGuide服务器使用了多线程和线程池的技术来提高操作处理和响应请求的性能。在MapGuide服务器启动时，会创建一个操作请求队列和一个用于处理操作请求的线程池。当一个操作请求进入操作队列，MapGuide服务器会在线程池中找一个空闲的线程执行操作。如果没有空闲的线程，那么这个操作请求会处于等待状态，直到线程池中有了空闲的线程。

首先，让我们查看一下服务器的入口函数的源代码，看看服务器是如何启动的。MapGuide服务器可以像普通的应用程序一样运行，还可以在Windows操作系统可以运行为Windows服务，在Linux操作系统运行为守护进程，下面的代码中只保留了运行为普通应用程序部分的代码。

在上面的代码中，我们可以看到大量以“ACE”为前缀的类，这些类是ACE自适配通信环境（Adaptive Communication Environment）工具包中的类。ACE是一个开源的工具包，它实现了许多用于并发通信软件的核心模式。ACE的目标用户是在UNIX和Win32平台上开发高性能通信服务和应用的开发者。ACE简化了使用进程间通信、事件多路分离、显式动态链接和并发的OO网络应用和服务的开发。ACE提供了一组丰富的可复用C++ Wrapper Facade（包装外观）和框架组件，可跨越多种平台完成通用的通信软件任务，其中包括：事件多路分离和事件处理器分派、信号处理、服务初始化、进程间通信、共享内存管理、消息路由、分布式服务动态（重）配置、并发执行和同步等。

类MgServer继承自AEC工具包中的类ACE_NT_Service或ACE_Service_Object，对应于服务器的主线程，图19‑12显示了服务器主线程类的类图。MgServer::svc()是主线程的入口，调用方法MgServer::open()会启动主线程并且执行方法MgServer::svc()，调用MgServer::fini()会终止主线程。MapGuide使用了Singleton模板ACE_Singleton将MgServer封装为一个单实例类，为了方便使用MapGuide使用typedef为ACE_Singleton定义了一个别名SERVER，调用方法SERVER::instance()可以创建类MgServer的一个实例。

图 19‑13 服务器主线程类的类图

MgServer::svc()是主线程的入口，该方法会创建一个操作请求队列和一个用于处理操作请求的线程池，它的代码如下所示。事实上，该方法还定义了其它类型的队列和线程池，为了便于理解我们省略掉了这些代码。

上面的代码中创建一个类MgOperationThread的实例，该对象创建了一个线程池，维护了一个操作请求队列。类MgOperationThread 继承自ACE工具包中的模板类AEC_Task，对应于操作线程，图19‑13显示了操作线程类的类图。ACE_Task封装了任务，每个任务都含有一或多个线程，以及一个底层消息队列。方法ACE_Task::svc()是线程的启动入口，调用方法ACE_Task::open()用于初始化任务，调用方法ACE_Task::close()用于终止任务，调用方法ACE_Task::activate()用于启动线程，调用方法ACE_Task::putq()放置消息到任务的消息队列中，调用方法ACE_Task::getq()从任务的消息队列中取出消息。

图 19‑14 操作线程类的类图

方法MgOperationThread::svc()是操作线程的入口，它的代码如下所示。

从上面的代码可以看到，方法MgOperationThread::svc()会调用方法getq(…)循环访问消息队列，取出等待处理的消息。如果是数据类型的消息，那么调用方法MgOperationThread:: ProcessMessage(...)处理这个消息。方法MgOperationThread::ProcessMessage(...)会解析这个消息的头和数据，如果消息数据中包含了一个操作请求，那么调用方法MgOperationThread:: ProcessOperation(…)处理这个操作请求。

2） 处理服务请求

方法MgOperationThread::ProcessOperation(…) 首先会解析消息数据中的服务ID、操作ID、操作的版本号等信息，然后根据服务ID使用工厂类MgServiceHanlderFactory来创建一个服务请求处理器类的实例，最后调用这个服务请求处理器类的方法IMgServiceHandler:: ProcessOperation(...)处理这个服务请求。

本节的示例中客户端发送的是一个枚举资源的操作请求，所以工厂类会创建一个MgResourceServiceHandler的实例，调用方法MgResourceServiceHandler::ProcessOperation(...)处理这个服务请求。

3） 处理操作请求

首先，方法MgResourceServiceHandler::ProcessOperation(...)会根据操作请求的ID，调用资源操作工厂类的方法MgResourceOperationFactory::GetOperation(…)创建相应的资源服务操作类MgOpEnumerateResources的实例。然后，调用MgOpEnumerateResources:: Initialize(...)初始化枚举资源操作处理器，调用方法MgServiceManager::RequestService(…)创建服务器资源服务MgServerResourceService的实例。最后，调用方法MgOpEnumerateResources::Execute()处理操作请求，该方法会调用MgServerResourceService::EnumerateResources(…)实际执行枚举资源的功能。

本节中，我们将通过介绍如何完成枚举资源功能来介绍MapGuide Web扩展的部分源代码。

在浏览器端的地址栏输入类似如下字符串，就会发送一个枚举资源的HTTP请求。

下面我们来看看MapGuide Web扩展如何处理这个请求。

在介绍MapGuide Web扩展如何处理枚举资源HTTP请求之前，让我们首先来看看MapGuide Web扩展用于处理HTTP请求和响应的类，这些类的类图如图19‑4所示。

图 19‑5 HTTP请求和响应类的类图

类MgHttpRequest和类MgHttpResponse分别是对HTTP请求和响应结果的抽象，这两个类可以用于任何类型的Web应用服务器，也就是说它们的代码不依赖于任何Web应用服务器API。在文件夹“\MgDev\Web\src\HttpHandler”下可以找到所有前缀为“MgHttp”类的源代码。

类MgHttpRequest用于处理HTTP请求，它包含了一个HTTP请求头MgHttpHeader的实例、一个HTTP请求参数HttpRequestParam的实例和一个HTTP请求元数据HttpRequestMetadata的实例。调用方法MgHttpRequest::Execute()会将HTTP请求转发给MapGuide服务器，当MapGuide服务器处理完这个请求，将请求结果返回给Web扩展之后，这个方法会返回一个MgHttpResponse对象，它表示HTTP请求的响应结果。

接下来让我们看看MapGuide Web扩展如何处理枚举资源的HTTP请求。大多数MapGuide用户都是使用IIS作为Web应用服务器，并且使用Web扩展模块isapi_MapAgent.dll来处理HTTP请求，所以本节侧重于isapi_MapAgent.dll模块处理HTTP请求的流程，这个处理流程的时序图如图19‑5所示。

图 19‑6 Web扩展处理枚举资源请求的时序图

1） 加载Web应用服务器扩展模块

如果使用的是IIS Web应用服务，那么在接收到后缀为“fcgi”的HTTP请求后，IIS会加载Web应用服务器扩展模块isapi_MapAgent.dll或MapAgent.exe。其中，isapi_MapAgent.dll基于IIS API，具有更好的性能；MapAgent.exe基于CGI技术，性能要稍微差一些。如果使用的是Apache Web应用服务器，那么在Windows平台上Apache会加载Web应用服务器扩展模块MapAgent.exe，在Linux平台上会加载模块mod_mgmapagent.so。

这三个Web服务器扩展模块实现了类似的功能，它们的源代码位置如表19‑2所示。

表 19‑2 Web服务器扩展模块的源代码位置

从图19‑6中可以看到这三个Web服务器扩展模块提供了类似的类，这些类提供了相同的接口，类XXXPostParser用于解析HTTP请求中传入的参数及参数值，类XXXResponseHandler用于将HTTP请求的响应结果发送给客户端。其中，“XXX”表示“Cgi”、“Isapi”或“Apache”。

图 19‑7 Web扩展的请求处理模块

对于模块isapi_MapAgent.dll，每个“fcgi”类型的HTTP请求会调用此模块中的方法HttpExtensionProc，这个方法的代码如下所示，为了便于理解我们只保留了一些核心代码。

2） 创建MgHttpRequest的实例，用于处理HTTP请求

在加载Web应用服务器扩展模块后，需要创建一个MgHttpRequest的实例用于处理HTTP请求。类MgHttpRequest并不关联与任何类型的Web应用服务器，所以Web应用服务器扩展模块会使用类XXXPostParser解析HTTP请求中传入的参数及参数值，将这些参数设置到MgHttpRequest对象中。

3） 调用方法MgHttpRequest::Execute()处理HTTP请求

方法MgHttpRequest::Execute()的源代码如下所示。为了便于理解，我们同样只保留了一些核心代码。

每个HTTP请求中包含一个参数“OPERATION”，它用于代表操作的类型。对于不同的操作，MapGuide定义了不同的请求响应处理器类，这个类会调用MapGuide服务中对应的方法处理这个操作，这些请求响应处理器类的类图如图19‑7所示。从图19‑7可以看到，所有请求响应处理器类都继承自类MgHttpRequestResponseHandler，每一种操作都有一个对应的子类，例如枚举资源操作使用了类MgHttpEnumerateResources，描述模式操作使用了类MgHttpDescribeSchema。

图 19‑8 HTTP请求响应处理器的类图

MapGuide定义了一个全局map对象用于存放每种操作对应的请求响应处理器类对象，它的键是操作的名称，值是请求响应处理器类对象。

调用方法MgHttpRequest::CreateRequestResponseHandler(...)可以根据操作的名称获得对应的请求响应处理器类对象。对于枚举资源操作，它会返回一个类MgHttpEnumerateResources的对象。

调用这些请求响应处理器类的Execute(…)方法，会创建一个代理服务类对象，然后调用代理服务中对应的方法。为什么说创建的是一个代理服务类对象呢？我想看完图19‑8之后大家会有所明白。从图19‑8中可以看到，所有的MapGuide服务有两个子类，一个是名称为MgProxyXXXService的代理服务类，它是MapGuide Web扩展端的一个类，另一个是名称为MgServerXXXService的服务器服务类，它是MapGuide服务器端的一个类。MgProxyXXXService最终会将服务请求转发给服务器端类MgServerXXXService，所以说真正处理服务请求的类是MgServerXXXService，MgProxyXXXService仅仅起到一个转发的作用，这也就是为什么称类MgProxyXXXService为代理服务类的原因。

图 19‑9 代理服务和服务器服务类的类图

对于枚举资源操作，MgHttpEnumerateResources::Execute(...)的源代码如下所示。调用这个方法会创建一个代理资源服务类MgProxyResourceService的对象，然后调用MgProxyResourceService::EnumerateResources(...)枚举资源，最后将操作的执行结果放入MgHttpResponse对象中。

4） 将HTTP请求的响应结果返回给客户端

调用MgHttpRequest::Execute()会返回一个MgHttpResponse对象，这个对象包含了HTTP请求的响应结果。不过，还需要调用方法XXXResponseHandler::SendResponse(...)，这样Web应用服务器才会将这个响应结果返回给客户端。

MapGuide 代码的修改可以分为两大类：功能增强 (Ehancement) 和缺陷修正 (Defect) ， MapGuide 使用 Tickets 来管理和跟踪这些修改，访问 http://trac.osgeo.org/mapguide/report 可以浏览和查询活动的和已经关闭的 Tickets ，对于功能增强 MapGuide 还使用了 RFC 进行管理。需要注意的是无论创建 Tickets 还是 RFC ，都需要有一个 OSGeo 的帐户，使用 OSGeo 帐户登录后才可以创建 Tickets 和 RFC ，访问 https://www.osgeo.org/cgi-bin/ldap_create_user.py   可以注册一个 OSGeo 的用户。

1）    缺陷修正

如果你在使用 MapGuide 的过程中发现了一个 Bug ，那么可以考虑创建一个 Ticket 。在创建 Ticket 之前，最好访问 http://trac.osgeo.org/mapguide/search 查找是否已经有其他人提交过类似的 Ticket ，或者给 mapguide-users 邮件列表发 email 问询是否见到过类似问题。在为一个 Bug 创建 Ticket 之时，需要提供一个完整的、可以重现 Bug 的步骤，如果可能的话最好提供一段代码用于重现 Bug ，最后填写 图 18 ‑3 所示的 Ticket 属性。其中， Priority 代表 Bug 的优先级， Component 代表 Bug 所属的功能组件， Severity 代表 Bug 的严重性， Milestone 代表修正了 Bug 的版本， Version 代表可以重现 Bug 的版本。最重要的是要填写正确的 Version 值，如果不清楚需要为其他属性填写什么样的值，那么可以将其他值保留为空，在其他人检阅和分配这个 Bug 时会为这些属性填写合适的值。

图  18 ‑ 3  Ticket的属性

2）    功能增强

如果要改进 MapGuide 现有的功能，或者添加一些新的功能，那么需要创建一个 RFC 。访问 http://trac.osgeo.org/mapguide/wiki/MapGuideRfcs 可以浏览现有的 RFC ，通过这些 RFC 我们可以了解 MapGuide 的每个版本添加了哪些功能，甚至下一个版本会添加哪些新的功能。 RFC 页面使用 Wiki 的方式进行维护，使用如下的步骤可以创建一个新的 RFC 。

1）    点击“ login ”登录。

2）    点击“ Edit this page ”编辑 RFC 列表页面。

3）    加入如下 Wiki 格式的字符串。其中，“ XX ”代表 RFC 的序号，“ V.V ”代表实现 RFC 的 MapGuide 版本号。

||[wiki:MapGuideRfcXX MapGuide RFC XX - xxxxxxxxxxxx]||draft||V.V||

4）    点击“ Submit changes ”按钮提交修改。

5）    点击超链接“ MapGuide RFC XX ”会出现一个新的页面用于创建新的 RFC 。

6）    在按照 RFC 模板的格式创建完成新的 RFC 之后，发 email 给 MapGuide 邮件列表 mapguide-internals@lists.osgeo.org 要求 MapGuide 开源社区的人们评阅此 RFC 。

7）    在 RFC 发布一周后，并且解答了 MapGuide 开源社区人们的所有问题之后，可以要求 PSC 的成员对此 RFC 投票。如果由多于两个 PSC 成员同意此 RFC ，没有任何 PSC 成员反对此 RFC ，那么此 RFC 就投票通过可以实现了。

8）    创建一个类型为“ enhancement ”的 Ticket 用于跟踪这个修改。

在修正了一个缺陷或实现了一个 RFC 之后，需要将相应的代码修改创建为一个 SVN Patch 文件，将其上传到相应的 Ticket 上便于开源社区的人们评阅此修改，在评阅完成之后就可以提交代码了。如果你不是项目开发 人员，没有提交权限， 项目开发 人员会帮助你提交代码的。

作为 OSGeo 的一个子项目， MapGuide 遵守与其他 OSGeo 项目的类似的管理方式，由如下四类组织和角色进行项目的开发和管理。

1）    项目筹划指导委员 会(Project Steering Committee)

项目筹划指导委员会简称为 PSC ，负责 MapGuide 开源项目的管理工作，决定 MapGuide 开源版的发布日期、哪些功能和缺陷修正整合到那个发布版本、那些人可以成为项目开发人员等，而且 PSC 还负责定期为 OSGeo 委员会提供项目状况报告。

2）    项目开发 人员(Project Developer)

项目开发人员具有 MapGuide 源代码的读写权限，能够直接修改 MapGuide 的源代码，并且负责检阅项目捐助人员的代码，帮助他们提交代码。

3）    项目捐助 人员(Project Contributor)

项目捐助人员也是 MapGuide 的开发人员，但是没有 MapGuide 源代码的修改权限，他们通过项目跟踪 (Tracker) 工具为 MapGuide 贡献补丁 (Patch) 、代码、文档等，项目开发人员会检阅他们的修改，和他们进行交流，最后帮助他们提交代码。通常情况下，项目开发人员是从项目捐助人员着手做起，在项目捐助人员贡献了大量有价值的补丁 (Patch) 之后，他会被提名为项目开发人员，在 PSC 投票同意之后，他就会正式成为项目开发人员，具有了 MapGuide 代码的修改权限。

4）    用 户(Users)

    用户是 MapGuide 的使用者，他们基于 MapGuide 进行二次开发。

如果想自己编译MapGuide的源代码和运行MapGuide，那么请参考MapGuide开源版的文档 (http://mapguide.osgeo.org/documentation.html)，各个版本MapGuide的编译步骤基本相同，但是细节却不尽相同，所以要找到使用的源代码所对应的文档，严格按照文档中描述的步骤编译MapGuide。

因为MapGuide服务器和Web扩展是两个独立的组件，所以它们也是独立编译的。编译MapGuide服务器组件的基本步骤如下：

1）   编译FDO

MapGuide 使用了FDO来访问GIS数据，但是MapGuide的源代码中并没有包含FDO的源代码，所以需要开发人员自己下载FDO的源代码和编译FDO。

2）   设置环境变量

需要注意的是不同版本的MapGuide源代码需要设置不同的环境变量，所以要注意参考对应版本的文档。

3）   编译CS-MAP

从MapGuide开源版2.1之后，MapGuide使用CS-MAP替代了PROJ4来处理坐标系。现在CS-MAP也是OSGeo的一个开源项目，在使用SVN下载MapGuide源码的时候会自动下载CS-MAP的代码，不过需要用户独立编译CS-MAP。

4）   编译OEM

OEM 就是MapGuide所依赖的第三方组件，例如ACE、SWIG、DWF Toolkit、FDO、Oracle Berkeley DB XML等，MapGuide服务器和Web扩展都依赖于OEM，所以在编译MapGuide服务器和Web扩展时都需要编译OEM，但是只需要编译一次。

在Windows平台上，打开文件夹\MgDev\Oem\下的Visual Studio Solution文件oem.sln就可以编译OEM组件。

5）   编译MapGuide服务器

这部分代码是MapGuide服务器真正的代码，在Window平台上打开文件夹\MgDev\Server\下的Visual Studio Solution文件Server.sln就可以编译MapGuide服务器。

编译MapGuide Web扩展的步骤如下：

1）   安装JDK

MapGuide Web 扩展需要安装Java JDK 1.3或更高的版本，如果没有安装JDK，请访问http://java.sun.com下载安装它。

2）   设置环境变量

需要注意的是不同版本的MapGuide源代码需要设置不同的环境变量，所以要注意参考对应版本的文档。

3）   编译OEM

OEM 组件只需要编译一次，如果在编译MapGuide服务器时已经编译了OEM，那么无需重新编译。

4）   编译MapGuide Web扩展

这部分代码是MapGuide Web扩展真正的代码，在Window平台上打开文件夹\MgDev\Web\src下的Visual Studio Solution文件WebTier.sln就可以编译MapGuide Web扩展。

MapGuide 源代码的目录结构如 表 18 ‑1 和 图 18 ‑2 所示，在后续的章节中我们将重点介绍 Common 、 OEM 、服务器和 Web 扩展部分的源代码。

表  18 ‑ 1  MapGuide源代码目录结构

如果要访问 MapGuide 的源代码，需要先安装一个 Subversion 的客户端，通过 Subversion 的网站 ( http://subversion.tigris.org/ ) 可以了解到关于 Subversion 最为详尽的信息。一般情况下，推荐大家使用 TortoiseSVN 访问 MapGuide 的源代码，它将 SVN 客户端和 Windows Shell 很好地整合在一起，在 TortoiseSVN 的网站 ( http://tortoisesvn.tigris.org/ ) 上可以下载到最新版本的 TortoiseSVN 。

Subversion 仓储的位置为 http://svn.osgeo.org/mapguide/ ，在 Windows Shell 中点击鼠标右键，选择菜单“ SVN Checkout ”将显示如 图 18 ‑1 所示的用户界面，在“ Checkout Directory ”中输入代码下载位置，然后点击“ OK ”按钮就可以下载 MapGuide 的源代码。在“ Trunk ”目录下包含的是 MapGuide 最新的源代码，在“ branches ”目录下包含了 MapGuide 从版本 1.0.0 到 2.1 的所有源代码。

图  18 ‑ 1  TortoiseSVN用于Checkout代码的用户界面

如果仅仅是希望浏览 MapGuide 的源代码，可以访问 http://trac.osgeo.org/mapguide/browser 在浏览器中浏览 MapGuide 的源代码。

许多人都知道MapGuide提供了.NET、PHP和Java三种类型的Web API，但是不知道MapGuide是如何创建这三种类型的API的。试想一下，如果分别去创建这三种API，这将是一个很难维护的工作。每次增加或修改一些功能，就需要对三种类型的API都进行修改。所以，MapGuide使用了SWIG来自动生成这三种类型的API。我想这个时候许多人会问，什么是SWIG呢？我怎么从来没有听说过这个东东呢！其实，我也是在做MapGuide开发的时候才开始了解SWIG的。所以，首先让我们来认识一下SWIG，然后再来看MapGuide是如何使用SWIG来生成API的。

1. SWIG简介

    SWIG是Simple Wrapper and Interface Generator的缩写，是一个帮助使用C或者C++编写的软件创建其他编语言的API的工具。例如，我想要为一个C++编写的程序创建.NET API，一般情况下我必须使用托管C++(Managed C++)去编写大量的代码才能生成它的.NET API。有了SWIG，这个机械的工作将变得非常简单。你只须要使用一个接口文件告诉SWIG要为那些类创建.NET API，SWIG就会自动帮你生成它的.NET API。是不是非常的酷啊？

    当然，SWIG不仅仅支持创建.NET API。最新版本的SWIG支持常用脚本语言Perl、PHP、Python、Tcl、Ruby和非脚本语言C#, Common Lisp (CLISP, Allegro CL, CFFI, UFFI), Java, Modula-3, OCAML以及R，甚至是编译器或者汇编的计划应用（Guile, MzScheme, Chicken）。

    下面我们通过一个例子来看看SWIG是如何帮我们创建API的。假设我打算为如下的C++类创建C#和Java的API。

    /* SwigTest.h */

    class CSwigTest {
    public:
        CSwigTest();
        virtual ~CSwigTest();
        int Add(int a, int b) { return a + b; }
        int Substract(int a, int b) { return a - b; }

        int Multiple(int a, int b) { return a * b; }
        float Divide(int a, int b) { return (float)a / (float)b; }
    };

1.1 接口文件

    首先，你需要写一个接口文件(Interface File)，告诉SWIG要为那些类的那些方法创建API。如下的接口文件只为类CSwigTest的方法Add(...)和Subtract(...)生成API，因为在接口文件的接口声明部分只声明了两个方法。

    /* SwigTest.i */
    %module SwigTest
    %{
    #include "SwigTest.h"
    %}

    /* --- 接口声明部分 ---*/
    class CSwigTest {
    public:
        int Add(int a, int b);

        int Substract(int a, int b);

    };

    注解：%module标记用于定义SWIG生成的模块的名称，%{%}标记中的内容会被一字不差地插入SWIG自动生成的文件xxx_wrapper.c中，其中xxx代表用%module指定的模块名称。这个文件会在下面介绍，不必着急去理解它究竟有什么作用。

    如果打算为类中所有方法创建API，那么有一个非常简单的办法，在接口文件的类声明部分使用%include标记。SWIG将对%include所指定的文件进行语法分析，类中所有公有方法(Public Method)都将在API中暴露。

    /* SwigTest.i */
    %module SwigTest
    %{
    #include "SwigTest.h"
    %}
    #include “SwigTest.h” 

1.2 编译模块

    有了接口文件之后，剩下的事就是执行几条命令。下面我们以Windows平台上生成.NET API为例介绍这些命令。

    (a) 调用SWIG自动生成代码

    swig -csharp  SwigTest.i

    执行上面的命令会产生一个C语言文件SwigTest_wrapper.c和多个C#文件。在文件SwigTest_wrapper.c中，SWIG为接口文件中接口声明部分指定的每个方法产生一个全局方法，以便C#使用Pinvoke调用这些函数。而那些C#文件就是用来生成.NET API的。

    (b) 为C++代码生成DLL(动态链接库)

    cl SwigTest_wrapper.c *.cpp

    link *.obj /out:SwigTest.dll

    执行上面的命令，会为我们编写C++代码生成DLL。在编译C++文件时，一定要包括SWIG为我们生成的C++文件SwigTest_wrapper.cpp。

    注意：为了让大家便于理解上述命令，这些命令并没有列出完整的编译和链接选项。

    (C) 生成.NET模块

    csc /out:SwigTestNotNetAPI.dll /target:library *.cs

    执行上面的命令就生成了.NET API模块SwigTestNotNetAPI.dll。如果用户想使用这些API，只需要添加对SwigTestNotNetAPI.dll的引用(Reference)就可以了。

    生成其它语言类型API的命令基本类似，下面我们再以Java在Unix平台下的命令为例结束对SWIG的介绍。事实上，SWIG也是一个开源项目。如果想了解更多关于SWIG的信息，大家可以登陆SWIG的官方网站www.swig.org，那里有SWIG最详细的资料。
    $ swig -java SwigTest_wrapper.i
    $ gcc -c *.cpp SwigTest_wrapper.c -I/c/jdk1.3.1/include -I/c/jdk1.3.1/include/win32
    $ gcc -shared *.o -mno-cygwin -Wl,--add-stdcall-alias  -o SwigTest.dll

2. SWIG在MapGuide中的应用

    我们在前面已经提到过，MapGuide使用了SWIG来自动生成.NET、Java和PHP这三种类型的API。但是，SWIG也有不少限制和缺陷，所以MapGuide对SWIG源代码进行了大量的修改，以满足自己的要求。下面，我们看看这些改进。

2.1 IMake工具

    SWIG要求开发人员编写一个接口文件，那么能否让接口文件自动生成呢？借用一句中国移动的广告词，我能！虽然SWIG没有提供这方面的工具，但是我们可以自己开发吗！IMake(Interface Maker)就是为了满足这样的要求而开发一个工具，给定一个XML文件，它能帮你自动生成SWIG接口文件。登录MapGuide开源版的代码浏览页面(http://trac.osgeo.org/mapguide/browser)，在root/trunk/MgDev/BuildTools/WebTools/IMake文件夹下可以找到IMake的源代码。

     下面我们以MapGuide中使用的XML文件/trunk/MgDev/Web/src/MapGuideApi/MapGuideApiGen.xml为例，介绍一下IMake的用法。为了便于理解，在此我删掉了文件中的部分内容。

    <?xml version="1.0" encoding="UTF-8"?>
    <Parameters>
      <!-- 对应于%Module标记. -->
      <Module name="MapGuideApi" />

      <!-- 生成的接口文件的名称. -->
      <Target path="./MapGuideApi.i" />

      <!-- 对应于%{%}标记 -->
      <CppInline>
        #include &lt;string&gt;
        #include &lt;map&gt;
        #include "MapGuideCommon.h"
        #include "WebApp.h"
        ......
      </CppInline>

      <!-- 用于替换接口中使用的部分类型 -->
      <TypeReplacements>
        <TypeReplacement oldtype="CREFSTRING" newtype="STRINGPARAM" />
        <TypeReplacement oldtype="INT64" newtype="long long" />
      </TypeReplacements>

      <!-- 此部分的内容添加在%{%}之后，接口声明部分之前 -->
      <SwigInline>
        %include "language.i"   //typemaps specific for each language
        ......
      </SwigInline>
      
      <!-- 为指定的C++文件生成接口声明 -->
      <Headers>
        <Header path="../../../Common/Foundation/Data/Property.h" />
        ......
      </Headers>
    </Parameters>

    执行命令“IMake MapGuideApiGen.xml”，IMake就帮我们自动生成了如下SWIG接口文件MapGuideApi.i。

    /* MapGuideApi.i */
    %module MapGuideApi 
    %{
        #include <string>;
        #include <map>;
        #include "MapGuideCommon.h"
        #include "WebApp.h"
        ......
    %}
 
    %include "language.i"   //typemaps specific for each language
    ......

    class MgProperty: public MgNamedSerializable
    {
    public:
        virtual INT16 GetPropertyType();
        STRING GetName();
        void SetName(CREFSTRING name);
    };

    ......

    如果打开文件Proper.h，我们可以看到MgProperty有更多的方法，例如CanSetName(...)。为什么只有三个方法添加到了SWIG接口文件中？IMake在生成接口文件时，它会查找C++头文件中的宏PUBLISHED_API。只有被PUBLISHED_API修饰的方法，才会添加到接口文件中。

    注：宏PUBLISHED_API和INTERNAL_API的定义如下。

    #define PUBLISHED_API public

    #define INTERNAL_API public

    class MG_FOUNDATION_API MgProperty : public MgNamedSerializable 
    { 
    PUBLISHED_API:

        virtual INT16 GetPropertyType() = 0;  /// __get   
        STRING GetName();  /// __get, __set 
        void SetName(CREFSTRING name); 
  
    INTERNAL_API: 
        virtual bool CanSetName(); 
  
    protected:  
        INT32 GetClassId(); 
        MgProperty(); 
        virtual ~MgProperty(); 
        virtual void Dispose();   
        virtual void ToXml(string &str, bool includeType = true, string rootElmName = "Property") = 0; 
  
    private: 
        friend class MgPropertyCollection; 
        STRING m_propertyName; 
 
    CLASS_ID: 
        static const INT32 m_cls_id = Foundation_Property_Property; 
    };     
    给定一个C++常量定义文件，IMake还可以自动生成对应的其他语言的常量定义文件。MapGuide .NET Web API中的所有常量都是使用IMake来生成的，例如MgMineType、MgPropertyType等。下面我们以MapGuide中使用的XML文件/trunk/MgDev/Web/src/MapGuideApi/Constants.xml为例，介绍如何自动生成各种语言的常量定义文件。同样，为了便于理解，在此我删掉了文件中的部分内容。与MapGuideApiGen.xml不同，Constants.xml包含一个新的元素Classes用来指出需要在目标语言中产生对应的常量类的C++类。
    <?xml version="1.0" encoding="UTF-8"?>

    <Parameters>

    <!-- 用于替换类型 -->

    <PHPTypeReplacements> 
        <TypeReplacement oldtype="STRING" newtype="" />
        <TypeReplacement oldtype="INT16" newtype="" />
        ......
    </PHPTypeReplacements>
    <CSharpTypeReplacements>
        <TypeReplacement oldtype="STRING" newtype="string" />
        <TypeReplacement oldtype="INT16" newtype="short" />
        ......
    </CSharpTypeReplacements>
    <JavaTypeReplacements>
        <TypeReplacement oldtype="STRING" newtype="String" />
        <TypeReplacement oldtype="INT16" newtype="short" />
        ......
    </JavaTypeReplacements>

    <Namespace>OSGeo.MapGuide</Namespace>
    <Package>org.osgeo.mapguide</Package>

    <!-- 用于指出需要在目标语言中产生对应的常量类的C++类 -->

    <Classes>
        <Class name="MgMineType" />
        <Class name="MgPropertyType" />
        ......
    </Classes>

    <Headers>
        <Header path="../../../Common/Foundation/Data/MimeType.h" />
        <Header path="../../../Common/Foundation/Data/PropertyType.h" />
        ......
    </Headers>

    </Parameters>

    执行命令“IMake.exe Constants.xml C# Constants.cs”，IMake就帮我们自动生成了一个C#常量文件Constants.cs。对于文件/trunk/MgDev/Common/Foundation/Data/PropertyType.h中定义了如下常量，

    class MgPropertyType 
    { 
    PUBLISHED_API:  
       static const int Null     =  0;
       static const int Boolean  =  1; 
       static const int Byte     =  2; 
       static const int DateTime =  3;
       static const int Single   =  4; 
       ......
    };

    在生成的Constants.cs文件中，有如下的类定义。
    class MgPropertyType 
    { 
       static const int Null     =  0;
       static const int Boolean  =  1; 
       static const int Byte     =  2; 
       static const int DateTime =  3;
       static const int Single   =  4; 
       ......
    };

    这个文件可以被C#的编译器直接编译，所以MapGuide没有使用SWIG生成常量的API，而是直接使用IMake。 如果想生成PHP或Java的常量定义文件，只需要将IMake命令的参数"C#"替换为"PHP"或"Jave"就可以了。

2.2 MapGuide对SWIG的修改
    在MapGuide开始使用SWIG的时候，可用的SWIG的最高版本是1.3.21，从那以后MapGuide在没有升级过SWIG。所以，到现在为止，MapGuide的SWIG版本仍然是1.3.21。这个版本的SWIG有不少限制和缺陷，

• 无法创建基于自定义根异常类MgException的异常处理机制。
• 无法创建属性(Property)。
• 对某些方法无法产生正确的API。例如，如果方法GetA(...)返回的是类A的子类B的实例，SWIG创建的API返回的仍然是A类的实例。此时如果你把返回值转换为类B，那么转换会失败。
      A* GetA();
• ......

    事实上最新的SWIG版本也没有全部解决这些问题，所以MapGuide对SWIG源代码进行了大量的修改，以满足自己的要求。看看MapGuide在使用SWIG命令是传入的参数，我们可以发现有许多参数不是SWIG标准的参数，例如proxydir、clsidcode、clsiddata、catchallcode等。

swig -c++ -csharp -dllname MapGuideUnmanagedApid -namespace OSGeo.MapGuide -proxydir .\custom -baseexception MgException -clsidcode getclassid.code -clsiddata m_cls_id -catchallcode catchall.code -dispose &quot;((MgDisposable*)arg1)-&gt;Release()&quot; -rethrow &quot;e-&gt;Raise();&quot; -nodefault -noconstants -module MapGuideApi -o MgApi_wrap.cpp -lib ..\..\..\Oem\SWIGEx\Lib MapGuideApi.i

    在此，我们不打算一一介绍这些参数，因为在多数情况下你没有必要对了解参数的含义。我们只介绍MapGuide是如何来解决上述SWIG的第二和第三个问题的，因为在扩展MapGuide Web API的时候你可能会用得着。

2.2.1 创建属性
    如果你看过MapGuide源代码的话，你会发现有许多方法声明之后有“__get”、“__set”或“__get, __set”这样的注释，如类MgProperty中的方法。
    class MgProperty : public MgNamedSerializable 
    { 
    PUBLISHED_API: 
        virtual INT16 GetPropertyType() = 0;  /// __get   
        STRING GetName();  /// __get, __set 
        void SetName(CREFSTRING name); 
        ......
};
    这些注释是有特殊含义的，它们就是用来解决上述SWIG的第二个问题的。当IMake工具扫描C++头文件时发现这注释后，会在目录“.\custom”下为每个类产生一个帮助创建属性的代码文件。例如，如果要类MgProperty生成.NET API，IMake会在“.\custom”生成一个文件名为MgProperty的C#代码文件，它的内容如下：
    public int PropertyType {
        get {return GetPropertyType(); }
    }
    public int Name {
        get { return GetPropertyType(); }
        set { setName(value);}
    }
    如果在SWIG的命令行中使用了参数proxydir，那么SWIG在为每个类生成代码的时候，会在proxydir所指定的目录下查找和类名相同的文件，并且将这个文件中的代码插入类的目标代码中。通过这种办法，就解决了上述SWIG的第二个问题。

2.2.2 ClassId
    MapGuide Web API中的所有类都是从MgObject继承而来的，在类MgObject中有一个方法GetClassId()用来返回每个类唯一的ID值。MapGuide就是用这个方法来解决上述SWIG的第三个问题的，所以如果要在MapGuide Web API中增加一个新类，一定要覆盖(override)这个方法，并且提供一个唯一的ID值。
    class MgObject
    {
    EXTERNAL_API:
        virtual INT32 GetClassId();
        virtual STRING GetClassName();
    INTERNAL_API:
        virtual ~MgObject();
        bool IsOfClass(INT32 classId);
    };

3. 扩展MapGudie Web API

    如果你发现现有的MapGuide Web API无法满足你的要求，没有关系，你可以去尝试扩展它，因为MapGuide是开源的。

    如果要新添类，基本步骤如下：
    (a) 修改C++代码，添加新的类。对于需要暴露于API的方法，使用宏PUBLISHED_API修饰。
    (b) 修改XML文件/trunk/MgDev/Web/src/MapGuideApi/MapGuideApiGen.xml的Headers部分，为每个新添加类所在的C++头文件增加一个Header元素。下面的示例中，"path"代表C++头文件的路径，"filename.h"代表文件的名称。
    <Headers>
        <Header path="path/filename.h" />
        ......
    </Headers>
    (c) 重新编译MapGuide的Web模块(/trunk/MgDev/Web/src/)。
 
    如果要增加一些新的方法到现有的类中，基本步骤如下：
    (a) 修改C++代码，添加新的方法，并且使用宏PUBLISHED_API修饰这些方法。
    (b) 重新编译MapGuide的Web模块(/trunk/MgDev/Web/src/)。

    如果要新增常量类，基本步骤如下：
    (a) 修改C++代码，添加新的常量类。
    (b) 修改XML文件/trunk/MgDev/Web/src/MapGuideApi/Constants.xml，在Classes部分为每个新添加常量类增加一个Class元素，在Headers部分为每个新添加常量类所在的C++头文件增加一个Header元素。下面的示例中，"ClassName"代表新添加的C++常量类的名称。

    <Classes>
        <Class name="ClassName" />
        ......
    </Classes>
    <Headers>
        <Header path="path/filename.h" />
        ......
    </Headers>    
    (c) 重新编译MapGuide的Web模块(/trunk/MgDev/Web/src/)。