com.esri.arcgis.carto
Interface ILayerDescription

All Superinterfaces:
Serializable
All Known Subinterfaces:
ILayerDescription2, ILayerDescription3
All Known Implementing Classes:
LayerDescription

public interface ILayerDescription
extends Serializable

Provides access to the available properties of a layer description object.

Superseded By

ILayerDescription3

Remarks

Please note the difference of use between IMapLayerInfo and ILayerDescription: Use ILayerDescription to access layer settings that can be changed on the server object without changing the state of the underlying fine-grained ArcObjects that the layer is based on. MapLayerInfo is used to retrieve information about a layer that can only be changed by directly accessing the map document or the fine-grained ArcObjects it is based on.

In some cases you may want limit or adjust the geometry being returned in the find result. This can be done for performance reasons. Use ILayerResultOptions to manage this. If IncludeGeometry is set to False, FeatureShape returns nothing. This should increase performance in cases where feature geometry is large. You can also choose to densify or generalize the geometry returned in FeatureShape using GeometryResultOptions. Densification is used to better support clients that do not support Arcs (e.g. Bezier, Circular etc.). Generalization reduces the amount of geography being sent across the network and should lead to better performance. If LayerResultOptions are not specified for the LayerDescription, query results will include the original geometry.

Layer settings of the Server object can be permanently changed by accessing fine-grained ArcObjects. This is accomplished using IMapServerObjects. This should be done with objects in a non-pooled environment. Changing the state of pooled objects this way will lead to unexpected results. Changes made using IMapServerObjects reside in memory only. They affect only the instance of the map service being accessed. They do not change anything in the original map document (.mxd) saved on disk. These changes exist until the service is restarted or recycled.

When To Use

Use the ILayerDescription interface to access read and write properties of a layer.

Product Availability

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


Method Summary
 String getDefinitionExpression()
          The definition expression for the layer.
 int getID()
          The layer ID.
 double getSelectionBufferDistance()
          The selection buffer distance.
 IColor getSelectionColor()
          The selection color (used when SetSelectionSymbol = FALSE).
 IFIDSet getSelectionFeatures()
          Array of selected features.
 ISymbol getSelectionSymbol()
          The selection symbol.
 boolean isScaleSymbols()
          Indicates whether the layer should scale its symbols according to the reference scale.
 boolean isSetSelectionSymbol()
          Indicates if the selected set of features is drawn using the SelectionSymbol.
 boolean isShowLabels()
          Indicates whether the layer should display its dynamic labels.
 boolean isShowSelectionBuffer()
          Indicates whether the selection buffer should be displayed.
 boolean isVisible()
          Indicates whether the layer is visible as defined in the TOC (i.e.
 void setDefinitionExpression(String expression)
          The definition expression for the layer.
 void setID(int layerID)
          The layer ID.
 void setScaleSymbols(boolean scale)
          Indicates whether the layer should scale its symbols according to the reference scale.
 void setSelectionBufferDistance(double distance)
          The selection buffer distance.
 void setSelectionColorByRef(IColor color)
          The selection color (used when SetSelectionSymbol = FALSE).
 void setSelectionFeatures(IFIDSet featureIDs)
          Array of selected features.
 void setSelectionSymbolByRef(ISymbol symbol)
          The selection symbol.
 void setSetSelectionSymbol(boolean setSymbol)
          Indicates if the selected set of features is drawn using the SelectionSymbol.
 void setShowLabels(boolean show)
          Indicates whether the layer should display its dynamic labels.
 void setShowSelectionBuffer(boolean show)
          Indicates whether the selection buffer should be displayed.
 void setVisible(boolean visible)
          Indicates whether the layer is visible as defined in the TOC (i.e.
 

Method Detail

getID

int getID()
          throws IOException,
                 AutomationException
The layer ID. This is a unique ID for the layer, and is used to identify the layer in a number of method calls.

Remarks

ID is a unique identifier for a layer in a given instance of ArcGIS Server map service. It is important to note that ID, SourceID and the index of layers (see MapLayerInfos) in map document are not the same. SourceID is used for map service interaction with the GPServer.

When a map service is published, a unique ID is assigned to all layers within the original map document (.mxd) starting from 0 (zero). This ID is accessible from IMapServerObjects2, MapLayerInfo, LayerDescription, MapServerLegendInfo, MapServerIdentifyResult, MapServerFindResult and FeatureExtent.

ID is not re-usable and does not change if the order of the layer is changed. This would change the how each layer is ordered in the index of layers. Adding new a layer results in a new ID being assigned. IDs keep incrementing as new layers are added to the map service. The limit of id numbers available is the limit of Long data type.

Please note that if the layer order in the TOC of the original map is changed or if layers are added/removed, the IDs will change accordingly.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The layerID
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setID

void setID(int layerID)
           throws IOException,
                  AutomationException
The layer ID. This is a unique ID for the layer, and is used to identify the layer in a number of method calls.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
layerID - The layerID (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isVisible

boolean isVisible()
                  throws IOException,
                         AutomationException
Indicates whether the layer is visible as defined in the TOC (i.e. marked on).

Remarks

This property only reflects the layer's on/off state in the TOC. A layer's visibility property may be TRUE and the layer may still not be visible on the map. This occurs when a layer is marked "on" but is not drawn in the map display because its display is dependent on the scale of the map.

Use VisibleLayers on IMapImage to retrieve an array of layers that are both "on" in the TOC and visible in the map display.

You can also use MinScale and MaxScale on IMapLayerInfo2 to see if the layer has any scale dependencies and then use MapScale on IMapImage or ComputeScale on IMapServer2 to determine the map scale. If the map scale falls outside the specified scale range set for the layer, the layer will not display.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The visible
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setVisible

void setVisible(boolean visible)
                throws IOException,
                       AutomationException
Indicates whether the layer is visible as defined in the TOC (i.e. marked on).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
visible - The visible (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isScaleSymbols

boolean isScaleSymbols()
                       throws IOException,
                              AutomationException
Indicates whether the layer should scale its symbols according to the reference scale.

Remarks

In order for symbols to scale, the map must have a reference scale set and the layer must support symbol scaling. Use ScaleSymbols to activate or deactivate a layer's symbol scaling. If a map does not have a set reference scale setting, ScaleSymbols will have no effect. Use CanScaleSymbols on IMapLayerInfo2 to verify if a layer supports symbol scaling. A reference scale is set within the original map document.

You can set a new reference scale for the MapServer object by accessing the IMap interface through IMapServerObjects2. This should be done with objects in a non-pooled environment. Changing the state of pooled objects this way will lead to unexpected results.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The scale
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setScaleSymbols

void setScaleSymbols(boolean scale)
                     throws IOException,
                            AutomationException
Indicates whether the layer should scale its symbols according to the reference scale.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
scale - The scale (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowLabels

boolean isShowLabels()
                     throws IOException,
                            AutomationException
Indicates whether the layer should display its dynamic labels.

Remarks

This only applies to layers where the property HasLabels on IMapLayerInfo2 is TRUE. This means that the layer's labels must be "on" in the original map document.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The show
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setShowLabels

void setShowLabels(boolean show)
                   throws IOException,
                          AutomationException
Indicates whether the layer should display its dynamic labels.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
show - The show (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelectionFeatures

IFIDSet getSelectionFeatures()
                             throws IOException,
                                    AutomationException
Array of selected features.

Remarks

If you want to clear the selection, set SelectionFeatures to Null/Nothing. If you forget to do this, the previous selection will be added to the current selection.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geodatabase.IFIDSet
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSelectionFeatures

void setSelectionFeatures(IFIDSet featureIDs)
                          throws IOException,
                                 AutomationException
Array of selected features.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
featureIDs - A reference to a com.esri.arcgis.geodatabase.IFIDSet (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelectionColor

IColor getSelectionColor()
                         throws IOException,
                                AutomationException
The selection color (used when SetSelectionSymbol = FALSE).

Description

The color with which selected features for this particular layer are drawn.

Remarks

This property should be used when you want to apply a different selection color for an individual layer. If you wish to change the selection color for all layers you should use SelectionColor on IMapDescription2. If you wish to change the symbology of selected features you need to use SetSelectionSymbol and SelectionSymbol on the LayerDescription.


SelectionColor on ILayerDescription overrides SelectionColor on IMapDescription. If SetSelectionSymbol is set to TRUE, SelectionColor will not be applied. Instead, the selection color of the symbol you specify (SelectionSymbol) will be used.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.display.IColor
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSelectionColorByRef

void setSelectionColorByRef(IColor color)
                            throws IOException,
                                   AutomationException
The selection color (used when SetSelectionSymbol = FALSE).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
color - A reference to a com.esri.arcgis.display.IColor (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelectionSymbol

ISymbol getSelectionSymbol()
                           throws IOException,
                                  AutomationException
The selection symbol.

Remarks

Use this property when you want something other than the default symbology to indicate selected features. For example, you want to use a star symbol to indicate selected point features. SelectionSymbol is only applied if SetSelectionSymbol is set to TRUE. Otherwise, default symbols are used.

Only ISimpleMarkerSymbol, ICharacterMarkerSymbol, IPictureMarkerSymbol, ISimpleLineSymbol and ISimpleFillSymbol, IPictureFillSymbol are supported when accessing a MapServer object through AGSServerConnection (LAN or internet).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.display.ISymbol
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSelectionSymbolByRef

void setSelectionSymbolByRef(ISymbol symbol)
                             throws IOException,
                                    AutomationException
The selection symbol.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
symbol - A reference to a com.esri.arcgis.display.ISymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isSetSelectionSymbol

boolean isSetSelectionSymbol()
                             throws IOException,
                                    AutomationException
Indicates if the selected set of features is drawn using the SelectionSymbol.

Remarks

This property should be set to TRUE if you wish to use something other than the default selection symbology. For example, you want to use a star symbol to indicate selected point features. If SetSelectionSymbol is set to TRUE, SelectionColor will not be applied. You will need to set the selection color as part of the properties of the new selection symbol object.

Only ISimpleMarkerSymbol, ICharacterMarkerSymbol, IPictureMarkerSymbol, ISimpleLineSymbol and ISimpleFillSymbol, IPictureFillSymbol are supported when accessing a MapServer object through AGSServerConnection (LAN or internet).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The setSymbol
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSetSelectionSymbol

void setSetSelectionSymbol(boolean setSymbol)
                           throws IOException,
                                  AutomationException
Indicates if the selected set of features is drawn using the SelectionSymbol.

Product Availability

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

Parameters:
setSymbol - The setSymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelectionBufferDistance

double getSelectionBufferDistance()
                                  throws IOException,
                                         AutomationException
The selection buffer distance. When drawing, and if a selection filter is specified, a buffer zone of the specified distance will be displayed around the selected features.

Remarks

The selection buffer is based on Euclidian distance. The accuracy of the buffer is dependent on the spatial reference used in the map. An inappropriate spatial reference will result in inaccurate buffer distances. For best results, the map should be in an appropriate spatial reference.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The distance
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSelectionBufferDistance

void setSelectionBufferDistance(double distance)
                                throws IOException,
                                       AutomationException
The selection buffer distance. When drawing, and if a selection filter is specified, a buffer zone of the specified distance will be displayed around the selected features.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
distance - The distance (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowSelectionBuffer

boolean isShowSelectionBuffer()
                              throws IOException,
                                     AutomationException
Indicates whether the selection buffer should be displayed.

Remarks

The selection buffer is based on Euclidian distance. The accuracy of the buffer is dependent on the spatial reference used in the map. An inappropriate spatial reference will result in inaccurate buffer distances. For best results, the map should be in an appropriate spatial reference.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The show
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setShowSelectionBuffer

void setShowSelectionBuffer(boolean show)
                            throws IOException,
                                   AutomationException
Indicates whether the selection buffer should be displayed.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
show - The show (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDefinitionExpression

String getDefinitionExpression()
                               throws IOException,
                                      AutomationException
The definition expression for the layer.

Remarks

A DefinitionExpression can be set on a layer in order to limit layer features available for display or query. This expression can be also be set in the source map document as a definition query. An expression set in the LayerDescription will override one set for the layer in the source map. This only applies for the session state and does not replace the definition query set in the source map.

Let's look at some examples. You have a layer in your map that represents sales regions. The layer includes fields: REGIONS, SALES and MANAGER.

Example #1: In the source map the layer has a definition query, "REGION = North". No DefintionExpression is specified in LayerDescription. Only those features where REGION = North will be displayed in your map.

Example #2: In the source map the layer has a definition query, "REGION = ‘North’". You apply a DefinitionExpression in LayerDescription as "SALES > 1000". The LayerDescription DefinitionExpression overrides the definition query set in the source map. Only those features where SALES > 1000 will be displayed in your map.

If you wish to use the DefinitionExpression as a way of getting a subset of the features already filtered by the definition query in the map you will need to save the original expression and then add it to the new expression to form one compound expression, “REGION = ‘North’ AND SALES > 1000”. This will display map features that are belong to the North region and have sales over 1000.

Example #3: In the source map the layer has no definition query. You apply a DefinitionExpression in LayerDescription as "SALES > 1000". Only those features where SALES > 1000 will be displayed in your map.

The following MapServer methods will honor DefinitionExpression: Find, Identify, QueryFeatureCount2, QueryFeatureIds2, QueryFeatureData2 and QueryHyperlinks2.

Although the DefinitionExpression set in the LayerDescription will override any any definition query set in the source map, there are MapServer methods that only honor the expression set in the source document. Any expression set in DefinitionExpression in the LayerDescription will be ignored. These mothods include: QueryFeatureCount, QueryFeatureIds, and QueryFeatureData. MapDescription, which contains the LayerDescriptions, are not a parameter for these methods.

DefinitionExpression does not affect spatial extents.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The expression
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setDefinitionExpression

void setDefinitionExpression(String expression)
                             throws IOException,
                                    AutomationException
The definition expression for the layer.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
expression - The expression (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.