com.esri.arcgis.carto
Class MapServer

java.lang.Object
  extended bycom.esri.arcgis.carto.MapServer
All Implemented Interfaces:
ILogSupport, IMapServer, IMapServerData, IMapServerInit, IMapServerLayout, IMapServerObjects, IObjectActivate, IObjectConstruct, IRequestHandler, ISupportErrorInfo, Serializable

public class MapServer
extends Object
implements IMapServer, IObjectConstruct, IRequestHandler, IMapServerObjects, IMapServerData, IMapServerLayout, IMapServerInit, IObjectActivate, ILogSupport, ISupportErrorInfo

The MapServer component provides programmatic access to the contents of a map document on disk, and creates images of the map contents based on user requests. Designed for use in building map-based web services and web applications.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Remarks

MapServer is a coarse-grained ArcObject.  This object allows users to display and query ArcGIS map documents in either desktop, LAN/WAN, or internet development environments. In the desktop environment you can use MapServer, as well as other coarse-grained objects as a "short-cut" for ArcObjects development.  Operations that took many lines of code may now just take a few. In a server environment, MapServer objects can be accessed via Distributed COM (DCOM) over a TCP/IP connection (Intranet) or via SOAP/XML over an HTTP connection (Internet).  In order to make MapServer objects available over the Internet, you will need to publish the map server object to an ASP- or JSP-based web catalog.

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).

In addition to MapServer, a number of MapServer objects are defined to 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.

Though the methods and properties available through MapServer and its associated objects offer important mapping functionality, they cannot possibly 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 would include changes to the MapDescription or LayerDescription using IMapDescription and ILayerDescription. For example, you might change the geographic extent of a map (MapArea) or change 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 it's default state.

Permanent changes to the MapServer object can be done in two ways.  The first is by changing MapServer properties using such interfaces as IMapDescription and ILayerDescription and then calling the IMapServerObjects method ApplyMapDescription. This will update the state of the fine-grained ArcObjects. Another way to change the MapServer object is to access the underlaying fine-grained ArcObjects directly using the methods on IMapServerObjects, make a change such as adding a new layer or changing a layer's rendering, and then calling RefreshServerObjects. This refreshes the MapServer object with the current state held by the fine-grained ArcObjects.

You should use non-pooled objects when permently changing the state of fine-grained ArcObjects.

Only simple symbols (ISimpleMarkerSymbol, ISimpleLineSymbol and ISimpleFillSymbol) are supported when accessing a MapServer object through an AGSServerConnection (LAN or internet).

See Also:
Serialized Form

Constructor Summary
MapServer()
          Constructs a MapServer on the local host.
MapServer(com.linar.jintegra.AuthInfo authInfo)
          See Security section in the J-Integra for COM documentation
MapServer(Object obj)
          Construct a MapServer using a reference to such an object returned from a COM server
MapServer(String host)
          Construct a MapServer on specified host.
MapServer(String host, com.linar.jintegra.AuthInfo authInfo)
          See Security section in the J-Integra for COM documentation
 
Method Summary
 void activate()
          Activates the object.
 void applyMapDescription(IMapDescription mapDescription, IImageDisplay mapDisplay)
          Applies the current state of the map description to the map server object.
static MapServer bindUsingMoniker(String moniker)
          Bind to a running instance of this class using the supplied ObjRef moniker
 double computeDistance(String mapName, IPoint fromPoint, IPoint toPoint, int units)
          Computes the distance between two points on the specified map.
 double computeScale(IMapDescription mapDesc, IImageDisplay mapDisplay)
          Computes the scale of the specified map, at the given map extent, for an image with the given size.
 void connect(String filePath)
          Initializes the map server with an mxd or pmf file stored at the specified path.
 void construct(IPropertySet props)
          Two phase object construction
 void deactivate()
          Deactivates the object.
 boolean equals(Object o)
          Compare this object with another
 ILayoutImage exportLayout(IPageDescription pageDesc, IImageDescription imageDesc)
          Generates an image of the layout, based on the given page description object, and writes the image to a specified file on disk.
 IImageResult exportLegend(ILegend legend, IMapDescription mapDesc, IImageDisplay pMapDisplay, IColor backgroundColor, IImageDescription imageDesc)
          Exports a legend to an image file.
 IMapImage exportMapImage(IMapDescription mapDesc, IImageDescription imageDesc)
          Generates an image of the map, based on the given map description, and writes the image to a specified file on disk.
 IImageResult exportNorthArrow(INorthArrow arrow, IMapDescription mapDesc, IColor backgroundColor, IImageDescription imageDesc)
          Exports a north arrow to an image file.
 IImageResult exportScaleBar(IScaleBar scalebar, IMapDescription mapDesc, IImageDisplay pMapDisplay, IColor backgroundColor, IImageDescription imageDesc)
          Exports a scale bar to an image file.
 IMapServerFindResults find(IMapDescription mapDesc, IImageDisplay mapImage, String searchString, boolean contains, String searchFields, int option, ILongArray layerIds)
          Returns a collection of Map Server Find Result objects that contain the given search string.
 void fromMapPoints(IMapDescription mapDescription, IImageDisplay mapDisplay, IPointCollection mapPoints, ILongArray[] screenXValues, ILongArray[] screenYValues)
          Converts a map coordinate to a screen location.
 void fromPagePoints(IEnvelope pageExtent, IImageDisplay pageDisplay, IPointCollection pagePoints, ILongArray[] screenXValues, ILongArray[] screenYValues)
          Converts a page coordinate to a screen location.
static MapServer getActiveObject()
          Get a reference to a running instance of this class on the current machine using native code.
 ILogSupport getAsILogSupport()
          Access this class's com.esri.arcgis.system.ILogSupport interface
 IMapServer getAsIMapServer()
          Access this class's com.esri.arcgis.carto.IMapServer interface
 IMapServerData getAsIMapServerData()
          Access this class's com.esri.arcgis.carto.IMapServerData interface
 IMapServerInit getAsIMapServerInit()
          Access this class's com.esri.arcgis.carto.IMapServerInit interface
 IMapServerLayout getAsIMapServerLayout()
          Access this class's com.esri.arcgis.carto.IMapServerLayout interface
 IMapServerObjects getAsIMapServerObjects()
          Access this class's com.esri.arcgis.carto.IMapServerObjects interface
 IObjectActivate getAsIObjectActivate()
          Access this class's com.esri.arcgis.system.IObjectActivate interface
 IObjectConstruct getAsIObjectConstruct()
          Access this class's com.esri.arcgis.system.IObjectConstruct interface
 IRequestHandler getAsIRequestHandler()
          Access this class's com.esri.arcgis.system.IRequestHandler interface
 ISupportErrorInfo getAsISupportErrorInfo()
          Access this class's com.esri.arcgis.system.ISupportErrorInfo interface
static String getClsid()
           
 String getDefaultMapName()
          Name of the document's active map (data frame).
 IPageDescription getDefaultPageDescription()
          The default page settings.
 IPropertySet getDocumentInfo()
          A set of name-value pairs for properties set for the map document (mxd only).
 IFeature getFeature(String mapName, int layerID, int featureId)
          Returns a feature, given the feature ID and layer.
 String getFeatureValue(String mapName, int layerID, IFeature feature, String fieldName)
          Returns the value of a given feature as a string.
 String getFilePath()
          The map document path.
 ILayer getLayer(String mapName, int layerID)
          The layer specified by the map name and layer ID.
 IMapServerLegendInfos getLegendInfo(String mapName, ILongArray layerIds, IMapServerLegendPatch patch, IImageType imgType)
          Returns a collection of Map Server Legend Info objects for the specified layers.
 IMap getMap(String mapName)
          The map corresponding to the specified map name.
 int getMapCount()
          The number of maps (data frames) in the document.
 String getMapName(int index)
          Name of the map (data frame) as indicated by the index.
 int getMaxBufferCount()
          The maximum number of records buffered on the server for display.
 int getMaxImageHeight()
          The maximum height in pixels of an image request.
 int getMaxImageWidth()
          The maximum width in pixels of an image request.
 int getMaxRecordCount()
          The maximum number of records returned for query results (Identify, Find, QueryFeatureData, and QueryHyperlinks).
 IPageLayout getPageLayout()
          The page layout object for the current map document.
 String getPhysicalOutputDirectory()
          The physical directory for output files.
 Object getPropertyByName(String name)
          Get the value of a property dynamically at run-time, based on its name
 Object getPropertyByName(String name, Object rhs)
          Get the value of a property dynamically at run-time, based on its name and a parameter
 IMapServerInfo getServerInfo(String mapName)
          Returns information about a map (data frame).
 ISQLSyntaxInfo getSQLSyntaxInfo(String mapName, int layerID)
          Returns the SQL syntax information for the specified layer.
 int getSupportedImageReturnTypes()
          The supported image return types for the map server.
 Picture getThumbnail()
          The thumbnail stored in the map document.
 String getVirtualOutputDirectory()
          The virtual directory for output files.
 byte[] handleBinaryRequest(byte[] request)
          Handles a binary request.
 String handleStringRequest(String capabilities, String request)
          Handles a SOAP string request.
 int hashCode()
          the hashcode for this object
 IMapServerIdentifyResults identify(IMapDescription mapDesc, IImageDisplay mapImage, IGeometry searchShape, int tolerance, int option, ILongArray layerIds)
          Returns a collection of Map Server Identify Result objects at the given location.
 void initLogging(ILog log)
          Initializes an object with a log.
 void interfaceSupportsErrorInfo(GUID riid)
          Supported Platforms
 Object invokeMethodByName(String name)
           
 Object invokeMethodByName(String name, Object[] parameters)
          Invoke a method dynamically at run-time to pass primitive types (eg Integer to pass an int).
 int queryFeatureCount(String mapName, int layerID, IQueryFilter filter)
          Returns the count of the features that meet the query filter selection criteria for the specified layer.
 IRecordSet queryFeatureData(String mapName, int layerID, IQueryFilter filter)
          Returns a record set of features that meet the query filter selection criteria for the specified layer.
 IFIDSet queryFeatureIDs(String mapName, int layerID, IQueryFilter filter)
          Returns the IDs of the features that meet the query filter selection criteria for the specified layer.
 IMapServerHyperlinks queryHyperlinks(IMapDescription mapDesc, IImageDisplay mapImage, ILongArray layerIds)
          Returns a collection of Map Server Hyperlink objects for the specified layers.
 void refreshServerObjects()
          Updates the server info based on the current state of the underlying fine-grained objects.
 void setMaxBufferCount(int count)
          The maximum number of records buffered on the server for display.
 void setMaxImageHeight(int height)
          The maximum height in pixels of an image request.
 void setMaxImageWidth(int width)
          The maximum width in pixels of an image request.
 void setMaxRecordCount(int count)
          The maximum number of records returned for query results (Identify, Find, QueryFeatureData, and QueryHyperlinks).
 void setPhysicalOutputDirectory(String dirPath)
          The physical directory for output files.
 void setVirtualOutputDirectory(String dirPath)
          The virtual directory for output files.
 void startWithData(IDataset pDataset)
          An alternative to calling Connect().
 void stop()
          Clears out all of the map objects in memory.
 IPointCollection toMapPoints(IMapDescription mapDescription, IImageDisplay mapDisplay, ILongArray screenXValues, ILongArray screenYValues)
          Converts a screen location to a map coordinate.
 IPointCollection toPagePoints(IEnvelope pageExtent, IImageDisplay pageDisplay, ILongArray screenXValues, ILongArray screenYValues)
          Converts a screen location to a page coordinate.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MapServer

public MapServer()
          throws IOException,
                 UnknownHostException
Constructs a MapServer on the local host.

Throws:
IOException - if there are problems communicating via DCOM
UnknownHostException - if the host can not be found

MapServer

public MapServer(String host)
          throws IOException,
                 UnknownHostException
Construct a MapServer on specified host.

Parameters:
host - the host on which the object should be created
Throws:
IOException - if there are problems communicating via DCOM
UnknownHostException - if the host can not be found

MapServer

public MapServer(com.linar.jintegra.AuthInfo authInfo)
          throws IOException,
                 UnknownHostException
See Security section in the J-Integra for COM documentation


MapServer

public MapServer(String host,
                 com.linar.jintegra.AuthInfo authInfo)
          throws IOException,
                 UnknownHostException
See Security section in the J-Integra for COM documentation


MapServer

public MapServer(Object obj)
          throws IOException
Construct a MapServer using a reference to such an object returned from a COM server

Parameters:
obj - an object returned from a COM server
Throws:
IOException - if there are problems communicating via DCOM
Method Detail

getClsid

public static String getClsid()

getAsIMapServer

public IMapServer getAsIMapServer()
Access this class's com.esri.arcgis.carto.IMapServer interface


getAsIObjectConstruct

public IObjectConstruct getAsIObjectConstruct()
Access this class's com.esri.arcgis.system.IObjectConstruct interface


getAsIRequestHandler

public IRequestHandler getAsIRequestHandler()
Access this class's com.esri.arcgis.system.IRequestHandler interface


getAsIMapServerObjects

public IMapServerObjects getAsIMapServerObjects()
Access this class's com.esri.arcgis.carto.IMapServerObjects interface


getAsIMapServerData

public IMapServerData getAsIMapServerData()
Access this class's com.esri.arcgis.carto.IMapServerData interface


getAsIMapServerLayout

public IMapServerLayout getAsIMapServerLayout()
Access this class's com.esri.arcgis.carto.IMapServerLayout interface


getAsIMapServerInit

public IMapServerInit getAsIMapServerInit()
Access this class's com.esri.arcgis.carto.IMapServerInit interface


getAsIObjectActivate

public IObjectActivate getAsIObjectActivate()
Access this class's com.esri.arcgis.system.IObjectActivate interface


getAsILogSupport

public ILogSupport getAsILogSupport()
Access this class's com.esri.arcgis.system.ILogSupport interface


getAsISupportErrorInfo

public ISupportErrorInfo getAsISupportErrorInfo()
Access this class's com.esri.arcgis.system.ISupportErrorInfo interface


equals

public boolean equals(Object o)
Compare this object with another


hashCode

public int hashCode()
the hashcode for this object


getActiveObject

public static MapServer getActiveObject()
                                 throws AutomationException,
                                        IOException
Get a reference to a running instance of this class on the current machine using native code. Uses native code (See GetActiveObject() in MS doc) and thus can only be used on MS Windows

Returns:
A reference to the running object.
Throws:
IOException - If there are communications problems.
AutomationException - If there was an error attaching to the instance.

bindUsingMoniker

public static MapServer bindUsingMoniker(String moniker)
                                  throws AutomationException,
                                         IOException
Bind to a running instance of this class using the supplied ObjRef moniker

Parameters:
moniker - The ObjRef Moniker (Created using Windows CreateObjrefMoniker() and IMoniker->GetDisplayName).
Returns:
A reference to the running object.
Throws:
IOException - If there are communications problems.
AutomationException - If there was an error attaching to the instance.

getPropertyByName

public Object getPropertyByName(String name)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException
Get the value of a property dynamically at run-time, based on its name

Parameters:
name - The name of the property to get.
Returns:
The value of the property.
Throws:
NoSuchFieldException - If the property does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getPropertyByName

public Object getPropertyByName(String name,
                                Object rhs)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException
Get the value of a property dynamically at run-time, based on its name and a parameter

Parameters:
name - The name of the property to get.
rhs - A parameter used when getting the proxy.
Returns:
The value of the property.
Throws:
NoSuchFieldException - If the property does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name,
                                 Object[] parameters)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException
Invoke a method dynamically at run-time to pass primitive types (eg Integer to pass an int).

Parameters:
name - The name of the method to be invoked.
parameters - One element for each parameter. Use primitive type wrappers.
Returns:
The value returned by the method (null if none).
Throws:
NoSuchMethodException - If the method does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException
Throws:
NoSuchMethodException
IOException
AutomationException

getDocumentInfo

public IPropertySet getDocumentInfo()
                             throws IOException,
                                    AutomationException
Description copied from interface: IMapServer
A set of name-value pairs for properties set for the map document (mxd only). These properties are string values set in the map document's Map Properties dialog and include: Title, Subject, Author, Category, Keywords and Comments.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getDocumentInfo in interface IMapServer
Returns:
An reference to a com.esri.arcgis.system.IPropertySet
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getMapCount

public int getMapCount()
                throws IOException,
                       AutomationException
Description copied from interface: IMapServer
The number of maps (data frames) in the document.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getMapCount in interface IMapServer
Returns:
The count
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getMapName

public String getMapName(int index)
                  throws IOException,
                         AutomationException
Description copied from interface: IMapServer
Name of the map (data frame) as indicated by the index. The first beginning with 0.

Supported Platforms

Windows, Solaris, Linux

Remarks

If two (or more) data frames have the same name, Map Server adds a distinctive number at the end of the second name. E.g. Layers and Layers2.

Specified by:
getMapName in interface IMapServer
Parameters:
index - The index (in)
Returns:
The mapName
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getDefaultMapName

public String getDefaultMapName()
                         throws IOException,
                                AutomationException
Description copied from interface: IMapServer
Name of the document's active map (data frame).

Supported Platforms

Windows, Solaris, Linux

Remarks

If two (or more) data frames have the same name, Map Server adds a distinctive number at the end of the second name. E.g. Layers and Layers2.

Specified by:
getDefaultMapName in interface IMapServer
Returns:
The mapName
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getServerInfo

public IMapServerInfo getServerInfo(String mapName)
                             throws IOException,
                                    AutomationException
Description copied from interface: IMapServer
Returns information about a map (data frame).

Supported Platforms

Windows, Solaris, Linux

Remarks

Using IMapServerInfo you can retrieve information regarding the present state of the MapServer object.

If two (or more) data frames have the same name, Map Server adds a distinctive number at the end of the second name. E.g. Layers and Layers2.

This method returns an MapServerInfo object.

Specified by:
getServerInfo in interface IMapServer
Parameters:
mapName - The mapName (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapServerInfo
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

exportMapImage

public IMapImage exportMapImage(IMapDescription mapDesc,
                                IImageDescription imageDesc)
                         throws IOException,
                                AutomationException
Description copied from interface: IMapServer
Generates an image of the map, based on the given map description, and writes the image to a specified file on disk. Supported file types are: 'bmp', 'jpg', 'tif', 'png'/'png8', 'png24', 'emf', 'ps', 'pdf', 'ai', 'gif', and 'svg'/'svgz'.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ExportMapImage to generate an image of the map.The input parameter MapDescription contains properties describing the map (data frame). These include the map's Name, the map's MapArea,and SpatialReference, as well as collections of LayerDescription objects. Size, resolution and file format are determined by ImageDescription, which includes ImageDisplay and ImageType.

In order to control the size of an exported map image, the interface IMapServerInit contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 2048 pixels. This value can also be changed by modifying the XML tag in the MapServer's configuration file.

ExportMapImage returns a MapImage object.

Specified by:
exportMapImage in interface IMapServer
Parameters:
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
imageDesc - An reference to a com.esri.arcgis.carto.IImageDescription (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapImage
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

find

public IMapServerFindResults find(IMapDescription mapDesc,
                                  IImageDisplay mapImage,
                                  String searchString,
                                  boolean contains,
                                  String searchFields,
                                  int option,
                                  ILongArray layerIds)
                           throws IOException,
                                  AutomationException
Description copied from interface: IMapServer
Returns a collection of Map Server Find Result objects that contain the given search string. If LayerIDs is Nothing/Null or empty, all layers are searched.

Supported Platforms

Windows, Solaris, Linux

Remarks

Find performs a search based on a string value. This search can be conducted on a single field of a single layer, on many fields of a single layer or on many fields on many layers. 

Find requires a number of input parameters.  These include: a map description, an image display (this is needed to determine whether layers are visible or not based on the current map scale),  the search string, a Boolean value on whether the search string is an exact match (False) or not (True), a comma delimited list of string values for the names of the fields you want to search, the esriFindOption, and an array of layer Ids to be searched.

The esriFindOption parameter includes: esriFindAllLayers and esriFindVisibleLayers.  If esriFindAllLayers is being used all layers are valid. If esriFindVisibleLayers is used, the search will be conducted only on layers that are visible in the map display. Layer visibility depends on whether the layer is on or off (the Visible property on ILayerDescription) or whether the layer is on, but not visible due to scale dependencies (the MinScale and MaxScale properties on IMapLayerInfo). The mapImage parameter is needed to determine whether the layer is not visible based on scale dependencies. This parameter can be Nothing/Null if esriFindAllLayers is used.

The parameters esriFindOption and LayerIDs behave like a boolean AND. There is no precedence. For example: if esriFindOption is esriFindVisibleLayers and pLayerIDs is Nothing/Null or empty, all the visible layers are searched. If esriFindOption is esriFindVisibleLayers and pLayerIDs contains only the first layer, the first layer is searched only if it is visible.

If the searchFields parameter is blank all fields will be searched.

There are two key differences between Find and the IMapServer methods QueryFeatureCount, QueryFeatureIDs and QueryFeatureData. The first is that Find can work on multiple layers while the query methods work with a single layer. The second is that Find only works with a search string. The query methods use a queryFilter as a parameter. This allows the query to be based on either an attribute filter (SQL expression) or a spatial filter.

Find returns a collection of objects that implement IMapServerFindResult.

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount affects the following MapServer methods: Find, Identify, QueryFeatureData, and QueryHyperlinks.. It does not affect QueryFeatureCount or QueryFeatureIds. The MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

Specified by:
find in interface IMapServer
Parameters:
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapImage - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
searchString - The searchString (in)
contains - The contains (in)
searchFields - The searchFields (in)
option - A com.esri.arcgis.carto.esriFindOption constant (in)
layerIds - An reference to a com.esri.arcgis.system.ILongArray (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapServerFindResults
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

identify

public IMapServerIdentifyResults identify(IMapDescription mapDesc,
                                          IImageDisplay mapImage,
                                          IGeometry searchShape,
                                          int tolerance,
                                          int option,
                                          ILongArray layerIds)
                                   throws IOException,
                                          AutomationException
Description copied from interface: IMapServer
Returns a collection of Map Server Identify Result objects at the given location. If LayerIDs is Nothing/Null or empty, all layers are searched.

Supported Platforms

Windows, Solaris, Linux

Remarks

Identify returns map features and their attribute values based on a search location. This can be conducted on an individual layer, the top-most layer, all layers, or just on all the visible layers.

Identify requires a number of input parameters. These include: a map description, an image display (this is needed to determine whether layers are visible or not based on the current map scale), a search shape (usually a point), a tolerance, the esriIdentifyOption, and an array of layer Ids to be identified.

It is important to note that the geometry of the searchShape must have the same spatial reference as the map description.

The esriIdentifyOption parameter includes: esriIdentifyAllLayers, esriIdentifyVisibleLayers and esriIdentifyTopmost. If esriIdentifyAllLayers is being used all features for all layers in the map that fall within the tolerance value of the searchShape will be returned. If esriIdentifyVisibleLayers is used then only features from visible layers are returned. Layer visibility depends on whether the layer is on or off (the Visible property on ILayerDescription) or whether the layer is on, but not visible due to scale dependencies (the MinScale and MaxScale properties on IMapLayerInfo). The mapImage parameter is needed to determine whether the layer is not visible based on scale dependencies. The esriIdentifyOption esriIdentifyTopmost refers to the visible layer that is topmost in the map drawing order at the location specified by searchShape.

The parameters esriIdentifyOption and LayerIDs behave like a boolean AND. There is no precedence. For example: if esriIdentifyOption is esriIdentifyVisibleLayers and pLayerIDs is Nothing/Null or empty, all the visible layers are searched. If esriIdentifyOption is esriIdentifyVisibleLayers and pLayerIDs contains only the first layer, the first layer is searched only if it is visible.

If the layer being identified has a relationship to other tables, the IMapServerRelationship and IMapServerRow interfaces provide access to properties of the relationship and related tables.

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount affects the following MapServer methods: Find, Identify, QueryFeatureData, and QueryHyperlinks.. It does not affect QueryFeatureCount or QueryFeatureIds. The MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

This method returns a collection of objects that implement IMapServerIdentifyResult.

Specified by:
identify in interface IMapServer
Parameters:
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapImage - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
searchShape - An reference to a com.esri.arcgis.geometry.IGeometry (in)
tolerance - The tolerance (in)
option - A com.esri.arcgis.carto.esriIdentifyOption constant (in)
layerIds - An reference to a com.esri.arcgis.system.ILongArray (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapServerIdentifyResults
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

queryFeatureCount

public int queryFeatureCount(String mapName,
                             int layerID,
                             IQueryFilter filter)
                      throws IOException,
                             AutomationException
Description copied from interface: IMapServer
Returns the count of the features that meet the query filter selection criteria for the specified layer.

Supported Platforms

Windows, Solaris, Linux

Remarks

The query filter can be based on either an attribute filter (SQL expression) or a spatial filter.  The expression used in the filter parameter of either QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData methods on MapServer will override any filters set for the layer in the original map document (layer definition query) or set for the MapServer object layer in the DefinitionQuery property on LayerDescription.  In order to apply previous query filters to the new filter set by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData the original query expression will need to be appended to the new expression to form one compounded query expression.  This compound expression can then be used by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData.

Specified by:
queryFeatureCount in interface IMapServer
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
filter - An reference to a com.esri.arcgis.geodatabase.IQueryFilter (in)
Returns:
The count
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

queryFeatureIDs

public IFIDSet queryFeatureIDs(String mapName,
                               int layerID,
                               IQueryFilter filter)
                        throws IOException,
                               AutomationException
Description copied from interface: IMapServer
Returns the IDs of the features that meet the query filter selection criteria for the specified layer.

Supported Platforms

Windows, Solaris, Linux

Remarks

The query filter can be based on either an attribute filter (SQL expression) or a spatial filter.  The expression used in the filter parameter of either QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData methods on MapServer will override any filters set for the layer in the original map document (layer definition query) or set for the MapServer object layer in the DefinitionQuery property on LayerDescription .  In order to apply previous query filters to the new filter set by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData the original query expression will need to be appended to the new expression to form one compounded query expression.  This compound expression can then be used by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData.

Specified by:
queryFeatureIDs in interface IMapServer
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
filter - An reference to a com.esri.arcgis.geodatabase.IQueryFilter (in)
Returns:
An reference to a com.esri.arcgis.geodatabase.IFIDSet
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

queryFeatureData

public IRecordSet queryFeatureData(String mapName,
                                   int layerID,
                                   IQueryFilter filter)
                            throws IOException,
                                   AutomationException
Description copied from interface: IMapServer
Returns a record set of features that meet the query filter selection criteria for the specified layer.

Supported Platforms

Windows, Solaris, Linux

Remarks

The query filter can be based on either an attribute filter (SQL expression) or on a spatial filter. In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount affects the following IMapServer methods: Find, Identify, QueryFeatureData, and QueryHyperlinks. It does not affect QueryFeatureCount or QueryFeatureIDs. The MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

The expression used in the filter parameter of either QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData methods on MapServer will override any filters set for the layer in the original map document (layer definition query) or set for the MapServer object layer in the DefinitionQuery property on LayerDescription .  In order to apply previous query filters to the new filter set by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData the original query expression will need to be appended to the new expression to form one compounded query expression.  This compound expression can then be used by QueryFeatureCount, QueryFeatureIDs, or QueryFeatureData.

Specified by:
queryFeatureData in interface IMapServer
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
filter - An reference to a com.esri.arcgis.geodatabase.IQueryFilter (in)
Returns:
An reference to a com.esri.arcgis.geodatabase.IRecordSet
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

queryHyperlinks

public IMapServerHyperlinks queryHyperlinks(IMapDescription mapDesc,
                                            IImageDisplay mapImage,
                                            ILongArray layerIds)
                                     throws IOException,
                                            AutomationException
Description copied from interface: IMapServer
Returns a collection of Map Server Hyperlink objects for the specified layers. Only hyperlinks of visible layers are returned. If LayerIDs is Nothing/Null or empty, all layers are searched.

Supported Platforms

Windows, Solaris, Linux

Remarks

Layer visibility depends on whether the layer is on or off (the Visible property on ILayerDescription) or whether the layer is on, but not visible due to scale dependencies (the MinScale and MaxScale properties on IMapLayerInfo). The mapImage parameter is needed to determine whether the layer is not visible based on scale dependencies.

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount affects the following IMapServer methods: Find, Identify, QueryFeatureData, and QueryHyperlinks. It does not affect QueryFeatureCount or QueryFeatureIDs. The MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

This method returns a collection of objects that implement IMapServerHyperlink.

Specified by:
queryHyperlinks in interface IMapServer
Parameters:
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapImage - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
layerIds - An reference to a com.esri.arcgis.system.ILongArray (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapServerHyperlinks
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

computeScale

public double computeScale(IMapDescription mapDesc,
                           IImageDisplay mapDisplay)
                    throws IOException,
                           AutomationException
Description copied from interface: IMapServer
Computes the scale of the specified map, at the given map extent, for an image with the given size.

Supported Platforms

Windows, Solaris, Linux

Specified by:
computeScale in interface IMapServer
Parameters:
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
Returns:
The scale
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

computeDistance

public double computeDistance(String mapName,
                              IPoint fromPoint,
                              IPoint toPoint,
                              int units)
                       throws IOException,
                              AutomationException
Description copied from interface: IMapServer
Computes the distance between two points on the specified map. The result is in the map units of the specified map.

Supported Platforms

Windows, Solaris, Linux

Specified by:
computeDistance in interface IMapServer
Parameters:
mapName - The mapName (in)
fromPoint - An reference to a com.esri.arcgis.geometry.IPoint (in)
toPoint - An reference to a com.esri.arcgis.geometry.IPoint (in)
units - A com.esri.arcgis.system.esriUnits constant (in)
Returns:
The distance
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

toMapPoints

public IPointCollection toMapPoints(IMapDescription mapDescription,
                                    IImageDisplay mapDisplay,
                                    ILongArray screenXValues,
                                    ILongArray screenYValues)
                             throws IOException,
                                    AutomationException
Description copied from interface: IMapServer
Converts a screen location to a map coordinate.

Supported Platforms

Windows, Solaris, Linux

Specified by:
toMapPoints in interface IMapServer
Parameters:
mapDescription - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
screenXValues - An reference to a com.esri.arcgis.system.ILongArray (in)
screenYValues - An reference to a com.esri.arcgis.system.ILongArray (in)
Returns:
An reference to a com.esri.arcgis.geometry.IPointCollection
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

fromMapPoints

public void fromMapPoints(IMapDescription mapDescription,
                          IImageDisplay mapDisplay,
                          IPointCollection mapPoints,
                          ILongArray[] screenXValues,
                          ILongArray[] screenYValues)
                   throws IOException,
                          AutomationException
Description copied from interface: IMapServer
Converts a map coordinate to a screen location.

Supported Platforms

Windows, Solaris, Linux

Specified by:
fromMapPoints in interface IMapServer
Parameters:
mapDescription - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
mapPoints - An reference to a com.esri.arcgis.geometry.IPointCollection (in)
screenXValues - An reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)
screenYValues - An reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getLegendInfo

public IMapServerLegendInfos getLegendInfo(String mapName,
                                           ILongArray layerIds,
                                           IMapServerLegendPatch patch,
                                           IImageType imgType)
                                    throws IOException,
                                           AutomationException
Description copied from interface: IMapServer
Returns a collection of Map Server Legend Info objects for the specified layers. If layerIDs is Nothing/Null or empty, legend information for all layers is returned.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use GetLegendInfo to retrieve individual legend elements including the symbol image, labels, descriptions and headings. A common use would be to populate a table of contents. Note that composite layers such as group layers and annotation layers do not contain legend elements. To export a single image of the legend use ExportLegend on IMapServerLayout.

The GetLegendInfo method returns a collection of MapServerLegendInfo objects. Legends are associated with renderers that belong to each layer in a map. Each layer has a separate renderer. Each renderer has one or more legend groups.  Each legend group has one or more legend classes. Customizing the legend patch can be done using IMapServerLegendPatch . When passing in "Nothing" for this input parameter ("patch") the default legend patch is used.

MapServerLegendInfo doesn't contain information about whether the data frame and the layers in the TOC are expanded or collapsed in the original map document. You have to write your own code to find this out.

Specified by:
getLegendInfo in interface IMapServer
Parameters:
mapName - The mapName (in)
layerIds - An reference to a com.esri.arcgis.system.ILongArray (in)
patch - An reference to a com.esri.arcgis.carto.IMapServerLegendPatch (in)
imgType - An reference to a com.esri.arcgis.carto.IImageType (in)
Returns:
An reference to a com.esri.arcgis.carto.IMapServerLegendInfos
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getSQLSyntaxInfo

public ISQLSyntaxInfo getSQLSyntaxInfo(String mapName,
                                       int layerID)
                                throws IOException,
                                       AutomationException
Description copied from interface: IMapServer
Returns the SQL syntax information for the specified layer.

Supported Platforms

Windows, Solaris, Linux

Remarks

The members of the ISQLSyntaxInfo interface provide information regarding the SQL functionality for the DBMS underlying a map layer.

Specified by:
getSQLSyntaxInfo in interface IMapServer
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
Returns:
An reference to a com.esri.arcgis.carto.ISQLSyntaxInfo
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getSupportedImageReturnTypes

public int getSupportedImageReturnTypes()
                                 throws IOException,
                                        AutomationException
Description copied from interface: IMapServer
The supported image return types for the map server. A value of esriImageReturnMimeData means that only MIME data is supported. Otherwise, either MIME data or URLs are supported.

Specified by:
getSupportedImageReturnTypes in interface IMapServer
Returns:
A com.esri.arcgis.carto.esriImageReturnType constant
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

construct

public void construct(IPropertySet props)
               throws IOException,
                      AutomationException
Description copied from interface: IObjectConstruct
Two phase object construction

Supported Platforms

Windows, Solaris, Linux

Specified by:
construct in interface IObjectConstruct
Parameters:
props - An reference to a com.esri.arcgis.system.IPropertySet (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

handleBinaryRequest

public byte[] handleBinaryRequest(byte[] request)
                           throws IOException,
                                  AutomationException
Description copied from interface: IRequestHandler
Handles a binary request.

Supported Platforms

Windows, Solaris, Linux

Specified by:
handleBinaryRequest in interface IRequestHandler
Parameters:
request - An unsigned byte (in)
Returns:
An unsigned byte
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

handleStringRequest

public String handleStringRequest(String capabilities,
                                  String request)
                           throws IOException,
                                  AutomationException
Description copied from interface: IRequestHandler
Handles a SOAP string request.

Supported Platforms

Windows, Solaris, Linux

Specified by:
handleStringRequest in interface IRequestHandler
Parameters:
capabilities - The capabilities (in)
request - The request (in)
Returns:
The response
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getMap

public IMap getMap(String mapName)
            throws IOException,
                   AutomationException
Description copied from interface: IMapServerObjects
The map corresponding to the specified map name. Pass in a blank string for mapName to get the default map (active data frame).

Supported Platforms

Windows, Solaris, Linux

Remarks

Use Map to access the members of IMap.

Specified by:
getMap in interface IMapServerObjects
Parameters:
mapName - The mapName (in)
Returns:
An reference to a com.esri.arcgis.carto.IMap
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getLayer

public ILayer getLayer(String mapName,
                       int layerID)
                throws IOException,
                       AutomationException
Description copied from interface: IMapServerObjects
The layer specified by the map name and layer ID. If the mapName is blank, the default map (active data frame) will be assumed.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use Layer to access the members of ILayer.

Specified by:
getLayer in interface IMapServerObjects
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
Returns:
An reference to a com.esri.arcgis.carto.ILayer
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getPageLayout

public IPageLayout getPageLayout()
                          throws IOException,
                                 AutomationException
Description copied from interface: IMapServerObjects
The page layout object for the current map document.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use PageLayout to access the members of IPageLayout.

Specified by:
getPageLayout in interface IMapServerObjects
Returns:
An reference to a com.esri.arcgis.carto.IPageLayout
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getThumbnail

public Picture getThumbnail()
                     throws IOException,
                            AutomationException
Description copied from interface: IMapServerObjects
The thumbnail stored in the map document.

Supported Platforms

Windows, Solaris, Linux

Remarks

You cannot access the Thumbnail though DCOM.

Specified by:
getThumbnail in interface IMapServerObjects
Returns:
An reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

refreshServerObjects

public void refreshServerObjects()
                          throws IOException,
                                 AutomationException
Description copied from interface: IMapServerObjects
Updates the server info based on the current state of the underlying fine-grained objects.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use RefreshServerObjects when you have made changes to the fine-grained ArcObjects and want to apply them to the MapServer object. Keep in mind that this will change the default state of the MapServer object. In order to get the updated MapDescription, you have to call GetServerInfo on IMapServer again.

Any custom graphics (IMapDescription or IPageDescription) set previous to the RefreshServerObjects call will be lost. You will need to repeat the code for the custom graphics.

RefreshServerObjects does not refresh the extent on IPageDescription . Therefore, if you have zoomed to a particular extent of the page layout using the fine-grained ArcObjects (IActiveView) and you want to apply this extent to the PageDescription, you have to do this manually.

Specified by:
refreshServerObjects in interface IMapServerObjects
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

applyMapDescription

public void applyMapDescription(IMapDescription mapDescription,
                                IImageDisplay mapDisplay)
                         throws IOException,
                                AutomationException
Description copied from interface: IMapServerObjects
Applies the current state of the map description to the map server object.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ApplyMapDescription to apply changes made in IMapDescription to the map server object. ApplyMapDescription will not apply any custom graphics (IMapDescription or IPageDescription) to the map server object. See the following example on how to apply custom graphics to the map server object.

Specified by:
applyMapDescription in interface IMapServerObjects
Parameters:
mapDescription - An reference to a com.esri.arcgis.carto.IMapDescription (in)
mapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getFeatureValue

public String getFeatureValue(String mapName,
                              int layerID,
                              IFeature feature,
                              String fieldName)
                       throws IOException,
                              AutomationException
Description copied from interface: IMapServerData
Returns the value of a given feature as a string.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getFeatureValue in interface IMapServerData
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
feature - An reference to a com.esri.arcgis.geodatabase.IFeature (in)
fieldName - The fieldName (in)
Returns:
The fieldValue
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getFeature

public IFeature getFeature(String mapName,
                           int layerID,
                           int featureId)
                    throws IOException,
                           AutomationException
Description copied from interface: IMapServerData
Returns a feature, given the feature ID and layer.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getFeature in interface IMapServerData
Parameters:
mapName - The mapName (in)
layerID - The layerID (in)
featureId - The featureId (in)
Returns:
An reference to a com.esri.arcgis.geodatabase.IFeature
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getDefaultPageDescription

public IPageDescription getDefaultPageDescription()
                                           throws IOException,
                                                  AutomationException
Description copied from interface: IMapServerLayout
The default page settings.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getDefaultPageDescription in interface IMapServerLayout
Returns:
An reference to a com.esri.arcgis.carto.IPageDescription
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

exportLayout

public ILayoutImage exportLayout(IPageDescription pageDesc,
                                 IImageDescription imageDesc)
                          throws IOException,
                                 AutomationException
Description copied from interface: IMapServerLayout
Generates an image of the layout, based on the given page description object, and writes the image to a specified file on disk. Supported file types are: 'bmp', 'jpg', 'tif', 'png'/'png8', 'png24', 'emf', 'ps', 'pdf', 'ai', 'gif', and 'svg'/'svgz'.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ExportLayout to retrieve an image of the map's layout.

PageDescription refers to properties describing the actual map layout. These include the height and width of the layout in page units, the layout page extent in page units, map descriptions for each map frame in the layout and any CustomGraphics to be placed in the layout. Size, resolution and file format are determined by the ImageDescription, which includes ImageDisplay and ImageType.

ExportLayout returns a LayoutImage object. The page extent of the layout, an array of map images (data frames), can be gleaned from this object. In addition, the geographic extent, map scale and an array of visible layers for each data frame in the layout can be retrieved from the MapImage object.

Do not use IMapServerLayout to create new layouts or to create layouts "on-the-fly". You cannot change the actual page size of the map layout, reposition map elements on the layout nor can you add or remove layout elements such as titles, text, graphics, scale bars, north arrows and legends.

Let's look at an example. An existing map layout has a portrait page orientation with a height of 11 inches and a width of 8.5 inches. The absolute scale for the map is 1:30,000,000. This scale is based on the page size of the layout and the relative size of the map's data frame.

To export this layout at the size set in the ArcMap document enter a value of 0 for the height or width properties of IImageDisplay. ImageDisplay is part of the ImageDescription parameter needed to ExportLayout. In this example exporting to a raster format at 96 dpi would result in an image 1056 by 816 pixels.

Though the size of ExportLayout results can be adjusted using the height and width properties of IImageDisplay it is important to keep in mind the limitations of doing so. For example, you wish to reduce the image of the 11 by 8.5 layout described above by half.  You specify a height of 528 and a width of 408 for the image result. Please note that the map scale does not change. Remember, it is the output size that is being adjusted, not the actual layout. Therefore, the aboslute scale of the map will be incorrect, though the scale bar should be correct since its size changes relative to the change in output size. This effect is similar to shrinking or enlarging a printed map using a photocopying machine.

Changing the aspect ratio (height x width) of the ExportLayout output will not change the aspect ratio of the map layout. For example, again using the layout example above, a height of 816 and a width of 1056 pixels are specified. This will not change the orientation of the page layout from portrait to landscape. Instead, the original portrait orientation of the layout will be maintained and will be fitted into the 816 x 1056 space. This will result in white space on either side of the layout.

In order to control the size of an exported image, IMapServerInit contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 1024 pixels.

Another important thing to consider when exporting layouts using IMapServerLayout is to uncheck the "Use Printer Paper Settings" checkbox on the Page and Print Setup dialog in ArcMap. Otherwise, the page setup may be dependent on a printer unavailable to the server or users. This may result in a rescaling of the map and unexpected results.

Specified by:
exportLayout in interface IMapServerLayout
Parameters:
pageDesc - An reference to a com.esri.arcgis.carto.IPageDescription (in)
imageDesc - An reference to a com.esri.arcgis.carto.IImageDescription (in)
Returns:
An reference to a com.esri.arcgis.carto.ILayoutImage
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

exportLegend

public IImageResult exportLegend(ILegend legend,
                                 IMapDescription mapDesc,
                                 IImageDisplay pMapDisplay,
                                 IColor backgroundColor,
                                 IImageDescription imageDesc)
                          throws IOException,
                                 AutomationException
Description copied from interface: IMapServerLayout
Exports a legend to an image file. The client can create the legend object and set its desired properties appropriately. If legend is Nothing/Null, a default legend will be generated.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ExportLegend to export a single image representing the map's legend. Use the input parameter ILegend to access the Legend object in order to customize the legend. If the MapDescription parameter is Nothing/Null the default map description is used. Size, resolution and file format are determined by the ImageDescription object, which includes ImageDisplay and ImageType. ExportLegend results in an ImageResult object.

An ExportLegend result displays all visible layers in the map (default). 

The default size of a legend is based on the number of layers, symbol size and length of label or description text. This size is likely to vary from map to map.

To best manage the size of the ExportLegend request keep either the width or the height set in ImageDisplay constant. This ImageDisplay object is part of the imageDesc parameter. Don't confuse this ImageDisplay object with the one that refers to the map (pMapDisplay). 

For example, set the ImageDisplay width at 150 and set the height at 0. A setting of 0 will calculate a default value for best fit. The actual height value will adjust as the legend changes to accommodate changes in layer visibility.

Make sure to provide an adequate size to the legend. Otherwise, parts of the legend may be cut off or the legend may be illegible. You may need to experiment to find an adequate size. Remember, setting 0 for both the height and width will result in a default size for the legend. This might be a good place to start.

To manage more control over the legend of a MapServer map use the ILegend input parameter or use GetLegendInfo on IMapServer.

Specified by:
exportLegend in interface IMapServerLayout
Parameters:
legend - An reference to a com.esri.arcgis.carto.ILegend (in)
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
pMapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
backgroundColor - An reference to a com.esri.arcgis.display.IColor (in)
imageDesc - An reference to a com.esri.arcgis.carto.IImageDescription (in)
Returns:
An reference to a com.esri.arcgis.carto.IImageResult
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

exportScaleBar

public IImageResult exportScaleBar(IScaleBar scalebar,
                                   IMapDescription mapDesc,
                                   IImageDisplay pMapDisplay,
                                   IColor backgroundColor,
                                   IImageDescription imageDesc)
                            throws IOException,
                                   AutomationException
Description copied from interface: IMapServerLayout
Exports a scale bar to an image file. The client can create the scaleBar object and set its desired properties appropriately. If scaleBar is Nothing/Null, a default scale bar will be generated.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ExportScaleBar to retrieve the map's scale bar. To customize the scale bar pass in a ScaleBar object. If you pass in Nothing/Null for the input paramter ScaleBar, a default alternating scale bar is drawn. The scale is calculated according to the height and width of the the image (pMapDisplay). This ImageDisplay object refers to the map. Another ImageDisplay object will be used (as part of the imageDesc parameter) that refers to the Scale Bar image. A color background can be set for the ScaleBar swatch by using the backgroundColor parameter. If this is Nothing/Null a white background will be used. Size, resolution and file format are determined by ImageDescription, which includes ImageDisplay and ImageType. ExportScaleBar returns an ImageResult object.

Use the height and width properties of IImageDisplay (as part of the imageDesc parameter) to set the proper size of the scalebar. Entering a 0 for either the height or the width for ExportScaleBar output results in an error.


 

Specified by:
exportScaleBar in interface IMapServerLayout
Parameters:
scalebar - An reference to a com.esri.arcgis.carto.IScaleBar (in)
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
pMapDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
backgroundColor - An reference to a com.esri.arcgis.display.IColor (in)
imageDesc - An reference to a com.esri.arcgis.carto.IImageDescription (in)
Returns:
An reference to a com.esri.arcgis.carto.IImageResult
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

exportNorthArrow

public IImageResult exportNorthArrow(INorthArrow arrow,
                                     IMapDescription mapDesc,
                                     IColor backgroundColor,
                                     IImageDescription imageDesc)
                              throws IOException,
                                     AutomationException
Description copied from interface: IMapServerLayout
Exports a north arrow to an image file. The client can create the arrow object and set its desired properties appropriately. If arrow is Nothing/Null, a default north arrow will be generated.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ExportNorthArrow to export the map's north arrow. To customize the north arrow (e.g. size) or to change the type of north arrow marker pass in a NorthArrow object. If you pass in Nothing/Null for this input parameter, a standard north arrow is drawn. A color background can be set for the North Arrow swatch by using the backgroundColor parameter. If this is Nothing/Null a white background will be used. Size, resolution and file format are determined by ImageDescription, which includes ImageDisplay and ImageType. ExportNorthArrow results in an ImageResult object.

The orientation of the NorthArrow is determined by the MapRotation property on IMapDescription.

ExportNorthArrow output does not require a size. A default size is calculated based on the size of the NorthArrowMarker symbol. Setting 0 for both the height and the width property of IImageDisplay for ExportNorthArrow output results in a default size that best fits the NorthArrowMarker symbol.

Specified by:
exportNorthArrow in interface IMapServerLayout
Parameters:
arrow - An reference to a com.esri.arcgis.carto.INorthArrow (in)
mapDesc - An reference to a com.esri.arcgis.carto.IMapDescription (in)
backgroundColor - An reference to a com.esri.arcgis.display.IColor (in)
imageDesc - An reference to a com.esri.arcgis.carto.IImageDescription (in)
Returns:
An reference to a com.esri.arcgis.carto.IImageResult
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

toPagePoints

public IPointCollection toPagePoints(IEnvelope pageExtent,
                                     IImageDisplay pageDisplay,
                                     ILongArray screenXValues,
                                     ILongArray screenYValues)
                              throws IOException,
                                     AutomationException
Description copied from interface: IMapServerLayout
Converts a screen location to a page coordinate.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use ToPagePoints to convert pixel coordinates on the screen to page units coordinates on the layout.

Specified by:
toPagePoints in interface IMapServerLayout
Parameters:
pageExtent - An reference to a com.esri.arcgis.geometry.IEnvelope (in)
pageDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
screenXValues - An reference to a com.esri.arcgis.system.ILongArray (in)
screenYValues - An reference to a com.esri.arcgis.system.ILongArray (in)
Returns:
An reference to a com.esri.arcgis.geometry.IPointCollection
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

fromPagePoints

public void fromPagePoints(IEnvelope pageExtent,
                           IImageDisplay pageDisplay,
                           IPointCollection pagePoints,
                           ILongArray[] screenXValues,
                           ILongArray[] screenYValues)
                    throws IOException,
                           AutomationException
Description copied from interface: IMapServerLayout
Converts a page coordinate to a screen location.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use FromPagePoints to convert page unit coordinates on the layout to pixel coordinates on the screen.

Specified by:
fromPagePoints in interface IMapServerLayout
Parameters:
pageExtent - An reference to a com.esri.arcgis.geometry.IEnvelope (in)
pageDisplay - An reference to a com.esri.arcgis.carto.IImageDisplay (in)
pagePoints - An reference to a com.esri.arcgis.geometry.IPointCollection (in)
screenXValues - An reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)
screenYValues - An reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

connect

public void connect(String filePath)
             throws IOException,
                    AutomationException
Description copied from interface: IMapServerInit
Initializes the map server with an mxd or pmf file stored at the specified path. The path must be accessible to the server machine.

Supported Platforms

Windows, Solaris, Linux

Specified by:
connect in interface IMapServerInit
Parameters:
filePath - The filePath (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

startWithData

public void startWithData(IDataset pDataset)
                   throws IOException,
                          AutomationException
Description copied from interface: IMapServerInit
An alternative to calling Connect(). This method synthesizes a map document with a single layer based on the given IDataset object and initializes the map server for processing.

Supported Platforms

Windows, Solaris, Linux

Specified by:
startWithData in interface IMapServerInit
Parameters:
pDataset - An reference to a com.esri.arcgis.geodatabase.IDataset (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

stop

public void stop()
          throws IOException,
                 AutomationException
Description copied from interface: IMapServerInit
Clears out all of the map objects in memory. The client must call one of the Start methods again before attempting any other operations.

Supported Platforms

Windows, Solaris, Linux

Specified by:
stop in interface IMapServerInit
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

setPhysicalOutputDirectory

public void setPhysicalOutputDirectory(String dirPath)
                                throws IOException,
                                       AutomationException
Description copied from interface: IMapServerInit
The physical directory for output files.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setPhysicalOutputDirectory in interface IMapServerInit
Parameters:
dirPath - The dirPath (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getPhysicalOutputDirectory

public String getPhysicalOutputDirectory()
                                  throws IOException,
                                         AutomationException
Description copied from interface: IMapServerInit
The physical directory for output files.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getPhysicalOutputDirectory in interface IMapServerInit
Returns:
The dirPath
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

setVirtualOutputDirectory

public void setVirtualOutputDirectory(String dirPath)
                               throws IOException,
                                      AutomationException
Description copied from interface: IMapServerInit
The virtual directory for output files.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setVirtualOutputDirectory in interface IMapServerInit
Parameters:
dirPath - The dirPath (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getVirtualOutputDirectory

public String getVirtualOutputDirectory()
                                 throws IOException,
                                        AutomationException
Description copied from interface: IMapServerInit
The virtual directory for output files.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getVirtualOutputDirectory in interface IMapServerInit
Returns:
The dirPath
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getFilePath

public String getFilePath()
                   throws IOException,
                          AutomationException
Description copied from interface: IMapServerInit
The map document path.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getFilePath in interface IMapServerInit
Returns:
The filePath
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getMaxRecordCount

public int getMaxRecordCount()
                      throws IOException,
                             AutomationException
Description copied from interface: IMapServerInit
The maximum number of records returned for query results (Identify, Find, QueryFeatureData, and QueryHyperlinks).

Supported Platforms

Windows, Solaris, Linux

Remarks

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount affects the following IMapServer methods: Find, Identify, QueryFeatureData, and QueryHyperlinks. It does not affect QueryFeatureCount or QueryFeatureIDs. The MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

Specified by:
getMaxRecordCount in interface IMapServerInit
Returns:
The count
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

setMaxRecordCount

public void setMaxRecordCount(int count)
                       throws IOException,
                              AutomationException
Description copied from interface: IMapServerInit
The maximum number of records returned for query results (Identify, Find, QueryFeatureData, and QueryHyperlinks).

Specified by:
setMaxRecordCount in interface IMapServerInit
Parameters:
count - The count (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getMaxBufferCount

public int getMaxBufferCount()
                      throws IOException,
                             AutomationException
Description copied from interface: IMapServerInit
The maximum number of records buffered on the server for display.

Supported Platforms

Windows, Solaris, Linux

Remarks

In order to control the amount of information MapServer needs to process for a buffer, a maximum number of records to be buffered can be set. This value is contained in the MaxBufferCount property. The default value for this property is 100. If the number of features to be buffered exceeds MaxBufferCount no features will be buffered. The MaxBufferCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

Specified by:
getMaxBufferCount in interface IMapServerInit
Returns:
The count
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

setMaxBufferCount

public void setMaxBufferCount(int count)
                       throws IOException,
                              AutomationException
Description copied from interface: IMapServerInit
The maximum number of records buffered on the server for display.

Specified by:
setMaxBufferCount in interface IMapServerInit
Parameters:
count - The count (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getMaxImageWidth

public int getMaxImageWidth()
                     throws IOException,
                            AutomationException
Description copied from interface: IMapServerInit
The maximum width in pixels of an image request.

Supported Platforms

Windows, Solaris, Linux

Remarks

In order to control the size of an exported map image, IMapServerInit contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 2048 pixels. The MaxImageHeight can also be changed by modifying the MaxImageHeight XML tag in the MapServer's configuration file.

Specified by:
getMaxImageWidth in interface IMapServerInit
Returns:
The width
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

setMaxImageWidth

public void setMaxImageWidth(int width)
                      throws IOException,
                             AutomationException
Description copied from interface: IMapServerInit
The maximum width in pixels of an image request.

Specified by:
setMaxImageWidth in interface IMapServerInit
Parameters:
width - The width (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

getMaxImageHeight

public int getMaxImageHeight()
                      throws IOException,
                             AutomationException
Description copied from interface: IMapServerInit
The maximum height in pixels of an image request.

Supported Platforms

Windows, Solaris, Linux

Remarks

In order to control the size of an exported map image, IMapServerInit contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 2048 pixels. The MaxImageHeight can also be changed by modifying the MaxImageHeight XML tag in the MapServer's configuration file.

Specified by:
getMaxImageHeight in interface IMapServerInit
Returns:
The height
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

setMaxImageHeight

public void setMaxImageHeight(int height)
                       throws IOException,
                              AutomationException
Description copied from interface: IMapServerInit
The maximum height in pixels of an image request.

Specified by:
setMaxImageHeight in interface IMapServerInit
Parameters:
height - The height (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

activate

public void activate()
              throws IOException,
                     AutomationException
Description copied from interface: IObjectActivate
Activates the object.

Supported Platforms

Windows, Solaris, Linux

Specified by:
activate in interface IObjectActivate
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

deactivate

public void deactivate()
                throws IOException,
                       AutomationException
Description copied from interface: IObjectActivate
Deactivates the object.

Supported Platforms

Windows, Solaris, Linux

Specified by:
deactivate in interface IObjectActivate
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

initLogging

public void initLogging(ILog log)
                 throws IOException,
                        AutomationException
Description copied from interface: ILogSupport
Initializes an object with a log.

Supported Platforms

Windows, Solaris, Linux

Specified by:
initLogging in interface ILogSupport
Parameters:
log - An reference to a com.esri.arcgis.system.ILog (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException
Description copied from interface: ISupportErrorInfo

Supported Platforms

Windows, Solaris, Linux

Description

Indicates whether the interface supports IErrorInfo.

Specified by:
interfaceSupportsErrorInfo in interface ISupportErrorInfo
Parameters:
riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.