The org.tm4j.topicmap.utils.AssociationUtils class contains methods for retrieving a unique "signature" string for both Association and Member objects. Two Associations in the same scope with the same Topics playing the same roles will return equal signature strings and two Member objects containing the same players and with the same role specification topic will return the same signature.
The static method AssociationUtils.getPlayers(Association) provides a short cut to retrieve all topics which play any role in the specified association.
The static method AssociationUtils.removeDuplicateRolePlayers(Association) will ensure that any Topic which is a player in a Member of the specified Association apears only once as a player of that role.
This class provides a single static method getSignature(BaseName) which returns a unique signature string for the BaseName. Two BaseName instances which have the same data string and a scope consisting of the same set of Topic instances will return equal signature strings.
The static method ScopeUtils.areEquivalent(Set, Set) returns true if the two specified Sets of Topic instances are considered equivalent according to the Scope equality principle defined in XTM 1.0.
The static method getSignature(Set) returns a unique signature string for the specified Set of Topic instances. Two Sets consisting of the same set of Topic instances from the same TopicMap will return equal signature strings.
The static method getThemesSignature(Collection) returns a signature string which is unique for all distinct collection of theme Topics.
The org.tm4j.topicmap.utils.TopicMapFragment class is a helper class for extracting a small subset of objects from one TopicMap and copying them into another (usually empty) target TopicMap.
A TopicMapFragment is constructed by specifying the target TopicMap into which objects will be copied and the radius of the fragment. Once created, Topic or Association objects may be added from a source TopicMap to the TopicMapFragment. For each Topic or Association added, a subset of the source TopicMap will be copied to the target TopicMap.
The size of the copied subset is governed by two parameters. The first parameter is the maxRadius parameter passed to the constructor of the TopicMapFragment. This determines the maximum number of "hops" that can be counted from an added Topic or Association when copying it into the destination. The second parameter is the depth parameter passed to the TopicMapFragment.addTopic() or TopicMapFragment.addAssociation() methods. This parameter governs how many hops the copying algorithm should consider to have already been taken when the object is added.
When a Topic is added, the following algorithm is applied.
Perform a deep copy of the Topic from the source topic map to the destination topic map. This copies all names, occurrences, subject and subject indicators from the source topic map to the destination topic map. The types of the topic are copied as "shallow" copies which are a minimal copy consisting of just the subject, subject indicators and base names of the source typing topics.
If the depth at which the Topic was added is less than the value of the maxRadius parameter passed to the TopicMapFragment constructor then:
Add each typing topic to the fragment at the current + 1.
Add each Association in which the Topic plays a role at the current depth.
When an Association is added, the following algorithm is applied:
Make a shallow copy of the Association from the source topic map to the destination topic map. A shallow copy means that the role-playing and type and role-specifing topics are all made as shallow copies.
If the (current depth + 1) the value of the maxRadius parameter passed to the TopicMapFragment constructor then:
For each Member child of the Association, add the role-specifying topic and all role-playing topics at the current depth + 1.
This copying procedure will attempt to preserve the ID values of the source objects in the destination topic map, the ID values will only be modified if they clash with existing IDs in the destination topic map.
A typical use for the TopicMapFragment is to create a small results set to pass from a topic map server to a client which has requested a specific topic or set of topics. In this case, the recommended settings are a maxRadius of 1 and a depth of 0 for the result objects. This means that a topic is copied with all of its types also being deep copied and all of the topics it is related to being shallow copied; and an association is copied with all of its role-playing and role-specifying topics being deep copied.