MaestroAPI Code Structure

This document describes the code structure of the MapGuide Maestro API.

Before you read this document, please read the MaestroAPI usage instructions.

Project contents

The MaestroAPI project contains the following folders:

• BinarySerializer
• Generated
• RuntimeClasses
• Schemas
• XmlSerializer

The BinarySerializer contains code that mimics the binary serialization/deserialization of objects in the MapGuide server. These classes are used to read and create the RuntimeClasses.

The Generated folder contains classes that are generated from the Xsd schema of the server. There exists a folder in the source called "XSD Generator" which contains the code used to generate these classes. After generation, I have hand modified/fixed the classes so it is not possible to automatically regenerate/update these.

The RuntimeClasses folder contains classes that support the binary format objects in the MapGuide server.

The Schemas folder contains the Xsd documents from the server.

The XmlSerializer contains incomplete code for an XmlSerializer that I have planned. There are some unfortunate properties of the current XmlSerialization process that I want to fix.

Class relationships

The main entry for using the API is the ServerConnectionI class. Many functions in the ServerConnectionI are overloads that merely insert appropriate default values. To avoid generating large amounts of trivial code, I have added the abstract base class ServerConnectionBase. The base class declares some abstract methods (such as GetResourceXmlData) and implements functions using these abstract methods. The real classes (HttpServerConnection and LocalNativeConnection) can then be limitied to implementing these abstract methods.

Most functions in the ServerConnectionBase class reads an Xml document from the server, and creates an object based on the Xml. To achieve this, the .Net XmlSerializer class is used. When saving an object, the resulting Xml must be encoded in UTF-8, and the Utf8XmlWriter does just this. When creating an UTF-8 encoded Xml document in .Net, it inserts the standard UTF-8 BOM marker. Unfortunately the MapGuide server has a bug that prevents it from correctly reading a document with a BOM.

The Utility class contains various static methods, such as CopyStream (why is this not in the .Net framework?).

The RequestBuilder class is exclusively used by the HttpServerConnection, and contains code that constructs requests to the web server (POST and GET). The code here is really simple, but moving it out of the HttpServerConnection class keeps it much more readable.

The CoordinateSystem class contains code to retrieve Coordinate System info from the server. This was not avalible in the Web interface before MGOS 1.2.

The functions MoveResourceWithReferences, MoveFolderWithReferences and CopyFolderWithReferences updates references in all related resources, and can take a _very_ long time to complete. To remedy this, there exists a callback method that can be used to display progress. Unfortunately the current implementation is messy, and should be redesigned.

The last class that deserves special mentioning, is the FeatureSetReader. When querying a FeatureSource (or layer), the result is a FeatureSetReader. The reader is very much like the IDataReader, and has a ReadNext() method that returns true as long as there are more rows. Data read from the reader is typed into the correct .Net type. Geometry is converted from WKT into the corresponding object with help from ht ​TF-net module. The FileBufferedStreamReader is an incomplete implementation of a StreamReader that will exhaust a stream as fast as possible, while providing immediate acces to the stream contents. The idea behind this class, was to finish off reading a featureset very fast, and thus release any server resources held. This could be usefull if the client computations are slow on each row, but the reader is not yet implemented.