ITopology Interface

Provides access to members that control a topology.

When To Use

The ITopolgy interface is used to access the members of an existing topology. The interface also allows adding or removing objects, features, and attributed relationship classes to the topology and validating it.

Members

	Name	Description
	AddClass	Add an object, feature, or attributed relationship class to the topology.
	Cache	The topology graph of the topology.
	ClusterTolerance	The cluster tolerance of the topology.
	DirtyArea	The dirty area polygon of the topology.
	FeatureDataset	The feature dataset that contains the topology.
	MaximumGeneratedErrorCount	The maximum number of errors to generate when validating a topology.
	RemoveClass	Remove an object, feature, or attributed relationship class to the topology.
	State	Indicates whether the topology is clean or not.
	TopologyID	The ID of the topology.
	ValidateTopology	Validate the specified area in the topology.
	ZClusterTolerance	The z cluster tolerance of the topology.

ITopology.AddClass Method

Add an object, feature, or attributed relationship class to the topology.

Public Sub AddClass ( _
    ByVal classToAdd As IClass, _
    ByVal Weight As Double, _
    ByVal XYRank As Integer, _
    ByVal ZRank As Integer, _
    ByVal EventNotificationOnValidate As Boolean _
)

public void AddClass (
    IClass classToAdd,
    double Weight,
    int XYRank,
    int ZRank,
    bool EventNotificationOnValidate
);

Errors Returned

FDO_E_INVALID_FEATURE_TYPE_FOR_TOPOLOGY

The specified feature class cannot be added to the Topology. Feature classes that cannot participate in a Topology include:

~ Dimension feature classes

~ Annotation feature classes

~ Network feature classes

FDO_E_INVALID_GEOMETRY_TYPE_FOR_TOPOLOGY

The specified feature class cannot be added to the Topology as it has an invalid shape type. Invalid shape types include: esriGeometryMultipoint and esriGeometryMultiPatch

FDO_E_CLASS_ALREADY_MEMBER_OF_TOPOLOGY

Feature classes that already participate in a Topology cannot be added to another Topology.

FDO_E_CANNOT_ADD_REGISTERED_CLASS_TO_TOPOLOGY

Cannot add a registered as a versioned class to the topology.

FDO_E_TOPOLOGY_INVALID_RANK

The rank associated with the feature class is less than 0 or greater than 63

Remarks

The AddClass method is used to add a feature class to the topology, with the specified weight and ranks. The Weight must be an integer between 1 and 10. Although it is not used in ArcGIS, it must still be specified. The XY and Z Rank must each be an integer between 1 and 63 (Ranks higher than 51 are will result in errors when specified in either the New Topology wizard or Topology property page). Even if the feature class is added to the topology is not Z aware, it must have a Z rank specified. The XY and Z ranks represent the accuracies of the feature class, relative to other feature classes participating in the topology. Feature classes with a higher rank, such as 1 are more accurate than feature classes with a lower rank, such as 2. Ranks are a relative measure of accuracy; the difference between two features classes of ranks 1 and 2 is the same as two feature classes with ranks of 1 and 50. Multiple feature classes in topology can have the same rank.

The EventNotificationOnValidate parameter indicates if an event is broadcast when the Topology that the feature class participates in, is validated. The EventNotificationOnValidate property can only be set if the Topology is created programmatically. Feature classes added to a topology using the New Topology wizard in ArcCatalog, will have a value of False for EventNotificationOnValidate.

Non-simple feature classes, such as annotation, dimension, geometric network feature classes, and feature classes already in the topology cannot be added to a topology. Object classes or tables and versioned simple feature classes, cannot be added to a topology. After a populated feature class is added to a topology that has been validated, in whole or in part, the state of the topology will be changed and a dirty area corresponding to the extent of the feature class will be created. If an unpopulated feature class is added to a topology, the topology's state will not change and no dirty area will be created. The AddClass method cannot be called on versioned topologies in SDE, but can be called on non-versioned topologies in SDE and topologies in a file or personal geodatabase.

ITopology.Cache Property

The topology graph of the topology.

Public ReadOnly Property Cache As ITopologyGraph

public ITopologyGraph Cache {get;}

Description

The Cache property returns a reference to the topology graph of the Topology. The topology graph can be used for working with topological primitives such as edges and nodes. For more information, see the ITopologyGraph object for additional help.

ITopology.ClusterTolerance Property

The cluster tolerance of the topology.

Public ReadOnly Property ClusterTolerance As Double

public double ClusterTolerance {get;}

Description

The ClusterTolerance property returns the tolerance that was specified when the topology was built. The cluster tolerance of the topology cannot be changed. In order to modify the tolerance, the Topology must be deleted and rebuilt with the new ClusterTolerance value.

ITopology.DirtyArea Property

The dirty area polygon of the topology.

Public Function get_DirtyArea ( _
    ByVal Location As IPolygon _
) As IPolygon

public IPolygon get_DirtyArea (
    IPolygon Location
);

Description

The DirtyArea property returns a dirty area polygon of the topology associated with the input polygon object. The IPolygon can correspond to the extent of the topology or a subset of the extent. If there is no dirty area intersecting the specified area, an empty polygon is returned. The dirty area polygon that is returned may be a multipart polygon. Use the State property on ITopology to determine if the Topology has any dirty areas or if it has been validated.

Remarks

A topology has an associated dirty area or dirty areas. A dirty area corresponds to regions within the extent of the topology where features participating within the topology have been modified (added, deleted, or updated) and have yet to be validated. The topological relationships between features covered by dirty areas are unknown. The dirty area must be validated in order to discover the topological relationships and evaluate any topology rules.

Whenever the geometry or subtype of a feature participating within a topology is modified, the extent of the dirty area is enlarged to encompass the envelope of the modified feature.

ITopology.FeatureDataset Property

The feature dataset that contains the topology.

Public ReadOnly Property FeatureDataset As IFeatureDataset

public IFeatureDataset FeatureDataset {get;}

ITopology.MaximumGeneratedErrorCount Property

The maximum number of errors to generate when validating a topology.

Public ReadOnly Property MaximumGeneratedErrorCount As Integer

public int MaximumGeneratedErrorCount {get;}

Description

Each topology has a maximum number of errors that can be generated on Validate, which can be determined through the MaximumGeneratedErrorCount property. MaximumGeneratedErrorCount can only be specified when a Topology is created programmatically. All topologies created with the New Topology wizard in ArcCatalog have a MaximumGeneratedErrorCount of -1, indicating no limit to the number of errors that can be generated. As with the ClusterTolerance, the MaximumGeneratedErrorCount property cannot be changed, a topology must be deleted and rebuilt in order to specify a new value.

ITopology.RemoveClass Method

Remove an object, feature, or attributed relationship class to the topology.

Public Sub RemoveClass ( _
    ByVal classToRemove As IClass _
)

public void RemoveClass (
    IClass classToRemove
);

Errors Returned

An error will be raised if RemoveClass is called on a versioned topology.

Remarks

Removes the specified class from the topology.

RemoveClass will remove any topology rules and errors associated with the class and will not result in the creation of a dirty area, nor will the state of the topology change.

ITopology.State Property

Indicates whether the topology is clean or not.

Public ReadOnly Property State As esriTopologyState

public esriTopologyState State {get;}

Remarks

The State property indicates the current status of the Topology; whether the topology has been validated and if so, whether any topology errors have been discovered.

ITopology.TopologyID Property

The ID of the topology.

Public ReadOnly Property TopologyID As Integer

public int TopologyID {get;}

Remarks

Each topology in a Geodatabase is identified by a unique value, the TopologyID property. The TopologyID can be used to get a reference to the corresponding topology through the ITopologyContainer::TopologyByID property.

ITopology.ValidateTopology Method

Validate the specified area in the topology.

Public Function ValidateTopology ( _
    ByVal areaToValidate As IEnvelope _
) As IEnvelope

public IEnvelope ValidateTopology (
    IEnvelope areaToValidate
);

Description

ValidateTopology validates the topology in the area specified by the areaToValidate envelope and returns the envelope of the validated area. If an empty envelope is supplied, ValidateTopology will return an empty validated area. If an envelope is provided which does not intersect or contain a dirty area, an empty envelope is returned.

Before validating a given area, use a polygon object to verify a Dirty Area is present at the given location. The dirty area can be accessed using the ITopology::DirtyArea property. The envelope of the polygon can then be passed into the ValidateTopology.

Errors Returned

FDO_E_EDIT_OPERATION_REQUIRED

When ValidateTopology is called on a versioned topology from within an edit session and without an edit operation or on a Topology in a file or personal geodatabase from within an edit session.

If nothing is supplied for areaToValidate, an error is returned.

Remarks

ValidateTopology can be performed outside of an edit session on topologies within Personal or File Geodatabases or on topologies within ArcSDE Geodatabases that have not been registered as versioned. Once the topology is registered as versioned, ValidateTopology must be performed within an edit session. The IWorkspaceEdit interfaces can be used to manage edit sessions and edit operations.

ValidateTopology validates the dirty area of the topology in the area specified by the areaToValidate envelope. The validate process evaluates all the rules and produces any topology errors corresponding to areas in which a rule has been violated. The ValidateTopology function returns the envelope of the validated area. If an empty envelope is supplied, ValidateTopology will return an empty validated area. It is not necessary to validate the entire dirty area of the topology. Subsets of the dirty area can be specified, resulting in a partial validation. When a partial validation occurs, the original dirty area is clipped by the envelope that was supplied for the validation. An entire topology can be validated by supplying the envelope of the extent of the topology.

By supplying a polygon object to the ITopology::DirtyArea property, the dirty area at a particular location can be returned. The envelope of the returned dirty area polygon can then be passed into ValidateTopology.

The OnCreate, OnDelete, or OnChange events are not fired during a topology validation. The OnCreate and OnDelete events are not applicable since a validate does not create or delete features. The OnChange event is not fired for performance reasons as a large number of features may be changed during validation. In addition, features may be changed many times.

ITopology.ZClusterTolerance Property

The z cluster tolerance of the topology.

Public ReadOnly Property ZClusterTolerance As Double

public double ZClusterTolerance {get;}

Description

The Z cluster tolerance defines the minimum difference in elevation, or z-value, between coincident vertices.

Remarks

The ZClusterTolerance property returns the Z cluster tolerance that was specified when the topology was built. As with the cluster tolerance, the Z cluster tolerance of the topology cannot be changed. In order to modify the Z cluster tolerance, the topology must be deleted and rebuilt with the new ZClusterTolerance value.

Unlike the cluster tolerance property, the ZClusterTolerance value indicates cluster tolerance distance as well as the Z clustering model that applies to the topology. A ZClusterTolerance value of 0 signifies the Building model, Z values of coincident vertices are not changed. A ZClusterTolerance value greater than 0 signifies the Terrain model, Z values of coincident vertices that are within the Z cluster tolerance will be averaged together, based on the ZRank assigned to the features. (see ITopologyClass::ZRank )

ZClusterTolerance will return a value of -1 for any topology:

• created in a pre-9.0 geodatabase (8.3 with or without any service pack), either programmatically or with the New Topology Wizard

Classes that implement ITopology

Classes	Description

Remarks

A Topology is a collection of simple feature classes within the same feature dataset that participate in topological relationships with a set of rules that govern those relationships. Topologies can have multiple feature classes in the same topological role. A feature dataset may have numerous topologies, but a feature class can only belong to one topology, and only simple feature classes may participate in a topology. Each topology has one associated topology graph. The topology graph is a planar representation of the geometries in the feature classes participating in a geodatabase topology. If you need to access the topology graph directly for working with topology primitives such as edges and nodes, see the ITopologyGraph.

When new features are created, edited, or deleted, the topology is responsible for creating or modifying a dirty area that will encompass the envelope of the feature. A dirty area is a special type of feature under which, the state of the topology is unknown. Features that are covered by dirty areas can still be edited and queried, but their topological relationships cannot be guaranteed to be correct. A dirty area must be validated in order to discover the topology of its underlying features and guarantee their correctness.

ITopology topology = topologyContainer.get_TopologyByName("Default Topology");

IGeoDataset geoDataset = (IGeoDataset)topology;



IPolygon searchArea = new PolygonClass();

ISegmentCollection segmentCollection = (ISegmentCollection)searchArea;

segmentCollection.SetRectangle(geoDataset.Extent); 



// Get dirty area

IPolygon dirtyArea = topology.get_DirtyArea(searchArea);

IEnvelope dirtyAreaEnvelope = dirtyArea.Envelope;



// Validation

IEnvelope validateResults =  topology.ValidateTopology(dirtyAreaEnvelope);



// Topology graph

ITopologyGraph topologyGraph = topology.Cache;