com.esri.arcgis.geodatabase
Interface ITopology

All Superinterfaces:
Serializable
All Known Subinterfaces:
ITopology2
All Known Implementing Classes:
ITopology2Proxy, ITopologyProxy, Topology

public interface ITopology
extends Serializable

Provides access to members that control a topology.

Superseded By

ITopology2

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 multiple 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 help.

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 guarnatee their correctness.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 void addClass(IClass classToAdd, double weight, int xYRank, int zRank, boolean eventNotificationOnValidate)
          Add an object, feature, or attributed relationship class to the topology.
 ITopologyGraph getCache()
          The topology graph of the topology.
 double getClusterTolerance()
          The cluster tolerance of the topology.
 IPolygon getDirtyArea(IPolygon location)
          The dirty area polygon of the topology.
 IFeatureDataset getFeatureDataset()
          The feature dataset that contains the topology.
 int getMaximumGeneratedErrorCount()
          The maximum number of errors to generate when validating a topology.
 int getState()
          Indicates whether the topology is clean or not.
 int getTopologyID()
          The ID of the topology.
 void removeClass(IClass classToRemove)
          Remove an object, feature, or attributed relationship class to the topology.
 IEnvelope validateTopology(IEnvelope areaToValidate)
          Validate the specified area in the topology.
 

Method Detail

getState

int getState()
             throws IOException,
                    AutomationException
Indicates whether the topology is clean or not.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.geodatabase.esriTopologyState constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

validateTopology

IEnvelope validateTopology(IEnvelope areaToValidate)
                           throws IOException,
                                  AutomationException
Validate the specified area in the topology.

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 supplied 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. This can be done using the ITopology::DirtyArea property. The envelope of the polygon can then be passed into ValidateTopology.

Remarks

ValidateTopology can be performed outside of an edit session on Topologies within Personal or File Geodatabases or on Topologies within ArcSDE Geodatabases which have not been registered as versioned. Once the Topology is registered as versioned, ValidateTopology must be performed within an edit session. When performed within an edit session, ValidateTopology must also be bracketed within an edit operation.

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.

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. ValidateTopology can be performed outside of an edit session on topologies within Personal Geodatabases or on topologies within ArcSDE Geodatabases that have not been registered as versioned. Once a topology is registered as versioned, ValidateTopology must be performed within an edit session and bracketed within an edit operation. The IWorkspaceEdit or IEditor interfaces can be used to manage edit sessions and edit operations.

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 a Validate. In addition, features may be changed many times.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getClusterTolerance

double getClusterTolerance()
                           throws IOException,
                                  AutomationException
The cluster tolerance of the topology.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getCache

ITopologyGraph getCache()
                        throws IOException,
                               AutomationException
The topology graph of the topology.

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 TopologyGraph object for additional help.

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.ITopologyGraph
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFeatureDataset

IFeatureDataset getFeatureDataset()
                                  throws IOException,
                                         AutomationException
The feature dataset that contains the topology.

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.IFeatureDataset
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addClass

void addClass(IClass classToAdd,
              double weight,
              int xYRank,
              int zRank,
              boolean eventNotificationOnValidate)
              throws IOException,
                     AutomationException
Add an object, feature, or attributed relationship class to the topology.

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 being 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 a 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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
classToAdd - A reference to a com.esri.arcgis.geodatabase.IClass (in)
weight - The weight (in)
xYRank - The xYRank (in)
zRank - The zRank (in)
eventNotificationOnValidate - The eventNotificationOnValidate (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

removeClass

void removeClass(IClass classToRemove)
                 throws IOException,
                        AutomationException
Remove an object, feature, or attributed relationship class to the 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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getMaximumGeneratedErrorCount

int getMaximumGeneratedErrorCount()
                                  throws IOException,
                                         AutomationException
The maximum number of errors to generate when validating a topology.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getTopologyID

int getTopologyID()
                  throws IOException,
                         AutomationException
The ID of the topology.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getDirtyArea

IPolygon getDirtyArea(IPolygon location)
                      throws IOException,
                             AutomationException
The dirty area polygon of the topology.

Product Availability

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

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