rtm-activerecord 0.2.0

data/lib/rtm/activerecord/topic.rb

@@ -0,0 +1,204 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::AR
+  class Topic < Construct
+    include RTM::Topic
+    wrapper_cache
+    
+    # parent :topic_map
+    alias :parent :topic_map
+    property_set :subject_identifiers, :aka => [:si,:sid], :type => :SubjectIdentifier, :wrap => true,
+      #:create => :subject_identifier, :create_aka => [:csi,:csid],
+      #:create_args => [{:name => :reference, :type => :String}]
+      :add => :subject_identifier, :remove => :subject_identifier
+    alias :getSubjectIdentifiers :subject_identifiers
+    
+    property_set :subject_locators, :aka => [:sl,:slo], :type => :SubjectLocator, :wrap => true,
+      #:create => :subject_locator, :create_aka => [:csl, :cslo],
+      #:create_args => [{:name => :reference, :type => :String}]
+      :add => :subject_locator, :remove => :subject_locator
+    alias :getSubjectLocators :subject_locators
+
+    property :reified, :computable => true, :type => :Reifiable, :wrap => true
+
+    property_set :names, :aka => [:n, :topic_names], :type => :Name, :wrap => true,
+      :create => :name_internal, # :create_aka => [:create_topic_name, :cn], 
+      :create_args => [ {:name => :value, :type => :String}, {:name => :type, :type => :Topic, :optional => true}, {:name => :scope, :type => :Collection} ]
+    
+    alias :names_by :names # intermediate solution, check real TMAPI usage
+    
+    
+      def create_name(arg1,arg2 = :nothing, arg3 = :nothing)
+        if (arg2 == :nothing) && (arg3 == :nothing) #arg1 = value
+          raise "create_name(value): value must be a String" unless arg1.is_a?(String)
+          return create_name_internal(:value => arg1, :type => self.parent._topic_by_locator!(RTM::PSI[:name_type]))
+        end
+        if (arg3 == :nothing)
+          if arg2.is_a?(Array) #arg1 = value, arg2 = scope
+            raise "create_name(value, scope): value must be a String" unless arg1.is_a?(String)
+            arg2.each do |theme|
+              raise "create_name(value, scope): scope must be an Array of Topics/Topic-References" unless (theme.is_a?(String) || theme.is_a?(RTM::Topic) || theme.is_a?(RTM::Locator))
+            end
+            return arg2.empty? ? create_name_internal(:value => arg1) : create_name_internal(:value => arg1, :scope => self.parent._topic_by_locator!(arg2))
+          elsif arg2.is_a?(String) #arg1 = type, arg2 = value
+            raise "create_name(type, value): type must be a Topic/Topic-Reference" unless (arg1.is_a?(String) || arg1.is_a?(RTM::Topic) || arg1.is_a?(RTM::Locator))
+            return create_name_internal(:type => self.parent._topic_by_locator!(arg1), :value => arg2)
+          else
+            raise "create_name(?,?): arguments don't match"
+          end
+        end
+        #arg1 = type, arg2 = value, arg3 = scope
+        raise "create_name(type, value, scope): type must be a Topic/Topic-Reference" unless (arg1.is_a?(String) || arg1.is_a?(RTM::Topic) || arg1.is_a?(RTM::Locator))
+        raise "create_name(type, value, scope): value must be a String" unless arg2.is_a?(String)
+        raise "create_name(type, value, scope): scope must be an Array" unless arg3.is_a?(Array)
+        arg3.each do |theme|
+          raise "create_name(type, value, scope): scope must be an Array of Topics/Topic-References" unless (theme.is_a?(String) || theme.is_a?(RTM::Topic) || theme.is_a?(RTM::Locator))
+        end
+        return create_name_internal(:type => self.parent._topic_by_locator!(arg1), :value => arg2, :scope => self.parent._topic_by_locator!(arg3))
+      end
+      alias :cn :create_name
+      alias :create_topic_name :create_name
+
+    property_set :occurrences, :aka => :o, :type => :Occurrence, :wrap => true,
+      :create => :occurrence_internal, :create_aka => :co,
+      :create_args => [ {:name => :type, :type => :Topic}, {:name => :value, :type => [:String, :Locator]}, {:name => :scope, :type => :Collection} ]
+      
+    alias :occurrences_by :occurrences # intermediate solution, check real TMAPI usage
+      
+    def create_occurrence(type,value,params={})
+      if params[:scope]
+        if value.is_a?(RTM::Locator)
+          return create_occurrence_internal(topic_map.get!(type),value,topic_map._topic_by_locator!(params[:scope]), :datatype => RTM::PSI[:IRI])
+        elsif !params[:datatype]
+          return create_occurrence_internal(topic_map.get!(type),value,topic_map._topic_by_locator!(params[:scope]))
+        else # datatype given, no locator
+          return create_occurrence_internal(topic_map.get!(type),value,topic_map.create_locator(params[:datatype]),topic_map._topic_by_locator!(params[:scope]))
+        end
+      else #no scope
+        if value.is_a?(RTM::Locator)
+          return create_occurrence_internal(topic_map.get!(type),value, :datatype => RTM::PSI[:IRI])
+        elsif !params[:datatype]
+          return create_occurrence_internal(topic_map.get!(type),value, params)
+        else #datatype given, no locator
+          return create_occurrence_internal(topic_map.get!(type),value,topic_map.create_locator(params[:datatype]))
+        end
+      end
+    end
+
+    def characteristics(*args)
+      names(*args).to_a + occurrences(*args).to_a
+    end
+    alias :children :characteristics
+    alias :characteristics_by :characteristics # intermediate solution, check real TMAPI usage
+    
+    property_set :roles, :aka => [:r, :roles_played, :association_roles], :computable => true, :type => :Role, :wrap => true
+
+    def filter_roles(*args)
+      puts
+      puts "topic filter roles:"
+      puts args.inspect
+      if args.size == 1
+        a1 = args.shift
+        # if a1 == :any
+        #   a1 = nil
+        # end
+        role_type = topic_map.get(a1)
+        return self.roles unless role_type
+        if role_type.respond_to?(:each)
+          query_conditions = (["ttype_id = ?"] * role_type.size).join(" OR ")
+          puts
+          puts "qq:"
+          puts query_conditions
+          puts role_type.map{|rt| rt.id}
+          puts
+          return self.roles.find(:all,:conditions => [query_conditions, role_type.map{|rt| rt.id}])
+        else
+          return self.roles.find(:all,:conditions => ["ttype_id = ?", role_type.id])
+        end
+      elsif args.size == 2
+        role_type = args.shift
+        # if role_type == :any
+        #   role_type = nil
+        # end
+        role_type = topic_map.get(role_type)
+        
+        assoc_type = args.shift
+        # if assoc_type == :any
+        #   assoc_type = nil
+        # end
+        assoc_type = topic_map.get(assoc_type)
+        
+        if role_type && assoc_type
+          puts "trying to return topic.roles for #{role_type.inspect} and #{assoc_type.inspect}"
+          res = self.roles.find(:all, :conditions => ["roles.ttype_id = ? and associations.ttype_id = ?", role_type.id, assoc_type.id])
+          puts res.inspect
+          return res
+        elsif assoc_type
+          return self.roles.find(:all, :conditions => ["associations.ttype_id = ?", assoc_type.id])
+        elsif role_type
+          return self.roles.find(:all,:conditions => ["ttype_id = ?", role_type.id])
+        else
+          warn("Topic#roles got 2 arguments but doesn't know how to handle (or referenced topics where not found)")
+        end
+      end
+      false
+    end
+
+    property_set :associations, :aka => [:a, :associations_played], :type => :Association, :wrap => true
+
+    property_set :scoped, :aka => :scoped_objects, :type => :Construct, :wrap => true
+    property_set :scoped_associations, :type => :Association, :wrap => true
+    property_set :scoped_names, :aka => :scoped_topic_names, :type => :Name, :wrap => true
+    property_set :scoped_variants, :type => :Variant, :wrap => true
+    property_set :scoped_occurrences, :type => :Occurrence, :wrap => true
+
+    property_set :typed, :aka => :typed_objects, :type => :Construct, :wrap => true
+    property_set :typed_associations, :aka => [:ta,:associations_typed,:at], :type => :Association, :wrap => true
+    property_set :typed_roles, :aka => [:rt,:roles_typed,:association_roles_typed,:art,:rt], :type => :Role, :wrap => true
+    property_set :typed_names, :aka => [:nt,:names_typed,:topic_names_typed,:tnt,:nt], :type => :Name, :wrap => true
+    property_set :typed_occurrences, :aka => [:to,:occurrences_typed,:ot], :type => :Occurrence, :wrap => true
+    
+    def id
+      __getobj__.id
+    end
+
+    # class:Topic equality, http://www.isotopicmaps.org/sam/sam-model/#d0e1029
+    #
+    # This method is all crap. These ActiveRecord Arrays can't be intersected,
+    # so I map the identifiers to their reference which seems long winded.
+    # Still I find it better than using their ID in the long.
+    # 
+    def ==(o)
+      return false unless o
+      return false unless o.respond_to?(:subject_identifiers)
+      return false unless o.respond_to?(:subject_locators)
+      return false unless o.respond_to?(:names)
+      # Two topic items are equal if they have:
+      # * at least one equal string in their [subject identifiers] properties,
+      # -> test if intersection are > 0
+      my_si = self.subject_identifiers.map{|si| si.reference}
+      ot_si = o.subject_identifiers.map{|si| si.reference}
+      return true if ( my_si & ot_si).size > 0 
+
+      # * at least one equal string in their [item identifiers] properties,
+      my_ii = self.item_identifiers.map{|ii| ii.reference}
+      ot_ii = o.item_identifiers.map{|ii| ii.reference}
+      return true if (my_ii & ot_ii).size > 0 
+
+      # * at least one equal string in their [subject locators] properties,
+      my_sl = self.subject_locators.map{|sl| sl.reference}
+      ot_sl = o.subject_locators.map{|sl| sl.reference}
+      return true if (my_sl & ot_sl).size > 0 
+
+      # * an equal string in the [subject identifiers] property of the one topic item and the [item identifiers] property of the other, or
+      return true if (my_si & ot_ii).size > 0 
+      return true if (my_ii & ot_si).size > 0 
+
+      # * the same information item in their [reified] properties.
+      return true if self.reified != nil && o.reified != nil && (self.reified == o.reified)
+      # ... otherwise
+      false
+    end
+  end
+end

data/lib/rtm/activerecord/topic_map.rb

@@ -0,0 +1,435 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::AR
+  class TopicMap < Reifiable
+    include RTM::TopicMap
+    
+    def close 
+    end
+    
+    wrapper_cache
+    property_set :topics, :aka => :t, :type => :Topic, :wrap => true,
+      :create => :topic,  :create_aka => :ct
+     
+    property_set :associations, :aka => [:a, :assocs], :type => :Association, :wrap => true,
+      :create => :association_internal, :create_aka => :ca,
+      :create_args => [{:name => :type, :type => :Topic}]
+
+    def create_association(type, scope = :default)
+      raise "type must be a Topic or Topic-Reference" unless type.is_a?(RTM::Topic) || type.is_a?(String) || type.is_a?(RTM::Locator)
+      if scope.eql? :default
+        return create_association_internal(get!(type))
+      else
+        raise "scope must be an Array" unless scope.is_a?(Array)
+        a = create_association_internal(get!(type))
+        scope.each {|s| a.add_scope(get!(s))}
+        return a
+      end
+    end
+
+    delegate :base_locator
+
+    property_set :association_types, :aka => :at, :type => :Topic, :wrap => true
+    property_set :role_types, :aka => [:association_role_types,:art,:rt], :type => :Topic, :wrap => true
+    property_set :name_types, :aka => [:topic_name_types,:tnt,:nt], :type => :Topic, :wrap => true
+    property_set :occurrence_types, :aka => :ot, :type => :Topic, :wrap => true
+    
+    property_set :names, :aka => [:topic_names,:n], :type => :Name, :wrap => :true
+    property_set :occurrences, :aka => :o, :type => :Occurrence, :wrap => :true
+    property_set :roles, :aka => [:association_roles, :r], :type => :Role, :wrap => :true
+
+    def types
+      topics.select{|t| t.instances.size > 0}
+    end
+    alias :topic_types :types
+    def fast_types
+      
+    end
+    
+    # This fetches all topics who have no topic-instances (but they might be types for associations etc.).
+    # See indivduals
+    def non_types
+      topics.select{|t| t.instances.size == 0}
+    end
+    
+    # This fetches all topics which are not type for something else (including topics, associations etc.).
+    # See non_types
+    def individuals
+      non_types.select{|t| t.associations_typed.size==0 && t.roles_typed.size==0 && t.names_typed.size==0 && t.occurrences_typed.size==0}
+    end
+    def instances
+      topics.select{|t| t.types.size > 0}
+    end
+    def non_instances
+      topics.reject{|t| t.types.size > 0}
+    end
+    def internal_occurrences
+      occurrences.select{|o| o.datatype != RTM::PSI[:IRI]}
+    end
+    def external_occurrences
+      occurrences.select{|o| o.datatype == RTM::PSI[:IRI]}
+    end
+    
+    def self.create(base_locator, params={})
+      bl_uri = URI.parse(base_locator)
+      raise "The locator for the Topic Map must be absolute! \"#{base_locator}\" is not an absolute locator." unless bl_uri.absolute?
+      tm = self.wrap(TMDM::TopicMap.find_or_create_by_base_locator(base_locator))
+      yield tm if block_given?
+      tm
+    end
+
+    def self.topic_maps
+      TopicMaps.wrap(TMDM::TopicMap.find(:all))
+    end
+
+    # Resolves an IRI or fragment relative to the base_locator of this topic_map or an optional given alternative_base_locator
+    # 
+    # Absolute IRIs are taken as is.
+    # 
+    # Relative IRIs:
+    # If the base_locator is a directory (ends with "/") it is appended like a file, i.e. directly
+    # If the base_locator is a file it is appended as a fragment (with # in between)
+    def resolve(obj,alternative_base_locator=nil)
+      uri = obj.to_s
+# TODO     uri = URI.decode(obj.to_s) # this InvalidURIError somethimes :(
+      begin
+        uri_uri = URI.parse(uri)
+      rescue URI::InvalidComponentError => ice
+        warn "Catched an URI::InvalidComponentError for URI: #{uri}, message was \"#{ice.message}\"\n" +
+          "Will continue using the UNRESOLVED IRI, claiming it is absolute."
+        return uri
+      end
+      if uri_uri.absolute?
+        return uri_uri.to_s
+      end
+      
+      uri = uri[1..-1] if uri[0] == "#"[0]
+      bl = alternative_base_locator || base_locator
+      if bl[-1,1] == "/"
+        return bl + uri
+      else
+        return bl + "#" + uri
+      end
+    end
+    
+    #private
+    
+    def _item_identifier(iid)
+      __getobj__.locators.find_by_reference(resolve(iid)) # doesn't work :( --> , :include => [ :construct ])
+    end
+    def _item_identifier!(iid)
+      __getobj__.locators.find_or_create_by_reference(resolve(iid)) # doesn't work :( --> , :include => [ :construct ])
+    end
+    
+    def _subject_identifier(iid)
+      __getobj__.subject_identifiers.find_by_reference(iid, :include => :topic)
+    end
+    def _subject_identifier!(iid)
+      __getobj__.subject_identifiers.find_or_create_by_reference(iid, :include => :topic)
+    end
+    
+    def _subject_locator(iid)
+      __getobj__.subject_locators.find_by_reference(iid, :include => :topic)
+    end
+    def _subject_locator!(iid)
+      __getobj__.subject_locators.find_or_create_by_reference(iid, :include => :topic)
+    end
+    
+    
+    # internal helper for by_item_identifier, doesn't wrap result
+    def _by_item_identifier(iid)
+      iid = RTM::LocatorHelpers.iid2iri(iid) if RTM::LocatorHelpers.is_a_iid?(iid)
+      ii = __getobj__.locators.find_by_reference(resolve(iid.to_s.sub(/^(\^|ii:)\s*/,""))) #, :include => [ :construct ])
+      return ii.construct if ii
+      nil
+    end
+    def _topic_by_item_identifier(iid)
+      t = _by_item_identifier(iid)
+      return nil unless t
+      return t if t.class.name =~ /::Topic$/ # only return something if the thing is a topic
+      nil
+    end
+    
+    # internal helper for topic_by_item_identifier!, doesn't wrap result
+    def _topic_by_item_identifier!(iid)
+      iid = RTM::LocatorHelpers.iid2iri(iid) if RTM::LocatorHelpers.is_a_iid?(iid)
+      ii = __getobj__.locators.find_or_create_by_reference(resolve(iid.to_s.sub(/^(\^|ii:)\s*/,"")))#, :include => [ :construct ])
+      return ii.construct if ii.construct && ii.construct_type =~ /::Topic$/
+      top2 = _topic_by_subject_identifier(resolve(iid))
+      if top2
+        ii.construct = top2
+      else
+        ii.construct = create_topic.__getobj__
+      end
+      ii.save
+      ii.construct
+    end        
+    # internal helper for topic_by_subject_identifier, doesn't wrap result
+    def _topic_by_subject_identifier(sid)
+      si = __getobj__.subject_identifiers.find_by_reference(resolve(sid.to_s.sub(/^(si:)\s*/,"")), :include => [ :topic ])
+      return si.topic if si
+      nil
+    end
+    # internal helper for topic_by_subject_identifier!, doesn't wrap result
+    def _topic_by_subject_identifier!(sid)
+      si =  __getobj__.subject_identifiers.find_or_create_by_reference(resolve(sid.to_s.sub(/^(si:)\s*/,"")), :include => [ :topic ])
+      return si.topic if si.topic
+      begin
+      top2 = _by_item_identifier(sid)
+      rescue ActiveRecord::RecordNotFound => rnf
+        si.topic = create_topic.__getobj__
+      else
+        if top2 && top2.respond_to?(:subject_identifiers)
+          si.topic = top2
+        else
+          si.topic = create_topic.__getobj__
+        end
+      end
+      si.save
+      si.topic
+    end
+
+    # internal helper for topic_by_subject_locator, doesn't wrap result
+    def _topic_by_subject_locator(slo)
+      sl = __getobj__.subject_locators.find_by_reference(resolve(RTM::LocatorHelpers.slo2iri(slo))) #, :include => [ :topic ])
+      return sl.topic if sl
+      nil
+    end
+
+    # internal helper for topic_by_subject_locator!, doesn't wrap result
+    def _topic_by_subject_locator!(slo)
+      sl = __getobj__.subject_locators.find_or_create_by_reference(resolve(RTM::LocatorHelpers.slo2iri(slo)), :include => [ :topic ])
+      return sl.topic if sl.topic
+      sl.topic = create_topic.__getobj__
+      sl.save
+      sl.topic
+    end
+    def _topic_by_locator(iri)
+      raise "Locator may not be nil" unless iri
+      return iri if iri.is_a?(RTM::AR::TMDM::Topic)
+      return iri.__getobj__ if iri.is_a?(RTM::AR::Topic)
+      if iri.is_a?(Array)
+        return iri.map{|i| _topic_by_locator(i)}
+      end
+      if RTM::LocatorHelpers.is_a_slo?(iri)
+        _topic_by_subject_locator(iri)
+      elsif RTM::LocatorHelpers.is_a_iid?(iri)
+        _topic_by_item_identifier(iri)
+      #elsif URI.parse(iri).absolute?
+      #  _topic_by_subject_identifier(iri)
+      else
+        _topic_by_subject_identifier(iri)
+      end
+    end
+
+    def _topic_by_locator!(iri)
+      raise "Locator may not be nil" unless iri
+      return iri if iri.is_a?(RTM::AR::TMDM::Topic)
+      return iri.__getobj__ if iri.is_a?(RTM::AR::Topic)
+      if iri.is_a?(Array)
+        return iri.map{|i| _topic_by_locator!(i)}
+      end
+      if RTM::LocatorHelpers.is_a_slo?(iri)
+        _topic_by_subject_locator!(iri)
+      elsif RTM::LocatorHelpers.is_a_iid?(iri)
+        _topic_by_item_identifier!(iri)
+      #elsif RTM::LocatorHelpers.is_a_sid?(iri)
+      #  _topic_by_subject_identifier!(iri)
+      else
+        _topic_by_subject_identifier!(iri)
+      end
+    end
+    
+    %w[topic association role name occurrence variant].each do |x|
+      eval <<-EOI
+        def _#{x}_by_id(id)
+          __getobj__.#{x}s.find(id)
+        end
+      EOI
+    end
+    public
+    # returns an item identifier from the topic_map if it exists
+    def item_identifier(iid)
+      ItemIdentifier.wrap(_item_identifier(iid))
+    end
+    # returns an item identififier from the topic_map or creates it if it doesn't exist
+    def item_identifier!(iid)
+      ItemIdentifier.wrap(_item_identifier!(iid))
+    end
+    alias :create_locator :item_identifier!
+    
+    # Returns a topic map construct by it's item identifier or nil if not found.
+    # It's the equivalent to TMAPI's TopicMapObjectIndex.getTopicMapObjectBySourceLocator
+    def by_item_identifier(iid)
+      Construct.wrap(_by_item_identifier(iid))
+    end
+    alias :get_construct_by_item_identifier :by_item_identifier
+    
+    # Returns a topic by it's item identifier. The topic will be created if not found.
+    def topic_by_item_identifier!(iid)
+      Topic.wrap(_topic_by_item_identifier!(iid))
+    end
+    alias :create_topic_by_item_identifier :topic_by_item_identifier!
+
+    # Returns a topic by it's subject identifier or nil if not found.
+    # It's the equivalent to TMAPI's TopicsIndex.getTopicBySubjectIdentifier.
+    def topic_by_subject_identifier(sid)
+      Topic.wrap(_topic_by_subject_identifier(sid))
+    end
+    alias :get_topic_by_subject_identifier :topic_by_subject_identifier
+    
+    # returns a topic by it's subject identifier. The topic will be created if not found.
+    def topic_by_subject_identifier!(sid)
+      Topic.wrap(_topic_by_subject_identifier!(sid))
+    end
+    alias :create_topic_by_subject_identifier :topic_by_subject_identifier!
+    
+    # Returns a topic by it's subject locator or nil if not found.
+    # It's the equivalent to TMAPI's TopicsIndex.getTopicBySubjectLocator
+    def topic_by_subject_locator(slo)
+      Topic.wrap(_topic_by_subject_locator(slo))
+    end
+    alias :get_topic_by_subject_locator :topic_by_subject_locator
+    
+    # returns a topic by it's subject locator. The topic will be created if not found.
+    def topic_by_subject_locator!(slo)
+      Topic.wrap(_topic_by_subject_locator!(slo))
+    end
+    alias :create_topic_by_subject_locator :topic_by_subject_locator!
+    
+    # Gets a topic from this topic map using its (relative) item identifier,
+    # its (absolute) subject identifier or its (absolute and by "=" prepended) subject locator)
+    #
+    # Returns nil if the Topic does not exist.
+    #
+    # It's also possible to pass a number, which is used to fetch a topic using the internal id. In this case, an exception is thrown, if the topic does not exist.
+    #
+    def topic_by_locator(iri)
+      return nil unless iri
+      return iri if iri.is_a? Topic
+      return topic_by_id(iri) if iri.is_a? Integer
+      if iri.is_a?(Array)
+        return iri.map{|i| topic_by_locator(i)}
+      end
+#      @tblc ||= {}
+#      t = @tblc[iri]
+#      return t if t
+      Topic.wrap(_topic_by_locator(iri)) # t = ...
+#      @tblc[iri] = t if t
+#      t
+    end
+    alias :get :topic_by_locator
+
+    # Gets a topic from this topic map using its (relative) item identifier,
+    # its (absolute) subject identifier or its (absolute and by "=" prepended) subject locator)
+    #
+    # If there is no topic with this item identifier, subject identifier or subject locator, it is created.
+    # Please be aware, the creation does not work with the internal (numeric) ids.
+    # 
+    def topic_by_locator!(iri)
+      return nil unless iri
+      return iri if iri.is_a? Topic
+      return topic_by_id(iri) if iri.is_a? Integer
+      if iri.is_a?(Array)
+        return iri.map{|i| topic_by_locator!(i)}
+      end
+#      @tblc ||= {}
+#      t = @tblc[iri]
+#      return t if t
+      Topic.wrap(_topic_by_locator!(iri)) # t = ...
+#      @tblc[iri] = t
+#      t
+    end
+    alias :get! :topic_by_locator!
+    
+    # Assumes identifier is an IRI (Locator or String) or an Array of IRIs.
+    # Returns an existing or created Topic or an Array of Topics according
+    # to the nature of the IRI.
+    #
+    # :call-seq:
+    #   create_topic_by(identifier) -> Topic
+    #   create_topic_by(identifier-Array) -> Array of Topics
+    #
+    def create_topic_by(identifier)
+      case identifier
+        when RTM::Locator
+          return create_topic_by_subject_identifier(identifier)
+        when String
+          reroute_for_create(identifier)
+        when Array
+          return identifier.map{|i| create_topic_by(i)}
+        else
+          return nil
+      end
+    end
+    
+    # Identifies the identifier as item identifier, subject locator or
+    # subject identifier and calls create_topic_by_.. accordingly. Creates
+    # new topic if topic does not exist yet. Returns the topic.
+    #
+    # :call-seq:
+    #   reroute_for_create(identifier) -> Topic
+    #
+    def reroute_for_create(identifier)
+      case identifier
+       when /^(\^|ii:)\s*(.*)/ #identifiers starts with ^ or ii:
+         create_topic_by_item_identifier(create_locator($2))
+       when /^(=|sl:)\s*(.*)/ #identifier starts with = or sl:
+         create_topic_by_subject_locator(create_locator($2))
+       when /^(si:)\s*(.*)/ #identifier starts with si:
+         create_topic_by_subject_identifier(create_locator($2))
+       else #identifier does not start with a special character
+         create_topic_by_subject_identifier(create_locator(identifier.lstrip))#lstrip: leading whitespace chars removed
+      end
+    end
+
+    # Identifies the identifier as item identifier, subject locator or
+    # subject identifier and calls get_construct/topic_by_.. accordingly.
+    # Returns the topic.
+    #
+    # :call-seq:
+    #   reroute_for_get(identifier) -> Topic
+    #
+    def reroute_for_get(identifier)
+      case identifier
+        when /^(si:|sl:|ii:|=|^)$/
+          return nil
+        when /^(\^|ii:)\s*(.*)/ #identifiers starts with ^ or ii:
+          get_construct_by_item_identifier(create_locator($2))
+        when /^(=|sl:)\s*(.+)/ #identifier starts with = or sl:
+          get_topic_by_subject_locator(create_locator($2))
+        when /^(si:)\s*(.+)/ #identifier starts with si:
+          get_topic_by_subject_identifier(create_locator($2))
+      else #identifier does not start with a special character
+        get_topic_by_subject_identifier(create_locator(identifier.lstrip)) #lstrip: leading whitespace chars removed
+      end
+    end
+
+    %w[topic association role name occurrence variant].each do |x|
+      eval <<-EOI
+        def #{x}_by_id(id)
+          #{x.camelize}.wrap(_#{x}_by_id(id))
+        end
+        alias :#{x[0].chr}id :#{x}_by_id
+      EOI
+    end
+
+    # I am not sure if this is at all correct. TMDM doesn't say a word about it
+    # and the approach to compare topic maps is CXTM. I chose this because we 
+    # should (at least at the time of writing) have only one topic with a given
+    # base locator in RTM. If you don't like it, drop me a mail and explain why
+    # and propose something better.
+    equality [:base_locator]
+    
+    def children
+      topics.to_a + associations.to_a
+    end
+    
+    def literal_index
+      LiteralIndex.new(self)
+    end
+    #def type_instance_index
+    #end
+  end
+end