News

Implementing the Java Delegation Event Model and JavaBeans Events in C++

• By Craig Larman
• October 2, 2000

THIS ARTICLE EXAMINES the design of the delegation event model (DEM) used in Java and how it may be implemented in C++. In addition, the design and C++ implementations of JavaBeans-style bound and constrained properties are presented. DEM experts will note that some minor modifications have been made to take advantage of multiple implementation inheritance in C++, and to make some simplifications.

Why bother to learn about an implementation of the DEM in C++? Three reasons:

1. The DEM is a relatively elegant and efficient publish-subscribe style design, worthy of emulation in C++.
2. Java—and thus the use of the DEM—is widespread, and many C++ developers need to work in both languages. Thus, it is advantageous to use similar publish-subscribe architectures across languages in order to increase the congruence in designs, improve porting opportunities, and reduce the cross-language learning curve.
3. To promote examples of interface-based design in C++, which is a Good Thing.

Figure 1. An interface in the UML notation.

In C++, interfaces are defined by pure abstract base classes that only contain pure virtual function definitions, such as:

class /* INTERFACE */ ILowAltitudeListener
{
public:
   virtual void onLowAltitude( LowAltitudeEvent* evt ) = 0;
};

Figure 2. Interface implementation and subclassing in the UML.

The derived C++ class that implements an interface must, of course, provide a member function body for the abstract operations it inherits:

class AirTrafficControl :
    public Organization,
    public ILowAltitudeListener
{
public:
    virtual void onLowAltitude( LowAltitudeEvent* evt )
    {
        cout < "warning:="" low="" altitude="" plane";="" }="" ...="" };="">

A basic design goal of Publish-Subscribe (e.g., the DEM) is to provide a form of loosely coupled signaling from a publisher to subscribers, and a means to dynamically register/deregister subscribers with a publisher. A common implementation technique to achieve low coupling from publisher to subscriber is to design in terms of interfaces, rather than regular classes. This will be illustrated in the following sample implementation.

In DEM nomenclature, the publisher is called the event source, and the subscriber is the event listener.

Events are represented as classes of objects, and the publishing of an event is implemented as a regular message send (synchronous member function invocation).

Most of the concepts presented in the first part of this article are summarized in Figure 3, which illustrates a sample use of the DEM with an Airplane, which is a source of LowAltitudeEvents, and AirTrafficControl, a listener for these events. The DEM is quite simple, so this diagram might provide enough insight to proceed directly to the second major section on JavaBeans-style bound and constrained properties.

Figure 3. An example use of the DEM.

Event Objects Events in the DEM are represented as objects, and all derive from class EventObject, which is responsible for knowing the source object of the event (Figure 4). It is common, though not required, that subclasses of EventObject add additional properties pertaining to the event. For example, a KeyboardEvent could know the key pressed, and so forth. A sample definition of EventObject is:

template 
class EventObject
{
public:
    EventObject( SOURCE_TYPE* source )
       : m_source( source ) {}

    virtual ~EventObject() {}

    SOURCE_TYPE* getSource() { return m_source; }

private:
    SOURCE_TYPE* m_source;
};

The most common difference between the Java implementation and this C++ implementation of EventObject and other classes in the DEM is the inclusion of parameterized types in the C++ version (for example, for the event source class). In contrast, the Java version declares the event source as of class Object—the root of all Java classes—and requires downcasting from class Object for most usage. Of course, the template classes in C++ eliminate the need to cast.

Event Listeners (Subscribers) Event listener classes (i.e., subscribers) are responsible for responding to event notification when an event source sends them a message. In effect, the event source says to the listener, "Hey! I'm having an event," and the listener must react to that notification.

A concrete event listener must implement a particular interface for an event. By convention, the interface names all end with the term Listener, such as ILowAltitudeListener. The name of the listener operation(s) ideally suggests the signaling of the event, such as onLowAltitude or alarmRaised.

It is required that all event-handling operations must receive the EventObject (or a subclass) as a parameter, such as onLowAltitude(LowAltitudeEvent*) (see Fig. 5). This gives the listener potential visibility back to the source object of the event because an EventObject knows its source.

Figure 5. Examples of Listener interface names and operations signatures.

In the C++ implementation, the listener interface requires a template parameter for the event source type because the event object parameter definition requires it. An example is:

template 
class /* INTERFACE */ ILowAltitudeListener
{
public:
    virtual void onLowAltitude( 
        LowAltitudeEvent* evt ) = 0;
};

class AirTrafficControl :
    public Organization,
    public ILowAltitudeListener
{
public:
    // this event handling method is called when a 
    // source "has an event" and sends this message.

    void onLowAltitude( LowAltitudeEvent* evt )
    {
        // in contrast to the Java DEM, the parameterized event
        // class avoids the need to down-cast the event source

        Airplane* plane = evt->getSource();

        cout < "warning:="" low="" altitude="" plane";="" }="" snip="" ...="" };="">

• Register listener objects.
• Notify listener objects when an event happens by sending them a message.

The event source class must implement methods to register—add and remove—listeners. By convention, the signature pattern for the registration methods will usually be:

void addFooListener( FooListener* )
void removeFooListener( FooListener* )

For example, if Airplane is a source of LowAltitudeEvents, it must be able to register ILowAltitudeListener instances. The group of registered listeners will probably be saved in an STL container, such as a vector. To illustrate:

class Airplane
{ 
public:
    void addLowAltitudeListener( ILowAltitudeListener* lis )
    {
        // add lis to a container
    }

    void removeLowAltitudeListener( ILowAltitudeListener* lis )
    {
       // remove lis from a container
    }

// ...
};

class Airplane
{ 
public:
    // broadcast the event to all listeners

    void broadcastLowAltitude( LowAltitudeEvent* evt )
    {
        for each listener lis in the container,
            lis->onLowAltitude( evt )
    }

    // modify the altitude, and possibly signal
    // event multicasting

    void setAltitude( int alt )
    { 
        m_altitude = alt;

        // if necessary, broadcast the LowAltitudeEvent

        if ( alt < getaltitudethreshold()="" )="" {="">* evt =
                 new LowAltitudeEvent( this ) ;

             broadcastLowAltitude( evt );

             delete evt ;
        }
    }
// snip ...
};

In the DEM, the listener interface definition is the Abstract Client definition, and the event sources are the servers that register callbacks on the event listener clients. The event-handling method that a listener implements is the callback method.

Adding a Common EventSourceMulticaster Superclass The previous implementation of the event source class Airplane can be improved upon in C++. Because the responsibilities of listener management and broadcasting are invariably the same for all event sources, it is desirable to factor the listener management and broadcasting code into a common abstract base class such as EventSourceMulticaster (the Java DEM calls such classes multicasters). The only points of variation are the source type, which can be specified with a parameterized type, and the specific listener method to invoke, which can be specified with a function pointer. Please see Listing 1 for an example implementation.

The base EventSourceMulticaster can be further specialized into specific derived event source multicaster subclasses, which fill in the details required by the very generic EventSourceMulticaster class. For example, a LowAltitudeEventSource class definition is shown in Listing 2. Note that the derived multicaster inherits privately from the base multicaster, because we want to ensure that none of the base class behavior will ever encroach upon the ultimate concrete derived class, such as Airplane.

Once these helper abstract superclasses are defined, we can finally derive our concrete event source classes from them, and inherit the correct behavior for being an event source.

class Airplane :
    public LowAltitudeEventSource
{
    // snip ...
};

Figure 6. Example implementation of the DEM, with helper multicaster classes.

PUTTING IT ALL TOGETHER
We have defined the following components:

• AirTrafficControl (a LowAltitudeListener)
• Airplane (a source of LowAltitudeEvents)
• Various supporting components (ILowAltitudeListener, LowAltitudeEvent, and so on)

// Airplane is a source of LowAltitudeEvents.

Airplane plane;

// ATC (AirTrafficControl) is a listener
// for LowAltitudeEvents

ATC atc;

// register the ATC as a listener with
// the source.

plane.addLowAltitudeListener( &atc );

// change the plane's altitude so that it emits
// a LowAltitudeEvent. the ATC::onLowAltitude
// method will be invoked.

plane.setAltitude( 50 );

Bound Properties A bound property is a logical attribute of a class that emits a PropertyChangeEvent when the property changes. A PropertyChangeEvent knows the property name and old and new values. For example:

template 
class PropertyChangeEvent :
    public EventObject
{
public:
    // snip ...

    VAL_TYPE*   getNewValue() { return m_newValue; }
    VAL_TYPE*   getOldValue() { return m_oldValue; }
    string  getPropertyName() { return m_propertyName; }

    // snip ...
};

class Flight :
    public PropertyChangeEventSource
{
public:
    void setDestination( string dest )
    {
        string old = m_destination;
        m_destination = dest;

        PropertyChangeEvent* evt =
            new PropertyChangeEvent
                (this, "destination", &old, &dest) ; 

        broadcastPropertyChange( evt ) ;

        delete evt ;
    }

    // snip ...
};

Figure 7. Bound properties and IPropertyChangeListeners.

What are bound properties good for? One common use is when data widgets in a window need to refresh when the data they are associated with changes. For an example in Java, a TextField in a FlightApplet (a kind of graphical panel displayable in Web browsers) may display the destination property of a Flight instance. The FlightApplet can be an IPropertyChangeListener on a Flight instance. When the Flight destination changes, the Flight can emit a PropertyChangeEvent to the FlightApplet, which then refreshes the TextField widget with the new value. To generalize this case: Bound properties are useful to communicate state changes in a domain layer of objects up to a presentation layer of windows that are visualizing domain state, while maintaining low coupling from the domain to presentation layer (which is a desirable design goal). This technique can also be applied in C++ to the Document-View framework in Microsoft's MFC.

Constrained Properties A constrained property is a logical attribute of a class that emits a VetoableChangeEvent when the property is attempting to change. Like PropertyChangeEvents, a VetoableChangeEvent knows the property name and old and new values. The key idea is that the listener may veto the potential property change, and the change will be aborted. The "vetoing" of a change request occurs with C++ exceptions. The exception may be thrown before the line of code that would actually cause the data member to be assigned.

To illustrate, if altitude is a constrained property in ConstrainedAirplane, then the setAltitude mutator will create and broadcast a VetoableChangeEvent using a helper multicaster base class named VetoableChangeEventSource. Note that the AirTrafficControl listener may throw an exception, thus causing an exit from the setAltitude method before the data member change can occur.

First, here is the ConstrainedAirplane class that has the constrained property:

class ConstrainedAirplane :
    public VetoableChangeEventSource
{
public:

    void setAltitude( int alt ) throw (PropertyVetoException)
    {

        cout < endl="">< "before="" veto="" "="">< alt="">< endl="" ;="">* evt =
            new VetoableChangeEvent
                (this, "altitude", &m_altitude, &alt) ;

        // ask my listeners if they want to veto the change.
        // a PropertyVetoException can occur here

        try { broadcastVetoableChange( evt ) ; }
        catch (...)
        {
            delete( evt ) ;
            throw ;
        }
    
        // only if we get past the above attempt
        // do we change the property value

        cout < "success.="" no="" veto="" "="">< endl="" ;="" delete(="" evt="" )="" ;="" m_altitude="alt" ;="" }="" snip="" ...="" };="">

Presumably, at some point an AirTrafficControl instance has registered as an IVetoableChangeListener with the ConstrainedAirplane. The vetoableChange method is the event-handling callback method that the listener must implement, and which does the source object invoke when it is attempting to change a constrained property, such as the altitude property in the ConstrainedAirplane.

class AirTrafficControl :
    public IVetoableChangeListener
{
public:

    void vetoableChange( VetoableChangeEvent* evt )
        throw (PropertyVetoException)
    {
        int altitude = *( evt->getNewValue() );

        if ( altitude < getaltitudethreshold()="" )="" {="" cout="">< endl="">< "vetoing="" the="" change"="">< endl;="" throw="" propertyvetoexception();="" }="" }="" snip="" ...="" };="">

Source Code The complete source code for this article that demonstrates the basic DEM implementation, plus support for bound and constrained properties, can be found at www.oma.com/C++Report/Issues/Apr99/Larman.

CONCLUSION
In this article we examined a C++ implementation of the Java DEM. It deviates from the Java implementation to take advantage of multiple implementation inheritance for common event source responsibilities. In addition, we explored the use of the DEM to support bound and constrained properties—an idiosyncratic use of the DEM for notification to listeners when object properties in a source object change.

References
1. Gamma, E. et al. Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley, Reading, MA, 1995.
2. Martin, R. Pattern Languages of Programming, Vol. 1, Prentice-Hall, Englewood Cliffs, NJ, 1996.