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

Table of Contents

1. Overview
2. Related Documents
3. Terms and Definitions
4. High Level View
   1. Client Tier View
      1. AJAX VIEWER
      2. DWF VIEWER
      3. FUSION VIEWER
      4. MAESTRO
      5. SITE ADMINISTRATOR
   2. Web Tier View
   3. Server Tier View
   4. Interaction Model
5. Shared Component Overview
   1. MgFoundation
   2. MgGeometry
   3. MgMapGuideCommon
   4. MgMdfModel
   5. MgMdfParser
   6. MgPlatformBase
   7. MgRenderers
   8. MgStylization
6. Server Component Architecture
   1. Server Framework
   2. Thread Management
      1. Main Process Thread
      2. Worker Thread
   3. Memory Management
      1. Smart Pointers
      2. Caching
      3. Windows
      4. Linux
   4. Operation Processing
      1. Client Operations
      2. Admin Operations
      3. Site Operations
      4. Operation Processing Sequence
      5. Internal Operation Processing Interaction Model
      6. Retrieving a Tile
   5. Session Management
      1. Overview
      2. Session Object
      3. Properties
7. Web Tier Component Architecture
   1. Language Binding Generation
      1. Build process
      2. .net binding specifics
   2. mapagent
   3. AJAX Viewer
   4. Fusion
8. Configuration Settings
9. TBD

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.

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 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.

Figure 2 - Interaction between tiers

The following diagram shows the interaction between servers.

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.

​mg-desktop and ​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 ​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

Figure ? - Stylization Process

Server Component Architecture

Figure ? - Server Components

TBD

Server Framework

At the high level the server framework looks like the following:

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

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 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 ​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.

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.

Figure 7 - Simplified operation object

Operation Object Base Class

The ​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.

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.

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

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 ​SWIG
• ​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 MapGuideRfc44 for an example
• default parameters (not supported by Java). This is why methods like MgRenderingService::RenderMap have so many overloads.

Build process

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 MapGuideRfc68, but the same principle applies)
• MapGuideApiGen.xml (for .net this is split into 5 different files due to 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 ​JNI
• For .net, this is ​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 ​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 ​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<Name>. So IMake will generate an equivalent property named <Name>
• Apply .net exception serialization info for each file

mapagent

TBD

AJAX Viewer

TBD

Fusion

TBD

Configuration Settings

TBD