TM4J provides a generic way for any client application to detect changes made in a topic map. This architecture enables TM4J to act as a Model in the popular Model-View-Controller (MVC) application architecture. This facility is provided by allowing client objects to register themselves with any core topic map object as a property change listener. A property change listener is simply a class that implements the java.beans.PropertyChangeListener interface and, as the name suggests, it may be registered to listen for changes made to a named property of the object or to changes made to any of the properties of the object. Each subclass of TopicMapObjectImpl defines a number of named properties, which are shown in the table below.
Table 5.1. Properties of TM4J Objects
| Class | Property Name | Description |
|---|---|---|
| TopicMapObject | sourceLocators | The Locator of the XTM element(s) from which this object was created. |
| Topic | subject | The single Locator addressing the subject of this topic. |
| subjectIndicators | The collection of Locators of subject indicators of this topic. | |
| types | The Topics which type this Topic | |
| names | The BaseNames of this Topic | |
| occurrences | The Occurrences of this Topic. | |
| rolesPlayed | The Members of which this Topic is a part. | |
| baseTopic | The topic with which this topic is merged. | |
| BaseName | string | The string value of this name |
| variants | The set of child Variants of this BaseName | |
| scopeString | The string encoding of the scope of this BaseName | |
| Variant | string | The string value of the name |
| variants | The set of child Variants of this Variant | |
| variantName | The child VariantName of this Variant | |
| VariantName | resourceRef | The URI of the resource which is the value of the VariantName |
| resource | The string which is the value of the VariantName | |
| Association | members | The Members of this Association |
| type | The Topic which types this Association | |
| Member | parent | The Association of which this Member is part. |
| roleSpec | The Topic which defines the role played by this Member in the Association | |
| players | The Topics which participate in the role played by this Member in the Association | |
| Occurrence | type | The Topic which defines the type of the Occurrence |
| resourceRef | The URI of the resource which is the value of this Occurrence | |
| resource | The string which is the value of this Occurrence. | |
| ScopedObject | scope | The Scope object which defines the collection of scoping topics applied to the ScopedObject. |
When a property of an object is altered, the propertyChange() method is invoked on each listener registered against that property (or against all properties) of the object. The propertyChange() method receives a single parameter - a PropertyChangeEvent object. From this object, the listener may determine which object was changed (the 'source' of the property change event); which property was changed; the value of that property prior to its alteration and its value after the alteration has been made.
Some of the properties are reflexive, modifying the rolesPlayed property of a Topic object also modifies the players property of one or more Member objects - in cases such as this, both events are generated by TM4J.
There are some limitations to the current implementation of the property change listeners, which are worth noting here.
This last detail has three implications. Firstly, it means that code that makes the change is blocked until all listeners have received and processed the notification. Secondly it means that it is important for implementers of change listeners to ensure that a live-lock situation is not caused by a series of property change listeners altering properties of the same object. Finally, it means that in systems which have a multi-user database backend such as a remote Ozone database back-end or a relational database back-end, you must not assume that your code will be notified of all changes taking place on the topic map - any changes made by applications in other JVMs or even in other threads of your application will not necessarily be notified to your listeners.