MapGuide Web API----通用类、集合类和异常类

最新推荐文章于 2019-01-08 04:30:50 发布

iteye_3055

最新推荐文章于 2019-01-08 04:30:50 发布

阅读量149

点赞数

文章标签： Web 应用服务器 XML PHP json

1. 通用类

通用类包含MgObject、MgDisposable、MgGuardDisposable、MgByteSource、MgByteSink、MgSerializable、MgService、MgNamedSerializable、MgWarnings、MgByteReader、MgColor、MgDateTime、MgServiceType和MgMimeType共14个类，图 3‑3是这些类的类图。

图 3‑3 MapGudie Web API通用类类图

我们可以将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显示了集合类的类图。一般情况下，集合类将其元素置于一个动态数组中加以管理，所有元素是按照插入顺序排列的。它支持随机存取，也就是说你可以利用索引存取任何一个元素。集合类不过需要注意的是，集合类并不是线程安全的。

图 3‑4 MapGudie Web API集合类类图

类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的元素。

表 3‑1 类MgCollection的方法

对于.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时产生的错误。

图 3‑5 MapGudie Web API异常类类图

类MgException的接口比较简单，表 3‑2列出了该类的主要方法。

方法	描述
string GetDetails()	获得本地化后的异常细节信息。
string GetMessage()	获得本地化后的异常信息。
string GetStackTrace()	获得产生异常时的调用堆栈。