1. 通用类
通用类包含MgObject、MgDisposable、MgGuardDisposable、MgByteSource、MgByteSink、MgSerializable、MgService、MgNamedSerializable、MgWarnings、MgByteReader、MgColor、MgDateTime、MgServiceType和MgMimeType共14个类，图 3‑3是这些类的类图。
我们可以将MapGuide Web API中的所有类分为常量类和非常量类两种。常量类只定义了一些常量，没有定义其他任何额外的成员属性或方法。对于PHP类型的API来说，所有的常量类都定义在文件“/www/mapviewerphp/constants.php”中。如下的代码摘取自文件“constants.php”中，它定义了通用类中的常量类MgMimeType和MgServiceType。
|
Class MgMimeType { const Agf = "application/agf"; const Binary = "application/octet-stream"; const Dwf = "model/vnd.dwf"; const Gif = "image/gif"; const Jpeg = "image/jpeg"; const Png = "image/png"; const Text = "text/plain"; const Tiff = "image/tiff"; const Xml = "text/xml"; const Json = "application/json"; const Html = "text/html"; const Kml = "application/vnd.google-earth.kml+xml"; const Kmz = "application/vnd.google-earth.kmz"; } class MgServiceType { const ResourceService = 0 ; const DrawingService = 1 ; const FeatureService = 2 ; const MappingService = 3 ; const RenderingService = 4 ; const TileService = 5 ; const KmlService = 6 ; } |
对于.NET类型的API来说，常量类定义在MapGuide Web .NET API程序集（Assembly）中，常量类中的常量被定义为静态常量（static const）。所以，在使用常量类中定义的这些常量时并不需要创建常量类的实例。
类MgObject是所有非常量类的根类，用来为每个类提供一个类ID。类MgDisposable继承自MgObject，实现了引用计数功能，只有在引用计数为0的时候才会删除类的实例。类MgGuardDisposable继承自MgDisposable，实现了线程安全的引用计数功能。类MgSerializable继承自MgGuardDisposable，定义了序列化（Serialize）和反序列化（Deserialize）接口。如果某个了类继承自MgSerializable，那么代表这个类的实例是可以被序列化和反序列化的。类MgNamedSerializable继承自MgSerializable，为可序列化对象提供了一个名称。但是，目前MapGuide Web API并没有为类MgObject、MgDisposable、MgGuardDisposable、MgSerializable和MgNamedSerializable暴露任何方法，对于MapGuide二次开发用户来说，这五个类并没有太多实际意义。
类MgColor用于存储由ARGB（Alpha、Red、Green、Blue）组成的颜色值，该类使用“signed short”表示颜色的A、R、G、B分量。调用MgColor::GetColor()可以将MgColor实例所代表的颜色值转换为一个格式为“0xRRGGBBAA”的字符串。其中，“RR”代表Red（红色）分量、“GG”代表Green（绿色）分量、“BB”代表Blue（蓝色）分量、“AA”代表Alpha（透明度）分量。
类MgDateTime用于存储日期和时间，该类的实例可以存储从1970年1月1日0点0分0秒到2038年1月18日19点14分07秒之间的任意日期和时间。类MgDateTime既可以表示日期和时间，也可以只表示日期或时间。如果该类的实例存储的是日期和时间，那么方法MgDateTime::IsDateTime()会返回true；如果该类的实例存储的只是日期，那么方法MgDateTime::IsDate ()会返回true；如果该类的实例存储的只是时间，那么方法MgDateTime::IsTime()会返回true。
类MgService是所有MapGuide服务类的基类，例如资源服务MgResourceService、要素服务MgFeatureService等。常量类MgServiceType为每一种MapGuide服务定义了一个常量。在后续章节中，我们会分别介绍MapGuide提供的每一种类型的服务。
类MgWarnings用于存储MapGuide服务最后一个操作的警告信息，调用方法MgService::GetWarningsObjec()可以返回该警告。在执行下一个MapGuide服务操作之前，MapGuide会清除该服务的警告信息。
类MgByteSource用于表示某种类型的字节数据源，通过一个字节数组或文件可以创建一个字节数据源的实例。常量类MgMimeType定义了所有的字节数据源类型，调用方法MgByteSource::GetMimeType()可以得到字节数据源的类型。类MgByteSink用于将MgByteSource实例的内容保存到一个文件。类MgByteReader用于读取字节数据源中的数据。
类MgByteSource、MgByteSink和MgByteReader经常会一起使用，在后续的章节中我们也会经常使用到这三个类。通常，它们使用在如下场景中：
1） 加载一个文件的内容，创建一个MgByteReader的实例，将该实例传递给某个MapGuide服务API。
l 调用类MgByteSource的构造方法，为该方法传递一个文件名，从而创建一个MgByteSource的实例。
l 调用MgByteSource::GetReader()获取一个MgByteReader的实例，将该实例作为实参传入某个MapGuide服务API。
|
$resourceID = new MgResourceIdentifier(“Library://Geography/World.MapDefinition"); $content = "DataMapsWorld.MapDefinition"; $content_byteSource = new MgByteSource($content); $content_byteSource->setMimeType("text/xml"); $content_byteReader = $content_byteSource->GetReader(); $header = " DataMapsResourceDocumentHeader.xml"; $header_byteSource = new MgByteSource($header); $header_byteSource->setMimeType("text/xml"); $header_byteReader = $header_byteSource->GetReader(); $resourceService->SetResource($resourceID, $content_byteReader, $header_byteReader); |
2） 调用某个MapGuide服务API返回一个MgByteReader的实例，将该实例中的内容保存到一个文件中。
l 调用类MgByteSink的构造方法，为该方法传递一个MgByteReader实例，从而创建一个MgByteSink的实例。
l 调用方法MgByteSink::ToFile(…)将字节流的内容保存到一个文件。
|
$resourceID = new MgResourceIdentifier(“Library://Geography/World.MapDefinition"); $byteReader = $resourceService->EnumerateResources($resourceID, 0, "MapDefinition"); $byteSink = new MgByteSink($byteReader); $byteSink->ToFile("map_definition.xml"); |
3） 将一个字符串或一段内存缓存区的内容保存到一个文件。
l 调用类MgByteSource的构造方法，为该方法传递一个字符串或一段内存缓存区和它们的字节长度，从而创建一个MgByteSource的实例。
l 调用MgByteSource::GetReader()获取一个MgByteReader的实例。
l 调用类MgByteSink的构造方法，为该方法传递上一步获得的MgByteReader实例，从而创建一个MgByteSink的实例。
l 调用方法MgByteSink::ToFile(…)将字节流的内容保存到一个文件。
|
$byteSource = new MgByteSource("This is a test.", 15); $byteSink = new MgByteSink($byteSource->GetReader()); $byteSink->ToFile("test.txt"); |
2. 集合类
MapGuide Web API中的所有集合类都继承自类MgCollection，图 3‑4显示了集合类的类图。一般情况下，集合类将其元素置于一个动态数组中加以管理，所有元素是按照插入顺序排列的。它支持随机存取，也就是说你可以利用索引存取任何一个元素。集合类不过需要注意的是，集合类并不是线程安全的。
类MgCollection的接口非常简单，该类只定义了如表 3‑1所示的三个方法。集合中元素的类型完全由子类决定，子类会实现Add、Contains、GetItem、IndexOf、Insert、Remove等方法。集合类使用了C++标准模板库中的容器std::vector存储元素，例如MgStringCollection、MgIntCollection等类。如果集合中的元素有一个名称，你不仅可以通过索引，也可以通过元素的名称存取集合中的元素，例如MgPropertyCollection、MgLayerCollection等类。这些集合类在使用C++标准模板库容器std::vector存储元素的同时，又使用了容器std::map存储名称和元素的对应关系，从而加快了按照元素名称存取元素的速度。
|
方法 |
描述 |
|
void Clear() |
清除集合中的所有元素。 |
|
int GetCount() |
获得集合中元素的总数。 |
|
void RemoveAt(int index) |
删除集合中序号为index的元素。 |
对于.NET类型的Web API，为了支持使用foreach语句遍历集合中的元素，类MgCollection实现了接口System.Collections.IEnumerable，所有从类MgCollection继承而来的集合类都包含一个实现了接口System.Collections.IEnumerator的内嵌类（Inner Class）。例如，类MgIntCollection包含了一个内嵌类MgIntCollectionEnumerator，如下代码是对类MgIntCollection反编译的结果：
|
public class MgIntCollection : MgCollection, IList, ICollection, IEnumerable, IEnumerable { // Fields private IntPtr swigCPtr; // Methods public MgIntCollection(); public MgIntCollection(IntPtr cPtr, bool cMemoryOwn); public virtual void Add(int value); public override void Clear(); public virtual bool Contains(int value); public void CopyTo(int[] array, int arrayIndex); public override void Dispose(); protected override void Finalize(); public override int GetCount(); internal static IntPtr getCPtr(MgIntCollection obj); public IEnumerator GetEnumerator(); public virtual int GetItem(int index); public virtual int IndexOf(int value); public virtual void Insert(int index, int value); public virtual bool Remove(int value); public override void RemoveAt(int index); public virtual void SetItem(int index, int value); IEnumerator IEnumerable.GetEnumerator(); public override MgByteReader ToXml(); // Properties public int Count { get; } public bool IsReadOnly { get; } public int this[int index] { get; set; } // Nested Types public class MgIntCollectionEnumerator : IEnumerator, IDisposable, IEnumerator { // Fields private MgIntCollection m_coll; private int m_pos; // Methods public MgIntCollectionEnumerator(MgIntCollection coll); public void Dispose(); public bool MoveNext(); public void Reset(); // Properties public int Current { get; } object IEnumerator.Current { get; } } } |
所以，在使用C#遍历集合中的元素时，可以使用如下所示的foreach语句：
|
MgIntCollection col = new MgIntCollection(); foreach (int i in col) { Console.WriteLine(i); } |
3. 异常类
类MgException是所有MapGuide Web API异常类的根类，它有三个直接子类MgApplicationException、MgSystemException、MgThirdPartyException，图 3‑5显示了它们的类图。换而言之，MapGuide Web API异常类可以分为三大类：
l 应用程序异常（MgApplicationException）
用于处理和MapGuide应用逻辑相关的错误，例如：类MgResourceNotFoundException表示在MapGuide服务器中找不到指定的资源，类MgFeatureServiceException表示在调用要素服务是发生的错误。
l 系统异常（MgSystemException）
用于处理系统错误，例如，类MgNotImplementedException表示调用了没有完成的API，类MgOutOfRangeException表示一个越界错误，这些异常和MapGuide应用逻辑无关，即使在编写和MapGuide应用无关的功能时也会产生这类错误。
l 第三方组件异常（MgThirdPartyException）
表示在调用第三方组件（如FDO、BerkeleyDB、XML解析器等）时产生的错误，例如：类MgFdoException表示在调用FDO API是产生的错误，类MgXmlException表示在处理XML时产生的错误。
类MgException的接口比较简单，表 3‑2列出了该类的主要方法。
|
方法 |
描述 |
|
string GetDetails() |
获得本地化后的异常细节信息。 |
|
string GetMessage() |
获得本地化后的异常信息。 |
|
string GetStackTrace() |
获得产生异常时的调用堆栈。 |
