= !MapGuide Architecture = ---- '''Revision History''' ||'''Revision'''||'''Date'''||'''Author'''||'''Comment'''|| ||1.0||October 31, 2008||Bruce Dechant||Initial public revision|| ||1.0||November 4, 2008||Bruce Dechant||Updated various sections|| ||1.0||November 24, 2008||Bruce Dechant||Updated various sections|| ||1.0||February 12, 2010||Jackie Ng||Described Shared Components|| ||1.0||November 24, 2012||Jackie Ng||Described Web Tier Components|| [[PageOutline(2-4,Table of Contents,inline)]] == Overview == This document describes the !MapGuide architecture. The !MapGuide server is based on the ACE (ADAPTIVE Communications Environment) framework. == Related Documents == ||'''Document'''||'''Link'''|| ||ACE (ADAPTIVE Communication Environment)||http://www.cs.wustl.edu/~schmidt/ACE.html|| ||AGG (Anti-Grain Geometry)||http://www.antigrain.com/|| ||Oracle Berkeley DB XML||http://www.oracle.com/technology/products/berkeley-db/index.html|| == Terms and Definitions == ||'''Term'''||'''Definition'''|| ||ACE||ADAPTIVE Communication Environment|| ||AGG||Anti-Grain Geometry|| ||API||Application Programming Interface|| ||Data connection||A connection between the server and underlying data stores.|| ||DTD||XML Document Type Definition|| ||FDO||Feature Data Objects|| ||FDO connection||A connection between the server and underlying FDO data store.|| ||FIFO||First In First Out|| ||HTTP||Hypertext Transfer Protocol|| ||LDAP||Lightweight Directory Access Protocol|| ||RDBMS||Relational Database Management System|| ||SMP||Symmetric Multiprocessing|| ||SQL||Structured Query Language|| ||TCP/IP||Transmission Control Protocol over Internet Protocol|| ||XML||eXtensible Markup Language|| ||XMLDB||Native XML Database || ||XPath||XML Path Language|| ||XQuery||XML Query Language|| ||XSD||XML Schema Definition|| == High Level View == The following diagram shows the !MapGuide web-based platform 3-tier architecture.[[BR]][[BR]] ||[[Image(image1.jpg)]]|| ||Figure 1 - !MapGuide 3-tier architecture|| === Client Tier View === ==== AJAX VIEWER ==== The AJAX Viewer is a pure DHTML viewer based on AJAX technology that does not require any downloadable plug-ins. This viewer works in all major browsers on Windows, Mac, and Linux. ==== DWF VIEWER ==== The DWF Viewer embeds the downloadable Autodesk DWF Viewer which is based on a Microsoft ActiveX Control with full support for the Autodesk DWF format. This viewer works in Microsoft Internet Explorer only. ==== FUSION VIEWER ==== Built primarily in !JavaScript, Fusion is a web mapping application development framework. Fusion allows web designers and developers to build rich mapping applications quickly and easily. Using “widgets” that provide the interface functionality within Fusion’s modular architecture, developers are able to add, remove, or modify functionality using standard-compliant HTML and CSS. Fusion requires no proprietary browser plug-ins, and it produces applications that work in all major browsers on Windows, Mac, and Linux. Fusion provides a flexible means of interacting with !MapGuide Open Source. Using a growing suite of widgets, this modular-based system allows you to build powerful, interactive AJAX applications quickly with minimal programming experience. For applications requiring special functionality, Fusion provides an extensible platform that allows you to develop your own widgets. ==== MAESTRO ==== See [wiki:maestro] for an overview ==== SITE ADMINISTRATOR ==== The !MapGuide Site Administrator is an application for managing your site and its servers. This application uses a web-based interface that you can access from any web browser. To start the program, open a browser and enter: !http://servername:port/mapguide/mapadmin/login.php, using the name of the site server and port that you specified during installation. You use the !MapGuide Site Administrator to add and remove servers, take servers offline for maintenance, modify the configuration of a server, assign services to the servers, and monitor the status of any server. The !MapGuide Site Administrator is not a separate product component, but it is installed as a part of the !MapGuide Web Server Extensions. === Web Tier View === TBD === Server Tier View === TBD === Interaction Model === The following diagram shows the interaction between the various tiers.[[BR]][[BR]] ||[[Image(image5.jpg)]]|| ||Figure 2 - Interaction between tiers|| The following diagram shows the interaction between servers.[[BR]][[BR]] ||[[Image(image6.jpg)]]|| ||Figure 3 - Interaction between servers|| == Shared Component Overview == The following components under MgDev\Common are shared and reused across the entire MapGuide source tree, and can be used outside of MapGuide. [http://mg-desktop.googlecode.com mg-desktop] and [http://www.georest.org GeoREST] are examples of applications using these shared MapGuide components. === !MgFoundation === Source: MgDev\Common\Foundation Defines the core classes and types used throughout the entire MapGuide source tree. === !MgGeometry === Source: MgDev\Common\Geometry Source: MgDev\Common\CoordinateSystem Defines the MapGuide geometry model. Wraps the CS-Map library in an object-oriented API (!MgCoordinateSystem). Wraps GEOS for geometry operations (buffer, union, etc) === !MgMapGuideCommon === Source: MgDev\Common\MapGuideCommon The MapGuide-specific implementation of !PlatformBase. Also provides client proxies to server-side services (!MgResourceService, !MgFeatureService, etc) === !MgMdfModel === Source: MgDev\Common\MdfModel Defines the object-oriented form of MapGuide resources (LayerDefinition, FeatureSource, etc) === !MgMdfParser === Source: MgDev\Common\MdfParser Provides APIs to parse MapGuide resource XML documents into their object-oriented form (MdfModel) === !MgPlatformBase === Source: MgDev\Common\PlatformBase Defines the base platform API. Extended in MapGuide as MgMapGuideCommon.dll. Extended in AutoCAD Map as the Geospatial Platform API. Extended on the MapGuide Server side as MgServer*.dll. Extended also in [http://mg-desktop.googlecode.com mg-desktop]. Code that operates on classes defined in this library can generally work across these various implementations. === !MgRenderers === Source: MgDev\Common\Renderers Defines all the MapGuide renderers (GD, AGG, DWF, KML) === !MgStylization === Source: MgDev\Common\Stylization Defines the MapGuide stylization engine for handling labeling and symbology ||[[Image(image4.jpg)]]|| ||Figure ? - Stylization Process|| == Server Component Architecture == ||[[Image(image2.jpg)]]|| ||Figure ? - Server Components|| TBD === Server Framework === At the high level the server framework looks like the following:[[BR]][[BR]] ||[[Image(image12.jpg)]]|| ||Figure 4 - Internal server framework|| The server framework essentially shows that “Operations” coming from either a web application server or another !MapGuide server will be received by the server on a specified port. The server will then dispatch the incoming operation to an “Operation” queue for processing. The server dispatcher is based on the ACE reactor model. The “Operation” queue is a FIFO design which is connected to a thread pool of worker threads. Operations on the queue are removed by a worker thread from the thread pool for processing. The ACE framework thread manager handles the determination of which worker thread gets to process the queued operation. The worker thread will then process the operation and when the operation processing is complete the worker thread will rejoin the thread pool ready to process another operation. === Thread Management === The !MapGuide server is a multithreaded in design. This allows for improved processing and response to operations. The server will consist of the following types of threads: * Main process thread * Worker threads ||[[Image(image13.jpg)]]|| ||Figure 5 - Thread identification|| ==== Main Process Thread ==== This is the main executable thread of the server. The main purpose of this thread is to dispatch incoming operations to the queue for processing by the worker threads. This thread will also be responsible for initializing the server which includes initializing the coordinate system library, opening the repository, creating the worker thread pools, etc… ==== Worker Thread ==== This is a thread that is used to process an operation. Essentially, this is a thread that does all the work. The main process thread of the server will be responsible for creating thread pools consisting of these worker threads based on the configuration settings of the server. === Memory Management === The server and any components used by the server must be conscious of their memory use and reclamation of used resources when no longer needed. ==== Smart Pointers ==== Wherever possible in the server and any of its components [wiki:MapGuideCodingStandards#SmartPointers smart pointers] are used. ==== Caching ==== In order to improve performance the server caches several types of resources. The following lists some of what the server caches: * FDO connections (when specified in the server configuration) * FDO Schema Definitions (Object and XML representation) * FDO Class Definitions (Object and XML representation) * FDO Property Definitions (Object and XML representation) * Coordinate Systems Invalidation of cached FDO information is generally triggered on saving of any related Feature Source documents. Invalidation of Tile Caches is triggered on saving of the Map Definition or any of its upstream dependent resources. This is generally acknowledged as a [http://osgeo-org.1560.n6.nabble.com/Avoiding-unnecessary-Tile-Cache-invalidation-Trac-Ticket-1332-td4211581.html overly aggressive measure] that could definitely use with some refinement. ==== Windows ==== The default memory management library is used. ==== Linux ==== The default memory management library is used.   === Operation Processing === The server supports the processing of 3 types of operations: * Client operations * Admin operations * Site operations ==== Client Operations ==== The majority of operations processed by the server will be of the “Client” type. Essentially, these are the operations that come from !MapGuide clients. ==== Admin Operations ==== The “Admin” operations will be specific to managing and administering a !MapGuide server using the !MapAdmin. ==== Site Operations ==== The “Site” operations will be specific to managing session/repository replication in a future release. ==== Operation Processing Sequence ==== The diagram below shows the sequence for processing either a “Client” or “Admin” operation. ||[[Image(image14.jpg)]]|| ||Figure 6 - Operation sequence|| ==== Internal Operation Processing Interaction Model ==== ===== Operation Objects ===== All server requests and their associated responses are represented internally by Operation objects. A simplified object diagram is shown in figure 7. ||[[Image(image15.jpg)]]|| ||Figure 7 - Simplified operation object|| ====== Operation Object Base Class ====== The [http://trac.osgeo.org/mapguide/browser/trunk/MgDev/Server/src/Common/Base/ServiceOperation.h Operation] class is an abstract class that provides the base level of functionality. This functionality includes methods to serialize and deserialize the Operation from the data packets sent to the server. It also maintains a reference back to the object that handles its transmission back to the client. ====== !OperationRequest Base Class ====== This class represents the operation request or other action that the server can execute. It has an Execute method that the server will call to fulfill the request. This class is abstract, so !OperationRequest classes must be implemented for every operation that the server can perform. The Execute method will return an !OperationResponse object. ====== !OperationResponse ====== This class encapsulates the result of an executed !OperationRequest. It is serialized and sent back to the web tier or other server. ===== Operation Processing Details ===== A more detailed sequence diagram showing the creation and processing of operations is shown in figure 8. ||[[Image(image16.jpg)]]|| ||Figure 8 - Operation processing sequence|| The following describes the “Operation Processing” seqeunce: * The Web Tier connects to a socket on the server. A !ClientAcceptor object server-side is listening on the port, accepts the connection, and creates a !ClientService object to handle the the connection. The !ClientAcceptor object will create a separate !ClientService object for each connection. * The !ClientService object handler creates Operation objects from the raw request stream sent from the web tier. It reads the input stream from the socket, deserializes the packets from the stream, and then creates the specific Operation objects as determined by the deserialized objects. It then places the object in the servers !OperationQueue to be processed by a worker thread in the server’s thread pool. The handler then returns to allow other !ClientService objects to process their data. * It will periodically check to see if it has obtained a !OperationResponse object to return to the Web Tier client. * Once in the queue, the Operation object sits until an !OperationHandler can process it. A !OperationHandler processes the object by calling its Execute() method. The handler then takes the reponse and gives it back to the !ClientService. * The !ClientService will eventually realize that it has obtained a response. It will then pack the response up and sent it back to the Web Tier or other client. The object will remain to process additional client requests or be destroyed if the client closes the connection. ==== Retrieving a Tile ==== A more detailed sequence diagram showing the creation and processing of Tiles is shown in Figure A. ||[[Image(GetTileSequence.png)]]|| ||Figure A - Get Tile Processing sequence|| The TileService renders the tile only after checking the tile cache. If the tile needs to be rendered, first the map cache is checked before the map is reloaded from the library. The map cache contains serialized forms of the maps which can be deserialized as MgMap objects. When the map is in the cache again the rendering service is called with the map & layer information and the desired screen area to compute the image. This is done with a Renderer Helper object which can be changed by configuration. Finally an image compressor is called in AGGImageIo to create an image according to the selected ImageFormat (currently JPEG,PNG,PNG8,GIF). === Session Management === ==== Overview ==== Session management will be used to enhance request/response performance in connections between the server and the web-tier as well as to track information about the connection for logging output. Session management will be handled through the use of a session object, which will be present in every server connection. ==== Session Object ==== A session object is created when a connection between the web-tier and server is established. A connection is authenticated throughout its lifetime. The session is closed when the connection is closed. The session object is used to store state information about a particular connection that can be written to a log. Such information includes connection ID, connection start time, total number of operations received, total number of operations successfully processed and information on any data (FDO) connections established during a session. When a data connection (or FDO connection) is established during a session, operations to that data connection can be made until the data connection is explicitly closed or until the session is closed. Data connections opened during the session will be maintained in a dynamic collection that will grow as data connections are added to it. The session object will hold references to any established data connections, but will not manage them. It will be the caller’s responsibility to allocate memory and to open data connections. Once a data connection has been established, it should be added to the session’s collection set. Similarly, the caller will be responsible for closing data connections and performing memory de-allocation. ==== Properties ==== The following table describes the session object properties that will be associated with each connection. TBD == Web Tier Component Architecture == ||[[Image(image3.jpg)]]|| ||Figure ? - Web tier components|| TBD === Language Binding Generation === MapGuide's core and API is all C++. To make the MapGuide API available to higher level languages, the following set of tools are used to generate the necessary bindings in .net/Java/PHP: * A modified version of [http://www.swig.org SWIG] * [http://trac.osgeo.org/mapguide/browser/trunk/MgDev/BuildTools/WebTools/IMake IMake.exe] You can see the design of the C++ classes in the MapGuide API mostly being a convention-based lowest common denominator approach to facilitate the ease of language binding generation to the 3 platforms. The C++ classes in the MapGuide API do not use C++ features that may not be expressible or convertible to the target language. Some examples include: * enums (not supported by PHP) * const correctness (not supported and/or expressible in .net/Java/PHP) * Pass-by-reference (not supported and/or expressible in PHP/Java). Where possible, C++ classes employ "boxing" to work around this (see [wiki:MapGuideRfc44] for an example * default parameters (not supported by Java). This is why methods like MgRenderingService::RenderMap have so many overloads. ==== Build process ==== ||[[Image(SWIG build process.png)]]|| ||Figure ? - SWIG build process for generating PHP/Java/.net wrappers for the MapGuide API|| IMake.exe reads from 2 XML files: * Constants.xml (for .net this is split into 5 different files due to [wiki:MapGuideRfc68], but the same principle applies) * MapGuideApiGen.xml (for .net this is split into 5 different files due to [wiki:MapGuideRfc68], but the same principle applies) These two files mainly define: * The paths of the header files of the MapGuide public API * SWIG input file generation options IMake.exe takes these 2 files and produces the following: * A set of source files in the target language, defining the various constants in the MapGuide API * A SWIG input file containing a "sanitized" class definition from each header file IMake.exe looks for special #define'd markers in the header files: * `PUBLISHED_API`: Members under here are included in the sanitized class definition and represent the public API * `INTERNAL_API`: Members under here are excluded from the sanitized class definition * `EXTERNAL_API`: Members under here are included in the sanitized class definition and represent undocumented public APIs that are not for general use (but nothing stops a MapGuide application developer from using them) Because C++ does not expose the concept of internal visibility, this IMake build system in conjunction with the above markers approximates this type of desired encapsulation. Once the SWIG input file is generated, it is then fed to SWIG which will do the following: * Generate the source code for the managed-native interop glue library * Generate the MapGuide API proxy classes that call into this managed-native interop glue library SWIG will use whatever supported native interop mechanism that is provided by the target language: * For Java, this is [http://en.wikipedia.org/wiki/Java_Native_Interface JNI] * For .net, this is [http://en.wikipedia.org/wiki/Platform_Invocation_Services P/Invoke] Once SWIG has generated the files, MSVC/gcc is used to compile the glue library while csc/javac is used to compile the proxy classes into a matching assemblies/jar file. These two binary outputs, combined with the [http://trac.osgeo.org/mapguide/wiki/MapGuideArchitecture#SharedComponentOverview shared component binaries and its dependencies] comprises the final set of binaries needed to build a MapGuide application ==== .net binding specifics ==== IMake.exe has special behavior for .net. You may see markers like these throughout the MapGuide headers: * `__get` * `__set` In addition, you may see files [http://trac.osgeo.org/mapguide/browser/trunk/MgDev/Web/src/DotNetUnmanagedApi/Foundation/FoundationCustom like this] These files and markers serve as hints to IMake to do the following: * Generate a read-only property for any method with a `__get` marker. Generate a regular property for a method if a `__get` and `__set` marker. Such methods follow a convention of being applied to any method of the form Get. So IMake will generate an equivalent property named * Apply .net exception serialization info for each file === mapagent === TBD === AJAX Viewer === TBD === Fusion === TBD == Configuration Settings == == TBD ==