xamplr 1.9.13 → 1.9.14

data/lib/xamplr/persistence.rb

@@ -76,34 +76,40 @@ module Xampl
     @@default_persister_options[:format] = format
   end
 
-  def Xampl.enable_persister(name, kind=nil, format=nil)
-    kind = kind || Xampl.default_persister_kind
-    format = format || Xampl.default_persister_format
+  def Xampl.create_named_persister(name, kind, arg=nil)
+    raise NoAnonymousPersisters.new unless name # there is no such thing as an anonymous persister, maybe later
 
-    @@persister = @@known_persisters[name]
+    persister = @@known_persisters[name]
+    return persister if persister
 
-    if @@persister then
-      #      @@persister.open # this won't work
-      # TODO -- if we know the persister, why are we being so anal about kind and format???
+    persister_class = @@persister_kinds[kind]
+    return nil unless persister_class
 
-      kind = @@persister.kind || kind
-      format = @@persister.format || format
+    persister = persister_class.new(name, :xml_format, arg)
+    @@known_persisters[name] = persister
 
-      if kind and kind != @@persister.kind then
-        raise IncompatiblePersisterRequest.new(@@persister, "kind", kind, @@persister.kind)
-      end
-      if format and format != @@persister.format then
-        raise IncompatiblePersisterRequest.new(@@persister, "format", format, @@persister.format)
-      end
-    end
+    return persister
+  end
 
-    unless @@persister then
-      @@persister = @@persister_kinds[kind].new(name, format)
-      if (nil != name) then
-        @@known_persisters[name] = @@persister
-      end
-    end
+  def Xampl.find_named_persister(name)
+    persister = @@known_persisters[name]
+  end
+
+  def Xampl.enable_named_persister(name)
+    persister = @@known_persisters[name]
+    raise NoPersisterNamed.new(name) unless persister
+
+    @@persister = persister
+  end
+
+  def Xampl.enable_persister(name, preferred_kind=nil)
+    # you'd better know what you are doing if you call this
+
+    raise NoPersisterNamed.new unless name
 
+    preferred_kind = preferred_kind || Xampl.default_persister_kind
+
+    @@persister = @@known_persisters[name] || Xampl.create_named_persister(name, preferred_kind, nil)
     @@persister
   end
 
@@ -111,11 +117,12 @@ module Xampl
     puts "Known Persisters:: --------------------------"
     @@known_persisters.each { |n, k| puts " #{n} #{k}" }
     puts "---------------------------------------------"
+    puts caller(0)
   end
 
   def Xampl.flush_persister_caches
     Xampl.print_known_persisters
-    @persister.close
+    @@persister.close
     @@known_persisters.delete(@@persister.name)
     Xampl.print_known_persisters
   end
@@ -137,19 +144,21 @@ module Xampl
   end
 
   def Xampl.drop_persister(name)
-    Xampl.print_known_persisters
+#    Xampl.print_known_persisters
     p = @@known_persisters[name]
     p.close if p
     @@known_persisters.delete(name)
-    Xampl.print_known_persisters
+#    Xampl.print_known_persisters
   end
 
   def Xampl.add_lexical_indexs(indexes)
     case Xampl.default_persister_kind
       when :tokyo_cabinet then
         Xampl::TokyoCabinetPersister.add_lexical_indexs(indexes)
-      when :monto then
-        Xampl::MongoPersister.add_lexical_indexs(indexes)
+      when :redis then
+        Xampl::RedisPersister.add_lexical_indexs(indexes)
+      #when :mongo then
+      #  Xampl::MongoPersister.add_lexical_indexs(indexes)
       else
         raise IncompatiblePersisterConfiguration.new(Xampl.default_persister_kind, "lexical_indexes")
     end
@@ -159,8 +168,10 @@ module Xampl
     case Xampl.default_persister_kind
       when :tokyo_cabinet then
         Xampl::TokyoCabinetPersister.add_numerical_indexs(indexes)
-      when :mongo then
-        Xampl::MongoPersister.add_numerical_indexs(indexes)
+      when :redis then
+        Xampl::RedisPersister.add_numerical_indexs(indexes)
+      #when :mongo then
+      #  Xampl::MongoPersister.add_numerical_indexs(indexes)
       else
         raise IncompatiblePersisterConfiguration.new(Xampl.default_persister_kind, "numerical_indexs")
     end
@@ -213,7 +224,7 @@ module Xampl
     @@xampl_lock.synchronize(:EX) do
       begin
         initial_persister = @@persister
-        Xampl.enable_persister(name, kind, format)
+        Xampl.enable_persister(name, kind)
 
         original_automatic = @@persister.automatic
 
@@ -278,7 +289,6 @@ module Xampl
     end
   end
 
-  #def Xampl.transaction_using_proc(thing, kind=nil, automatic=true, format=nil, & block)
   def Xampl.transaction(thing, kind=nil, automatic=true, format=nil, & block)
     # this method cannot account for returns in transactions (proc vs lambda/method issues)
     if String === thing then
@@ -289,13 +299,89 @@ module Xampl
       raise XamplException.new("can't base a transaction on a #{thing.class.name} (#{thing})")
     end
 
+    if block_given? then
+      @@xampl_lock.synchronize(:EX) do
+        rollback = true
+        exception = nil
+        begin
+          initial_persister = @@persister
+          Xampl.enable_persister(name, kind)
+
+          original_automatic = @@persister.automatic
+
+          begin
+            #TODO -- impose some rules on nested transactions/enable_persisters??
+
+            Xampl.auto_persistence(automatic)
+
+            result = yield
+
+            rollback = false
+            Xampl.block_future_changes(true)
+            Xampl.sync
+            return result
+          rescue => e
+#            puts e.backtrace
+            exception = e
+          ensure
+            Xampl.block_future_changes(false)
+            Xampl.auto_persistence(original_automatic)
+
+            if rollback then
+              # we get here if the transaction block finishes early, for one of three reasons:
+              #    1) exception
+              #    2) throw
+              #    3) explicit return in the block
+              # it is arguable that throw and returns are 'okay', or normal exits from the block... I don't know???
+
+              if exception then
+                # the early finish was caused by an exception
+
+                Xampl.rollback
+              else
+                # this is the throw/explicit-return
+
+                #TODO -- is this a good idea??
+                Xampl.block_future_changes(true)
+                Xampl.sync
+
+
+                #TODO -- uncomment this, it's handy
+#                STDERR.puts "---------"
+#                STDERR.puts "Either a return or a throw from a transaction. The DB is synced, but this is not a good thing to be doing."
+#                STDERR.puts caller(0)
+#                STDERR.puts "---------"
+              end
+            end
+          end
+        ensure
+          @@persister = initial_persister
+
+          if exception then
+            raise RuntimeError, "ROLLBACK(#{__LINE__}):: #{exception}", exception.backtrace
+          end
+        end
+      end
+    end
+  end
+
+  def Xampl.transaction_not_so_good(thing, kind=nil, automatic=true, format=nil, & block)
+    # this method cannot account for returns in transactions (proc vs lambda/method issues)
+    if String === thing then
+      name = thing
+    elsif XamplObject === thing then
+      name = thing.persister.name
+    else
+      raise XamplException.new("can't base a transaction on a #{thing.class.name} (#{thing})")
+    end
+
     if block_given? then
       @@xampl_lock.synchronize(:EX) do
 #      if true then
         begin
 #          @@xampl_lock.sync_lock(:EX)
           initial_persister = @@persister
-          Xampl.enable_persister(name, kind, format)
+          Xampl.enable_persister(name, kind)
 
           rollback = true
           exception = nil
@@ -305,22 +391,32 @@ module Xampl
             #TODO -- impose some rules on nested transactions/enable_persisters??
 
             Xampl.auto_persistence(automatic)
+
             result = yield
+
+            rollback = false
             Xampl.block_future_changes(true)
             Xampl.sync
-            rollback = false
             return result
           rescue => e
+            puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+            puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
             exception = e
           ensure
             Xampl.block_future_changes(false)
             Xampl.auto_persistence(original_automatic)
+
+            puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
             if rollback then
+              puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+              puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
               # we get here if the transaction block finishes early
               if exception then
+                puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
                 # the early finish was caused by an exception
                 raise RuntimeError, "ROLLBACK(#{__LINE__}):: #{exception}", exception.backtrace
               else
+                puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
                 # How could we have arrived at this point???
                 # Well, I don't know all the reasons, but the ones I do know are:
                 #  - return was used in the block passed into the transaction
@@ -337,32 +433,30 @@ module Xampl
                   STDERR.puts(trace)
                 end
                 STDERR.puts "---------"
-
-=begin
-
-                begin
-                  puts "#{ __FILE__ }:#{ __LINE__ } [#{__method__}] "
-                  Xampl.block_future_changes(true)
-                  puts "#{ __FILE__ }:#{ __LINE__ } [#{__method__}] "
-                  Xampl.sync
-                  rollback = false
-                rescue => e
-                  puts "#{ __FILE__ }:#{ __LINE__ } [#{__method__}] "
-                  # so we know the persister had a problem
-                  puts "PERSISTER ERROR(#{__LINE__}) #{ e }"
-                ensure
-                  puts "#{ __FILE__ }:#{ __LINE__ } [#{__method__}] "
-                  Xampl.block_future_changes(false)
-                end
-
-=end
               end
+            else
+              puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+            end
+
+            if rollback then
+              puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+              Xampl.rollback
+              rollback = false
+            else
+              puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
             end
-            Xampl.rollback if rollback
             @@persister = initial_persister
           end
-          raise exception if exception
-#        ensure
+          puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
+          if exception
+            puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
+            raise exception
+          else
+            puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback }"
+          end
+        ensure
+          puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME" if rollback
+          puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] rollback: #{ rollback } ????????????" if rollback
 #          @@xampl_lock.sync_unlock
         end
       end
@@ -382,7 +476,7 @@ module Xampl
     if block_given? then
       @@xampl_lock.synchronize(:EX) do
         initial_persister = @@persister
-        Xampl.enable_persister(name, kind, format)
+        Xampl.enable_persister(name, kind)
         target_persister = @@persister
 
         rollback = true
@@ -438,7 +532,7 @@ module Xampl
 
       if block_given? then
         initial_persister = @@persister
-        Xampl.enable_persister(name, target_persister.kind, target_persister.format)
+        Xampl.enable_persister(name, target_persister.kind)
 
         rollback = true
         original_automatic = @@persister.automatic

data/lib/xamplr/persister.rb

@@ -72,17 +72,9 @@ module Xampl
     end
 
     def has_changed(xampl)
-      #raise XamplException.new(:live_across_rollback) if @rolled_back
-      # puts "!!!! has_changed #{xampl} #{xampl.get_the_index} -- persist required: #{xampl.persist_required}"
       if xampl.persist_required && xampl.is_changed then
-        unless self == xampl.persister
-          raise MixedPersisters.new(xampl.persister, self)
-        end
+        raise MixedPersisters.new(xampl.persister, self) unless self == xampl.persister
         @changed[xampl] = xampl
-#         puts "!!!! change recorded ==> #{@changed.size}/#{count_changed} #{@changed.object_id} !!!!"
-        #         @changed.each{ | thing, ignore |
-        #           puts "             changed: #{thing}, index: #{thing.get_the_index},  changed: #{thing.is_changed}"
-        #         }
       end
     end
 
@@ -132,15 +124,7 @@ module Xampl
     end
 
     def represent(xampl, mentions=[])
-      #puts "REPRESENT #{xampl} load needed: #{xampl.load_needed}"
-      #      return nil if xampl.load_needed
-      rep = nil
-      case xampl.default_persister_format || @format
-        when nil, :xml_format then
-          rep = xampl.persist("", mentions)
-        when :ruby_format then
-          rep = xampl.to_ruby(mentions)
-      end
+      rep = xampl.persist("", mentions)
       return rep
     rescue => e
       msg = "Failed to represent #{ xampl } due to: #{ e }"
@@ -150,15 +134,15 @@ module Xampl
     end
 
     def realise(representation, target=nil)
-      # Normally we'd expect to see the representation in the @format format, but
-      # that isn't necessarily the case. Try to work out what the format might be...
-
-      #TODO -- this is a bit brutal, but it should work (it is the rule is that this is supposed to be UTF-8)
+      # This is a bit brutal, but it works (and, anyway, it *is* the rule is that this is supposed to be UTF-8)
       representation_fixed = representation.encode('UTF-8', :invalid => :replace, :undef => :replace)
-#      puts "#{ ::File.basename __FILE__ }:#{ __LINE__ } [#{__method__}] ENCODING: #{ representation.encoding } -> #{ representation_fixed.encoding }"
 
       xampl = nil
-      if representation_fixed =~ /^</ then
+
+      # These days 'new' representations can only be XML. Historically it could have been Ruby. Check the
+      # representations (quickly) and choose appropriately.
+      if '<' == representation_fixed[0] then
+        # well it isn't ruby, so it must be XML. Of course this means no leading whitespace, which happens to be true.
         xampl = XamplObject.realise_from_xml_string(representation_fixed, target)
       else
         xampl = XamplObject.from_ruby(representation_fixed, target)
@@ -364,13 +348,14 @@ module Xampl
   end
 
   begin
-    if require 'mongo' then
-      require "xamplr/persisters/mongo"
+    if require 'redis' then
+      require 'weakref'
+      require "xamplr/persisters/redis"
     end
   rescue LoadError => e
-    # Well. No MongoDB.
+    # Well. No redis.
   rescue
-    # Well. No MongoDB.
+    # Well. No redis.
   end
 
 end

data/lib/xamplr/persisters/dumb.rb

@@ -2,7 +2,7 @@ module Xampl
 
   class DumbPersister < Persister
 
-    def initialize(name=nil, format=nil)
+    def initialize(name=nil, format=nil, ignore=nil)
       super(name, format)
 
       @module_map = {}

data/lib/xamplr/persisters/filesystem.rb

@@ -5,7 +5,8 @@ module Xampl
 
   class FilesystemPersister < AbstractCachingPersister
 
-    def initialize(name=nil, format=nil, root=File.join(".", "repo"))
+    def initialize(name=nil, format=nil, root=nil)
+      root = File.join(".", "repo") if root.nil?
       super(root, name, format)
     end
 

data/lib/xamplr/persisters/in-memory.rb

@@ -5,6 +5,7 @@ module Xampl
   class InMemoryPersister < Persister
 
     def initialize(name=nil, format=nil, capacity=20)
+      capacity ||= 20
       super(name, format)
 
       @module_map = {}

data/lib/xamplr/persisters/redis.rb

@@ -0,0 +1,449 @@
+module Xampl
+
+  class RedisPersister < Persister
+
+    attr_reader :repo_name,
+                :instance_options,
+                :client, # currently it's an instance of ::Redis from the redis-rb library
+                :suggested_repo_properties,
+                :repo_properties
+
+    @@default_redis_options = {
+            :repo_properties => {
+                    # DB Properties, maybe only set when the DB is created for the first time.
+                    :mentions => true,
+                    },
+
+            # Connect Properties
+            :thread_safe => true, # redis connections will be thread safe
+            :redis_server => "redis://127.0.0.1:6379/0", #This is the format expected by redis-rb, just use it
+            :clobbering_allowed => false,
+            :allow_connections => true,
+            :connect_to_known => true, # will connect to repos already in the redis db
+            :connect_to_unknown => true, # will connect to repose not in the redis db
+            :testing => false
+    }
+
+    REPOSITORIES_KEY = "XAMPL::REPOSITORIES"
+
+    def initialize(name=nil, format=nil, options={})
+      super(name, format)
+
+      @repo_name = name
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] @@default_redis_options: #{ @@default_redis_options.inspect }"
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] Xampl.raw_persister_options: #{ Xampl.raw_persister_options.inspect }"
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] options: #{ options.inspect }"
+
+      @instance_options = {}
+      @instance_options = @instance_options.merge(@@default_redis_options)
+      @instance_options = @instance_options.merge(Xampl.raw_persister_options)
+      @instance_options = @instance_options.merge(options) if options
+
+      @suggested_repo_properties = @instance_options.delete(:repo_properties)
+
+      clear_cache
+      ensure_connected
+    end
+
+    def RedisPersister.kind
+      :redis
+    end
+
+    def kind
+      RedisPersister.kind
+    end
+
+    def ensure_connected
+      return if @client
+      return unless instance_options[:allow_connections]
+
+      server = @instance_options[:redis_server]
+      thread_safe = @instance_options[:thread_safe]
+      @client = Redis.connect(:url => server, :thread_safe => thread_safe)
+
+      # This check is necessary to make sure that the connection is made, otherwise the exception will be sometime in the future
+      # the redis exceptions are good enough, so don't bother trapping right here
+      @client.ping
+
+      # check to see if the repository with this name is known (in redis) already
+      load_repo_properties
+
+      if @repo_properties && !@instance_options[:connect_to_known] then
+        ensure_disconnected
+        raise IncompatiblePersisterConfiguration.new('redis', "prevent connections to existing repos named: '#{ repo_name }' in #{ server }")
+      end
+      if @repo_properties.nil? && !@instance_options[:connect_to_unknown] then
+        ensure_disconnected
+        raise IncompatiblePersisterConfiguration.new('redis', "prevent connections to unknown repos named: '#{ repo_name }' in #{ server }")
+      end
+
+      return if @repo_properties
+
+      # if it is unknown, then set it up
+
+      @repo_properties = {}
+      suggested_repo_properties.each do |k, v|
+        @repo_properties[k] = v
+      end
+      @repo_properties['name'] = repo_name
+      @repo_properties['created_at'] = DateTime.now.to_s
+
+      @client.multi do
+        @client.mapped_hmset(repo_properties_key, @repo_properties)
+        @client.sadd(REPOSITORIES_KEY, repo_name)
+      end
+
+      load_repo_properties
+    end
+
+    def ensure_disconnected
+      return unless client
+      return unless instance_options[:allow_connections]
+
+      @client.quit
+    ensure
+      @repo_properties = nil
+      @client = nil
+    end
+
+    def clobber
+      # TODO -- this is a BAD idea if there are any other connections to this repo (i.e. in different processes)
+
+      unless @instance_options[:clobbering_allowed] then
+        raise IncompatiblePersisterConfiguration.new('redis', "clobbering is not enabled for this connection to repo: '#{ repo_name }' in #{ @instance_options[:redis_server] }")
+      end
+
+      #TODO -- getting the keys outside the multi might allow some new key to sneak in there
+      keys = @client.keys("#{ common_key_prefix }*")
+      @client.multi do
+        @client.del(repo_properties_key)
+        @client.srem(REPOSITORIES_KEY, repo_name)
+
+        keys.each do |key|
+          @client.del(key)
+        end
+      end
+
+      ensure_disconnected
+    end
+
+    def repo_properties_key
+      key = "XAMPL::PROPERTIES::#{ @repo_name }"
+      return key
+    end
+
+    def load_repo_properties
+      key = repo_properties_key()
+      @repo_properties = @client.hgetall(key)
+      @repo_properties = nil if @repo_properties.empty?
+    end
+
+    def clear_cache
+      @cache_hits = 0
+      @cache = {}
+      @new_cache = {}
+    end
+
+    alias fresh_cache clear_cache
+
+    def close
+      ensure_disconnected
+      clear_cache
+    end
+
+    def common_key_prefix
+      "XAMPL::#{ @repo_name }::"
+    end
+
+    def key_for_class(klass, index)
+      #NOTE -- the XAMPL::#{ @repo_name }:: is a prefix common to all keys specific to this repository
+      "#{ common_key_prefix }#{ klass.name }[#{ index }]"
+    end
+
+    def key_for_xampl(xampl)
+      key_for_class(xampl.class, xampl.get_the_index)
+    end
+
+    def known_repos
+      return @client.smembers(REPOSITORIES_KEY)
+    end
+
+    def perm_cache(xampl)
+      raise NotXamplPersistedObject.new(xampl) unless xampl.kind_of?(XamplPersistedObject)
+
+      key = key_for_xampl(xampl)
+      existing = @cache[key]
+
+      begin
+#        raise DuplicateXamplInPersister.new(existing, xampl, self) if existing && (existing.weakref_alive?) && (existing.__getobj__ != xampl)
+        raise DuplicateXamplInPersister.new(existing, xampl, self) if existing && (existing.__getobj__ != xampl)
+      rescue WeakRef::RefError => e
+        # key is there but the original object isn't...
+      end
+
+      @cache[key] = WeakRef.new(xampl)
+    end
+
+    def perm_uncache(xampl)
+      raise NotXamplPersistedObject.new(xampl) unless xampl.kind_of?(XamplPersistedObject)
+
+      key = key_for_xampl(xampl)
+      @cache.delete(key).__getobj__
+    end
+
+    def cache(xampl)
+      # this is called by xampl for the temporary new_cache
+      raise NotXamplPersistedObject.new(xampl) unless xampl.kind_of?(XamplPersistedObject)
+
+      key = key_for_xampl(xampl)
+
+      existing = @new_cache[key]
+      raise DuplicateXamplInPersister.new(existing, xampl, self) if existing && (existing != xampl)
+
+      existing = @cache[key]
+      begin
+#        raise DuplicateXamplInPersister.new(existing, xampl, self) if existing && (existing.weakref_alive?) && (existing.__getobj__ != xampl)
+        raise DuplicateXamplInPersister.new(existing, xampl, self) if existing && (existing.__getobj__ != xampl)
+      rescue WeakRef::RefError => e
+        # key is there but the original object isn't...
+      end
+
+      @new_cache[key] = xampl
+    end
+
+    def uncache(xampl)
+      # this is called by xampl for the temporary new_cache
+      raise NotXamplPersistedObject.new(xampl) unless xampl.kind_of?(XamplPersistedObject)
+
+      key = key_for_xampl(xampl)
+      @new_cache.delete(key)
+    end
+
+    def in_perm_cache?(klass, index)
+      key = key_for_class(klass, index)
+      xampl = @cache[key]
+
+      (xampl && xampl.weakref_alive?) ? true : false
+    end
+
+    alias in_cache? in_perm_cache?
+
+    def in_new_cache?(klass, index)
+      key = key_for_class(klass, index)
+      @new_cache.include?(key)
+    end
+
+    def in_any_cache?(klass, index)
+      in_new_cache?(klass, index) || in_cache?(klass, index)
+    end
+
+    def read_from_cache(klass, index, target=nil)
+
+      key = key_for_class(klass, index)
+
+      xampl = @cache[key]
+      begin
+        xampl = xampl.__getobj__ if xampl
+      rescue WeakRef::RefError => e
+        #not there
+        xampl = nil
+      end
+#      xampl = (xampl && xampl.weakref_alive?) ? xampl.__getobj__ : nil
+
+      unless xampl then
+        xampl = @new_cache[key]
+      end
+
+      return nil, target unless xampl
+
+      if target and target != xampl then
+        puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+        target.invalidate
+        raise XamplException.new(:cache_conflict)
+      end
+      unless xampl.load_needed then
+        @cache_hits = @cache_hits + 1
+        return xampl, target
+      end
+      return xampl, xampl
+    end
+
+    def sync_done
+      # simply moves the new_cache to the permanent cache
+      (@new_cache || {}).each do |key, xampl|
+        @cache[key] = WeakRef.new(xampl)
+      end
+      @new_cache = {}
+    end
+
+    def write(xampl)
+      unless xampl.get_the_index
+        puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+        raise NotXamplPersistedObject.new(xampl)
+      end
+
+      #TODO -- honour the mentions config information (FROM THE DB not the configuration!!)
+      mentions = []
+      xml = represent(xampl, mentions)
+      key = key_for_xampl(xampl)
+
+      #TODO save the modified-time-like value to support multi processing
+
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] redis #{ self }"
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] write: #{ xampl } --> #{ xml }"
+#      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] key: #{ key }"
+
+      client.set(key, xml)
+      @write_count = @write_count + 1
+      xampl.changes_accepted
+      return true
+
+    rescue NotXamplPersistedObject => nxpo
+      raise nxpo
+    rescue => e
+      puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] #{ e }"
+      puts e.backtrace
+      return false
+    end
+
+    def read(klass, pid, target=nil)
+      xampl, target = read_from_cache(klass, pid, target)
+      return xampl if xampl and !target
+
+      key = key_for_class(klass, pid)
+      xml = client.get(key)
+      unless xml
+        puts "#{File.basename(__FILE__)}:#{__LINE__} [#{ __method__ }] TEST ME"
+        return nil
+      end
+
+      xampl = realise(xml, target)
+      Xampl.store_in_cache(@cache, xampl, self) { xampl }
+      xampl.introduce_persister(self)
+
+      @read_count = @read_count + 1
+      xampl.changes_accepted
+      @changed.delete(xampl)
+      return xampl
+    end
+
+    def rollback_cleanup
+
+      @new_cache.each { |name, xampl|
+        if xampl then
+          @changed.delete(xampl)
+          xampl.invalidate
+
+#          map.each { |name2, map2|
+#            if map2 then
+#              map2.each { |pid, xampl|
+#                @changed.delete(xampl)
+#                xampl.invalidate
+#              }
+#            end
+#          }
+        end
+      }
+      @changed.each { |xampl, ignore|
+        xampl.force_load
+      }
+      @new_cache = {}
+
+      super
+    end
+
+=begin
+
+
+
+
+
+
+  def backup(base_path)
+    #TODO
+  end
+
+  def do_sync_write
+    #TODO
+  end
+
+  def done_sync_write
+    #TODO
+  end
+
+  def expunge(xampl)
+    #TODO
+  end
+
+  def find_mentions_of(xampl)
+    #TODO
+  end
+
+  def find_meta(hint=false)
+    #TODO
+  end
+
+  def find_pids(hint=false)
+    #TODO
+  end
+
+  def find_xampl(hint=false)
+    #TODO
+  end
+
+  def how_indexed(xampl)
+    #TODO
+  end
+
+  def inspect
+    #TODO
+  end
+
+  def note_errors(msg="TokyoCabinet Error:: %s\n")
+    #TODO
+  end
+
+  def open_tc_db
+    #TODO
+  end
+
+  def optimise(opts={})
+    #TODO
+  end
+
+  def query(hint=false)
+    #TODO
+  end
+
+  def query_implemented
+    #TODO
+  end
+
+  def read_representation(klass, pid)
+    #TODO
+  end
+
+  def remove_all_mention(root, xampl)
+    #TODO
+  end
+
+  def setup_db
+    #TODO
+  end
+
+  def start_sync_write
+    #TODO
+  end
+
+  def to_s
+    #TODO
+  end
+
+=end
+
+  end
+
+
+  Xampl.register_persister_kind(RedisPersister)
+end
+