seomoz-ripple 1.0.0.pre

data/lib/rails/generators/ripple/model/model_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators/ripple_generator'
+
+module Ripple
+  module Generators
+    class ModelGenerator < NamedBase
+      desc 'Creates a ripple model'
+      argument :attributes, :type => :array, :default => [], :banner => 'field:type field:type'
+      class_option :parent, :type => :string, :desc => "The parent class for the generated model"
+      class_option :embedded, :type => :boolean, :desc => "Make an embedded document model.", :default => false
+      class_option :embedded_in, :type => :string, :desc => "Specify the enclosing model for the embedded document. Implies --embedded."
+      check_class_collision
+
+      def create_model_file
+        template 'model.rb', "app/models/#{file_path}.rb"
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/rails/generators/ripple/model/templates/model.rb

@@ -0,0 +1,10 @@
+class <%= class_name %><%= " < #{options[:parent].classify}" if options[:parent] %>
+<% unless options[:parent] -%>
+  include Ripple::<%= "Embedded" if options[:embedded] || options[:embedded_in] %>Document
+  <% if options[:embedded_in] -%>embedded_in :<%= options[:embedded_in].underscore %><% end -%> 
+<% end -%>
+
+<% attributes.reject{|attr| attr.reference?}.each do |attribute| -%>
+  property :<%= attribute.name %>, <%= attribute.type_class %>
+<% end -%>
+end

data/lib/rails/generators/ripple/observer/observer_generator.rb

@@ -0,0 +1,16 @@
+require 'rails/generators/ripple_generator'
+
+module Ripple
+  module Generators
+    class ObserverGenerator < NamedBase
+      desc 'Creates an observer for Ripple documents'
+      check_class_collision :suffix => "Observer"
+
+      def create_observer_file
+        template 'observer.rb', File.join("app/models", class_path, "#{file_name}_observer.rb")
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/rails/generators/ripple/observer/templates/observer.rb

@@ -0,0 +1,4 @@
+<% module_namespacing do -%>
+class <%= class_name %>Observer < ActiveModel::Observer
+end
+<% end -%>

data/lib/rails/generators/ripple/test/templates/test_server.rb

@@ -0,0 +1,46 @@
+require 'riak/test_server'
+
+module Ripple  
+  module TestServer
+    extend self
+
+    # Tweak this to change how your test server is configured
+    def test_server_config
+      {
+        :app_config => {
+          :riak_kv => {
+            :js_source_dir => Ripple.config.delete(:js_source_dir),
+            :map_cache_size => 0, # 0.14
+            :vnode_cache_entries => 0 # 0.13
+          },
+          :riak_core => { :web_port => Ripple.config[:http_port] || 8098 }
+        },
+        :bin_dir => Ripple.config.delete(:bin_dir),
+        :temp_dir => Rails.root + "tmp/riak_test_server"
+      }
+    end
+
+    # Prepares the subprocess Riak node for the test suite
+    def setup
+      unless @test_server
+        begin
+          _server = @test_server = Riak::TestServer.new(test_server_config)
+          @test_server.prepare!
+          @test_server.start
+          at_exit { _server.cleanup }
+        rescue => e
+          warn "Can't run tests with Riak::TestServer. Specify the location of your Riak installation in the config/ripple.yml #{Rails.env} environment."
+          warn e.inspect
+          @test_server = nil
+        end
+      end
+    end
+
+    # Clear the data after each test run
+    def clear
+      @test_server.recycle if @test_server
+    end
+  end
+end
+
+Ripple::TestServer.setup

data/lib/rails/generators/ripple/test/test_generator.rb

@@ -0,0 +1,39 @@
+require 'rails/generators/ripple_generator'
+
+module Ripple
+  module Generators
+    class TestGenerator < Base
+      desc 'Generates test helpers for Ripple. Test::Unit, RSpec and Cucumber are supported.'
+      # Cucumber
+      def create_cucumber_file
+        if File.directory?(Rails.root + "features/support")
+          template 'test_server.rb', 'features/support/ripple.rb'
+          insert_into_file 'features/support/ripple.rb', "\n\nAfter do\n  Ripple::TestServer.clear\nend", :after => "Ripple::TestServer.setup"
+        end
+      end
+
+      # RSpec
+      def create_rspec_file
+        if File.file?(Rails.root + 'spec/spec_helper.rb')
+          template 'test_server.rb', 'spec/support/ripple.rb'
+          inject_into_file 'spec/spec_helper.rb', :after => /R[Ss]pec\.configure do \|config\|/ do
+            "\n  config.after(:each) do\n    Ripple::TestServer.clear\n  end\n"
+          end
+        end
+      end
+
+      # Test::Unit
+      def create_test_unit_file
+        if File.file?(Rails.root + 'test/test_helper.rb')
+          template 'test_server.rb', 'test/ripple_test_helper.rb'
+          inject_into_file "test/test_helper.rb", :before => "class ActiveSupport::TestCase" do
+            "# Setup in-memory test server for Riak\nrequire File.expand_path('../ripple_test_helper.rb', __FILE__)\n\n"
+          end
+          inject_into_class "test/test_helper.rb", ActiveSupport::TestCase do
+            "  teardown { Ripple::TestServer.clear }\n\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/generators/ripple_generator.rb

@@ -0,0 +1,78 @@
+require "rails/generators/named_base"
+require "rails/generators/active_model"
+
+class RippleGenerator < ::Rails::Generators::Base
+  def create_ripple
+    invoke "ripple:configuration"
+    invoke "ripple:js"
+    invoke "ripple:test"
+  end
+end
+
+module Ripple
+  # ActiveModel generators for use in a Rails project.
+  module Generators
+    # @private
+    class Base < ::Rails::Generators::Base
+      def self.source_root
+        @_ripple_source_root ||=
+        File.expand_path("../#{base_name}/#{generator_name}/templates", __FILE__)
+      end
+    end
+
+    class NamedBase < ::Rails::Generators::NamedBase
+      def self.source_root
+        @_ripple_source_root ||=
+        File.expand_path("../#{base_name}/#{generator_name}/templates", __FILE__)
+      end
+    end
+
+    # Generator for a {Ripple::Document} model
+    class ActiveModel < ::Rails::Generators::ActiveModel
+      def self.all(klass)
+        "#{klass}.list"
+      end
+
+      def self.find(klass, params=nil)
+        "#{klass}.find(#{params})"
+      end
+
+      def self.build(klass, params=nil)
+        if params
+          "#{klass}.new(#{params})"
+        else
+          "#{klass}.new"
+        end
+      end
+
+      def save
+        "#{name}.save"
+      end
+
+      def update_attributes(params=nil)
+        "#{name}.update_attributes(#{params})"
+      end
+
+      def errors
+        "#{name}.errors"
+      end
+
+      def destroy
+        "#{name}.destroy"
+      end
+    end
+  end
+end
+
+# @private
+module Rails
+  module Generators
+    class GeneratedAttribute #:nodoc:
+      def type_class
+        return "Time" if type.to_s == "datetime"
+        return "String" if type.to_s == "text"
+        return type.to_s.camelcase
+      end
+    end
+  end
+end

data/lib/ripple.rb

@@ -0,0 +1,79 @@
+require 'riak'
+require 'erb'
+require 'yaml'
+require 'active_model'
+require 'ripple/core_ext'
+require 'ripple/translation'
+require 'ripple/document'
+require 'ripple/embedded_document'
+
+# Contains the classes and modules related to the ODM built on top of
+# the basic Riak client.
+module Ripple
+  class << self
+    # @return [Riak::Client] The client for the current thread.
+    def client
+      Thread.current[:ripple_client] ||= Riak::Client.new(client_config)
+    end
+
+    # Sets the client for the current thread.
+    # @param [Riak::Client] value the client
+    def client=(value)
+      Thread.current[:ripple_client] = value
+    end
+
+    # Sets the global Ripple configuration.
+    def config=(hash)
+      self.client = nil
+      @config = hash.symbolize_keys
+    end
+
+    # Reads the global Ripple configuration.
+    def config
+      @config ||= {}
+    end
+
+    # The format in which date/time objects will be serialized to
+    # strings in JSON.  Defaults to :iso8601, and can be set in
+    # Ripple.config.
+    # @return [Symbol] the date format
+    def date_format
+      (config[:date_format] ||= :iso8601).to_sym
+    end
+
+    # Sets the format for date/time objects that are serialized to
+    # JSON.
+    # @param [Symbol] format the date format
+    def date_format=(format)
+      config[:date_format] = format.to_sym
+    end
+
+    # Loads the Ripple configuration from a given YAML file.
+    # Evaluates the configuration with ERB before loading.
+    def load_configuration(config_file, config_keys = [:ripple])
+      config_file = File.expand_path(config_file)
+      config_hash = YAML.load(ERB.new(File.read(config_file)).result).with_indifferent_access
+      config_keys.each {|k| config_hash = config_hash[k]}
+      self.config = config_hash || {}
+    rescue Errno::ENOENT
+      raise Ripple::MissingConfiguration.new(config_file)
+    end
+    alias_method :load_config, :load_configuration
+
+    private
+    def client_config
+      config.slice(*Riak::Client::VALID_OPTIONS)
+    end
+  end
+
+  # Exception raised when the path passed to
+  # {Ripple::load_configuration} does not point to a existing file.
+  class MissingConfiguration < StandardError
+    include Translation
+    def initialize(file_path)
+      super(t("missing_configuration", :file => file_path))
+    end
+  end
+end
+
+require 'ripple/railtie' if defined? Rails::Railtie

data/lib/ripple/associations.rb

@@ -0,0 +1,356 @@
+require 'active_support/concern'
+require 'riak/walk_spec'
+require 'ripple/translation'
+require 'ripple/associations/proxy'
+require 'ripple/associations/instantiators'
+require 'ripple/associations/linked'
+require 'ripple/associations/embedded'
+require 'ripple/associations/many'
+require 'ripple/associations/one'
+require 'ripple/associations/linked'
+require 'ripple/associations/one_embedded_proxy'
+require 'ripple/associations/many_embedded_proxy'
+require 'ripple/associations/one_linked_proxy'
+require 'ripple/associations/many_linked_proxy'
+require 'ripple/associations/many_stored_key_proxy'
+require 'ripple/associations/one_key_proxy'
+require 'ripple/associations/one_stored_key_proxy'
+require 'ripple/associations/many_reference_proxy'
+
+module Ripple
+  # Adds associations via links and embedding to {Ripple::Document}
+  # models. Examples:
+  # 
+  #   # Documents can contain embedded documents, and link to other standalone documents
+  #   # via associations using the many and one class methods.
+  #   class Person
+  #     include Ripple::Document
+  #     property :name, String
+  #     many :addresses
+  #     many :friends, :class_name => "Person"
+  #     one :account
+  #   end
+  #    
+  #   # Account and Address are embeddable documents
+  #   class Account
+  #     include Ripple::EmbeddedDocument
+  #     property :paid_until, Time
+  #     embedded_in :person # Adds "person" method to get parent document
+  #   end
+  #    
+  #   class Address
+  #     include Ripple::EmbeddedDocument
+  #     property :street, String
+  #     property :city, String
+  #     property :state, String
+  #     property :zip, String
+  #   end
+  #    
+  #   person = Person.find("adamhunter")
+  #   person.friends << Person.find("seancribbs") # Links to people/seancribbs with tag "friend"
+  #   person.addresses << Address.new(:street => "100 Main Street") # Adds an embedded address
+  #   person.account.paid_until = 3.months.from_now
+  module Associations
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      include Translation
+      # @private
+      def inherited(subclass)
+        super
+        subclass.associations.merge!(associations)
+      end
+
+      # Associations defined on the document
+      def associations
+        @associations ||= {}.with_indifferent_access
+      end
+
+      # Associations of embedded documents
+      def embedded_associations
+        associations.values.select(&:embedded?)
+      end
+
+      # Associations of linked documents
+      def linked_associations
+        associations.values.select(&:linked?)
+      end
+
+      # Associations of stored_key documents
+      def stored_key_associations
+        associations.values.select(&:stored_key?)
+      end
+
+      # Creates a singular association
+      def one(name, options={})
+        configure_for_key_correspondence if options[:using] === :key
+        create_association(:one, name, options)
+      end
+
+      # Creates a plural association
+      def many(name, options={})
+        raise ArgumentError, t('many_key_association') if options[:using] === :key
+        create_association(:many, name, options)
+      end
+
+      def configure_for_key_correspondence
+        include Ripple::Associations::KeyDelegator
+      end
+
+      private
+      def create_association(type, name, options={})
+        association = associations[name] = Association.new(type, name, options)
+        association.setup_on(self)
+
+        define_method(name) do
+          get_proxy(association)
+        end
+
+        define_method("#{name}=") do |value|
+          get_proxy(association).replace(value)
+          value
+        end
+
+        unless association.many?
+          define_method("#{name}?") do
+            get_proxy(association).present?
+          end
+        end
+      end
+    end
+
+    module InstanceMethods
+      # @private
+      def get_proxy(association)
+        unless proxy = instance_variable_get(association.ivar)
+          proxy = association.proxy_class.new(self, association)
+          instance_variable_set(association.ivar, proxy)
+        end
+        proxy
+      end
+
+      # @private
+      def reset_associations
+        self.class.associations.each do |name, assoc_object|
+          send(name).reset
+        end
+      end
+
+      # Adds embedded documents to the attributes
+      # @private
+      def attributes_for_persistence
+        self.class.embedded_associations.inject(super) do |attrs, association|
+          documents = instance_variable_get(association.ivar)
+          # We must explicitly check #nil? (rather than just saying `if documents`)
+          # because documents can be an association proxy that is proxying nil.
+          # In this case ruby treats documents as true because it is not _really_ nil,
+          # but #nil? will tell us if it is proxying nil.
+
+          unless documents.nil?
+            attrs[association.name] = documents.is_a?(Array) ? documents.map(&:attributes_for_persistence) : documents.attributes_for_persistence
+          end
+          attrs
+        end
+      end
+
+      def propagate_callbacks_to_embedded_associations(name, kind)
+        self.class.embedded_associations.each do |association|
+          documents = instance_variable_get(association.ivar)
+          # We must explicitly check #nil? (rather than just saying `if documents`)
+          # because documents can be an association proxy that is proxying nil.
+          # In this case ruby treats documents as true because it is not _really_ nil,
+          # but #nil? will tell us if it is proxying nil.
+          next if documents.nil?
+
+          Array(documents).each do |doc|
+            doc.send("_#{name}_callbacks").each do |callback|
+              next unless callback.kind == kind
+              doc.send(callback.filter)
+            end
+          end
+        end
+      end
+
+      # Propagates callbacks (save/create/update/destroy) to embedded associated documents.
+      # This is necessary so that when a parent is saved, the embedded child's before_save
+      # hooks are run as well.
+      # @private
+      def run_callbacks(name, *args, &block)
+        # validation is already propagated to embedded documents via the
+        # AssociatedValidator.  We don't need to duplicate the propgation here.
+        return super if name == :validation
+
+        propagate_callbacks_to_embedded_associations(name, :before)
+        return_value = super
+        propagate_callbacks_to_embedded_associations(name, :after)
+        return_value
+      end
+    end
+  end
+
+  # The "reflection" for an association - metadata about how it is
+  # configured.
+  class Association
+    include Ripple::Translation
+    attr_reader :type, :name, :options
+
+    # association options :using, :class_name, :class, :extend,
+    # options that may be added :validate
+
+    def initialize(type, name, options={})
+      @type, @name, @options = type, name, options.to_options
+    end
+
+    # @return String The class name of the associated object(s)
+    def class_name
+      @class_name ||= case
+                      when @options[:class_name]
+                        @options[:class_name]
+                      when @options[:class]
+                        @options[:class].to_s
+                      when many?
+                        @name.to_s.classify
+                      else
+                        @name.to_s.camelize
+                      end
+    end
+
+    # @return [Class] The class of the associated object(s)
+    def klass
+      @klass ||= options[:class] || class_name.constantize
+    end
+
+    # @return [true,false] Is the cardinality of the association > 1
+    def many?
+      @type == :many
+    end
+
+    # @return [true,false] Is the cardinality of the association == 1
+    def one?
+      @type == :one
+    end
+
+    # @return [true,false] Is the associated class an EmbeddedDocument
+    def embedded?
+      klass.embeddable?
+    end
+
+    # TODO: Polymorphic not supported
+    # @return [true,false] Does the association support more than one associated class
+    def polymorphic?
+      false
+    end
+
+    # @return [true,false] Does the association use links
+    def linked?
+      using == :linked
+    end
+
+    # @return [true,false] Does the association use stored_key
+    def stored_key?
+      using == :stored_key
+    end
+
+    # @return [String] the instance variable in the owner where the association will be stored
+    def ivar
+      "@_#{name}"
+    end
+
+    # @return [Class] the association proxy class
+    def proxy_class
+      @proxy_class ||= proxy_class_name.constantize
+    end
+
+    # @return [String] the class name of the association proxy
+    def proxy_class_name
+      klass_name = (many? ? 'Many' : 'One') + using.to_s.camelize + ('Polymorphic' if polymorphic?).to_s + 'Proxy'
+      "Ripple::Associations::#{klass_name}"
+    end
+
+    # @return [Proc] a filter proc to be used with Enumerable#select for collecting links that belong to this association (only when #linked? is true)
+    def link_filter
+      linked? ? lambda {|link| link.tag == link_tag } : lambda {|_| false }
+    end
+
+    # @return [String,nil] when #linked? is true, the tag for outgoing links
+    def link_tag
+      linked? ? Array(link_spec).first.tag : nil
+    end
+
+    def bucket_name
+      polymorphic? ? '_' : klass.bucket_name
+    end
+
+    # @return [Riak::WalkSpec] when #linked? is true, a specification for which links to follow to retrieve the associated documents
+    def link_spec
+      # TODO: support transitive linked associations
+      if linked?
+        tag = name.to_s
+        Riak::WalkSpec.new(:tag => tag, :bucket => bucket_name)
+      else
+        nil
+      end
+    end
+
+    # @return [Symbol] which method is used for representing the association - currently only supports :embedded and :linked
+    def using
+      @using ||= options[:using] || (embedded? ? :embedded : :linked)
+    end
+
+    # @raise [ArgumentError] if the value does not match the class of the association
+    def verify_type!(value, owner)
+      unless type_matches?(value)
+        raise ArgumentError.new(t('invalid_association_value',
+                                  :name => name,
+                                  :owner => owner.inspect,
+                                  :klass => polymorphic? ? "<polymorphic>" : klass.name,
+                                  :value => value.inspect))
+      end
+    end
+
+    # @private
+    def type_matches?(value)
+      case
+      when polymorphic?
+        one? || Array === value
+      when many?
+        Array === value && value.all? {|d| (embedded? && Hash === d) || klass === d }
+      when one?
+        value.nil? || (embedded? && Hash === value) || value.kind_of?(klass)
+      end
+    end
+
+    def uses_search?
+      (options[:using] == :reference)
+    end
+
+    def setup_on(target)
+      define_callbacks_on(target)
+      if uses_search?
+        klass.before_save do |o|
+          unless o.class.bucket.is_indexed?
+            o.class.bucket.enable_index!
+          end
+        end
+      end
+    end
+
+    def define_callbacks_on(klass)
+      _association = self
+
+      klass.before_save do
+        if _association.linked? && !@_in_save_loaded_documents_callback
+          @_in_save_loaded_documents_callback = true
+
+          begin
+            send(_association.name).loaded_documents.each do |document|
+              document.save if document.new? || document.changed?
+            end
+          ensure
+            remove_instance_variable(:@_in_save_loaded_documents_callback)
+          end
+        end
+      end
+    end
+  end
+end