Changes between Initial Version and Version 1 of maestro/MaestroAPI/codebasics

Timestamp:

May 22, 2008, 12:13:46 PM (16 years ago)

Author:

ksgeograf

Comment:

--

maestro/MaestroAPI/codebasics

@@ +1 @@
+
+== MaestroAPI Code Structur ==
+This document describes the code structure of the [wiki:maestro MapGuide Maestro] API.
+
+Before you read this document, please read the [wiki:maestro/MaestroAPI/basics 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 [http://code.google.com/p/tf-net/ 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.