[tmapi-commit] SF.net SVN: tmapi:[68] trunk/TMAPI-1.0_MIGRATION.txt

[<lh...@us...>]

Revision: 68
          http://tmapi.svn.sourceforge.net/tmapi/?rev=68&view=rev
Author:   lheuer
Date:     2008-08-20 15:09:23 +0000 (Wed, 20 Aug 2008)

Log Message:
-----------
Added TMAPI 1.0 -> 2.0 changes doc

Added Paths:
-----------
    trunk/TMAPI-1.0_MIGRATION.txt

Added: trunk/TMAPI-1.0_MIGRATION.txt
===================================================================
--- trunk/TMAPI-1.0_MIGRATION.txt	                        (rev 0)
+++ trunk/TMAPI-1.0_MIGRATION.txt	2008-08-20 15:09:23 UTC (rev 68)
@@ -0,0 +1,104 @@
+===================
+TMAPI 1.0 Migration
+===================
+
+This document enumerates some important changes between TMAPI 1.0 and 2.0.
+
+
+Changes in core
+---------------
+
+TMAPI 2.0 introduces several generalized interfaces like ``Reifiable``, 
+``Typed``, ``Scoped``, and ``DatatypeAware``. These interfaces avoid redundant 
+method declaration (i.e. ``setType()`` / ``getType()``, ``setValue()`` / 
+``getValue()``, et al.). 
+
+Additionally, the ``ConfigurableHelperObject`` was eliminated since it was only 
+utilized by the ``Index`` interface. The indices are now available by simply 
+calling ``TopicMap.getIndex(Class<I> indexInterface)``. As one objective of 
+TMAPI 2.0 is to enforce TMDM constraints, it is more restrictive than its 
+predecessor concerning model constraints (i.e. disallows 
+``Role.setPlayer(null)``). The naming in TMAPI 2.0 is simplified for 
+convenience:
+
+    * TopicName is called Name 
+    * AssociationRole is called Role 
+    * TopicMapsConstruct is called Construct (TMAPI 1.0's equivalent is 
+      TopicMapObject)
+
+
+Changes in index
+----------------
+
+The main changing covers the reduction to only three indices:
+
+    * TypeInstanceIndex
+    * ScopedIndex
+    * LiteralIndex
+
+This approach distances from a single construct view to a generalized view on a 
+topic map ("literal view", "typed view", and "scoped view"). From these views 
+specific constructs can be accessed (i.e. return all associations in scope x).
+
+Topic Maps constructs are available in multiple indices, i.e. ``Occurrence`` in 
+``TypeInstanceIndex``, ``ScopedIndex``, and ``LiteralIndex``. The reduction to 
+three indices makes reindexing and / or syncronization more expensive: I.e. a 
+Type- InstanceIndex.reindex() operation has to resync the information about 
+topics, associations, roles, occurrences, and names, while a TMAPI 1.0 
+``AssociationsIndex.reindex()`` would only update the information about 
+associations. However the project members believe that ``Index`` implementations 
+will rather realize constant syncronization. The ``IndexFlags`` interface was 
+abolished. Its only method ``isAutoUpdated()`` is now available in the ``Index`` 
+interface.
+
+
+Specific Changes (constructs level)
+-----------------------------------
+* DatatypeAware
+  Is the superinterface for Occurrence and Variant. Therefore it provides 
+  several methods for value assignments. It requires the Topic Maps processor to 
+  set the datatype implicitly to xsd:string in setValue(String value) and to 
+  xsd:anyURI in setValue(Locator value). For convenience, it offers several 
+  other methods to set and read values where the datatype is implicitly assigned 
+  and introduces setValue(String value, Locator datatype) in order to be 
+  consistent with TMDM's concept of datatypes; getDatatype() returns the Locator 
+  identifying the datatype of the value.
+
+* Topic
+  Provides filter methods ``getRolesPlayed(Topic type)``, ``getNames(Topic 
+  type)``, ``getOccurrences(Topic type)`` which return only those constructs 
+  which have the specified type. Further, various factory methods for ``Name`` 
+  and ``Occurrence`` are provided, inter alia a method for creating names with 
+  the default name type (a Topic with subject identifier 
+  <http://psi.topicmaps.org/iso13250/model/topic-name>).
+
+* Variant
+  Returns the union of its own scope and the parent's (Name) scope in getScope()
+  (this has also to be considered in ``ScopedIndex.getVariants(Topic[] themes, boolean matchAll)``).
+
+* Association
+  Does not allow ``null`` for role player and type assignments Further, 
+  ``getRoleTypes()`` and a method ``getRoles(Topic type)`` to filter the 
+  association roles is provided.
+
+* Role
+  Does not allow to set the role player and type to ``null``.
+
+* TopicMap
+  Provides ``getTopicBySubjectIdentifier(Locator)`` and 
+  ``getTopicBySubjectLocator(Locator)`` (moved from the TMAPI 1.0 TopicIndex 
+  package). Even more importantly, the TopicMap interface does not allow to 
+  create topics without any identity, such as an item identifier, a subject 
+  identifier, or subject locator (non-transparent ``createTopic()`` enforces the 
+  Topic Maps system to assign an item identifier internally).
+
+* TopicMapSystemFactory
+  Does no more provide ``setProperties(Properties props)``; properties are set 
+  by calling ``setProperty(String propertyName, Object value)``.
+
+* Locator
+  Introduces IRI notation (TMAPI 1.0's Locator used URI notation).
+
+* Exceptions
+  Methods where ``null`` is not a valid argument throw 
+  ``ModelConstraintException`` in core, ``IllegalArgumentException`` in index.


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.