|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
- Related Documents
- Terms and Definitions
- High Level View
- Shared Component Overview
Server Component Architecture
- Server Framework
- Thread Management
- Memory Management
- Operation Processing
- Session Management
- Web Tier Component Architecture
- Configuration Settings
This document describes the MapGuide architecture. The MapGuide server is based on the ACE (ADAPTIVE Communications Environment) framework.
|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
|ACE||ADAPTIVE Communication Environment|
|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|
|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
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.
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.
See maestro for an overview
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
Server Tier View
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
Defines the core classes and types used throughout the entire MapGuide source tree.
Defines the MapGuide geometry model. Wraps the CS-Map library in an object-oriented API (MgCoordinateSystem). Wraps GEOS for geometry operations (buffer, union, etc)
The MapGuide-specific implementation of PlatformBase. Also provides client proxies to server-side services (MgResourceService, MgFeatureService, etc)
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.
Defines all the MapGuide renderers (GD, AGG, DWF, KML)
Defines the MapGuide stylization engine for handling labeling and symbology
|Figure ? - Stylization Process|
Server Component Architecture
|Figure ? - Server Components|
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.
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…
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.
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.
Wherever possible in the server and any of its components smart pointers are used.
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.
The default memory management library is used.
The default memory management library is used.
The server supports the processing of 3 types of operations:
- Client operations
- Admin operations
- Site 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.
The “Admin” operations will be specific to managing and administering a MapGuide server using the MapAdmin.
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
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.
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 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.
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.
The following table describes the session object properties that will be associated with each connection.
Web Tier Component Architecture
|Figure ? - Web tier components|
Language Binding Generation
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.
|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:
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:
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
__getmarker. Generate a regular property for a method if a
__setmarker. 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
image1.jpg (36.0 KB) - added by 8 years ago.
image2.jpg (42.2 KB) - added by 8 years ago.
image3.jpg (20.0 KB) - added by 8 years ago.
image4.jpg (24.8 KB) - added by 8 years ago.
image5.jpg (33.8 KB) - added by 8 years ago.
Interaction Client, Web, Server
image6.jpg (23.5 KB) - added by 8 years ago.
Interaction Server to Server
image7.jpg (48.5 KB) - added by 8 years ago.
Resource Repository Content
image8.jpg (17.6 KB) - added by 8 years ago.
image9.jpg (29.7 KB) - added by 8 years ago.
Resource Repository Structure
image10.jpg (16.5 KB) - added by 8 years ago.
Site Resource Contents Container
image11.jpg (27.8 KB) - added by 8 years ago.
Library Resource Contents Container
image12.jpg (74.1 KB) - added by 8 years ago.
Internal server framework
image13.jpg (34.4 KB) - added by 8 years ago.
image14.jpg (18.1 KB) - added by 8 years ago.
image15.jpg (12.4 KB) - added by 8 years ago.
Simplified operation object
image16.jpg (36.4 KB) - added by 8 years ago.
Operation processing sequence
- GetTileSequence.png (34.7 KB) - added by 8 years ago.
- SWIG build process.png (100.6 KB) - added by 4 years ago.
Download all attachments as: .zip