ceritium-relaxdb 0.2.8

data/lib/more/atomic_bulk_save_support.rb

@@ -0,0 +1,18 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'relaxdb'
+require File.dirname(__FILE__) + '/../../spec/spec_models.rb'
+
+RelaxDB.configure :host => "localhost", :port => 5984
+RelaxDB.delete_db "relaxdb_spec_db" rescue :ok
+RelaxDB.use_db "relaxdb_spec_db"
+
+a1 = Atom.new.save!
+a1_dup = a1.dup
+a1.save!
+begin
+  RelaxDB.bulk_save! a1_dup
+  puts "Atomic bulk_save _not_ supported"
+rescue RelaxDB::UpdateConflict
+  puts "Atomic bulk_save supported"
+end
+  

data/lib/more/grapher.rb

@@ -0,0 +1,48 @@
+module RelaxDB
+  
+  #
+  # The GraphCreator uses dot to create a graphical model of an entire CouchDB database
+  # It probably only makes sense to run it on a database of a limited size
+  # The created graphs can be very useful for exploring relationships
+  # Run ruby scratch/grapher_demo.rb for an example
+  #
+  class GraphCreator
+    
+    def self.create
+      system "mkdir -p graphs"
+      
+      data = JSON.parse(RelaxDB.db.get("_all_docs").body)
+      all_ids = data["rows"].map { |r| r["id"] }
+      all_ids = all_ids.reject { |id| id =~ /_/ }
+      
+      dot = "digraph G { \nrankdir=LR;\nnode [shape=record];\n"
+      all_ids.each do |id|
+        doc = RelaxDB.load(id)
+        atts = "#{doc.class}\\l|"
+        doc.properties.each do |prop|
+          # we don't care about the revision
+          next if prop == :_rev 
+          
+          prop_val = doc.instance_variable_get("@#{prop}".to_sym)
+          atts << "#{prop}\\l#{prop_val}|" if prop_val
+        end
+        atts = atts[0, atts.length-1]
+        
+        dot << %Q%#{doc._id} [ label ="#{atts}"];\n%
+        
+        doc.class.belongs_to_rels.each do |relationship, opts|
+          id = doc.instance_variable_get("@#{relationship}_id".to_sym)
+          dot << %Q%#{id} -> #{doc._id} [ label = "#{relationship}"];\n% if id
+        end
+                  
+      end
+      dot << "}"
+      
+      File.open("graphs/data.dot", "w") { |f| f.write(dot) }
+      
+      system "dot -Tpng -o graphs/all_docs.png graphs/data.dot"
+    end
+    
+  end
+  
+end

data/lib/relaxdb.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'extlib'
+require 'json'
+require 'uuid'
+
+require 'cgi'
+require 'net/http'
+require 'logger'
+require 'parsedate'
+require 'pp'
+require 'tempfile'
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'relaxdb/validators'
+
+require 'relaxdb/all_delegator'
+require 'relaxdb/belongs_to_proxy'
+require 'relaxdb/design_doc'
+require 'relaxdb/document'
+require 'relaxdb/extlib'
+require 'relaxdb/has_many_proxy'
+require 'relaxdb/has_one_proxy'
+require 'relaxdb/paginate_params'
+require 'relaxdb/paginator'
+require 'relaxdb/query'
+require 'relaxdb/references_many_proxy'
+require 'relaxdb/relaxdb'
+require 'relaxdb/server'
+require 'relaxdb/sorted_by_view'
+require 'relaxdb/uuid_generator'
+require 'relaxdb/view_object'
+require 'relaxdb/view_result'
+require 'relaxdb/view_uploader'
+require 'relaxdb/views'
+require 'more/grapher.rb'
+
+module RelaxDB
+end

data/lib/relaxdb/all_delegator.rb

@@ -0,0 +1,68 @@
+module RelaxDB
+  
+  #
+  # The AllDelegator allows clients to query CouchDB in a natural way
+  #   FooDoc.all - returns all docs in CouchDB of type FooDoc
+  #   FooDoc.all.sorted_by(:att1, :att2) - returns all docs in CouchDB of type FooDoc sorted by att1, then att2
+  #   FooDoc.all.sorted_by(:att1) { |q| q.key("bar") } - returns all docs of type FooDoc where att1 equals "bar"
+  #   FooDoc.all.destroy! - does what it says on the tin
+  #   FooDoc.all.size - issues a query to a reduce function that returns the total number of docs for that class
+  #
+  class AllDelegator < Delegator
+    
+    def initialize(class_name)
+      super([])
+      @class_name = class_name
+    end
+    
+    def __getobj__
+      view_path = "_design/#{@class_name}/_view/all?reduce=false"
+      map, reduce = ViewCreator.all(@class_name)
+      
+      RelaxDB.retrieve(view_path, @class_name, "all", map, reduce)
+    end
+
+    def sorted_by(*atts)
+      view = SortedByView.new(@class_name, *atts)
+
+      query = Query.new(@class_name, view.view_name)
+      yield query if block_given?
+      
+      view.query(query)
+    end
+    
+    # Note that this method leaves the corresponding DesignDoc for the associated class intact
+    def destroy!
+      each do |o| 
+        # A reload is required for deleting objects with a self referential references_many relationship
+        # This makes all.destroy! very slow. Given that references_many is now deprecated and will
+        # soon be removed, the required reload is no longer performed.
+        # obj = RelaxDB.load(o._id)
+        # obj.destroy!
+        
+        o.destroy!
+      end
+    end
+    
+    # This is pretty ugly - this pattern is now spread over three 
+    # places (sorted_by_view, relaxdb and here)
+    # Consolidation needed
+    def size
+      view_path = "_design/#{@class_name}/_view/all"
+      map, reduce = ViewCreator.all(@class_name)
+      
+      begin
+        resp = RelaxDB.db.get(view_path)
+      rescue => e
+        DesignDocument.get(@class_name).add_map_view("all", map).
+          add_reduce_view("all", reduce).save
+        resp = RelaxDB.db.get(view_path)
+      end
+      
+      data = JSON.parse(resp.body)
+      data["rows"][0] ? data["rows"][0]["value"] : 0
+    end
+            
+  end
+  
+end

data/lib/relaxdb/belongs_to_proxy.rb

@@ -0,0 +1,29 @@
+module RelaxDB
+
+  class BelongsToProxy
+
+    attr_reader :target
+  
+    def initialize(client, relationship)
+      @client = client
+      @relationship = relationship
+      @target = nil
+    end
+  
+    def target
+      return @target if @target
+            
+      id = @client.instance_variable_get("@#{@relationship}_id")
+      @target = RelaxDB.load(id) if id
+    end
+  
+    def target=(new_target)
+      id = new_target ? new_target._id : nil
+      @client.instance_variable_set("@#{@relationship}_id", id) 
+      
+      @target = new_target
+    end
+    
+  end
+
+end

data/lib/relaxdb/design_doc.rb

@@ -0,0 +1,55 @@
+module RelaxDB
+
+  class DesignDocument
+  
+    def initialize(client_class, data)
+      @client_class = client_class
+      @data = data
+    end
+      
+    def add_map_view(view_name, function)
+      add_view(view_name, "map", function)
+    end
+    
+    def add_reduce_view(view_name, function)
+      add_view(view_name, "reduce", function)
+    end
+    
+    def add_validation_func(function)
+      @data["validate_doc_update"] = function
+      self
+    end
+    
+    def add_view(view_name, type, function)
+      @data["views"] ||= {}
+      @data["views"][view_name] ||= {}
+      @data["views"][view_name][type] = function
+      self            
+    end
+  
+    def save
+      database = RelaxDB.db    
+      resp = database.put(@data["_id"], @data.to_json)
+      @data["_rev"] = JSON.parse(resp.body)["rev"]
+      self
+    end
+  
+    def self.get(client_class)
+      begin
+        database = RelaxDB.db
+        resp = database.get("_design/#{client_class}")
+        DesignDocument.new(client_class, JSON.parse(resp.body))
+      rescue HTTP_404
+        DesignDocument.new(client_class, {"_id" => "_design/#{client_class}"} )
+      end
+    end  
+    
+    def destroy!
+      # Implicitly prevent the object from being resaved by failing to update its revision
+      RelaxDB.db.delete("#{@data["_id"]}?rev=#{@data["_rev"]}")
+      self      
+    end
+  
+  end
+  
+end

data/lib/relaxdb/document.rb

@@ -0,0 +1,531 @@
+module RelaxDB
+    
+  class Document
+    
+    include RelaxDB::Validators
+    
+    # Used to store validation messages
+    attr_accessor :errors
+    
+    # Attribute symbols added to this list won't be validated on save
+    attr_accessor :validation_skip_list
+    
+    # Define properties and property methods
+    
+    def self.property(prop, opts={})
+      # Class instance varibles are not inherited, so the default properties must be explicitly listed 
+      # Perhaps a better solution exists. Revise. I think extlib contains a solution for this...
+      @properties ||= [:_id, :_rev]
+      @properties << prop
+
+      define_method(prop) do
+        instance_variable_get("@#{prop}".to_sym)        
+      end
+
+      define_method("#{prop}=") do |val|
+        instance_variable_set("@#{prop}".to_sym, val)
+      end
+      
+      if opts[:default]
+        define_method("set_default_#{prop}") do
+          default = opts[:default]
+          default = default.is_a?(Proc) ? default.call : default
+          instance_variable_set("@#{prop}".to_sym, default)
+        end
+      end
+      
+      if opts[:validator]
+        create_validator(prop, opts[:validator]) 
+      end
+      
+      if opts[:validation_msg]
+        create_validation_msg(prop, opts[:validation_msg])
+      end
+      
+      if opts[:derived]
+        add_derived_prop(prop, opts[:derived])
+      end
+    end
+
+    def self.properties
+      # Ensure that classes that don't define their own properties still function as CouchDB objects
+      @properties ||= [:_id, :_rev]
+    end
+    
+    def self.create_validator(att, v)
+      method_name = "validate_#{att}"
+      if v.is_a? Proc
+        v.arity == 1 ?
+          define_method(method_name) { |att_val| v.call(att_val) } :
+          define_method(method_name) { |att_val| v.call(att_val, self) }
+      elsif instance_methods.include? "validator_#{v}"
+        define_method(method_name) { |att_val| send("validator_#{v}", att_val, self) }
+      else
+        define_method(method_name) { |att_val| send(v, att_val) }
+      end          
+    end
+    
+    def self.create_validation_msg(att, validation_msg)
+      if validation_msg.is_a?(Proc)        
+        validation_msg.arity == 1 ?
+          define_method("#{att}_validation_msg") { |att_val| validation_msg.call(att_val) } :
+          define_method("#{att}_validation_msg") { |att_val| validation_msg.call(att_val, self) } 
+      else  
+        define_method("#{att}_validation_msg") { validation_msg } 
+      end
+    end
+    
+    # See derived_properties_spec.rb for usage
+    def self.add_derived_prop(prop, deriver)
+        source, writer = deriver[0], deriver[1]
+        @derived_prop_writers ||= {}
+        @derived_prop_writers[source] ||= {}
+        @derived_prop_writers[source][prop] = writer
+    end
+    
+    def self.derived_prop_writers
+      @derived_prop_writers ||= {}
+    end
+    
+    #
+    # The rationale for rescuing the send below is that the lambda for a derived 
+    # property shouldn't need to concern itself with checking the validity of
+    # the underlying property. Nor, IMO, should clients be exposed to the 
+    # possibility of a writer raising an exception.
+    #
+    def write_derived_props(source)
+      writers = self.class.derived_prop_writers[source]
+      if writers 
+        writers.each do |prop, writer|
+          current_val = send(prop)
+          begin
+            send("#{prop}=", writer.call(current_val, self)) 
+          rescue => e
+            RelaxDB.logger.warn "Deriving #{prop} from #{source} raised #{e}"
+          end
+        end
+      end
+    end
+
+    def properties
+      self.class.properties
+    end
+    
+    # Specifying these properties here (after property method has been defined) 
+    # is kinda ugly. Consider a better solution.
+    property :_id 
+    property :_rev    
+    
+    def initialize(hash={})
+      unless hash["_id"]
+        self._id = UuidGenerator.uuid 
+      end
+      
+      @errors = Errors.new
+      @validation_skip_list = []
+
+      # Set default properties if this object isn't being loaded from CouchDB
+      unless hash["_rev"]
+        properties.each do |prop|
+         if methods.include?("set_default_#{prop}")
+           send("set_default_#{prop}")
+         end
+        end
+      end
+            
+      @set_derived_props = hash["_rev"] ? false : true
+      set_attributes(hash)
+      @set_derived_props = true
+    end
+    
+    def set_attributes(data)
+      data.each do |key, val|
+        # Only set instance variables on creation - object references are resolved on demand
+
+        # If the variable name ends in _at, _on or _date try to convert it to a Time
+        if [/_at$/, /_on$/, /_date$/].inject(nil) { |i, r| i ||= (key =~ r) }
+            val = Time.parse(val).utc rescue val
+        end
+        
+        # Ignore param keys that don't have a corresponding writer
+        # This allows us to comfortably accept a hash containing superflous data 
+        # such as a params hash in a controller 
+        send("#{key}=".to_sym, val) if methods.include? "#{key}="
+      end
+    end  
+            
+    def inspect
+      s = "#<#{self.class}:#{self.object_id}"
+      properties.each do |prop|
+        prop_val = instance_variable_get("@#{prop}".to_sym)
+        s << ", #{prop}: #{prop_val.inspect}" if prop_val
+      end
+      self.class.belongs_to_rels.each do |relationship, opts|
+        id = instance_variable_get("@#{relationship}_id".to_sym)
+        s << ", #{relationship}_id: #{id}" if id
+      end
+      s << ", errors: #{errors.inspect}" unless errors.empty?
+      s << ">"
+    end
+    
+    alias_method :to_s, :inspect
+            
+    def to_json
+      data = {}
+      self.class.belongs_to_rels.each do |relationship, opts|
+        id = instance_variable_get("@#{relationship}_id".to_sym)
+        data["#{relationship}_id"] = id if id
+      end
+      properties.each do |prop|
+        prop_val = instance_variable_get("@#{prop}".to_sym)
+        data["#{prop}"] = prop_val if prop_val
+      end
+      data["class"] = self.class.name
+      data.to_json      
+    end
+            
+    # Not yet sure of final implemention for hooks - may lean more towards DM than AR
+    def save
+      if pre_save && save_to_couch
+        after_save
+        self
+      else
+        false
+      end
+    end  
+    
+    def save_to_couch
+      begin
+        resp = RelaxDB.db.put(_id, to_json)
+        self._rev = JSON.parse(resp.body)["rev"]
+      rescue HTTP_409
+        on_update_conflict
+        @update_conflict = true
+        return false
+      end      
+    end
+    
+    def on_update_conflict
+      # override with any behaviour you want to happen when
+      # CouchDB returns DocumentConflict on an attempt to save
+    end
+    
+    def pre_save
+      set_created_at if new_document?
+      return false unless validates?
+      return false unless before_save            
+      true 
+    end  
+    
+    def post_save
+      after_save
+    end
+    
+    def save!
+      if save
+        self
+      elsif update_conflict?
+        raise UpdateConflict, self
+      else
+        raise ValidationFailure, self.errors.to_json
+      end
+    end
+    
+    def save_all
+      RelaxDB.bulk_save(self, *all_children)
+    end
+
+    def save_all!
+      RelaxDB.bulk_save!(self, *all_children)
+    end
+    
+    def all_children      
+      ho = self.class.has_one_rels.map { |r| send(r) }
+      hm = self.class.has_many_rels.inject([]) { |m,r| m += send(r).children }
+      ho + hm
+    end
+    
+    def update_conflict?
+      @update_conflict
+    end
+    
+    def validates?
+      props = properties - validation_skip_list
+      prop_vals = props.map { |prop| instance_variable_get("@#{prop}") }
+      
+      rels = self.class.belongs_to_rels.keys - validation_skip_list
+      rel_vals = rels.map { |rel| instance_variable_get("@#{rel}_id") }
+      
+      att_names = props + rels
+      att_vals =  prop_vals + rel_vals
+      
+      total_success = true      
+      att_names.each_index do |i|
+        att_name, att_val = att_names[i], att_vals[i]
+        if methods.include? "validate_#{att_name}"
+          total_success &= validate_att(att_name, att_val)
+        end
+      end
+            
+      total_success
+    end
+    alias_method :validate, :validates?
+    
+    def validate_att(att_name, att_val)
+      begin
+        success = send("validate_#{att_name}", att_val)
+      rescue => e
+        RelaxDB.logger.warn "Validating #{att_name} with #{att_val} raised #{e}"
+        succes = false
+      end
+
+      unless success
+        if methods.include? "#{att_name}_validation_msg"
+          begin
+            @errors[att_name] = send("#{att_name}_validation_msg", att_val)
+          rescue => e
+            RelaxDB.logger.warn "Validation_msg for #{att_name} with #{att_val} raised #{e}"
+            @errors[att_name] = "validation_msg_exception:invalid:#{att_val}"
+          end
+        elsif @errors[att_name].nil?
+          # The above prevents overwriting when validators set their own
+          # validation messages
+          @errors[att_name] = "invalid:#{att_val}"
+        end
+      end
+      success
+    end
+            
+    def new_document?
+      @_rev.nil?
+    end
+    alias_method :new_record?, :new_document?
+    alias_method :unsaved?, :new_document?
+    
+    def to_param
+      self._id
+    end
+    alias_method :id, :to_param
+    
+    def set_created_at
+      if methods.include? "created_at"
+        # Don't override it if it's already been set
+        @created_at = Time.now if @created_at.nil?
+      end
+    end
+       
+    def create_or_get_proxy(klass, relationship, opts=nil)
+      proxy_sym = "@proxy_#{relationship}".to_sym
+      proxy = instance_variable_get(proxy_sym)
+      unless proxy
+        proxy = opts ? klass.new(self, relationship, opts) : klass.new(self, relationship)
+        instance_variable_set(proxy_sym, proxy)
+      end
+      proxy     
+    end
+    
+    # Returns true if CouchDB considers other to be the same as self
+    def ==(other)
+      other && _id == other._id
+    end
+   
+    # If you're using this method, read the specs and make sure you understand
+    # how it can be used and how it shouldn't be used
+    def self.references_many(relationship, opts={})
+      # Treat the representation as a standard property 
+      properties << relationship
+      
+      # Keep track of the relationship so peers can be disassociated on destroy
+      @references_many_rels ||= []
+      @references_many_rels << relationship
+     
+      id_arr_sym = "@#{relationship}".to_sym
+     
+      define_method(relationship) do
+        instance_variable_set(id_arr_sym, []) unless instance_variable_defined? id_arr_sym
+        create_or_get_proxy(ReferencesManyProxy, relationship, opts)
+      end
+      
+      define_method("#{relationship}_ids") do
+        instance_variable_set(id_arr_sym, []) unless instance_variable_defined? id_arr_sym
+        instance_variable_get(id_arr_sym)
+      end
+    
+      define_method("#{relationship}=") do |val|
+        # Don't invoke this method unless you know what you're doing
+        instance_variable_set(id_arr_sym, val)
+      end           
+    end
+   
+    def self.references_many_rels
+      @references_many_rels ||= []
+    end
+   
+    def self.has_many(relationship, opts={})
+      @has_many_rels ||= []
+      @has_many_rels << relationship
+      
+      define_method(relationship) do
+        create_or_get_proxy(HasManyProxy, relationship, opts)
+      end
+      
+      define_method("#{relationship}=") do |children|
+        create_or_get_proxy(HasManyProxy, relationship, opts).children = children
+        write_derived_props(relationship) if @set_derived_props
+        children
+      end      
+    end
+
+    def self.has_many_rels
+      # Don't force clients to check its instantiated
+      @has_many_rels ||= []
+    end
+            
+    def self.has_one(relationship)
+      @has_one_rels ||= []
+      @has_one_rels << relationship
+      
+      define_method(relationship) do      
+        create_or_get_proxy(HasOneProxy, relationship).target
+      end
+      
+      define_method("#{relationship}=") do |new_target|
+        create_or_get_proxy(HasOneProxy, relationship).target = new_target
+        write_derived_props(relationship) if @set_derived_props
+        new_target
+      end
+    end
+    
+    def self.has_one_rels
+      @has_one_rels ||= []      
+    end
+            
+    def self.belongs_to(relationship, opts={})
+      @belongs_to_rels ||= {}
+      @belongs_to_rels[relationship] = opts
+
+      define_method(relationship) do
+        create_or_get_proxy(BelongsToProxy, relationship).target
+      end
+      
+      define_method("#{relationship}=") do |new_target|
+        create_or_get_proxy(BelongsToProxy, relationship).target = new_target
+        write_derived_props(relationship) if @set_derived_props
+      end
+      
+      # Allows all writers to be invoked from the hash passed to initialize 
+      define_method("#{relationship}_id=") do |id|
+        instance_variable_set("@#{relationship}_id".to_sym, id)
+        write_derived_props(relationship) if @set_derived_props
+        id
+      end
+
+      # Allows belongs_to relationships to be used by the paginator
+      define_method("#{relationship}_id") do
+        instance_variable_get("@#{relationship}_id")
+      end
+      
+      create_validator(relationship, opts[:validator]) if opts[:validator]
+      
+      # Untested below
+      create_validation_msg(relationship, opts[:validation_msg]) if opts[:validation_msg]
+    end
+  
+    class << self
+      alias_method :references, :belongs_to
+    end
+    
+    def self.belongs_to_rels
+      @belongs_to_rels ||= {}
+    end
+    
+    def self.all_relationships
+      belongs_to_rels + has_one_rels + has_many_rels + references_many_rels
+    end
+        
+    def self.all
+      @all_delegator ||= AllDelegator.new(self.name)
+    end
+                    
+    # destroy! nullifies all relationships with peers and children before deleting 
+    # itself in CouchDB
+    # The nullification and deletion are not performed in a transaction
+    #
+    # TODO: Current implemention may be inappropriate - causing CouchDB to try to JSON
+    # encode undefined. Ensure nil is serialized? See has_many_spec#should nullify its child relationships
+    def destroy!
+      self.class.references_many_rels.each do |rel|
+        send(rel).clear
+      end
+      
+      self.class.has_many_rels.each do |rel|
+        send(rel).clear
+      end
+      
+      self.class.has_one_rels.each do |rel|
+        send("#{rel}=".to_sym, nil)
+      end
+      
+      # Implicitly prevent the object from being resaved by failing to update its revision
+      RelaxDB.db.delete("#{_id}?rev=#{_rev}")
+      self
+    end
+    
+    #
+    # Callbacks - define these in a module and mix'em'in ?
+    #
+    def self.before_save(callback)
+      before_save_callbacks << callback
+    end 
+    
+    def self.before_save_callbacks
+      @before_save ||= []
+    end       
+    
+    def before_save
+      self.class.before_save_callbacks.each do |callback|
+        resp = callback.is_a?(Proc) ? callback.call(self) : send(callback)
+        if resp == false
+          errors[:before_save] = :failed
+          return false
+        end
+      end
+    end
+    
+    def self.after_save(callback)
+      after_save_callbacks << callback
+    end
+    
+    def self.after_save_callbacks
+      @after_save_callbacks ||= []
+    end
+    
+    def after_save
+      self.class.after_save_callbacks.each do |callback|
+        callback.is_a?(Proc) ? callback.call(self) : send(callback)
+      end
+    end
+    
+    def self.paginate_by(page_params, *view_keys)
+      paginate_params = PaginateParams.new
+      yield paginate_params
+      raise paginate_params.error_msg if paginate_params.invalid? 
+      
+      paginator = Paginator.new(paginate_params, page_params)
+                  
+      design_doc_name = self.name
+      view = SortedByView.new(design_doc_name, *view_keys)
+      query = Query.new(design_doc_name, view.view_name)
+      query.merge(paginate_params)
+      
+      docs = view.query(query)
+      docs.reverse! if paginate_params.order_inverted?
+      
+      paginator.add_next_and_prev(docs, design_doc_name, view.view_name, view_keys)
+      
+      docs
+    end
+                
+  end
+  
+end