ArcGIS Server Java Help - Automating cache creation and updates with geoprocessing

If you're working with a basemap that is unlikely to change, chances are you'll create its cache only once. You can use the ArcCatalog caching interface (namely, the Caching tab of the Service Properties dialog box) to create the cache. This is also an appropriate way to update the cache if your data does not change very often.

If your data changes often, you still may be able to use caching. The caching tools have been designed to allow you to script cache updates and target the updates at specific parts of the cache. For example, you can:

Update the cache only for scale levels that have changed.
Update only areas of the cache that fall within the boundaries of a feature class.
Automate cache maintenance with utilities such as Windows Scheduled Tasks.

The way to automate the caching process is to write scripts that use the Server Tools, accessed from the Geoprocessing menu. On Linux/Solaris, the caching scripts are already created for you and installed with the ArcGIS Server SOC component under <ArcGIS Server Installation directory>/arcgis/server<10.0>/java/tools/caching. This help topic lists the tools available to you and contains some examples to help you get started writing scripts. It also describes migration of older scripts from ArcGIS Server 9.2 to later versions.

Caching tools

The Server Tools toolbox contains tools for both map caching and globe caching.

Map caching tools

The following tools are included for map caching. The tools reflect the pattern of creating the tiling scheme and filling the cache with tiles.

Create Map Server Cache—Initializes the cache and sets the tiling scheme. This tool does not create any tiles. To create the tiles, use Manage Map Server Cache Tiles.
Manage Map Server Cache Tiles—Creates new tiles, replaces old tiles, or deletes tiles from the cache.
Manage Map Server Cache Scales—Adds or removes scales from an existing cache.
Delete Map Server Cache—Deletes all cache tiles and the cache's folder structure.

A common scripting workflow is to use Create Map Server Cache to create a new empty cache, then use Manage Map Server Cache Tiles to fill the cache with tiles and periodically run updates.

A tool for standardizing map caches

If you'll be building many map caches to use in your organization, it's recommended that you use the same tiling scheme for each. Using a standard tiling scheme allows for a more efficient overlay of your caches.

The tiling scheme you choose might be the same tiling scheme used by online mapping services such as ArcGIS Online, Google Maps, or Bing Maps, or it may be a tiling scheme used only in your organization. Your choice of tiling scheme may be influenced by cartographic standards or practices in your organization. For example, if all your maps are required to use the polar stereographic projection, you will not be able to use the ArcGIS Online, Google Maps, or Bing Maps tiling schemes; you will need to create your own tiling scheme.

The Generate Map Server Cache Tiling Scheme tool in the Server Tools toolbox can help you create one tiling scheme to share throughout your organization. This tool creates an XML tiling scheme file, which you can place in a shared location and reference when you run Create Map Server Cache.

Map cache maintenance and collaboration tools

Several tools in the Caching toolset are designed for maintaining caches and building them collaboratively.

The Convert Map Server Cache Storage Format tool can convert old caches to the new compact format introduced at ArcGIS Server 10. This tool can actually convert both ways between exploded (pre-ArcGIS 10) and compact formats.

The Export Map Server Cache and Import Map Server Cache tools help move subsets of tiles between caches. Exporting and importing caches can be useful when several organizations collaborate to build one large cache or when an organization with a large cache wants to share some of its tiles with another organization.

Learn more about exporting and importing map caches

Globe caching tools

The following tools are included for globe caching:

Manage Globe Server Cache Tiles—Creates new tiles, replaces old tiles, or deletes tiles from a globe cache
Delete Globe Server Cache—Deletes the cache

Notice there are only two tools for working with globe caches. By nature, all globe services have a cache that is automatically created when you start the service. This cache uses a built-in tiling scheme that is the same for all globe services. Therefore, there are no tools for creating a new globe cache or tiling scheme.

You can use Manage Globe Server Cache Tiles to completely fill the cache with tiles, or you can use it to cache only selected areas and levels of detail.

Using the tools in scripts

Although you can manually open the caching tools from the Catalog or Search windows, it's more efficient to write a geoprocessing script that contains one or more tools that you want to run. You can then schedule this script to run automatically.

Scripting example: Updating a map cache

If your data changes frequently, scripting is the recommended way to update your cache. You can create a Python script that runs the update tool. You can write the Python inside of Notepad, or you can use a development environment such as IDLE or PythonWin.

The script does not have to be complex. It just needs to define the parameters for the tool and run it. The following Python script runs the Manage Map Server Cache Tiles tool to re-create an entire cache:

# This script updates a map cache containing changing data

# Any line that begins with a pound sign is a comment and will not be executed

# These lines are used to access ArcGIS geoprocessing tools
import arcpy, sys
from arcpy import env

# Here is where you define the input parameter values for the update tool. 
# Empty quotes take the default value.
server = "MyServer"
service = "Precipitation"
dataFrame = "Layers"
inputLayers = ""
extent = ""
scales = "128000;64000;32000;16000"
updateMode = "Recreate All Tiles"
threadCount = "2"
antialiasing = "NONE"
pathToFeatureClass = ""
ignoreStatus = ""

# These lines run the update tool
try:
    print 'Starting Cache Update'
    result = arcpy.ManageMapServerCacheTiles_server(server, service, dataFrame,
                                           inputLayers, scales, updateMode,
																																											extent, threadCount,
																																											antialiasing, pathToFeatureClass,
																																											ignoreStatus)		
    while result.status < 4:
									time.sleep(0.2)
				resultValue = result.getMessages()
				print str(resultValue)
				print 'Finished Cache Update'
# If there's a failure, these lines get the messages
except Exception, e:  
    tb = sys.exc_info()[2]
				print "Line %i" % tb.tb_lineno

It's important to use the correct syntax for all the input parameters. You can find instructions and examples for each parameter of each tool in the Geoprocessing Tool Reference book of the ArcGIS Desktop Help. For example, here is the reference topic for the Manage Map Server Cache Tiles tool used above: Manage Map Server Cache Tiles (Server).

If you're new to Python, these resources can help you learn more:

What is Python?—The ArcGIS Desktop Help contains an introduction to Python scripting, starting with this topic.
Exporting a model—If you've created models in ModelBuilder, you can export them to Python to see what the corresponding script looks like.

Scheduling your script to run on a regular basis

You can save your script as a Python script file (.py). Double-clicking the script in Windows Explorer will cause the script to run. This is useful for testing, but in most cases, you'll want to schedule the script to run automatically on a regular basis.

Your operating system contains utilities that help you schedule tasks such as running a script. In Windows you can use Scheduled Tasks or the schtasks command. You'll need to provide the location of the script file, how often you want it to run, and the name and password that the task will run as. For more information on scheduling tasks, see the following resources:

Scheduling a Python script to run at prescribed times
Scheduling scripts to run at prescribed times (Unix Documentation)
Schedule a new task (Microsoft documentation)
Schtasks command line reference (Microsoft documentation)

Note for Linux users

On Linux, before running Python scripts for working with the cache, you must execute the command source /arcgis/server10.0/servercore/.Server/init_server.sh as described in Step2 of Viewing and Managing Network Ports on Linux/Solaris.

Legacy:

If you used the Server Tools toolbox with ArcGIS Server 9.2, you'll notice some changes in versions 9.3 and beyond. Some tools from ArcGIS Server 9.2 have been deprecated. They are included with the software so that your existing scripts will continue to run, but you cannot add them to the toolbox and they are not available through the command line. You can only use them in a scripting environment.

This table shows the deprecated tools and their replacements in 9.3 and beyond:

9.2 deprecated tool	Replacement tool
Generate Map Server Cache	Create Map Server Cache Manage Map Server Cache Tiles
Update Map Server Cache	Manage Map Server Cache Tiles
Generate Globe Server Cache	Manage Globe Server Cache Tiles
Update Globe Server Cache	Manage Globe Server Cache Tiles

Generate Map Server Cache—This tool initialized the map cache, set the tiling scheme, and created all the tiles in the cache. At 9.3 and beyond, use Create Map Server Cache to initialize the cache and set the tiling scheme. Then use Manage Map Server Cache Tiles to create some or all of the tiles for the cache.
Update Map Server Cache—This tool created, replaced, or deleted tiles from a map cache. At 9.3 and beyond, use Manage Map Server Cache Tiles, which can do the same things with more flexibility for updating only selected areas of the cache.
Generate Globe Server Cache—This tool generated all tiles in a globe cache. At 9.3 and beyond, use Manage Globe Server Cache Tiles to create some or all of the tiles for the globe cache.

The order of parameters has changed in some of the new tools. For example, in ManageMapServerCacheTiles, constraining_extent is now a required parameter that immediately follows update_mode in the parameter list. Always consult the latest geoprocessing tool reference documentation when updating your scripts.

11/18/2013