The document introduces TMAPI 2.0, an updated version of the Topic Maps Application Programming Interface. It provides an agenda for the presentation, introduces the presenters, and discusses the background, status and purpose of TMAPI 2.0. It also provides hands-on examples for creating topic maps, topics, occurrences, names and associations using both the Java and PHP implementations of TMAPI 2.0.

1. TMAPI 2.0
Lars Heuer and Johannes
Schmidt

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. Who will bore you the next 3h? ;)
Johannes Schmidt Lars Heuer
js@sixgroups.com heuer@semagia.com
http://sixgroups.com/ http://www.semagia.com/
• 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. 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. 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. 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. 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. Status of TMAPI 2.0
• Currently Alpha
o See http://www.tmapi.org/2.0/
• tinyTiM 2.0 the only engine which supports TMAPI
2.0 at the moment
o See http://tinytim.sourceforge.net/
• PHPTMAPI 2.0: proposal published
o UML class diagrams
o Interfaces (in SVN)
o API docs
o See http://phptmapi.wiki.sourceforge.net/
• C# translation in the works (maybe Stefan can give
us an update :)

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. 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. 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. 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. Introduction into TMAPI
TMAPI 2.0 core (abbreviated UML class diagrams)

14. Hands-on TMAPI 2.0
• Full experience: Java with tinyTiM 2.0
o Get it here: http://tinytim.sourceforge.net/
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: http://phptmapi.sourceforge.net/tmra/
(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. Hands-on TMAPI -- API Docs
• For all details have a look at the API docs
o Java: http://www.tmapi.org/2.0/api/
o PHP: http://phptmapi.sourceforge.net/2.0/docs/
... and we like questions :)

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. Hands-on TMAPI -- TMSystem
• Create a TopicMapSystem
o Java:
TopicMapSystem tmSys =
tmSysFactory.newTopicMapSystem();
o PHP:
$tmSys = $tmSysFactory->newTopicMapSystem();

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;http://tmra.de/tmapi-
tutorialquot;);
o PHP:
$tm = $tmSys->createTopicMap(quot;http://tmra.de/
tmapi-tutorialquot;);

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;http://en.wikipedia.org/John_Len
nonquot;);
Topic john =
tm.createTopicBySubjectIdentifier(sid);
o PHP:
$john = $tm->createTopicBySubjectIdentifier
(quot;http://en.wikipedia.org/John_Lennonquot;);

20. Hands-on TMAPI -- Topics
• Creating a topic by a subject locator:
o Java:
Locator slo =
tm.createLocator(quot;http://www.google.comquot;);
Topic google =
tm.createTopicBySubjectLocator(slo);
o PHP:
$slo = quot;http://www.google.comquot;; // or pass the
string directly as parameter
$google =
$tm->createTopicBySubjectLocator($slo);

21. Hands-on TMAPI -- Topics
• Creating a topic by an item identifier:
o Java:
Locator iid =
tm.createLocator(quot;http://www.example.org/map#ii
d1quot;);
Topic aTopic = tm.createTopicByIdentifier(iid);
o PHP: Not yet implemented in the prototype.
• Second example, see next slide.

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. 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;http://en.wikipedia.org/John_Lennonquot; 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. 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. 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. 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;http://www.google.com/quot;);
Occurrence occ = t.createOccurrence(website,
value); // the occurrence will automatically have
the datatype xsd:anyURI

27. Hands-on TMAPI -- Occurrences
• PHP: You have to define the datatype explicitly
o $topic->createOccurrence($website,
quot;http://www.google.com/quot;,
VocabularyUtils::XSD_ANYURI);
VocabularyUtils::XSD_ANYURI =
quot;http://www.w3.org/2001/XMLSchema#anyURIquot;

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. 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. 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. Questions so far?
... from now on it's your turn :)

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. Hands-on TMAPI
This could be an inspiration for usage of Types:
http://www.ontopia.net/omnigator/models/topicmap_complete.jsp?tm=jill.xtm

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. 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. Questions and feedback
Do you have questions and/or feedback?

37. References
• TMAPI
http://www.tmapi.org/
TMAPI 2.0
http://www.tmapi.org/2.0/
• TM4J
TMAPI 1.0 implementation
http://tm4j.sourceforge.net/
• tinyTiM
TMAPI 1.0 / 2.0 implementation
http://tinytim.sourceforge.net/
• TMDM
Topic Maps – Data Model
http://www.isotopicmaps.org/sam/sam-model/

38. References
• PHPTMAPI
Port of TMAPI 1.0 / 2.0 to PHP5
http://sourceforge.net/phptmapi
• QuaaxTM
Topic Maps engine that implements PHPTMAPI
http://quaaxtm.sourceforge.net/
• TMAPI 4 .NET
Port of TMAPI 2.0 to C#
http://sourceforge.net/projects/tmapinet
• TM4L Editor
Topic Maps editor using TMAPI 1.0
http://compsci.wssu.edu/iis/nsdl/download.html