How applications access and use the image service cache
In this topic
A cached image service can behave as either a static or dynamic image service. Generally, due to the tiled structure and static nature of a cached image service it will be faster than one that is not cached (or accessed as a dynamic service). When you access a cached image service it's default behavior is static and you will have limited access to the service properties—meaning you cannot modify the mosaic method or transmission compression.
Any web application that can display an image service uses the cache, although how the tiles are retrieved and used varies between applications.
ArcMap and ArcGIS Pro
When you display an image service that has been cached, it will have limited image service capabilities. For example, you will not be able to change the mosaic method or transmission compression method. But you will still be able to do things like change the symbology and enhancement, perform an identify on the pixels, query the data, and download the source data.
If you need to work with the image service dynamically and use functionality such as the mosaic method, then you can change the layer's mode. To change the mode, right-click the image service layer and uncheck Enable Cache View Mode. To use the image service as a cached service, just check this option back on.
ArcGIS API for JavaScript applications
When developing with the ArcGIS API for JavaScript, you use the ArcGISTiledMapServiceLayer class to connect to a cached image service. When you use the cached image service, tiles are retrieved from the cache directory by REST calls to the image service. The tile request takes the form http://<image service URL>/tile/<level>/<row>/<column>.
If you see URLs like this, your application is successfully getting tiles from REST requests:
http://gisserver.domain.com:6080/arcgis/rest/services/myService/ImageServer/tile/10/1723/3495
If you see some other URL format for your image service, your application is retrieving the tile in a less efficient way or the cache is not being used.
If you are viewing a single cached service in any web application and pan to an area where tiles do not exist, the application does not display a dynamic image; instead, you don't see anything.
Tip:
If the image service appears more slowly than expected, examine the URLs of the image service to verify that the application is retrieving tiles. One way to do this is to open the application in Mozilla Firefox 4 and click Firefox > Web Developer > Web Console. When the console appears, click the Net button, then zoom or pan your image service.
Tip:
Make sure the data source being cached is in the same projection as the other data used in the web application. If it's not, then you may not see your data, since most web applications cannot reproject the data. Also, make sure the tiling scheme is the same for the cached image service as the other cached layers in the web application; otherwise, not all layers will be visible.
Improving the display performance of cached image services
When clients send requests to ArcGIS Server to display an image service, the response from the server is typically cached by the browser and reused for a certain period of time. This behavior helps ArcGIS Server achieve the best possible display performance for your image service. However, depending on how your image service and its associated data are used in applications, you may consider adjusting the length of time the browser will use a response in its cache. This can be achieved by adding a property called cacheControlMaxAge to the JavaScript Object Notation (JSON) of the service.
How the cacheControlMaxAge property is used
ArcGIS Server image service responses include a entity tag (ETag) and Cache-Control header. The ETag header value is a unique identifier of the response. The Cache-Control header has a max-age value that provides information to the browser regarding the maximum time period for which it can reuse a response from the browser's cache. This value is controlled by the cacheControlMaxAge property.
When a request is repeated and the maximum age of the cache has not expired, the browser will use the cached response without sending the request to the server. If the maximum age has expired, the browser must send the request to the server and set an IF-NONE-MATCH header with an associated ETag value corresponding to the response in its cache. ArcGIS Server evaluates the request and uses the ETag value to determine if the response has changed. If the response from the server is different from the copy on the browser, the server will send a completely new response to the browser. If the response is identical to the copy on the browser, the server alerts the browser to continue to use the response in its cache.
Defining the value of the cacheControlMaxAge property
As an ArcGIS Server administrator, you can define the cacheControlMaxAge property to specify how long a browser is allowed to use a cached response. By mitigating the need for ArcGIS Server to send a full response, you allow your browser caches to be more efficient, help optimize your applications, and save network bandwidth.
For cached image services that do not allow clients to cache tiles locally, the default is 0. This means the browser will always resend a request and ArcGIS Server will process the request and send a full response to the browser if the content has changed.
For cached image services that allow clients to cache tiles locally, the default is 12 hours (43200 seconds). This means that if a request is repeated within 12 hours, the browser will use the response from its cache. This value works well for most applications.
For cached image services where the map or data does not change frequently, it is recommended to increase the default to 30 days (2592000 seconds) or longer to minimize network traffic.
To add the cacheControlMaxAge property to your service and specify its default value, do the following:
- In a web browser, open the ArcGIS Server Administrator Directory and log in with a user that has administrator privileges. The URL is formatted http://gisserver.domain.com:6080/arcgis/admin.
- Click services and select the image service you want to modify from the Services list. If you don't see your service listed, it may be in a directory under the Root folder.
- On the Service - <service name> (<service type>) page, scroll to the bottom and click edit.
- In the Service Properties dialog box, locate the properties section of the service JSON.
- Add the cacheControlMaxAge property to the section and specify the value (in seconds) for the property, for example:
"properties": { "cacheControlMaxAge": "2592000", - Click Save Edits.
- On the Service - <service name> (<service type>) page, verify that the cacheControlMaxAge property and the value you specified for it appears in the Properties section.
Overlaying caches in web applications
As noted earlier, when designing image service caches that will overlay with other cached services, there are some important cache design factors to consider. Web applications built with the ArcGIS API for JavaScript require that you match coordinate system and tile size when overlaying caches. It's also a good practice to match as many scales as possible. The easiest way to do this is to match tiling schemes for both caches, then only create tiles at the scales that make sense for each cache. This way, you can be sure that you've matched coordinate system and tile size and that the software recognizes that the two caches have scales in common.
The recommended tiling scheme is the ArcGIS Online/Google Maps/Bing Maps tiling scheme.
OGC WMTS
The Open Geospatial Consortium, Inc. (OGC), Web Map Tile Service (WMTS) specification is an international specification for serving digital maps over the web using cached image tiles. When you create a cached map or image service using ArcGIS Server, the service and its tiles are automatically accessible using the WMTS specification.
The URL to connect to a cached image service using the WMTS protocol uses the following pattern:
http://gisserver.domain.com:6080/arcgis/rest/services/folder/service/ImageServer/WMTS