TMAPI 2.0 tutorial


Published on

TMAPI 2.0 is new generation of the common Topic Maps API. This tutorial gives an introduction into the changes between TMAPI 1.0 and 2.0 (Java) and demonstrates the API by several examples. Further, this tutorial will give an outlook how TMAPI was adapted to other programming languages (i.e. PHP5). Attendees are expected to have a good understanding of the Topic Maps Data Model (TMDM) and some experience with Java.

Published in: Technology, Education
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

TMAPI 2.0 tutorial

  1. 1. TMAPI 2.0 Lars Heuer and Johannes Schmidt
  2. 2. Agenda • Let's introduce :) • Background o Purpose and history o The need for TMAPI 2.0 • Status of TMAPI 2.0 • Theoretical introduction into TMAPI (short) • Hands-on TMAPI 2.0 (let's focus on that) • Questions and feedback      Experience TMAPI 2.0 by trying it out :)
  3. 3. Who will bore you the next 3h? ;) Johannes Schmidt Lars Heuer • Co-Creator TMAPI 2.0 • Member of TMAPI since (but no Java v1.0 Programmer ;) • Co-Creator of TMAPI 2.0 • Maintainer PHPTMAPI • Maintainer tinyTiM • Maintainer QuaaxTM 1.5/2.0 • Co-Editor CTM 1.0 (ISO 13250-6 - Compact Syntax)
  4. 4. Purpose • Common API to work with topic maps • Topic Maps engine independent: Applications implemented against TMAPI can use any Topic Maps engine which implements TMAPI.  • De facto standard API - however outside a standards body
  5. 5. Purpose • Provision of a set of Java interfaces • Provision of UML class diagrams used as boilerplate for the interfaces, and also for translations to other OO-languages • Provision of a test suite to ensure conformity
  6. 6. History • TMAPI 1.0 o Released 2004/2005. o Abstracts from XTM 1.0 and implements some TMDM features, but is not completely TMDM compatible. o Supported by several Topic Maps engines (Open Source and commercial). o TM4L Editor switched from TM4J to TMAPI. o Ported to PHP5 (PHPTMAPI 1.0) and C# (state unknown).
  7. 7. The need for TMAPI 2.0 • TMDM compatibility (and observance of TMDM constraints to some extent) • User friendliness • Convenience     Our TMRA 2008 paper describes the changes vs. TMAPI 1.0 in detail (TMAPI 2.0 comes with a raw enumeration).
  8. 8. Status of TMAPI 2.0 • Currently Alpha o See • tinyTiM 2.0 the only engine which supports TMAPI 2.0 at the moment o See • PHPTMAPI 2.0: proposal published o UML class diagrams o Interfaces (in SVN) o API docs o See • C# translation in the works (maybe Stefan can give us an update :)
  9. 9. Introduction into TMAPI • Factories o TopicMapSystemFactory creates TopicMapSystems o TopicMapSystem creates TopicMap o TopicMap creates Topics/Associations o Topic create Occurrences/Names o Name creates Variants o Association creates Roles • Each parent creates its children, it is not possible to create a quot;detachedquot; topic name which is later added to a topic.
  10. 10. Introduction into TMAPI • TopicMapSystemFactory Factory to create TopicMapSystems o Configure TopicMapSystems o Some features like quot;automergequot; (merge topics automatically and transparently for the user) are predefined by TMAPI. o Each Topic Maps engine may define a set of special features. o All TopicMapSystems created by the factory use the same configuration.
  11. 11. Introduction into TMAPI • TopicMapSystem Repository of topic maps which holds a collection of topic maps o Allows retrieval of topic maps. o Allows the creation of topic maps (if the TopicMapSystem was not configured in read-only modus).
  12. 12. Introduction into TMAPI • Construct The main interface from which all interfaces are derived; provides navigation to the constructs parent and manipulation of item identifiers. • TopicMap Main interface which provides access to topics, associations, and the indexes. • Topic o Occurrence o Name  Variant • Association o Role
  13. 13. Introduction into TMAPI TMAPI 2.0 core (abbreviated UML class diagrams)
  14. 14. Hands-on TMAPI 2.0 • Full experience: Java with tinyTiM 2.0 o Get it here: o Install: Put the TMAPI and tinyTiM jars in your classpath, ask Lars in case of problems. o Works in memory. • Limited experience*: PHP5 with a QuaaxTM prototype o Get it here: (User: tmra, Password: tmapi) o Install: Have a look at the resource given above or ask Johannes. o Works on a MySQL database.   *PHPTMAPI 2.0 is really brand-new ;)
  15. 15. Hands-on TMAPI -- API Docs • For all details have a look at the API docs o Java: o PHP:     ... and we like questions :)
  16. 16. Hands-on TMAPI -- TMSysFactory • Create a TopicMapSystemFactory o Java: TopicMapSystemFactory tmSysFactory =   TopicMapSystemFactory.newInstance(); o PHP: $tmSysFactory = TopicMapSystemFactory::newInstance(); • Configure the factory o Java: Skipped here, not necessary (for tinyTiM). o PHP: Skipped here, not implemented yet.
  17. 17. Hands-on TMAPI -- TMSystem • Create a TopicMapSystem o Java: TopicMapSystem tmSys = tmSysFactory.newTopicMapSystem(); o PHP: $tmSys = $tmSysFactory->newTopicMapSystem();
  18. 18. Hands-on TMAPI -- TopicMap • Create a topic map A TopicMap instance is simply a container for topics and associations o Java: TopicMap tm = tmSys.createTopicMap(quot; tutorialquot;); o PHP: $tm = $tmSys->createTopicMap(quot; tmapi-tutorialquot;);
  19. 19. Hands-on TMAPI -- Topics • Topics are either created via a subject identifier, a subject locator, or an item identifier. • Creating a topic by a subject identifier: o Java: Locator sid = tm.createLocator(quot; nonquot;); Topic john = tm.createTopicBySubjectIdentifier(sid); o PHP: $john = $tm->createTopicBySubjectIdentifier (quot;;);
  20. 20. Hands-on TMAPI -- Topics • Creating a topic by a subject locator: o Java: Locator slo =               tm.createLocator(quot;;); Topic google = tm.createTopicBySubjectLocator(slo); o PHP: $slo = quot;;; // or pass the string directly as parameter                           $google = $tm->createTopicBySubjectLocator($slo);
  21. 21. Hands-on TMAPI -- Topics • Creating a topic by an item identifier: o Java: Locator iid = tm.createLocator(quot; d1quot;); Topic aTopic = tm.createTopicByIdentifier(iid); o PHP: Not yet implemented in the prototype.   • Second example, see next slide.
  22. 22. Hands-on TMAPI -- Topics • Creating a topic by an automatically generated item identifier: o Java: Topic aTopic = tm.createTopic(); assert aTopic.getItemIdentifiers().size() == 2 o PHP: $aTopic = $tm->createTopic();   • The Topic Maps engine ensures that the topic will get an item identifier and takes care that this item identifier does not make the topic equal to another topic (at least in the topic map which generated that identifier).
  23. 23. Hands-on TMAPI -- Topics • Using this method is not recommended! • The quot;createTopicBy...quot; methods may return an already existing topic. • If you try to create a topic with the item identifier quot;; and a topic with the same subject identifier exists, you'll get the already existing topic (the topic may get an additional item identifier if it does not exist yet).
  24. 24. Hands-on TMAPI -- Topics • Rules: o BySubjectIdentifier/byItemIdentifier: If a topic with the specified subject identifier or an item identifier equals to the specified locator exists, return the existing topic. o BySubjectLocator: If a topic with the specified subject locator exists, return the existing topic.
  25. 25. Hands-on TMAPI -- Topics Summary for creating topics • An explicit identity (subject identifier, subject locator, or item identifier) is preferred. Subject identifiers and subject locators are quot;strongquot; identities, while item identifiers are not. • Automatically generated item identifiers should be avoided since this feature is Topic Maps engine dependent and they are not necessarily globally unique (GUID). • Best practice: Use an explicit identity!
  26. 26. Hands-on TMAPI -- Occurrences • First of all you need a topic to which you want to create occurrences (occurrences are always bound to a topic, you cannot detach/attach them). • Occurrences Occurrences have a value and a datatype o Java: Locator value =  tm.createLocator(quot;;); Occurrence occ = t.createOccurrence(website, value); // the occurrence will automatically have the datatype xsd:anyURI
  27. 27. Hands-on TMAPI -- Occurrences • PHP: You have to define the datatype explicitly o $topic->createOccurrence($website, quot;;, VocabularyUtils::XSD_ANYURI);   VocabularyUtils::XSD_ANYURI =  quot;;
  28. 28. Hands-on TMAPI -- Names Creating  a name • Using the default name type o Java: Name name = john.createName(quot;John Lennonquot;); o PHP: $name = $john->createName(quot;John Lennonquot;); • Using an explicit name type o Java: Name forename = john.createName(forename, quot;Johnquot;); o PHP: $forename = $john->createTypedName ($forename, quot;Johnquot;);
  29. 29. Hands-on TMAPI -- Associations Associations are created by a TopicMap instance, they are automatically added to the topic map • Java: o Association memberOf =                           tm.createAssociation(memberOfTopic); Role role = memberOf.createRole(member, john); // member: Type of the role // john: Role player • PHP: o $memberOf =                           $tm->createAssociation($memberOfTopic); $role = $memberOf->createRole($member, $john);
  30. 30. Hands-on TMAPI -- Modelling Type- Instance Associations For type-instance relationships, the short-cut ● topic.addType(type); can be used. The Topic Maps engine decides if either an association is created or if the topic has a property which holds references to the types. Example: • Java: john.addType(person); • PHP: $john->addType($person);
  31. 31. Questions so far? ... from now on it's your turn :)
  32. 32. Hands-on TMAPI 2.0 • Create your own topic map: You should start with a conceptual model (Ontology), i.e. of this tutorial. o Create Topic Types (which are Topics), o Association Types (which are Topics), o Occurrence Types (which are Topics), o and Role Types (which are Topics too)*.   Example: Create quot;Tutorialquot; first before you create a quot;TMAPI Tutorialquot; :) *Usage of TopicMap.createTopicBySubjectIdentifier(IRI) is a good idea here.
  33. 33. Hands-on TMAPI This could be an inspiration for usage of Types:
  34. 34. Hands-on TMAPI -- Reification • quot;The act of reification is the act of making a topic represent the subject of another topic map construct in the same topic map.quot; (TMDM) o Quite simple with TMAPI: setReifier(Topic reifier). o Retrieve the reifier: getReifier().
  35. 35. Hands-on TMAPI -- Index • TMAPI 2.0 provides three indexes. o LiteralIndex: Retrieve constructs by their value and datatype. o ScopedIndex: Retrieve statements by their scope (and the statements' scopes). o TypeInstanceIndex: Retrieve constructs by their type (and the constructs' types). • Not yet available in the QuaaxTM prototype :(
  36. 36. Questions and feedback  Do you have questions and/or feedback?
  37. 37. References • TMAPI TMAPI 2.0 • TM4J TMAPI 1.0 implementation • tinyTiM TMAPI 1.0 / 2.0 implementation • TMDM Topic Maps – Data Model
  38. 38. References • PHPTMAPI Port of TMAPI 1.0 / 2.0 to PHP5 • QuaaxTM Topic Maps engine that implements PHPTMAPI • TMAPI 4 .NET Port of TMAPI 2.0 to C# • TM4L Editor Topic Maps editor using TMAPI 1.0