MapServer

In this topic

The MapServer object

The majority of the mapping objects are in the esriCarto and esriDisplay libraries. Typically, your mapping application will use objects from a variety of libraries. When working with maps in ArcGIS Server applications, all such use is through the MapServer object.
The MapServer object is a coarse-grained server object that provides access to the contents of a map document as well as methods for querying and drawing the map. The map Web control is configured to display a specific MapServer running in a geographic information system (GIS) server. The smart client map control is also configured to connect to a MapServer data extraction Web service.
The MapServer object is shown in the following illustration.
MapServer can be configured as pooled or non-pooled, depending on the requirements of the application. An example of an application that requires a non-pooled MapServer is an application that changes the map (for example adds or removes layers) or one that manages a geodatabase edit session across multiple requests.
The MapServer coclass contains several interfaces with basic functions for displaying (IMapServer and IMapServerLayout) and querying (IMapServer and IMapServerData) an ArcGIS map document (.mxd or .pmf). There are a number of associated objects that represent input and output parameters for methods on MapServer interfaces. For example, the IMapServer method exportMapImage requires two inputs: a description of the map to be exported and a description of the output parameters. These inputs are captured in the MapDescription and ImageDescription objects. All the methods on IMapServer are stateless and can be called on both pooled and non-pooled MapServers.
The following code is an example of getting a MapServer object from the GIS server and making a call to draw itself at its default extent.
[Java] 
ServerInitializer init = new ServerInitializer();
init.initializeServer("domain", "username", "password");
ServerConnection con = new ServerConnection();
con.connect("myserver");
IServerObjectManager som = con.getServerObjectManager();
IServerContext serverContext = som.createServerContext("usa", "MapServer");
MapServer mapServer = (MapServer)serverContext.getServerObject();
ImageType it = (ImageType)serverContext.createObject(ImageType.getClsid());
it.setFormat(esriImageFormat.esriImageJPG);
it.setReturnType(esriImageReturnType.esriImageReturnMimeData);
ImageDisplay idisp = (ImageDisplay)serverContext.createObject(ImageDisplay.getClsid()
    );
idisp.setHeight(400);
idisp.setWidth(500);
idisp.setDeviceResolution(150);
ImageDescription pID = (ImageDescription)serverContext.createObject
    (ImageDescription.getClsid());
pID.setDisplay(idisp);
pID.setType(it);
IMapServerInfo mapServerInfo = mapServer.getServerInfo(mapServer.getDefaultMapName())
    ;
IMapDescription pMD = mapServerInfo.getDefaultMapDescription();
IImageResult pMI = mapServer.exportMapImage(pMD, pID);
// Do something with the result.
serverContext.releaseContext();

The map and its layers

To access information about a map and its layers, use the IMapServer method getServerInfo. getServerInfo returns a MapServerInfo object. Use the IMapServerInfo interface to access read-only information about a map (data frame). IMapServerInfo provides access to members describing the default state of a MapServer object, such as the name of the map, the background color, and the spatial extent of the map. This information cannot be changed without changing the state of the underlying fine-grained ArcObjects.
A MapServerInfo object contains a MapDescription. Use IMapDescription to access map settings that can be changed on the server object without changing the state of the underlying fine-grained ArcObjects on which the map document is based.
MapDescription is an important object when using MapServer in a stateless application, such as a Web application or Web service. MapDescription allows you to specify parameters for how the map will be drawn without changing the state of the MapServer object itself. The application keeps a serialized copy of the map description (created using SaveObject) in session state and deserializes it (using LoadObject) on each request. This allows each user of the application to have their own extent, set of visible layers, and so on, but on a pooled MapServer.
The map and layer information objects are shown in the following diagram.
Aspects of a map that can be modified in a stateless manner using the map description include the following:
  • The extent of the map
  • The angle of rotation of the map
  • The color in which selected features are drawn
  • The color that will be drawn transparent
  • The spatial reference of the map
  • Graphics to draw on the map
Layer settings can be retrieved from the IMapLayerInfo and ILayerDescription interfaces. Use the IMapLayerInfo interface to access read-only information about an individual layer in the map. Use the ILayerDescription interface to access read and write properties of a layer. As with the map description, the layer description allows you to modify aspects of each layer of the map in a stateless way. Aspects of a layer that can be modified in a stateless manner using the layer description include the following:
  • The visibility of the layer
  • The definition query expression for the layer
  • Whether the symbols used to draw the features in the layer should scale according to the map's reference scale
  • The color in which selected features are drawn
  • Whether selected features should be drawn with a specific symbol, and if so, the symbol to with which to draw them
  • Whether a buffer should be included around selected features in the layer
  • Whether or not the labels configured for the layer should be drawn
The following code is an example of getting a MapServer object from the GIS server and making a call to draw itself at its default extent with the first layer in the map not visible.
[Java] 
ServerInitializer init = new ServerInitializer();
init.initializeServer("domain", "username", "password");
ServerConnection con = new ServerConnection();
con.connect("myserver");
IServerObjectManager som = con.getServerObjectManager();
IServerContext serverContext = som.createServerContext("usa", "MapServer");
MapServer mapServer = (MapServer)serverContext.getServerObject();
ImageType it = (ImageType)serverContext.createObject(ImageType.getClsid());
it.setFormat(esriImageFormat.esriImageJPG);
it.setReturnType(esriImageReturnType.esriImageReturnMimeData);
ImageDisplay idisp = (ImageDisplay)serverContext.createObject(ImageDisplay.getClsid()
    );
idisp.setHeight(400);
idisp.setWidth(500);
idisp.setDeviceResolution(150);
ImageDescription pID = (ImageDescription)serverContext.createObject
    (ImageDescription.getClsid());
pID.setDisplay(idisp);
pID.setType(it);
IMapServerInfo mapServerInfo = mapServer.getServerInfo(mapServer.getDefaultMapName())
    ;
IMapDescription pMD = mapServerInfo.getDefaultMapDescription();
IImageResult pMI = mapServer.exportMapImage(pMD, pID);
ILayerDescriptions layerDescs = pMD.getLayerDescriptions();
ILayerDescription pLD = layerDescs.getElement(0);
pLD.setVisible(false);

// Do something with the result.
serverContext.releaseContext();
The map control Webmap object handles modifying, saving, and restoring the map and layer descriptions as users interact with the map and table of contents Web controls. 

Exporting a map image

Use the method exportMapImage on the interface IMapServer to export a map image. To specify the size and type of the output image, use the IImageDescription, IImageDisplay, and IImageType interfaces. MapServer supports all ArcGIS supported output types. exportMapImage returns a MapImage object. The interfaces IMapImage and ILayoutImage inherit from IImageResult. This is demonstrated in the previous code examples.
The map image exporting objects are shown in the following diagram.

Querying the map

IMapServer offers a number of methods to perform query operations on the map, such as find, identify, queryFeatureCount, queryFeatureData, queryFeatureIDs, and queryHyperlinks. To control the amount of information MapServer needs to process a query, a maximum number of records can be set. This value is set as part of configuring the MapServer server object and cannot be modified by application developers. This setting does not affect queryFeatureCount or queryFeatureIDs.
The find method returns a MapServerFindResults object. This is a collection of MapServerFindResult objects. Use IMapServerFindResult to access properties of found features.
The identify method returns a MapServerIdentifyResults object. This is a collection of MapServerIdentifyResult objects. Use IMapServerIdentifyResult to access properties of identified features including rows associated with the feature through a table relationship.
The MapServer identify result objects are shown in the following diagram.
The MapServer find result objects are shown in the following diagram.
The following sample code shows how to use the queryFeatureData method on IMapServer to find all the features in the first layer of the map that intersect MapServer's default map extent.[Java] 
IServerContext serverContext = som.createServerContext("usa", "MapServer");
MapServer mapServer = (MapServer)serverContext.getServerObject();
IMapServerInfo mapServerInfo = mapServer.getServerInfo(mapServer.getDefaultMapName())
    ;
IMapDescription pMD = mapServerInfo.getDefaultMapDescription();

SpatialFilter spatialFilter = (SpatialFilter)serverContext.createObject
    (SpatialFilter.getClsid());
spatialFilter.setGeometryByRef(pMD.getMapArea().getExtent());
spatialFilter.setSpatialRel(esriSpatialRelEnum.esriSpatialRelIntersects);
IRecordSet rs = mapServer.queryFeatureData(pMD.getName(), 0, (IQueryFilter)
    spatialFilter);

// Do something with the result.
serverContext.releaseContext();

Map layouts and surrounds

As described earlier, a MapServer serves a map document that contains one or more data frames and a layout. Use the IMapServerLayout interface to export the map layout or to export a legend, North arrow, or scale bar of a map. Also use IMapServerLayout to convert screen coordinates to page coordinates on the layout and vice versa.
One of the requirements for the exportLayout method on IMapServerLayout is a PageDescription object. PageDescription contains a MapFrameDescriptions object, which is the collection of MapFrameDescription objects (data frames) present in the layout from which you can get to the MapDescription for each data frame. The page description for a layout is analogous to the map description for a map in terms of how it is used to specify how to draw the layout in a stateless manner. The map description contains a collection of layer descriptions; the page description contains a collection of map frame descriptions, which in turn contain a map description—one for each data frame in the layout.

Individual legend elements

In addition to exporting a single image of the legend using IMapServerLayout, you can retrieve individual legend elements such as the symbol images, labels, descriptions and headings. A common use is to populate a table of contents. To retrieve this legend information, use getLegendInfo on IMapServer. This method returns a MapServerLegendInfos object, which is a collection of MapServerLegendInfo objects. Using these objects, you can retrieve the parts of the legend in which you are interested.
The MapServer legend information objects are shown in the following diagram.

Accessing fine-grained ArcObjects

Though the methods and properties available through MapServer and its associated objects offer important mapping functionality, they cannot encapsulate all that ArcObjects offers. In many cases, you may want to use other, finer-grained, ArcObjects in conjunction with MapServer. You can do this using the IMapServerObjects interface. Through this interface, you can access ILayer, IMap, and IPageLayout. For example, you can make changes to the map, such as adding a new layer, using IMap.
It is very important to distinguish between temporary and permanent changes to the MapServer object. A temporary change include changes to the MapDescription or LayerDescription using IMapDescription and ILayerDescription, respectively. For example, you can change the geographic extent of a map (MapArea) or the visibility of a layer (Visible). These changes can be temporary and valid for the duration of the call. Once the call has ended, the MapServer object returns to its default state.
Permanent changes to the MapServer object can be done in the following ways:
  • Change the map document itself, then restart the MapServer object.
  • Change the MapServer properties using such interfaces as IMapDescription and ILayerDescription, then call the IMapServerObjects method ApplyMapDescription. This updates the state of the MapServer object.
  • Access the underlying fine-grained ArcObjects directly using the methods on IMapServerObjects, make a change (such as adding a new layer or changing a layer's rendering), then call refreshServerObjects. This refreshes the MapServer object with the current state held by the fine-grained ArcObjects.
The following sample code is an example of using the finer-grained ArcObjects associated with a MapServer object to work with a feature class associated with a particular layer.
[Java] 
IServerContext serverContext = som.createServerContext("usa", "MapServer");
MapServer mapServer = (MapServer)serverContext.getServerObject();
IMap map = mapServer.getMap(mapServer.getDefaultMapName());
IFeatureLayer fLayer = (IFeatureLayer)map.getLayer(0);
IFeatureClass featureClass = fLayer.getFeatureClass();
System.out.println(featureClass.featureCount(null));
serverContext.releaseContext();

// Do something with the result.
serverContext.releaseContext();


See Also:

Managing application mapping state
Working with maps
MapServer extensions
Mapping Web services