Optional interfaces and event handlers in the geodatabase API

Summary

Custom applications and components can listen to geodatabase events in two different ways—optional interfaces and event handlers. This topic discusses the difference between the two approaches.

Optional interfaces

An optional interface is an interface that a class might or might not implement. A built-in example of this in the geodatabase application programming interface (API) is the IVersionedObject interface, which is implemented by versioned feature class objects using the SDE data source. Custom classes that integrate into the geodatabase framework can implement optional interfaces.

The following are two types of custom classes related to the geodatabase API that usually implement one or more optional interfaces:

Class extensions
Workspace extensions

Examples of the interfaces these classes often implement are IObjectClassEvents (for class extensions) and IVersionEvents (for workspace extensions). In both cases, the object that the extension is associated with checks whether the extension implements a particular interface, and if so, calls the appropriate method from that interface.

Optional interfaces are tightly coupled with specific types of extensions. Optional interfaces intended for class extensions should only be implemented by class extensions. Attempting to implement these interfaces on the incorrect type of extension (or on a custom class) will not provide the desired functionality, and an alternative solution should be investigated. For example, if a workspace extension needs to listen to ITopologyClassEvents, use an event handler rather than an optional interface.

When building a class that implements an optional interface in C#, the signatures of the interface members have to match those defined in the interface, including the return type, member name, and parameter types. In VB .NET, the Implements statement provides more flexibility, as it allows an arbitrarily named class member to implement one or more members from an interface, provided the return and parameter types still match.

For more information on how to implement optional interfaces, as well as concrete examples, see Creating class extensions and Creating workspace extensions.

Event handlers

An event handler is a method that is triggered when specific events occur, usually in another object. A class that defines an event handler—known as an event listener—is not obligated to implement any interface, but class instances are required to subscribe to the event at runtime (most event handlers are instance methods). In .NET, this is often referred to as wiring the handler. An event handler can be any method in any class, as long as the parameter types match those of the event's delegate type. For in-depth discussions of events and event handlers in .NET, see the Microsoft Developer's Network (MSDN) Web site documentation or How to wire ArcObjects .NET events.

There are several interfaces in the geodatabase API that expose events, such as ITopologyClassEvents, implemented by the Topology class; IRelationshipClassEvents, implemented by the RelationshipClass class; and IObjectClassEvents, implemented by the ObjectClass class.

Like several other geodatabase interfaces, IObjectClassEvents is an optional interface for class extensions and an event (or outbound) interface for the ObjectClass class. When given the choice of both options (such as listening for versioning events from a workspace extension), using an optional interface is typically the better solution.

Class extensions and workspace extensions can define event handlers, but in most cases they do not need to, since the events most often listen to are provided through optional interfaces. The following are two examples of when a class extension might act as an event listener:

Object class extensions that store the positions of fields in a class and modify row values in response to certain events. If the classes these extensions are associated with undergo schema changes, the extension can listen for the removal of fields, which might affect the position of the fields it modifies using the IObjectClassSchemaEvents event interface.
Feature class extensions that create or modify features in response to topology validation, but are not a part of the topology. These extensions should define an event handler for the ITopologyClassEvents.OnValidate event. A feature class that is extended this way should not participate in the topology.

In .NET, ArcObjects interfaces that expose events have an _Event suffix attached to the original interface name.

For more information on how to implement event handlers, as well as concrete examples, see the following topics:

Examples of geodatabase API event interfaces

The following table contains a selection of interfaces in the geodatabase API that allows custom classes to react to events. The second column indicates what type of component can implement it as an optional interface (if any) and the third column indicates the class that can be cast to the event interface to allow handler subscription.

Interface	Optional interface component	Exposed as event interface by
IConfirmSendRelatedObjectEvents	Class extensions	None
IObjectClassEvents	Class extensions	ObjectClass
IObjectClassSchemaEvents	None	ObjectClass
IRelatedObjectClassEvents	Class extensions	None
IRelationshipClassEvents	None	RelationshipClass
ITopologyClassEvents	Class extensions	Topology
IVersionEvents	Workspace extensions	VersionedWorkspace
IWorkspaceEditEvents	Workspace extensions	Workspace
IWorkspaceEvents	Workspace extensions	Workspace
IWorkspaceReplicaEvents	Workspace extensions	None