This paper introduces a new, event-based API to create topic maps. It is independent of particular Topic Maps processors and enables developers to convert any resource into a Topic Maps representation with minimal e?ort. The API is somewhat aligned to the "push-model" of the familiar Simple API for XML (SAX) and is therefore easy to learn. It has been implemented for different programming languages and supplements APIs like the object-orientated Topic Maps API (TMAPI).

1. Streaming
Topic Maps API
An event-based API to create
topic maps
Lars Heuer <heuer@semagia.com>
TMRA 2008, Leipzig · 17.10.2008

2. Table of Contents
Introduction
Overview
Architecture
Details
Outlook
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 2

3. Introduction
TMAPI is the Document Object Model (DOM) for
Topic Maps
Even if TMAPI is Topic Maps engine independent, a
deserializer would be TMAPI dependent
TMAPI is programming language dependent (even if
TMAPI has been ported to several languages)
Relative heavy API (a lot of factory methods)
Streaming Topic Maps API uses a push model
(more aligned to the Simple API for XML (SAX))
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 3

4. Overview
A parser notifies a handler about events
IMapHandler interface provides notification methods
for all TMDM facets:
startTopicMap
endTopicMap
startTopic
endTopic
startAssociation
endAssociation
startReifier
endReifier
... (32 callback methods)
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 4

5. Architecture
CTM Parser XTM Parser N3 Parser CSV Parser … Parser
sends events to
IMapHandler
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 5

6. Architecture
CTM Parser XTM Parser N3 Parser CSV Parser … Parser
sends events to
IMapHandler
implemented by
TMAPI RDF API … API
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 6

7. Details – IMapHandler
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 7

8. Details
IMapHandler provides 32 callback methods to cover
all aspects of TMDM
Each TMDM construct is introduced by a quot;startquot;
event and terminated by an quot;endquot; event
Subject identifiers, subject locators and item
identifiers are reported as absolute IRIs (strings)
IRefs are used for quot;startTopic(ref)quot; and
quot;topicRef(ref)quot; notifications, they provide the
absolute IRI (string) and the kind of identity
IMapHandler provides nested events (i.e. startTopic
followed by another startTopic event) iff the events
cannot be misinterpreted
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 8

9. Details
IMapHandler is reponsible to detect merging
situtations
Parser simply fires events and forgets
afterwards
IMapHandler usually keeps a stack of objects
/ states to interpret the events correctly
Events are sometimes context dependent,
i.e. quot;start/endTypequot;, quot;start/endScopequot;,
quot;start/endReifierquot;, …
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 9

10. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 10

11. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
startTopic(ItemIdentifier http://example.org/map#EricClapton)
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 11

12. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
startName()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 12

13. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
value(quot;Eric Claptonquot;)
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 13

14. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
endName()
endTopic()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 14

15. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
startAssociation()
startType()
topicRef(ItemIdentifier http://example.org/map#created)
endType()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 15

16. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
startRole()
startType()
topicRef(ItemIdentifier http://example.org/map#creator)
endType()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 16

17. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
startPlayer()
topicRef(ItemIdentifier http://example.org/map#EricClapton)
endPlayer()
endRole()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 17

18. Details – Parsing Example
EricClapton – quot;Eric Claptonquot;.
created(creator: EricClapton,
work: JustOneNight)
... other role
endAssociation()
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 18

19. Details – Stackability
Parser
IMapHandler
delegates to
IMapHandler IMapHandler
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 19

20. Details – SimpleMapHander
Parser has to send a lot of start/end events
Some syntaxes do not provide nested topics etc.
SimpleMapHandler is a wrapper around any
IMapHandler implemention
SimpleMapHandler provides additional methods like
quot;type(IRef ref)quot;, quot;player(IRef ref)quot;, quot;reifier(IRef ref)quot;…
These events are translated to the common
IMapHandler callback methods
Example:
player(IRef) startPlayer(), topicRef(IRef),
endPlayer()
Simplifies parser development
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 20

21. Details – MIO Framework
MIO (Map Input / Output) is built around the
IMapHandler and provides a Service Provider
Interface for registering IDeserializers
All IDeserializers use the IMapHandler for event
notification
Discovery of a suitable IDeserializer by file
extension, media type
Introduces some constraints: I.e. a subdeserializer
(i.e. merging XTM encoded topic map into a CTM
encoding topic map) must not send a
start/endTopicMap event
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 21

22. Conclusions / Outlook
Simplifies parser development because the parser
simply fires events and does not care about merging
constraints etc.
IMapHandler concept has been implemented in
Java, Python (Mappa) and PHP (QuaaxTM)
IMapHandler and MIO (Map Input/Output) will
become Open Source soon
Streaming Topic Maps API should be controlled /
adapted by the community (i.e. by the TMAPI
project)
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 22

23. References
TMAPI
http://www.tmapi.org/
TMAPI 2.0
http://www.tmapi.org/2.0/
tinyTiM
TMAPI 1.0 / TMAPI 2.0 Topic Maps engine
http://tinytim.sourceforge.net/
Mappa
Python Topic Maps engine (not finished)
http://mappa.googlecode.com/
MIO (Map I/O)
http://mio.semagia.com/
QuaaxTM
http://quaaxtm.sourceforge.net/
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 23

24. Discussion
Questions?
Answers! ☺
© 2008 Lars Heuer · http://www.semagia.com TMRA 2008, Leipzig · 17.10.2008 24