aqua 0.1.6 → 0.2.0

data/lib/aqua/store/couch_db/couch_db.rb

@@ -3,6 +3,7 @@ require File.dirname(__FILE__) + '/server'
 require File.dirname(__FILE__) + '/database'
 require File.dirname(__FILE__) + '/attachments'
 require File.dirname(__FILE__) + '/storage_methods'
+require File.dirname(__FILE__) + '/result_set'
 require File.dirname(__FILE__) + '/design_document'
 
 module Aqua

data/lib/aqua/store/couch_db/database.rb

@@ -146,7 +146,7 @@ module Aqua
           CouchDB.delete( uri )
         end  
     
-        # # Query the <tt>documents</tt> view. Accepts all the same arguments as view.
+        # Query the <tt>documents</tt> view. Accepts all the same arguments as view.
         def documents(params = {})
           keys = params.delete(:keys)
           url = CouchDB.paramify_url( "#{uri}/_all_docs", params )

data/lib/aqua/store/couch_db/design_document.rb

@@ -31,8 +31,16 @@ module Aqua
         def initialize( hash={} )
           hash = Mash.new( hash ) unless hash.empty?
           self.id = hash.delete(:name) if hash[:name]
-          document_initialize( hash )
-        end      
+          document_initialize( hash )  # TODO: can't this just be a call to super?
+        end 
+        
+        def do_rev( hash )
+          # TODO: This is a temp hack to deal with loading the right revision number so a design doc
+          # can be updated from the document. Without this hack, the rev is nil, and there is a conflict.
+        
+          hash.delete(:rev)   # This is omited to aleviate confusion
+          # hash.delete(:_rev)  # CouchDB determines _rev attribute
+        end     
         
         # couchdb database url for the design document
         # @return [String] representing CouchDB uri for document 
@@ -49,6 +57,122 @@ module Aqua
         def update_version( result ) 
           self.id     = result['id'].gsub(/\A_design\//, '')
           self.rev    = result['rev']
+        end
+        
+        # Gets a design document by name.
+        # @param [String] Id/Name of design document
+        # @return [Aqua::Store::CouchDB::DesignDocument]
+        # @api public
+        def self.get( name )
+          design = CouchDB.get( "#{database.uri}/_design/#{CGI.escape(name)}" )
+          new( design )
+        end
+        
+        # VIEWS --------------------
+        
+        # An array of indexed views for the design document.
+        # @return [Array]
+        # @api public
+        def views
+          self[:views] ||= Mash.new
+        end 
+        
+        # Adds or updates a view with the given options
+        #
+        # @param [String, Hash] Name of the view, or options hash
+        # @option arg [String] :name The view name, required
+        # @option arg [String] :map Javascript map function, optional
+        # @option arg [String] :reduce Javascript reduce function, optional
+        #
+        # @return [Mash] Map/Reduce mash of javascript functions
+        #
+        # @example 
+        #   design_doc << 'attribute_name'
+        #   design_doc << {:name => 'attribute_name', :map => 'function(doc){ ... }'}
+        #  
+        # @api public
+        def <<( arg )
+          # handle different argument options
+          if [String, Symbol].include?( arg.class )
+            view_name = arg
+            opts = {}
+          elsif arg.class.ancestors.include?( Hash )
+            opts = Mash.new( arg )
+            view_name = opts.delete( :name )
+            raise ArgumentError, 'Option must include a :name that is the view\'s name' unless view_name
+          else
+            raise ArgumentError, "Must be a string or Hash like object of options"    
+          end
+          
+          # build the map/reduce query  
+          map =     opts[:map]
+          reduce =  opts[:reduce]
+          views # to initialize self[:views]
+          self[:views][view_name] = { 
+            :map => map || build_map( view_name, opts[:class_constraint] ), 
+          }
+          self[:views][view_name][:reduce] = reduce if reduce
+          self[:views][view_name]
+        end
+        
+        alias :add :<<
+        
+        def add!( arg ) 
+          self << arg 
+          save!
+        end  
+        
+        private
+          # Builds a generic map assuming that the view_name is the name of a document attribute.
+          # @param [String, Symbol] Name of document attribute
+          # @param [Class, String] Optional constraint on to limit view to a given class
+          # @return [String] Javascript map function
+          #
+          # @api private
+          def build_map( view_name, class_constraint=nil )
+            class_constraint = if class_constraint.class == Class
+              " && doc['type'] == '#{class_constraint}'"
+            elsif class_constraint.class == String
+              " && #{class_constraint}"
+            end    
+            "function(doc) {
+              if( doc['#{view_name}'] #{class_constraint}){
+                emit( doc['#{view_name}'], 1 );
+              }
+            }"
+          end 
+        public
+        
+        # group=true Version 0.8.0 and forward
+        # group_level=int
+        # reduce=false Trunk only (0.9)
+        
+        def query( view_name, opts={} )
+          opts = Mash.new( opts ) unless opts.empty? 
+          doc_class = opts[:document_class] 
+          
+          params = []
+          params << 'include_docs=true' unless (opts[:select] && opts[:select] != 'all')
+          # TODO: this is according to couchdb really inefficent with large sets of data.
+          # A better way would involve, using start and end keys with limit. But this 
+          # is a really hard one to figure with jumping around to different pages
+          params << "skip=#{opts[:offset]}" if opts[:offset]
+          params << "limit=#{opts[:limit]}" if opts[:limit]
+          params << "key=#{opts[:equals]}" if opts[:equals] 
+          if opts[:order].to_s == 'desc' || opts[:order].to_s == 'descending'
+            desc = true
+            params << "descending=true"
+          end 
+          if opts[:range] && opts[:range].size == 2
+            params << "startkey=#{opts[:range][desc == true ? 1 : 0 ]}"  
+            params << "endkey=#{opts[:range][desc == true ? 0 : 1]}"   
+          end   
+          
+          query_uri = "#{uri}/_view/#{CGI.escape(view_name.to_s)}?"
+          query_uri << params.join('&')
+          
+          result = CouchDB.get( query_uri )
+          opts[:reduced] ? result['rows'].first['value'] : ResultSet.new( result, doc_class )
         end 
         
       end

data/lib/aqua/store/couch_db/result_set.rb

@@ -0,0 +1,36 @@
+module Aqua
+  module Store 
+    module CouchDB
+      class ResultSet < Array
+        
+        def self.document_class
+          @document_class
+        end
+        
+        def self.document_class=( klass )
+          @document_class = klass
+        end    
+        
+        attr_accessor :offset, :total, :rows, :document_class
+        
+        def initialize( response, doc_class=nil )
+          self.document_class = doc_class || self.class.document_class
+          self.total    = response['total_rows']
+          self.offset   = response['offset']
+          self.rows     = response['rows']
+          results = if rows && rows.first && rows.first['doc']
+            if document_class
+              rows.collect{ |h| document_class.new( h['doc'] ) }
+            else
+              rows.collect{ |h| h['doc'] }
+            end    
+          else
+            rows.collect{ |h| h['key'] } 
+          end    
+          super( results )
+        end
+           
+      end
+    end
+  end
+end    

data/lib/aqua/store/couch_db/storage_methods.rb

@@ -64,14 +64,33 @@ module Aqua
             @database = db
           end
           
-          # gets a document from the database based on id
+          # Gets a document from the database based on id
           # @param [String] id 
           # @return [Hash] representing the CouchDB data
           # @api public
           def get( id )
-            new( CouchDB.get( "#{database.uri}/#{CGI.escape(id)}" ) )
+            resource = begin # this is just in case the developer has already escaped the name
+              CouchDB.get( "#{database.uri}/#{CGI.escape(id)}" )
+            rescue
+              CouchDB.get( "#{database.uri}/#{id}" )  
+            end
+            new( resource ) 
           end 
           
+          # Will find a document by id, or create it if it doesn't exist. Alias is :get!
+          # @param [String] id
+          # @return [Hash] representing the CouchDB resource
+          # @api public
+          def find_or_create( id )
+            begin
+              get( id )
+            rescue
+              create!( :id => id )
+            end    
+          end  
+          
+          alias :get! :find_or_create
+          
           # Retrieves an attachment when provided the document id and attachment id, or the combined id 
           #
           # @return [Tempfile]
@@ -81,10 +100,149 @@ module Aqua
             new( :id => document_id ).attachments.get!( attachment_id )
           end
           
-          # Creates basic map reduce view for a given field
+          # Accessor for maintaining connection to aquatic class
+          # @api private
+          attr_accessor :parent_class
+          alias :design_name=  :parent_class=
+          alias :design_name   :parent_class 
+          
+          # Finds or creates design document based on aqua parent class name
+          # @api semi-private 
+          def design_document( reload=false )
+            @design_document = nil if reload 
+            @design_document ||= design_name ? DesignDocument.find_or_create( design_name ) : nil
+          end  
+          
+          # Stores stores a map name for a given index, allowing the same map 
+          # to be used for various reduce functions. This means only one index is created.
+          # @param [String] field being indexed, or the sub field
+          # @param [Hash, Mash] Hash of functions used to create views
+          # @option opts [String] :map Javascript/CouchDB map function
+          # @option opts [String] :reduce Javascript/CouchDB reduce function
+          # 
+          # @api public 
           def index_on( field, opts={} )
-            
-          end   
+            opts = Mash.new( opts )
+            design_document(true).add!( opts.merge!(:name => field) )
+            unless indexes.include?( field )
+              indexes << field.to_sym  
+              indexes << field.to_s 
+            end  
+            self     
+          end
+          
+          # This is an aqua specific indexer whereas index_on is a more generic CouchDB indexer. 
+          # This method seeks out the designated ivar in an Aqua structured document. Future iterations
+          # should go deeper into the ivar to reduce the overall size of the index, and make for more 
+          # usable searches.
+          # 
+          # @api private
+          def index_on_ivar( field ) 
+            index_on( field,
+              :map => "
+                function(doc) {
+                  if( doc['class'] == '#{parent_class}' &&
+                      doc['ivars'] && doc['ivars']['@#{field}']    ){
+                    emit( doc['ivars']['@#{field}'], 1 );
+                  }
+                }
+              "
+            )
+          end  
+          
+          # A list of index names that can be used to build other reduce functions.
+          # @api semi-private
+          def indexes
+            @indexes ||= []
+          end
+          
+          # @api public
+          def query( index, opts={} )
+            raise ArgumentError, 'Index not found' unless views.include?( index.to_s )
+            opts = Mash.new(opts)
+            opts.merge!(:document_class => self) unless opts[:document_class]
+            opts.merge!(:reduced => design_document.views[index][:reduce] ? true : false )
+            design_document.query( index, opts )
+          end 
+          
+          def reduced_query( reduce_type, index, opts)
+            view =  "#{index}_#{reduce_type}" 
+            unless views.include?( view )
+              design_document(true).add!(
+                :name => view, 
+                :map => design_document.views[ index.to_s ][:map],
+                :reduce => opts[:reduce]
+              )
+            end  
+            query( view, opts.merge!( :select => "index only" ) )
+          end  
+          
+          # @api semi-private
+          def views
+            design_document.views.keys
+          end
+          
+          # @api public
+          def count( index, opts={} )
+            opts = Mash.new(opts)
+            opts[:reduce] = "
+              function (key, values, rereduce) {
+                  return sum(values);
+              }" unless opts[:reduce]
+            reduced_query(:count, index, opts)
+          end
+          
+          # @api public
+          def sum( index, opts={} )
+            opts = Mash.new(opts)
+            opts[:reduce] = "
+              function (keys, values, rereduce) {
+                var key_values = []
+                keys.forEach( function(key) {
+                  key_values[key_values.length] = key[0]
+                });
+                return sum( key_values );
+              }" unless opts[:reduce]
+            reduced_query(:sum, index, opts)
+          end
+          
+          def average( index, opts={} )
+            sum(index, opts) / count(index, opts).to_f
+          end 
+          
+          alias :avg :average
+          
+          def min( index, opts={} )
+            opts = Mash.new(opts)
+            opts[:reduce] = "
+              function (keys, values, rereduce) {
+                var key_values = []
+                keys.forEach( function(key) {
+                  key_values[key_values.length] = key[0]
+                });
+                return Math.min.apply( Math, key_values ); ;
+              }" unless opts[:reduce]
+            reduced_query(:min, index, opts)
+          end
+          
+          alias :minimum :min
+          
+          def max( index, opts={} )
+            opts = Mash.new(opts)
+            opts[:reduce] = "
+              function (keys, values, rereduce) {
+                var key_values = []
+                keys.forEach( function(key) {
+                  key_values[key_values.length] = key[0]
+                });
+                return Math.max.apply( Math, key_values ); ;
+              }" unless opts[:reduce]
+            reduced_query(:max, index, opts)
+          end 
+          
+          alias :maximum :max
+               
+             
         end     
         
         module InstanceMethods
@@ -96,17 +254,23 @@ module Aqua
           # @api public
           def initialize( hash={} )
             hash = Mash.new( hash ) unless hash.empty?
-            self.id = hash.delete(:id) if hash[:id]
-          
-            # ignore these keys
-            hash.delete(:rev)   # This is omited to aleviate confusion
-            hash.delete(:_rev)  # CouchDB determines _rev attribute
-            hash.delete(:_id)   # this is set via by the id=(value) method 
-            # TODO: have to deal with attachments as well
+            
+            hashed_id = hash.delete(:id) || hash.delete(:_id)
+            self.id = hashed_id if hashed_id
           
+            do_rev( hash )
+            
             # feed the rest of the hash to the super 
             super( hash )      
-          end 
+          end
+          
+          # Temporary hack to allow design document refresh from within a doc.
+          # @todo The get method has to handle rev better!!!
+          def do_rev( hash, override=false )
+            hash.delete(:rev)   # This is omited to aleviate confusion 
+            # CouchDB determines _rev attribute on saving, but when #new is loading json passed from the 
+            # database rev needs to be added to the class. So, the :_rev param is not being deleted anymore
+          end   
         
           # Saves an Aqua::Storage instance to CouchDB as a document. Save can be deferred for bulk saving.
           #
@@ -191,8 +355,10 @@ module Aqua
           # @return [Hash] representing the CouchDB data
           # @api public
           def retrieve
-            self.class.new( CouchDB.get( uri ) )
-          end
+            self.class.get( id )
+          end 
+          
+          alias :reload :retrieve
           
           # reloads self from CouchDB database
           # @return [Hash] representing CouchDB data
@@ -395,8 +561,7 @@ module Aqua
           # @api public
           def attachments
             @attachments ||= Attachments.new( self )
-          end  
-            
+          end
         end # InstanceMethods           
         
       end # StoreMethods

data/lib/aqua/store/storage.rb

@@ -1,58 +1,14 @@
-# This is the interface between an individual object and the Storage representation.
-# The storage engine should provide a module that gets included into the Mash. The 
-# module should minimally provide this interface to the object:
-#
-#   InstanceMethods
-#     @inteface_level optional If no initialization is included. Then the Mash initialization will be used.
-#     initialize( hash )
-#       @param [optional Hash]
-#       @return [Aqua::Storage] the new storage instance
-#     
-#     @interface_level mandatory
-#     commit
-#       @return [Aqua::Storage] saved storage object
-#       @raise [Aqua::ObjectNotFound] if another error occurs in the engine, that should be raised instead 
-#         any of the Aqua Exceptions 
-# 
-#     @interface_level mandatory
-#     id
-#       @param none
-#       @return id object, whether String, Fixnum or other object as the store chooses
-# 
-#     @interface_level mandatory
-#     id=( custom_id )
-#       The library expects to save an object with a custom id. Id= method can set limits on the 
-#       types of objects that can be used as an id. Minimally it should support Strings. 
-#       @param String, Fixnum, or any other reasonable class
-#
-#     @interface_level mandatory
-#     new?
-#       The equivalent of AR's new_record? and can be used to set create hooks or determine how to handle
-#       object queries about whether it has changed. 
-#       @return [true, false]
-#   
-#    ClassMethods
-#     @interface_level mandatory
-#     load( id, class ) 
-#       The'load'  
-#       @param [String, Fixnum] The id used by the system to 
-#       @return [Aqua::Storage]
-#       @raise [Aqua::ResourceNotFound] if another error occurs in the engine, that should be raised instead 
-#         any of the Aqua Exceptions 
-#
-# Other methods used for the storage engine can be added as needed by the engine. 
-#
-# If no storage engine is configured before this class is used, CouchDB will automatically be used
-# as an engine.
+# When the api using CouchDB is stable, an interface and tests need to be created so that aqua can be extended 
+# to other storage engines.
 module Aqua
   class Storage < Mash 
     # auto loads the default store to CouchDB if Store is used without Aqua configuration of a store 
     def method_missing( method, *args )
       if respond_to?( :commit ) 
-        raise NoMethodError
+        raise NoMethodError, "#{method} undefined for #{self.inspect}"
       else
         Aqua.set_storage_engine # to default, currently CouchDB   
-        send( method.to_sym, eval(args.map{|value| "'#{value}'"}.join(', ')) ) # resend!
+        send( method.to_sym, *args ) # resend!
       end  
     end 
   end # Storage