Moving between TMAPI and TM4J APIs

The TM4J implementation of TMAPI uses "wrapper" objects that implement the TMAPI interfaces using TM4J API calls. All of the TM4J implementations of the org.tmapi.core package use this pattern. The helper class org.tm4j.tmapi.helpers.Wrapper can be used to retrieve the wrapped TM4J object - that object can then be used in TM4J API calls. The Wrapper class also provides methods to wrap a TM4J object (e.g. one returned from a tolog query) in a TMAPI shell so that it can be used in TMAPI methods.

The details of the Wrapper class methods can be found in the Javadoc, but there are a few features to point out here.

All Wrapping must be done in the context of a TopicMap or TopicMapSystem.  TMAPI objects are required to be able to return a pointer to their containing TMAPI TopicMap and the TMAPI TopicMap is required to be able to return a pointer to its containing TMAPI TopicMapSystem. These requirements mean that the wrap() methods require the TMAPI TopicMap instance to be specified for all items other than a TopicMap (for which the TMAPI TopicMapSystem) must be specified. This means that you must have established a proper TopicMapSystem instance (as detailed above) before attempting to wrap items from any TM4J TopicMap that is contained in that TMAPI TopicMapSystem.

Collections are always wrapped as Sets.  The Wrapper class provides a single method wrap(Collection) to wrap collections. This method wraps all of the items in the input Collection and returns the wrapped objects as a Set.

TM4J Member != TMAPI AssociationRole.  In TM4J the Member interface allows a single Member to contain many players. In TMAPI an AssociationRole contains only a single player and XTM member elements that contain multiple topicRef or subjectIndicatorRef elements are represented in TMAPI as multiple AssociationRole objects. This means that the unwrap(AssociationRole) method may return a Member object with more than one value for the players property, and also that the wrap method that returns an AssociationRole requires both the Member and the Topic that is the role player to be specified as parameters.