An event is an object which encapsulates a change in the state of some object. Events are used to propagate these changes to yet other objects interested in responding to them. This design allows for a weak coupling of object classes that would otherwise know too much about each other, making software change difficult or even impossible.

In good object-oriented design, objects interested in receiving event notifications should play one or more “listener” roles. These roles are usually played by classes implementing listener interfaces, which are implemented on top of the business or plumbing interfaces in the application domain space.

The Tensegrity Graph API provides many different event and listener interfaces and classes that you may take advantage of. Listener interfaces are fixed plumbing in the Tensegrity Graph API and therefore you cannot substitute them with your own. You may, however, implement your own classes that uniquely respond to any and all events.

Please have a look at the javadocs and study the numerous event class names and responsibilities. You will see events are categorized into element types and the kinds of state changes that are possible within these types. The package “com.tensegrity.graph.event” contains all event and listener interfaces and classes.

A GraphListener can be any business or non-business object interested in receiving event notifications. They are called “listeners” because that is the coupling technique. An object which throws an event knows about listeners awaiting notification only and not about some specific domain-related class or interface, such as JButton, XYZBusinessObject or anything else that is extraneous to this design pattern.

Once a listener has been registered or added to an event-throwing object, that listener will receive notifications when state changes occur. A “notification” is what happens when an event is passed to a registered listener. An actual event object does not have to be passed, however. Often it is sufficient when a method in a listener interface is invoked.

We now give you some sample code which shows how to create and attach a GraphListener to an existing Graph instance.

// register for graph model events
graphModel.addGraphListener(new GraphAdapter()
{
  public void nodeRemoved(GraphEvent graphevent)
  {
    logger.logGraphListener(graphevent);
  }

  public void edgeRemoved(GraphEvent graphevent)
  {
    logger.logGraphListener(graphevent);
  }
});

The code above shows the instantiation of a new GraphAdapter instance, which implements the GraphListener interface.

Registration is the process of calling the addGraphListener method of a Graph object, passing it the new listener implementation.