= !MapGuide RFC 30 - FDO Configuration XML Utility = This page contains an change request (RFC) for the !MapGuide Open Source project. More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page. == Status == ||RFC Template Version||(1.0)|| ||Submission Date||Aug 28, 2007|| ||Last Modified||Leaf Li [[Timestamp]]|| ||Author||Leaf Li|| ||RFC Status||draft|| ||Implementation Status||under development|| ||Proposed Milestone||1.3|| ||Assigned PSC guide(s)||(when determined)|| ||'''Voting History'''||(vote date)|| ||+1|||| ||+0|||| ||-0|||| ||-1|||| == Overview == The purpose of this RFC is to provide a utility named !ConfigDocument in !MapGuide Web API to facilitate configuration XML generation for FDO data sources, especially for WMS/ODBC/Raster data sources. == Motivation == When connecting to WMS/ODBC/non-geo-referenced raster data sources, FDO API need a configuration stream, which provides physical schema mapping information for these data sources. For example, given a non-geo-referenced raster file, users can use configuration XML file to set its spatial context, location, resolution, rotation, insertion point and information how it is mapped as FDO feature class. Although FDO API provides API to generate these configuration XMLs and is very flexible, it is cumbersome to use. With the API enhancements recommended by this RFC, it is more convenient for users to create a FDO Configuration file. == Proposed Solution == The new !ConfigDocument classes will be part of !MapGuide Web API, which depends on FDO, and will be implemented as code that is shared at both interface and implementation levels. !MapGuide Web API also needs other utilities such as utility to simplify the process to add a layer, which might be added in the future. So we are going to add a new project named !MapPlatformUtil. [[Image(ConfigDocument.jpg, 511)]][[BR]] The following classes will be added and exposed in !MapGuide Web API. * !MgRasterItem contains the basic information to create a feature class definition and its physical mapping for a raster. However, it doesn’t contain FDO provider specific information. [[Image(MgRasterItem.jpg, 317)]] * !MgRasterFileItem contains more Raster FDO provider specific information than !MgRasterItem such as insertion point, resolution, and rotation. [[Image(MgRasterFileItem.jpg, 750)]] * Similarly, !MgRasterWmsItem provides WMS FDO provider specific raster information such as transparency, background color, WMS styles. [[Image(MgRasterWmsItem.jpg, 227)]] * Previously, !MgSpatialContextData is an internal class of !MapGuide Web API, which is used to represent all information of a FDO spatial context. In this RFC, it will be extended and exposed so that users can use it add spatial context into configuration. * There isn’t a class existing to represent spatial context collection. So !MgSpatialContextDataCollection will be added, which is just a collection of !MgSpatialContextData. !MgConfigDocument uses it to maintain all spatial contexts of all feature classes. * !MgConfigDocument maintains three collections, schema collection, physical schema mapping collection, and spatial context collection. These three collections will provide all information to create configuration XML. So it generates configuration XML string or file only when MgConfigDocument::ToXML is called. !MgConfigDocument doesn’t provide any functions to add schema mapping. So it is derived classes’ responsibility to populate schema mapping information into schema mapping collection. [[Image(MgConfigDocument.png, 635)]] * !MgRasterConfigDocument, !MgWmsConfigDocument and !MgOdbcConfigDocument are derived from !MgConfigDocument. They implement a method !AddOverrideInfo to add feature class definitions and their physical mappings into configuration. [[Image(MgRasterConfigDocument.jpg, 457)]] [[Image(MgWmsConfigDocument.jpg, 457)]] [[Image(MgOdbcConfigDocument.png, 600)]] The relationships among these classes are shown in the following class diagram. [[Image(ClassDiagram.jpg, 554)]][[BR]] Given a raster file, code to generate configuration XML might be as follows. {{{ MgRasterConfigDocument configDocument = new MgRasterConfigDocument(); // Initialize spatial context by a Mentor/WKT coordinate system name. MgSpatialContextData spatialContext = new MgSpatialContextData("LL84"); configDocument.AddSpatialContext(spatialContext); MgRasterFileItem rasterItem = new RasterFileItem(".//image.jpg"); rasterItem.SpatialContextName = spaitalContext.Name; // Set raster’s insertion point, resolution and rotation rasterItem.SetPosition(3.14, 4.15, 100, 100, 0, 0); configDocument.AddOverrideInfo(rasterItem); // Generate configuration XML string MgByteReader reader = configDocument.ToXML(); }}} == Implications == Backwards compatibility should be maintained since !ConfigDocument is just a utility based on existing !MapGuide Web API and FDO and will not break any existing applications. Documentation will need to be updated for the new functionality. == Test Plan == Unit tests will be written to verify behavior of the !ConfigDocument. == Funding/Resources == Autodesk will supply the resources to implement this RFC.