Containment and Object Creation and Removal

Understanding the TMCore containment hierarchy is the key to working with the TMCore API. In a TMCore system, every object is considered to be contained within one (and only one) other object. The hierarchy is based on types, so all ITopic instances are contained within an ITopicMap instance; all IOccurrence instances are contained within an ITopic instance and so on. The containment hieararchy is shown below:

The containment hierarchy is important in three respects, object creation, object removal and commits to the TMCore system.

An object can only be created as a child of its parent in the containment hierarchy. This means that there are no public constructors for any of the TMCore interfaces, instead you must use the method CreateXXX() on the parent object in the containment hierarchy where the XXX is replaced by the name of the type of object you wish to create. For example, to create a topic, call the method ITopicMap.CreateTopic() on the ITopicMap instance that will contain the new topic. Some of the CreateXXX() methods are overloaded to provide different ways of initialising the created object.

An object can never be detatched from its parent in the containment hiearchy. The only way to remove an object from its parent is to call the Remove() method on the object itself. The Remove() method not only removes the object from its parent, but also deletes it completely from the TMCore system.

Finally, when an object in the containment hierarchy is committed to the TMCore system using the Save() method, changes to all of its children in the containment hierarchy are also committed in a single transaction. The Save() method is provided on the ITopicMap, IAssociation and ITopic interfaces only, so to save a change to an ITopicName instance, you must call the Save() method on the containing ITopic instance.