TM4J implements both subject-based and name-based topic merging. Merging requires that a topic exhibit its own characteristics (names, occurrences and roles played in associations) plus the characteristics of all topics which are merged with it. In TM4J, a merge can occur in one of two ways, either dynamically or statically.
The 'dynamic' approach to merging which does not actually assign characteristics to a topic as a result of merging. Instead, each topic in a TM4J system is a member of a set of topics which are considered to be merged together. When a topic characteristic is requested from a topic, the union of the characteristics of all of the members of the set of merged topics is returned.
Under TM4J's dynamic merging model, each set of merged topics consists of one base topic and a set of topics that are merged with that base topic. The org.tm4j.topicmap.Topic interface provides two methods for inspecting the results of dynamic merging. The method Topic.getBaseTopic() returns the base topic of the merged set of topics that this Topic belongs to. The method Topic.getMergedTopics() returns the set of Topics that this Topic is merged with.
It is also possible to access only the property values of the object, without regard to its merging - this is achieved through the getXXX(boolean) functions. Passing in the value false for the boolean parameter will return only the characteristics of the addressed Topic object.
TM4J's default implementation of merging is highly dynamic. Altering a characteristic of a topic may cause it to be instantly merged with another topic or to be un-merged again. The event of a topic being merged with another or de-merged may be trapped by listening for changes to the baseTopic property of the Topic object.
The 'static' merging method does a merge between two Topics by transferring all of the names, occurrences and roles played in associations from one Topic instance to the other. The choice of which Topic instance receives the characteristics is not deterministic. The merging process will also replace the Topic which has lost all of its characteristics wherever it is used as a type or as part of a scope, replacing it with the Topic which receives the characteristics. The Topic which has lost all of its characteristics is not immediately destroyed however, but instead becomes a proxy for the other Topic so all calls to methods of the Topic interface should behave as normal for either of the merged Topic instances.
Unlike the dynamic merge, the static merge is not reversible. Once the merge takes place, there is no way to return to the state with the two separate topics (unless this is part of a transaction which you subsequently revoke).
When a TopicMap instance is first created, the merging mode is defaulted by the TopicMapProvider that manages it. For persistent backends, the merging mode cannot be changed in subsequent sessions, even if you change the default mode for the TopicMapProvider.
The method TopicMap.getProperty() can be used to retrieve the value of the tm4j.static.merge property which indicates which merging mode is being used by the TopicMap. The property value is a Java Boolean object with a boolean value of true if the merging mode is static and false if the merging mode is dynamic.
Under the rules of XTM, it is a reportable error if after merging two or more topics the processor finds that there is more than one value provided for the subject property of the topic. A topic may have any number of subject indicators, but only one subject. If, during the processing of a merge, the TM4J processor discovers such an error, then a org.tm4j.topicmap.MergedTopicSubjectClashException will be thrown. This exception class provides a single additional method, getTopics() which returns the Topic objects which the system attempted to merge when the error condition was detected.