Weave 2.4.1 adds support for client side map caches, previously Weave utilised ArcGIS Server map caches only on the server.

If you're currently using a map engine that's pointing to ArcGIS server then the client will automatically utilise an available map cache once you've upgraded to Weave 2.4.1, there should be no changes required to the client configuration.

There are a couple of requirements that must be met before this can occur though:

The client configuration must be setup to utilise fixed scales and they must match those of the ArcGIS server map cache.
The users browser must be able to directly connect to ArcGIS server (unless you're using a pre-generated tile cache being served directly via a web server).

If the version of ArcGIS server you're running supports it then the update will work with:

Fused and multi-layer map caches
Dynamic and pre-generated map caches
Compressed and exploded map caches

Configuring the server side map engine

The use of the client side map cache still requires that a server side map engine be setup. The Weave server will interrogate the server to see if it supports a map cache and if it does will dynamically alter the client configuration for the map engine to make use of the map cache.

The server side map engine is also used to generate map images when required on the server, for example when embedding in a report.

The following sample configurations show standard ArcGIS Server server side map engine configurations.
They have been trimmed to keep the samples brief, but would normally contain at least additional connection pooling information and will usually contain other configuration options.

A map service with a fused map cache.

<arcgisws:mapserver id="raster.fused">
	<url>http://arcserver:8399/arcgis/services/AerialPhotography/MapServer</url>
	<format>image/jpg</format>
	<transparent>false</transparent>
	<background>white</background>
	<selection>false</selection>
	<acetate>false</acetate>
</arcgisws:mapserver>

A map service with a multi-layer map cache

<arcgisws:mapserver id="raster.multilayer">
	<url>http://arcserver:8399/arcgis/services/Water/MapServer</url>
	<format>image/png</format>
	<transparent>true</transparent>
	<selection>false</selection>
	<acetate>false</acetate>
</arcgisws:mapserver>

A map service with no map cache

<arcgisws:mapserver id="vector">
	<url>http://arcserver:8399/arcgis/services/Main/MapServer</url>
	<format>image/png</format>
	<transparent>true</transparent>
</arcgisws:mapserver>

Map engines with a fused map cache will always be registered with the Weave server as having a single layer, with the id '0' and the name 'image', regardless of what's in the .mxd file.

Map engines with multi-layer map caches or no map caches will take their layer information from the .mxd file, but the existing 'usename' setting still applies and tells Weave to register the layers using the layer name as the id, rather than the layer id itself which changes if layers are added/removed from the map service.

Sample Toc model

The following sample show how the three map engines would need to be configured in a toc model (this assumes that the vector map engine has three layers, the multilayer two layers and the fused layer always has one, and because we didn't set 'username' to true in the map engine config the layer ids are numeric indexes)

<toc:model id="sample">
	<mapengine>vector</mapengine>
	<entry label="Roads" layer="0"/>
	<entry label="Properties" layer="1"/>
	<entry label="Suburbs" layer="2"/>
	<entry label="Water Valves" mapengine="raster.multilayer" layer="0"/>
	<entry label="Water Pipes" mapengine="raster.multilayer" layer="1"/>
	<entry label="Aerial Photography" mapengine="raster.fused" layer="0"/>
</toc:model>

Configuring the client side map engine

Previously if you had these three map engines included in your client configuration then they would all communicate with the Weave server to generate their map images.

Previously to utilise the map cache on the server the 'mapcache' property must be set to true for the map engine, that is no longer required as the 'mapcache' property defaults to true. If you wish to disable use of the map cache then it must be explicitly set to false

The configuration for the client would be something similar to

<client:config id="sample">
	<!-- standard config items appear here -->
	<view id="com.cohga.html.client.map.mapView">
		<!-- standard map view config items appear here -->
		<!-- we must set the scale to match the map caches -->
		<scales>
			<scale>1000</scale>
			<scale>10000</scale>
			<scale>100000</scale>
			<scale>1000000</scale>
		</scales>
		<!-- now add the three map engines -->
		<mapEngine id="raster.fused">
			<options>
				<transitionEffect>resize</transitionEffect>
				<alpha>true</alpha>
			</options>
		</mapEngine>
		<mapEngine id="raster.multilayer"/>
			<options>
				<transitionEffect>resize</transitionEffect>
				<alpha>true</alpha>
			</options>
		</mapEngine>
		<mapEngine id="vector">
			<options>
				<transitionEffect>resize</transitionEffect>
				<alpha>true</alpha>
				<ratio>1.2</ratio>
			</options>
		</mapEngine>
	</view>
</client:config>

This would display the three map engines and the user will be able to turn any of the six layers on and off.
That should be enough, if map caches are enabled the user will utilise them. If the map caches were deleted for the map engines then the client will still work, but it will communicate with the Weave server to generate it's images.

Aligning a tile cache

Sometimes the tile cache will not align exactly with the vector data, this can be corrected by specifying a tileOffset, in either the server map engine or client map engine configs. The tileOffset specifies an x and y shift that should be performed on the tiles before being displayed.
If we wanted to fix the fused map cache in the server configuration then we'd change it to

<arcgisws:mapserver id="raster.fused">
	<url>http://arcserver:8399/arcgis/services/AerialPhotography/MapServer</url>
	<format>image/jpg</format>
	<transparent>false</transparent>
	<background>white</background>
	<selection>false</selection>
	<acetate>false</acetate>
	<tileOffset x="-15.5" y="6"/>
</arcgisws:mapserver>

to do it in the client we'd change the client config to be

<mapEngine id="raster.fused">
	<options>
		<transitionEffect>resize</transitionEffect>
		<alpha>true</alpha>
		<tileOffset x="-15.5" y="6"/>
	</options>
</mapEngine>

Unfortunately you'll need to figure out the correct values for x and y by trial and error (the measure distance tool in the Weave client can help here).
Generally setting the tileOffset in the server config would be better since it only needs to be done once.

Directly serving tiles

If you've pre-generated the tiles from a fused cache and have the tiles published via web server then you can alter the client configuration to take advantage of this (this could also be used for a multi-layer map cache, but you'd only be able to point to one of the sub-layers).

Firstly you must specify a base URL that gives the location of the tiles, secondly you need to tell the client to use a direct connection rather than talking to ArcGIS server and finally you need to tell the client what format the tiles are stored in.

Currently this must all be performed in the client configuration, so for our fused map engine we'd need to change it to something like the following:

<mapEngine id="raster.fused">
	<url>http://arcserver/arcgiscache/AerialPhotography/Layers/_alllayers</url>
	<options>
		<useArcGISServer>false</useArcGISServer>
		<type>jpg</type>
		<transitionEffect>resize</transitionEffect>
		<alpha>true</alpha>
		<tileOffset x="-15.5" y="6"/>
	</options>
</mapEngine>

This provides the best performance of all the client side map caching options, and with the proper use of expiry times in the web server can result in very fast map redraws.

Disabling client side map caching

If you want to disable the caching on the client you need to explicitly set the map engine type to 'weave'.

As part of the process of setting up the client side map tiling the Weave server will set the client map engine type to either 'agstiled' or 'agsrest' (depending upon the type of map cache created in AGS, fused vs. multi layer) UNLESS it's already explicitly set to something. We can take advantage of this to set the map type to 'weave', which is the default if not specified anyway, thereby stopping the alterations from taking place.

Disabling the use of client side tile caching.

<mapEngine id="raster.fused">
	<type>weave</type>
	<options>
		<type>jpg</type>
		<transitionEffect>resize</transitionEffect>
		<alpha>true</alpha>
	</options>
</mapEngine>

forcing the client to contact the Weave server to generate map images.

Locally caching tiles

If you're accessing a remote AGS map engine and the response time from that engine is slow then you can turn on local caching of the tiles so that the Weave server will keep a local copy of each tile that's downloaded, this will improve the response the next time the tile is needed.

Enabling local caching of tiles

<arcgisws:mapserver id="vector">
	<url>http://arcserver:8399/arcgis/services/Main/MapServer</url>
	<format>image/png</format>
	<transparent>true</transparent>
	<cachetiles>true</cachetiles>
</arcgisws:mapserver>

The tiles will be stored locally under the Weave directory at ...\weave\platform\workspace\.agscache unless a system properties called agscache.location is set pointing to another directory location (allowing one local cache to be reused by multiple Weave instances).

Tiles can be set to expire after a certain period if it's believed that the underlying tiles will change over time, this is done by setting a cacheexpiry value to the number of minutes that a tile should be valid for.

Expiring tiles after 1 week

<arcgisws:mapserver id="vector">
	<url>http://arcserver:8399/arcgis/services/Main/MapServer</url>
	<format>image/png</format>
	<transparent>true</transparent>
	<cachetiles>true</cachetiles>
	<cacheexpiry>10800</cacheexpiry>
</arcgisws:mapserver>