rtm 0.2.0 → 0.2.1

data/README

@@ -1,4 +1,39 @@
-Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
-License:   Apache License, Version 2.0
+==== Ruby Topic Maps (RTM)
+RTM is a Topic Maps engine written in Ruby. See http://rtm.topicmapslab.de/ for instructions.
+Several backends and extensions are available as separate gems.
 
-See http://rtm.topicmapslab.de/ for instructions.
+==== Overview
+From a developer's perspective, RTM is a schema-less database management system.
+The Topic Maps standard (described below) on which RTM is based provides a way of creating a self-describing schema just by using it.
+
+==== Quickstart
+ require 'rtm'
+ connection = RTM.connect # uses the default Ontopia in-memory backend
+ topic_map = connection.create "http://example.org/my_topic_map/"
+ some_topic = topicmap.get!("identifier_of_the_topic")
+ some_topic["-"] = "default name for the topic"
+ topic_map.to_xtm("my_xtm_file.xtm")
+
+==== Topic Maps
+Topic Maps is an international industry standard (ISO13250) for interchangeably representing information
+about the structure of information resources used to define topics, and the relationships between topics.
+A set of one or more interrelated documents that employs the notation defined by this International Standard is called a topic map.
+A topic map defines a multidimensional topic space - a space in which the locations are topics,
+and in which the distances between topics are measurable in terms of the number of intervening topics
+which must be visited in order to get from one topic to another, and the kinds of relationships that define
+the path from one topic to another, if any, through the intervening topics, if any.
+In addition, information objects can have properties, as well as values for those properties, assigned to them.
+The Topic Maps Data Model which is used in this implementation can be found on http://www.isotopicmaps.org/sam/sam-model/.
+
+==== Backends
+* rtm-ontopia: JRuby only, recommended, uses Ontopia: http://code.google.com/p/ontopia/
+* rtm-tinytim: JRuby only, uses TinyTiM: http://tinytim.sourceforge.net/
+* rtm-activerecord: uses a custom ActiveRecord schema
+
+==== Extensions
+* rtm-tmql: Adds support for the Topic Maps Query Language (TMQL), http://isotopicmaps.org/tmql/
+* rtm-tmcl: Adds support for the Topic Maps Constraint Language (TMCL), http://isotopicmaps.org/tmcl/
+
+==== License 
+Copyright 2009 Topic Maps Lab, University of Leipzig.
+Apache License, Version 2.0

data/lib/rtm.rb

@@ -1,12 +1,15 @@
-# (J)RTM: (J)Ruby Topic Maps.
-#   Copyright:                      Topic Maps Lab  www.topicmapslab.de
-#   License:                       Apache License, Version 2.0 
-#   Project lead:                   Benjamin Bock   bock(at)informatik.uni-leipzig.de
-#   Responsible for (J)RTM:         Arnim Bleier    bleier(at)informatik.uni-leipzig.de
-#   Responsible for Documentation:  Uta Schulze     uta.schulze(at)informatik.uni-leipzig.de
-#   Responsible for ActiveTM:       Daniel Exner    exner(at)informatik.uni-leipzig.de
-
-$: << File.expand_path(File.dirname(__FILE__))
+# Ruby Topic Maps (RTM)
+# Copyright:     Topic Maps Lab  http://www.topicmapslab.de
+# License:       Apache License, Version 2.0
+# Project lead:  Benjamin Bock   bock(at)informatik.uni-leipzig.de
+# Developers:    Benjamin Bock   bock(at)informatik.uni-leipzig.de
+#                Arnim Bleier    bleier(at)informatik.uni-leipzig.de
+#                Uta Schulze     uta.schulze(at)informatik.uni-leipzig.de
+#                Daniel Exner    exner(at)informatik.uni-leipzig.de
+# Testing:       Uta Schulze     uta.schulze(at)informatik.uni-leipzig.de
+# Documentation: Uta Schulze     uta.schulze(at)informatik.uni-leipzig.de
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__))
 
 module RTM
   module Topic
@@ -49,6 +52,9 @@ module RTM
     attr_accessor :engine
   end
 
+  module TopicMapSystem
+  end
+
   module ItemIdentifier
   end
 
@@ -57,14 +63,14 @@ module RTM
 
   module SubjectLocator
   end
-  
-  module TopicMapSystem
+
+  module DatatypeAware
   end
 end
 
 require 'rtm/version'
-require "rtm/engine"
 require 'rtm/extensions'
+require "rtm/engine"
 require 'rtm/psi'
 require "rtm/navigation"
 require "rtm/axes"
@@ -84,41 +90,9 @@ module RTM
   #   RTM.connect(:implementation => :merged)             -> Merged TMAPI backend
   #
   def self.connect(params = {}, *args)
-    implementation = params[:implementation]
-    
-    unless implementation
-      if Engine.list.first
-        implementation = Engine.list.first
-        warn("No engine implementation was specified for RTM.connect. Using the first already loaded engine (#{implementation.inspect}).")
-      else
-        if RUBY_PLATFORM =~ /java/
-          implementation = :ontopia
-        else
-          implementation = :activerecord
-          warn("No engine implementation was specified for RTM.connect. Choosing default (#{implementation.inspect}).")
-        end
-      end
-      params[:implementation] = implementation
-    end
-    
-    unless Engine.list.include?(implementation)
-      warn("Requested engine '#{implementation}' not loaded. Trying to autoload it.")
-      Engine.load(implementation)
-      if Engine.list.include?(implementation)
-        warn("Autoloading '#{implementation}' was successful")
-      else
-        raise "Autoloading '#{implementation}' failed. Make sure rtm-#{implementation} exists and is installed or require it manually."
-      end
-    end
-
-    engine = RTM::Engine[implementation]
-    
+    engine = Engine.load!(params[:implementation])
     connection = engine.new(params)
-
-    @connections ||= {}
-    @connections[implementation] ||= []
-    @connections[implementation] << connection
-
+    add_connection(connection)
     connection
   end
 
@@ -128,7 +102,7 @@ module RTM
   #   connections -> Hash
   #
   def self.connections
-    @connections ||= {}
+    @connections ||= Hash.new{|h,k| h[k] = []}
     @connections
   end
 
@@ -153,4 +127,8 @@ module RTM
     self.included_modules.each {|im| klass.extend(im)}
   end
 
+  private
+  def self.add_connection(connection)
+    self.connections[connection.class.identifier] << connection
+  end
 end

data/lib/rtm/axes.rb

@@ -226,7 +226,8 @@ module RTM
   end
 end
 
-module RTM::Topic
+module RTM::AxesExtension;end
+module RTM::AxesExtension::Topic
   
   # Changes from TMAPI-mode to Axes-mode.
   #
@@ -238,7 +239,7 @@ module RTM::Topic
   end
 end
 
-module RTM::Name
+module RTM::AxesExtension::Name
   
   # Changes from TMAPI-mode to Axes-mode.
   #
@@ -250,7 +251,7 @@ module RTM::Name
   end
 end
 
-module RTM::Occurrence
+module RTM::AxesExtension::Occurrence
   
   # Changes from TMAPI-mode to Axes-mode.
   #
@@ -262,7 +263,7 @@ module RTM::Occurrence
   end
 end
 
-module RTM::Association
+module RTM::AxesExtension::Association
   
   # Changes from TMAPI-mode to Axes-mode.
   #
@@ -288,6 +289,8 @@ class String
   end
 end
 
+RTM.register_extension(RTM::AxesExtension)
+
 require "rtm/axes/topics"
 require "rtm/axes/associations"
 require "rtm/axes/characteristics"

data/lib/rtm/axes/association.rb

@@ -10,7 +10,7 @@ module RTM::Axes
     # Returns all Role players of Roles in this Association.
     #
     # The optional identifier specifies the type of the Roles to be considered.
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # Multiple instances of the same Topic are possible.
     # The result may be empty.

data/lib/rtm/axes/associations.rb

@@ -18,7 +18,7 @@ module RTM::Axes
     # Returns all Role players of Roles in these Associations.
     #
     # The optional identifier specifies the type of the Roles to be considered.
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # Multiple instances of the same Topic are possible.
     # The result may be empty.

data/lib/rtm/axes/characteristic.rb

@@ -24,7 +24,7 @@ module RTM::Axes
     # Characteristic for its type. If the type
     # does not match, nil is returned.
     #
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # :call-seq:
     #   reverse_characteristics -> Topic

data/lib/rtm/axes/characteristics.rb

@@ -37,7 +37,7 @@ module RTM::Axes
     # Characteristics for their types. If the type
     # does not match, the Topic is not returned.
     #
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # :call-seq:
     #   reverse_characteristics -> Array of Topic

data/lib/rtm/axes/topic.rb

@@ -11,7 +11,7 @@ module RTM::Axes
     # If an identifier is given, only those Names and Occurrences are returned,
     # whose type or supertypes include the identifier.
     #
-    # Identifier may be a Topic or Topic-Reference.
+    # Identifier may be a topic reference.
     #
     # The result may be empty.
     #
@@ -68,7 +68,7 @@ module RTM::Axes
     #
     # The optional
     # identifier specifies the type of the Roles to be considered.
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # Multiple instances of the same Association are possible.
     # The result may be empty.
@@ -177,7 +177,7 @@ module RTM::Axes
     # The current Topic is deducted ones from the returned Array.
     # The result may be empty.
     #
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # :call-seq:
     #   traverse(identifier) -> Array of Topics

data/lib/rtm/axes/topics.rb

@@ -19,7 +19,7 @@ module RTM::Axes
     # If an identifier is given, only those Names and Occurrences are returned,
     # whose type or supertypes include the identifier.
     #
-    # Identifier may be a Topic or Topic-Reference.
+    # Identifier may be a topic reference.
     #
     # The result may be empty.
     #
@@ -90,7 +90,7 @@ module RTM::Axes
     #
     # The optional
     # identifier specifies the type of the Roles to be considered.
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # Multiple instances of the same Association are possible.
     # The result may be empty.
@@ -209,7 +209,7 @@ module RTM::Axes
     # Each Topic is deducted ones from the returned Array.
     # The result may be empty.
     #
-    # The identifier may be a Topic or Topic-Reference.
+    # The identifier may be a topic reference.
     #
     # :call-seq:
     #   traverse(identifier) -> Array of Topics

data/lib/rtm/engine.rb

@@ -1,5 +1,7 @@
 module RTM
-  class Engine    
+  class Engine
+    include RTM::TopicMapSystem
+
     def self.abstract?
       self == Engine
     end
@@ -38,21 +40,62 @@ module RTM
     end
     
     def self.load(engine_name)
-      begin
+      if Object.const_defined?("Gem") && rtmgem = Gem.loaded_specs["rtm"]
         require "rtm/#{engine_name}"
-      rescue LoadError
+      else
         engine_path = File.expand_path(File.join(File.dirname(__FILE__), "../../../rtm-#{engine_name}/lib"))
         if File.directory?(engine_path)
-          $:.unshift engine_path
+          $LOAD_PATH.unshift engine_path
           require "rtm/#{engine_name}"
         end
       end
+      self[engine_name]
+    end
+
+    def self.load!(engine_name=nil)
+      engine_name = self.detect unless engine_name
+      unless list.include?(engine_name)
+        warn("Requested engine '#{engine_name}' not loaded. Trying to autoload it.")
+        engine = load(engine_name)
+        if list.include?(engine_name)
+          warn("Autoloading '#{engine_name}' was successful")
+        else
+          raise "Autoloading '#{engine_name}' failed. Make sure rtm-#{engine_name} exists and is installed or require it manually."
+        end
+      end
+      engine || load(engine_name)
     end
     
+    def self.detect(preferred=nil)
+      if preferred # return the users preference, if given
+        implementation = preferred
+      elsif engine_name = ENV['RTM_IMPLEMENTATION'] # inspect system environment
+        implementation = engine_name.to_sym
+      elsif engine_name = ENV['RTM_ENGINE'] # inspect system environment (alternative)
+        implementation = engine_name.to_sym
+      elsif implementation = self.list.first # check if one is already loaded
+        warn("No engine implementation was specified for RTM.connect. Using the first already loaded engine (#{implementation.inspect}).")
+      else
+        implementation = self.default # use hardcoded default
+        warn("No engine implementation was specified for RTM.connect. Choosing default (#{implementation.inspect}).")
+        implementation
+      end
+      implementation
+    end
+
+    def self.default
+      if RUBY_PLATFORM =~ /java/
+        :ontopia
+      else
+        :activerecord
+      end
+    end
+
     attr_reader :connections
+
     def initialize(params={})
       @params = params
     end
-    
+
   end
 end

data/lib/rtm/extensions.rb

@@ -2,7 +2,7 @@
 # License:   Apache License, Version 2.0
 
 module RTM
-  # Register a module as extension.
+  # Register a module as extension to RTM.
   # 
   # Example:
   # module MyExtension
@@ -14,16 +14,66 @@ module RTM
   #   RTM.register_extension(self)
   # end
   #
-  def self.register_extension(plugin_mod)
-    plugin_mod.constants.each do |const|
-      const_get(const).send(:include, plugin_mod.const_get(const) ) if const_defined?(const)
+  def self.register_extension(module_with_modules)
+    # puts "[RTMEXT] registering extension #{module_with_modules}"
+    module_with_modules.constants.each do |sub_module|
+      self.const_get(sub_module).register_extension(module_with_modules.const_get(sub_module)) if self.const_defined?(sub_module)
     end
   end
-  module AR
-    def self.register_extension(plugin_mod)
-      plugin_mod.constants.each do |const|
-        const_get(const).send(:include, plugin_mod.const_get(const) ) if const_defined?(const)
+
+  # Extend a module or class with this method to make it a receiver for RTM extensions.
+  # E.g. MyModule.extend(Extendable) or MyClass.extend(Extendable).
+  #
+  # A extension can then be registered using
+  # MyModule.register_extension(MyExtension)
+  #
+  # The module will then keep track of all modules or classes it's included in.
+  # These modules and classes are called implementations here.
+  # If an extension is added later, the implementations will also be updated which would not be the case if normal includes were used.
+  module Extendable
+    # Register a module as an extension to an Entity in RTM.
+    # An entity may be e.g. RTM::TopicMap, RTM::Topic or any Module which was extended with RTM::Extendable
+    #
+    # Besides normal ruby inclusion of the module, this module keeps track of its implementations which are also updated in this method.
+    def register_extension(mod)
+      include mod
+      return unless @implementations
+      @implementations.each do |impl|
+        next if impl.ancestors.include?(mod)
+        impl.send(:include, mod)
+      end
+    end
+
+    # A standard Ruby hook to be notified about inclusions of this module.
+    # This normally eliminates the need to register a module as implementa
+    def included(klass)
+      # super
+      # puts "[RTMEXT] including #{self} into #{klass} in #{caller(1).first}"
+      register_implementation(klass)
+      klass.class_eval do
+        def self.included(klass2)
+          # puts "[RTMIMPLEXT] #{self} was included into #{klass2} in #{caller(1).first}"
+          # self.ancestors.select {|anc| anc.respond_to?(:register_implementation)}.each{|anc| anc.register_implementation(klass2) }
+          self.ancestors.find {|anc| anc.respond_to?(:register_implementation)}.register_implementation(klass2)
+        end
       end
     end
+
+    # Register an implementation to this module.
+    # Registred implementations will be updated if later any extensions are added.
+    # This method should normally be called from the included hook.
+    # Due to Ruby's restrictions on calling protected methods from other modules extending the very same module Extendable,
+    # this method must be public.
+    def register_implementation(klass)
+      # super if self.class.superclass.respond_to?(:register_implementation)
+      @implementations ||= []
+      @implementations << klass
+    end
   end
+  [
+    TopicMapSystem, Construct, Reifiable,
+    DatatypeAware, Scoped, Typed,
+    TopicMap, Topic, Name, Occurrence, Variant, Association, Role,
+    Locator, ItemIdentifier, SubjectIdentifier, SubjectLocator
+  ].each{|mod| mod.extend(Extendable)}
 end