paulcarey-relaxdb 0.2.0 → 0.2.1

data/README.textile

@@ -1,6 +1,10 @@
 h3. What's New?
- * Pagination! CouchDB offers great support for retrieving a subset of data, but the housekeeping is tricky. RelaxDB takes care of it.
- * Works with CouchDB 0.9 trunk as of 2008/10/08. Note that pagination won't work on trunk unil https://issues.apache.org/jira/browse/COUCHDB-135 is fixed.
+
+* Pagination! CouchDB offers great support for retrieving a subset of data, but the housekeeping is tricky. RelaxDB takes care of it.
+** Note that if you invoke paginate_by on an already created view, the necessary reduce function won't be automatically created. Take a look at SortedByView and create the reduce func by hand.
+* Works with CouchDB 0.9 trunk as of 2008/10/08. Note that pagination won't work correctly on trunk until issue "COUCHDB-135":http://issues.apache.org/jira/browse/COUCHDB-135 is fixed.
+
+*Note*: 0.2.1 requires CouchDB 0.9 trunk. 0.2.0 works with CouchDB 0.8 onwards.
 
 h2. Overview
 
@@ -68,7 +72,7 @@ h3. Exploring models
 </code>
 </pre>
 
-h3. Paginating
+h3. Paginating models
 
 <pre>
 <code>
@@ -94,6 +98,20 @@ h3. Paginating
 </code>
 </pre>
 
+h3. Paginating over your own views
+
+<pre>
+<code>
+
+RelaxDB.paginate_view(page_params, "Letter", "by_letter_and_number", :letter, :number) do |p|
+  p.startkey(["b"]).endkey(["b", {}]).count(2)
+end
+
+</code>
+</pre>
+
+A more illustrative example is listed in the .paginate_view spec in spec/paginate_spec.rb
+
 h3. Creating views by hand
 
 <pre>

data/Rakefile

@@ -4,7 +4,7 @@ require 'spec/rake/spectask'
 
 PLUGIN = "relaxdb"
 NAME = "relaxdb"
-GEM_VERSION = "0.2.0"
+GEM_VERSION = "0.2.1"
 AUTHOR = "Paul Carey"
 EMAIL = "paul.p.carey@gmail.com"
 HOMEPAGE = "http://github.com/paulcarey/relaxdb/"

data/lib/relaxdb/all_delegator.rb

@@ -9,25 +9,25 @@ module RelaxDB
   #
   class AllDelegator < Delegator
     
-    def initialize(klass)
+    def initialize(class_name)
       super([])
-      @klass = klass
+      @class_name = class_name
     end
     
     def __getobj__
-      view_path = "_view/#{@klass}/all"
-      map_function = ViewCreator.all(@klass)
+      view_path = "_view/#{@class_name}/all"
+      map_function = ViewCreator.all(@class_name)
       
-      @all = RelaxDB.retrieve(view_path, @klass, "all", map_function)      
+      @all = RelaxDB.retrieve(view_path, @class_name, "all", map_function)      
     end
 
     def sorted_by(*atts)
-      v = SortedByView.new(@klass.name, *atts)
+      view = SortedByView.new(@class_name, *atts)
 
-      q = Query.new(@klass.name, v.view_name)
-      yield q if block_given?
+      query = Query.new(@class_name, view.view_name)
+      yield query if block_given?
       
-      RelaxDB.retrieve(q.view_path, @klass, v.view_name, v.map_function)      
+      view.query(query)
     end
     
     # Note that this method leaves the corresponding DesignDoc for the associated class intact

data/lib/relaxdb/document.rb

@@ -296,7 +296,7 @@ module RelaxDB
     end
         
     def self.all
-      @all_delegator ||= AllDelegator.new(self)      
+      @all_delegator ||= AllDelegator.new(self.name)
     end
                     
     # destroy! nullifies all relationships with peers and children before deleting 
@@ -352,23 +352,34 @@ module RelaxDB
       end
     end
     
-    def self.paginate_by(page_params, *atts)
+    #
+    # Document views are generated on demand if they don't exist when queried. 
+    # The paginator is used with both document generated views, and user defined views.
+    # Auto generating document views on demand in the paginator makes it significantly
+    # more complex and less amendable to use by user defined views. For these reasons,
+    # the first call to paginate_by for a particular list of attributes for a particular 
+    # Document class will update the corresponding design doc, even if it already contains
+    # the required view. This should not incur a penalty with CouchDB as it uses the 
+    # same index for byte identical views.
+    #
+    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)
                   
-      doc_view = SortedByView.new(self.name, *atts)
-      doc_query = Query.new(self.name, doc_view.view_name)
-      doc_query.merge(paginator.paginate_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 = RelaxDB.retrieve(doc_query.view_path, self, doc_view.view_name, doc_view.map_function)
-      @docs.reverse! if paginate_params.order_inverted?
+      docs = view.query(query)
+      docs.reverse! if paginate_params.order_inverted?
       
-      paginator.add_next_and_prev(@docs, self.name, doc_view, atts)
+      paginator.add_next_and_prev(docs, design_doc_name, view.view_name, view_keys)
       
-      @docs
+      docs
     end
                 
   end

data/lib/relaxdb/paginate_params.rb

@@ -2,7 +2,7 @@ module RelaxDB
 
   class PaginateParams
         
-    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending group)
+    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending group reduce)
   
     @@params.each do |param|
       define_method(param.to_sym) do |*val|
@@ -20,6 +20,8 @@ module RelaxDB
     def initialize
       # If a client hasn't explicitly set descending, set it to the CouchDB default
       @descending = false if @descending.nil?
+      # CouchDB defaults reduce to true when a reduce func is present
+      @reduce = false
     end
   
     def update(params)

data/lib/relaxdb/paginator.rb

@@ -9,48 +9,32 @@ module RelaxDB
       @orig_paginate_params = @paginate_params.clone
       
       page_params = page_params.is_a?(String) ? JSON.parse(page_params).to_mash : page_params
+      # Where the magic happens - the original params are updated with the page specific params
       @paginate_params.update(page_params)
     end
 
-    def total_doc_count(design_doc, view)
-      query = lambda do
-        RelaxDB.view(design_doc, view.reduce_view_name) do |q|
-          q.group(true).group_level(0)
-          q.startkey(@orig_paginate_params.startkey).endkey(@orig_paginate_params.endkey).descending(@orig_paginate_params.descending)  
-        end
+    def total_doc_count(design_doc, view_name)
+      result = RelaxDB.view(design_doc, view_name) do |q|
+        q.group(true).group_level(0).reduce(true)
+        q.startkey(@orig_paginate_params.startkey).endkey(@orig_paginate_params.endkey).descending(@orig_paginate_params.descending)  
       end
       
-      begin
-        result = query.call
-      rescue
-        # add the map reduce func if it doesn't exist
-        DesignDocument.get(design_doc).add_map_view(view.reduce_view_name, view.map_function).
-          add_reduce_view(view.reduce_view_name, view.reduce_function).save
-        result = query.call
-      end        
-      
       total_docs = RelaxDB.reduce_result(result)
     end
     
-    def add_next_and_prev(docs, design_doc, view, view_keys)
+    def add_next_and_prev(docs, design_doc, view_name, view_keys)
       unless docs.empty?
         no_docs = docs.size
         offset = docs.offset
-        orig_offset = orig_offset(Query.new(design_doc, view.view_name), view)
-        total_doc_count = total_doc_count(design_doc, view)      
+        orig_offset = orig_offset(design_doc, view_name)
+        total_doc_count = total_doc_count(design_doc, view_name)      
       
-        next_key = view_keys.map { |a| docs.last.send(a) }
-        next_key = next_key.length == 1 ? next_key[0] : next_key
-        next_key_docid = docs.last._id
-        next_params = { :startkey => next_key, :startkey_docid => next_key_docid, :descending => @orig_paginate_params.descending }
         next_exists = !@paginate_params.order_inverted? ? (offset - orig_offset + no_docs < total_doc_count) : true
-      
-        prev_key = view_keys.map { |a| docs.first.send(a) }
-        prev_key = prev_key.length == 1 ? prev_key[0] : prev_key
-        prev_key_docid = docs.first._id
-        prev_params = { :startkey => prev_key, :startkey_docid => prev_key_docid, :descending => !@orig_paginate_params.descending }
+        next_params = create_next(docs.last, view_keys) if next_exists
+    
         prev_exists = @paginate_params.order_inverted? ? (offset - orig_offset + no_docs < total_doc_count) : 
           (offset - orig_offset == 0 ? false : true)
+        prev_params = create_prev(docs.first, view_keys) if prev_exists
       else
         next_exists, prev_exists = false
       end
@@ -64,14 +48,29 @@ module RelaxDB
       end      
     end
     
-    def orig_offset(query, view)
+    def create_next(doc, view_keys)
+      next_key = view_keys.map { |a| doc.send(a) }
+      next_key = next_key.length == 1 ? next_key[0] : next_key
+      next_key_docid = doc._id
+      { :startkey => next_key, :startkey_docid => next_key_docid, :descending => @orig_paginate_params.descending }
+    end
+    
+    def create_prev(doc, view_keys)
+      prev_key = view_keys.map { |a| doc.send(a) }
+      prev_key = prev_key.length == 1 ? prev_key[0] : prev_key
+      prev_key_docid = doc._id
+      prev_params = { :startkey => prev_key, :startkey_docid => prev_key_docid, :descending => !@orig_paginate_params.descending }
+    end
+    
+    def orig_offset(design_doc, view_name)
+      query = Query.new(design_doc, view_name)
       if @paginate_params.order_inverted?
         query.startkey(@orig_paginate_params.endkey).descending(!@orig_paginate_params.descending)
       else
         query.startkey(@orig_paginate_params.startkey).descending(@orig_paginate_params.descending)
       end
-      query.count(1)
-      RelaxDB.retrieve(query.view_path, self, view.view_name, view.map_function).offset
+      query.reduce(false).count(1)
+      RelaxDB.retrieve(query.view_path).offset
     end
     
   end

data/lib/relaxdb/query.rb

@@ -16,14 +16,18 @@ module RelaxDB
   #
   class Query
     
-    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending skip group group_level)
+    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending skip group group_level reduce)
     
     @@params.each do |param|
-      define_method(param.to_sym) do |val|
-        instance_variable_set("@#{param}", val)
-        # null is meaningful to CouchDB. _set allows us to know that a param has been set, even to nil        
-        instance_variable_set("@#{param}_set", true)
-        self
+      define_method(param.to_sym) do |*val|
+        if val.empty?
+          instance_variable_get("@#{param}")
+        else 
+          instance_variable_set("@#{param}", val[0])
+          # null is meaningful to CouchDB. _set allows us to know that a param has been set, even to nil        
+          instance_variable_set("@#{param}_set", true)
+          self
+        end
       end
     end
         

data/lib/relaxdb/relaxdb.rb

@@ -54,7 +54,7 @@ module RelaxDB
     end
     
     # Used internally by RelaxDB
-    def retrieve(view_path, design_doc, view_name, map_function)
+    def retrieve(view_path, design_doc=nil, view_name=nil, map_function=nil)
       begin
         resp = db.get(view_path)
       rescue => e
@@ -99,6 +99,24 @@ module RelaxDB
       obj = data["rows"][0] && data["rows"][0]["value"]
       ViewObject.create(obj)      
     end
+    
+    def paginate_view(page_params, design_doc, view_name, *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)
+                  
+      query = Query.new(design_doc, view_name)
+      query.merge(paginate_params)
+      
+      docs = ViewResult.new(JSON.parse(db.get(query.view_path).body))
+      docs.reverse! if paginate_params.order_inverted?
+      
+      paginator.add_next_and_prev(docs, design_doc, view_name, view_keys)
+      
+      docs
+    end
         
     def create_from_hash(data)
       data["rows"].map { |row| create_object(row["value"]) }

data/lib/relaxdb/sorted_by_view.rb

@@ -10,19 +10,13 @@ module RelaxDB
     end
 
     def map_function
-      # To guard against non existing attributes in older documents, an OR with an object literal 
-      # is inserted for each emitted key. The guard can be emitted in 0.9 trunk.
-      # The object literal is the lowest sorting JSON category
-        
-      # Create the key from the attributes, wrapping it in [] if the key is composite
-      raw = @atts.inject("") { |m,v| m << "(doc.#{v}||{}), " }
-      refined = raw[0, raw.size-2]
-      pure = @atts.size > 1 ? refined.sub(/^/, "[").sub(/$/, "]") : refined
+      key = @atts.map { |a| "doc.#{a}" }.join(", ")
+      key = @atts.size > 1 ? key.sub(/^/, "[").sub(/$/, "]") : key
     
       <<-QUERY
       function(doc) {
         if(doc.class == "#{@class_name}") {
-          emit(#{pure}, doc);
+          emit(#{key}, doc);
         }
       }
       QUERY
@@ -37,19 +31,30 @@ module RelaxDB
     end
     
     def view_name
-      name = "all_sorted_by#{suffix}"
-    end
-    
-    def reduce_view_name
-      "reduce_by#{suffix}"
-    end
-    
-    def suffix
-      s = @atts.inject("") do |s, att|
+      s = @atts.inject("all_sorted_by") do |s, att|
         s << "_#{att}_and"
       end
       s[0, s.size-4]
     end
+        
+    def query(query)
+      # If a view contains both a map and reduce function, CouchDB will by default return 
+      # the result of the reduce function when queried. 
+      # This class automatically creates both map and reduce functions so it can be used by the paginator.
+      # In normal usage, this class will be used with map functions, hence reduce is explicitly set to false.
+      query.reduce(false) if query.reduce.nil?
+      
+      begin
+        resp = RelaxDB.db.get(query.view_path)
+      rescue => e
+        design_doc = DesignDocument.get(@class_name) 
+        design_doc.add_map_view(view_name, map_function).add_reduce_view(view_name, reduce_function).save
+        resp = RelaxDB.db.get(query.view_path)
+      end
+
+      data = JSON.parse(resp.body)
+      ViewResult.new(data)            
+    end
   
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: paulcarey-relaxdb
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Paul Carey