In this topic
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:
- Listening to versioned events
- Listening to object class events
- Listening to the OnValidate event for a geodatabase topology
- Using replica creation events to extend the replica creation process
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 |
|
Class extensions |
None | |
|
Class extensions |
ObjectClass | |
|
None |
ObjectClass | |
|
Class extensions |
None | |
|
None |
RelationshipClass | |
|
Class extensions |
Topology | |
|
Workspace extensions |
VersionedWorkspace | |
|
Workspace extensions |
Workspace | |
|
Workspace extensions |
Workspace | |
|
Workspace extensions |
None |