Embed Size (px)
DESCRIPTION
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.
Citation preview
TMAPI 2.0
Lars Heuer and Johannes Schmidt
Agenda
• Let's introduce :)• Background
o Purpose and historyo 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 :)
Who will bore you the next 3h? ;)
Johannes [email protected] http://sixgroups.com/• Co-Creator TMAPI 2.0
(but no Java Programmer ;)
• Maintainer PHPTMAPI• Maintainer QuaaxTM
Lars [email protected]://www.semagia.com/• Member of TMAPI since
v1.0• Co-Creator of TMAPI 2.0• Maintainer tinyTiM
1.5/2.0• Co-Editor CTM 1.0 (ISO
13250-6 - Compact Syntax)
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
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
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).
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).
Status of TMAPI 2.0
• Currently Alphao See http://www.tmapi.org/2.0/
• tinyTiM 2.0 the only engine which supports TMAPI 2.0 at the momento See http://tinytim.sourceforge.net/
• PHPTMAPI 2.0: proposal published o UML class diagramso Interfaces (in SVN)o API docso See http://phptmapi.wiki.sourceforge.net/
• C# translation in the works (maybe Stefan can give us an update :)
Introduction into TMAPI
• Factories o TopicMapSystemFactory creates TopicMapSystemso TopicMapSystem creates TopicMapo TopicMap creates Topics/Associationso Topic create Occurrences/Nameso Name creates Variantso Association creates Roles
• Each parent creates its children, it is not possible to create a "detached" topic name which is later added to a topic.
Introduction into TMAPI
• TopicMapSystemFactoryFactory to create TopicMapSystemso Configure TopicMapSystemso Some features like "automerge" (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.
Introduction into TMAPI
• TopicMapSystemRepository of topic maps which holds a collection of topic mapso Allows retrieval of topic maps.o Allows the creation of topic maps (if the
TopicMapSystem was not configured in read-only modus).
Introduction into TMAPI
• ConstructThe main interface from which all interfaces are derived; provides navigation to the constructs parent and manipulation of item identifiers.
• TopicMapMain interface which provides access to topics, associations, and the indexes.
• Topico Occurrenceo Name
Variant• Association
o Role
Introduction into TMAPI
TMAPI 2.0 core (abbreviated UML class diagrams)
Hands-on TMAPI 2.0
• Full experience: Java with tinyTiM 2.0o 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 prototypeo 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 ;)
Hands-on TMAPI -- API Docs
• For all details have a look at the API docso Java: http://www.tmapi.org/2.0/api/o PHP: http://phptmapi.sourceforge.net/2.0/docs/
... and we like questions :)
Hands-on TMAPI -- TMSysFactory
• Create a TopicMapSystemFactoryo Java:
TopicMapSystemFactory tmSysFactory = TopicMapSystemFactory.newInstance();
o PHP:$tmSysFactory = TopicMapSystemFactory::newInstance();
• Configure the factoryo Java: Skipped here, not necessary (for tinyTiM).o PHP: Skipped here, not implemented yet.
Hands-on TMAPI -- TMSystem
• Create a TopicMapSystemo Java:
TopicMapSystem tmSys = tmSysFactory.newTopicMapSystem();
o PHP:$tmSys = $tmSysFactory->newTopicMapSystem();
Hands-on TMAPI -- TopicMap
• Create a topic mapA TopicMap instance is simply a container for topics and associationso Java:
TopicMap tm = tmSys.createTopicMap("http://tmra.de/tmapi-tutorial");
o PHP:$tm = $tmSys->createTopicMap("http://tmra.de/ tmapi-tutorial");
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("http://en.wikipedia.org/John_Lennon");Topic john = tm.createTopicBySubjectIdentifier(sid);
o PHP:$john = $tm->createTopicBySubjectIdentifier ("http://en.wikipedia.org/John_Lennon");
Hands-on TMAPI -- Topics
• Creating a topic by a subject locator:o Java:
Locator slo = tm.createLocator("http://www.google.com");Topic google = tm.createTopicBySubjectLocator(slo);
o PHP: $slo = "http://www.google.com"; // or pass the string directly as parameter $google = $tm->createTopicBySubjectLocator($slo);
Hands-on TMAPI -- Topics
• Creating a topic by an item identifier:o Java:
Locator iid = tm.createLocator("http://www.example.org/map#iid1");Topic aTopic = tm.createTopicByIdentifier(iid);
o PHP: Not yet implemented in the prototype. • Second example, see next slide.
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).
Hands-on TMAPI -- Topics
• Using this method is not recommended!• The "createTopicBy..." methods may return an
already existing topic.• If you try to create a topic with the item identifier
"http://en.wikipedia.org/John_Lennon" 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).
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.
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 "strong" 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!
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).
• OccurrencesOccurrences have a value and a datatypeo Java:
Locator value = tm.createLocator("http://www.google.com/");Occurrence occ = t.createOccurrence(website, value); // the occurrence will automatically have the datatype xsd:anyURI
Hands-on TMAPI -- Occurrences
• PHP: You have to define the datatype explicitlyo $topic->createOccurrence($website,
"http://www.google.com/", VocabularyUtils::XSD_ANYURI);
VocabularyUtils::XSD_ANYURI = "http://www.w3.org/2001/XMLSchema#anyURI"
Hands-on TMAPI -- Names
Creating a name• Using the default name type
o Java:Name name = john.createName("John Lennon");
o PHP:$name = $john->createName("John Lennon");
• Using an explicit name typeo Java:
Name forename = john.createName(forename, "John");
o PHP:$forename = $john->createTypedName ($forename, "John");
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);
Hands-on TMAPI -- Modelling Type-Instance AssociationsFor 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);
Questions so far?
... from now on it's your turn :)
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 "Tutorial" first before you create a "TMAPI Tutorial" :)
*Usage of TopicMap.createTopicBySubjectIdentifier(IRI) is a good idea here.
Hands-on TMAPI
This could be an inspiration for usage of Types:http://www.ontopia.net/omnigator/models/topicmap_complete.jsp?tm=jill.xtm
Hands-on TMAPI -- Reification
• "The act of reification is the act of making a topic represent the subject of another topic map construct in the same topic map." (TMDM)o Quite simple with TMAPI: setReifier(Topic reifier).o Retrieve the reifier: getReifier().
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 :(
Questions and feedback
Do you have questions and/or feedback?
References
• TMAPIhttp://www.tmapi.org/TMAPI 2.0http://www.tmapi.org/2.0/
• TM4JTMAPI 1.0 implementationhttp://tm4j.sourceforge.net/
• tinyTiMTMAPI 1.0 / 2.0 implementationhttp://tinytim.sourceforge.net/
• TMDM Topic Maps – Data Model http://www.isotopicmaps.org/sam/sam-model/
References
• PHPTMAPIPort of TMAPI 1.0 / 2.0 to PHP5http://sourceforge.net/phptmapi
• QuaaxTMTopic Maps engine that implements PHPTMAPIhttp://quaaxtm.sourceforge.net/
• TMAPI 4 .NETPort of TMAPI 2.0 to C#http://sourceforge.net/projects/tmapinet
• TM4L EditorTopic Maps editor using TMAPI 1.0http://compsci.wssu.edu/iis/nsdl/download.html
