The events and listeners

The EventListener mechanism is one of the least talked about items within jConfig, yet one of the most used features. The EventListener is like all other EventListeners, with the exception that more than one event can be fired at a time.

First thing one should know, is how the hierarchy is built up.

PropertyChangedEvent (Interface)
+ CategoryChangedEvent (Interface)
+ ConfigurationChangedEvent (Interface)
+ ConfigurationChangedEventImpl (Default implementation)

The events are based on the theory that a Configuration contains Categories that contains Properties. If a Property is a changed, the PropertyListeners should be informed, then the Category Listeners and, last but not least, the ConfigurationListeners. The same goes when just the Category changes. The Category Listeners are informed, then the Configuration Listeners. The Property Listeners would care about Category changes. And the last situation is just the Configuration changing. The Configuration Listeners are informed and the Property Listeners and Category Listeners are left in peace.

When is a PropertyChangedEvent delivered?

With regards to the DefaultCategory implementation, the PropertyListener is informed when a setProperty(String propertyName, String propertyValue) is called. The Event details will differ depending on what actually changed. The default implementation will notify when a property is removed. This is accomplished by setting the property value to null. If a property doesn't exist, then the Listener will be informed about the new property. Changing an existing Property will also provide the necessary information concerning the EventType. For multiple Property changes, multiple Events will be delivered.

If a PropertyChangedEvent is delivered, the information concerning which property, and the values (old or new) plus the EventType are available.

See also:

PropertyChangedEvent.PROPERTY_REMOVED, 
PropertyChangedEvent.PROPERTY_ADDED and
PropertyChangedEvent.PROPERTY_CHANGED.

When is a CategoryChangedEvent delivered?

With regards to the DefaultConfiguration implementation, the CategoryListener is delivered by various methods within the DefaultConfiguration. If the removeCategory(String categoryName), setCategory(Category categoryName) or setCategory(String categoryName, boolean isDefaultCategory) methods are called, the CategoryChangedEvent will be delivered. The Event is also delivered if any of the above described PropertyChangedEvents are delivered.

If a CategoryChangedEvent is delivered, the Category's name can be retrieved. If a PropertyChangedEvent was delivered, the information concerning the affected Property is also available.

See also:

PropertyChangedEvent.CATEGORY_REMOVED, 
PropertyChangedEvent.CATEGORY_ADDED and 
PropertyChangedEvent.CATEGORY_CHANGED.

When is a ConfigurationChangedEvent delivered?

The last of the described Events is typically delivered when anything within the current Configuration changes. All of the above described Events with regards to Properties and Categories will also be available to any ConfigurationListeners.

There isn't a way to see if new Configurations are added or removed. It probably wouldn't be difficult to implement something like this if one were to find it useful. I haven't had a use case yet for such a Listener, hence no implementation.

Hopefully this provides some insight to the EventListener mechanism within jConfig. Suggestions are always welcome for improvements.

// Andreas Code Example here
[code]

[/code]