Interface ITopology

Namespace
ESRI.ArcGIS.Geodatabase
Assembly
ESRI.Server.Geodatabase.dll

Provides access to members that control a topology.

[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
[Guid("C08348E2-5AC1-4D88-A2D0-B675317BB6CD")]
public interface ITopology

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.

[C#]

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;

Properties

Cache

The topology graph of the topology.

ITopologyGraph Cache { get; }

Property Value

ITopologyGraph

ClusterTolerance

The cluster tolerance of the topology.

double ClusterTolerance { get; }

Property Value

double

DirtyArea[IPolygon]

The dirty area polygon of the topology.

IPolygon DirtyArea[IPolygon Location] { get; }

Parameters

Location IPolygon

Property Value

IPolygon

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.

FeatureDataset

The feature dataset that contains the topology.

IFeatureDataset FeatureDataset { get; }

Property Value

IFeatureDataset

MaximumGeneratedErrorCount

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

int MaximumGeneratedErrorCount { get; }

Property Value

int

State

Indicates whether the topology is clean or not.

esriTopologyState State { get; }

Property Value

esriTopologyState

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.

TopologyID

The ID of the topology.

int TopologyID { get; }

Property Value

int

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.

ZClusterTolerance

The z cluster tolerance of the topology.

double ZClusterTolerance { get; }

Property Value

double

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

Methods

AddClass(IClass, double, int, int, bool)

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

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

Parameters

classToAdd IClass
Weight double
XYRank int
ZRank int
EventNotificationOnValidate bool

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.

RemoveClass(IClass)

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

void RemoveClass(IClass classToRemove)

Parameters

classToRemove IClass

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.

ValidateTopology(IEnvelope)

Validate the specified area in the topology.

IEnvelope ValidateTopology(IEnvelope areaToValidate)

Parameters

areaToValidate IEnvelope

Returns

IEnvelope

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.