The dynamic map engine is a virtual map engine that provides additional functionality on top of other map engines, for example load balancing and fail over support.

When a dynamic map engine is configured, it is setup so that it points to one or more other map engines then anything that previously pointed to the original map engine is changed to point to the new map engine, or the old map engine is renamed and the dynamic map engine is given the id of the old map engine then nothing else needs to change.

Depending upon how the dynamic map engine is configured it can provide the following different functionality:

• Redirect
  • If there's only one sub-map engine, then any request to the map engine will be sent directly to the sub-map engine.
• Fail-over
  • If "failover" is set to true for the map engine, then the first sub-map engine listed will be used until it fails, then the second sub-map engine will be used instead.
• Alternating styles
  • If "altlayers" is set by providing a list of layer id's, when none of those layers are requested, the first sub-map engine will be used, but if any of those layers are requested then the second sub-map engine will be used.
• Load balancing
  • If there is more than one sub-map engine listed and "failover" and "altlayers" are not set then incoming requests will be spread across the listed sub-map engines.
• Stitching
  • If there is only one sub-map engine and "maxwidth" and "maxheight" are set, then any request for a map over that size will be broken up into multiple requests to ensure the underlying map engine will generate the requested image size.
    
    

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0"
	xmlns:wms="urn:com.cohga.server.map.wms#1.0"
	xmlns:dynamic="urn:com.cohga.server.map.dynamic#1.0">

	<wms:mapengine id="wms1">
		<url>http://server1.local/wms</url>
		<!-- other WMS configuration items -->
	</wms:mapengine>
	<wms:mapengine id="wms2">
		<url>http://server2.local/wms</url>
		<!-- other WMS configuration items -->
	</wms:mapengine>

	<!-- will cycle requests for 'loadbalanced' between 'wms1' and 'wms2' -->
    <!-- you can list as many map engines as you need but they must all be configured identically -->
	<dynamic:mapengine id="loadbalanced">
		<mapengine>wms1</mapengine>
		<mapengine>wms2</mapengine>
	</dynamic:mapengine>

	<!-- will send requests for 'failover' to 'wms1' until that falls over, in which case it'll use 'wms2' -->
    <!-- you can list as many map engines as you need but they must all be configured identically -->
	<dynamic:mapengine id="failover">
		<failover>true</failover>
		<mapengine>wms1</mapengine>
		<mapengine>wms2</mapengine>
	</dynamic:mapengine>

	<!-- will send requests for 'alternate' to 'wms1' unless the user turns on an aerial photo layer, in which case it will use 'wms2' -->
    <!-- you can only list two map engines -->
    <!-- Only available since 2.5.16 -->
	<dynamic:mapengine id="alternate">
		<altlayers>aerial_photo_2001,aerial_photo_2008,aerial_photo_2015</altlayers>
		<mapengine>wms1</mapengine>
		<mapengine>wms2</mapengine>
	</dynamic:mapengine>

	<!-- any request that has a width greater than 4096 or a height greater than 4096 pixels will be broken up into multiple requests -->
	<!-- this example is assuming that the wms1 map engine has been configured to generate an image less than 4096 x 4096 pixels -->
	<!-- only available since 2.6.4 -->
	<dynamic:mapengine id="stitching">
		<maxwidth>4096</maxwidth>
		<maxheight>4096</maxheight>
		<mapengine>wms1</mapengine>
	</dynamic:mapengine>

	<!-- will redirect all requests for 'redirect' to 'wms1' -->
	<!-- this allows us to use "redirect" as the map engine id in the rest of the configuration -->
	<!-- but allow us to switch between different real map engines for testing, development, etc -->
	<dynamic:mapengine id="redirect">
		<mapengine>wms1</mapengine>
	</dynamic:mapengine>

</config>

In the above examples, any configuration item that previously references wms1 or wms2 map engines would now reference redirect, loadbalanced, failover, alternate or stitching and operate the same as before with the benefits of the particular function configured. Plus, dynamic map engines can also reference other dynamic map engines, so you can combine load balancing and fail over, for example.

Why would I use the Redirect Dynamic Map Engine?

In most cases, you wouldn't use it. The redirect dynamic map engine is probably only useful to the Cohga Support Team because they often have many different map engines that they need to test and don't want to have to update all the relevant configuration files each time they need to switch map engines. 

However here is a real life example of it in use. The "main" vector map engine is called "mapengine.vector" and there are a number of other map engines, roughly containing the same layers, called "mapengine.vector.wms.geoserver", "mapengine.vector.wms.gqis", "mapengine.vector.arcgis.soap.100", "mapengine.vector.arcgis.rest.140", etc. By just changing the sub-map engine id it's possible to switch to test a different map engine implementation (e.g. for problem solving a Support issue).  In this example, there is also a toc model, called "toc.vector" that has a single toc entry that is changed to the toc model that corresponds to the chosen map engine. This way all the other config files just reference "mapengine.vector" and "toc.vector" making testing different types of map engines easy. 

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:dynamic="urn:com.cohga.server.map.dynamic#1.0">

<?set vector.mapengine=wms.qgis?>

	<dynamic:mapengine id="mapengine.vector">
		<mapengine>mapengine.vector.${vector.mapengine}</mapengine>
	</dynamic:mapengine>

	<toc:model id="toc.vector">
		<entry toc="toc.vector.${vector.mapengine}"/>
	</toc:model>

</config>