muck-solr 0.4.0

data/Rakefile

@@ -0,0 +1,99 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+Dir["#{File.dirname(__FILE__)}/lib/acts_as_solr/tasks/**/*.rake"].sort.each { |ext| load ext }
+
+desc "Default Task"
+task :default => [:test]
+
+desc "Runs the unit tests"
+task :test => "test:unit"
+
+namespace :test do
+  task :setup do
+    RAILS_ROOT = File.expand_path("#{File.dirname(__FILE__)}/test") unless defined? RAILS_ROOT
+    ENV['RAILS_ENV'] = "test"
+    ENV["ACTS_AS_SOLR_TEST"] = "true"
+    require File.expand_path("#{File.dirname(__FILE__)}/config/solr_environment")
+    puts "Using " + DB
+    %x(mysql -u#{MYSQL_USER} < #{File.dirname(__FILE__) + "/test/fixtures/db_definitions/mysql.sql"}) if DB == 'mysql'
+
+    Rake::Task["test:migrate"].invoke
+  end
+  
+  desc 'Measures test coverage using rcov'
+  task :rcov => :setup do
+    rm_f "coverage"
+    rm_f "coverage.data"
+    rcov = "rcov --rails --aggregate coverage.data --text-summary -Ilib"
+    
+    system("#{rcov} --html #{Dir.glob('test/**/*_test.rb').join(' ')}")
+    system("open coverage/index.html") if PLATFORM['darwin']
+  end
+  
+  desc 'Runs the functional tests, testing integration with Solr'
+  Rake::TestTask.new('functional' => :setup) do |t|
+    t.pattern = "test/functional/*_test.rb"
+    t.verbose = true
+  end
+  
+  desc "Unit tests"
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << 'test/unit'
+    t.pattern = "test/unit/*_shoulda.rb"
+    t.verbose = true
+  end
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_dir = "rdoc"
+  rd.rdoc_files.exclude("lib/solr/**/*.rb", "lib/solr.rb")
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "muck-solr"
+    s.summary = "This gem adds full text search capabilities and many other nifty features from Apache�s Solr to any Rails model. I'm currently rearranging the test suite to include a real unit test suite, and adding a few features I need myself."
+    s.email = "meyer@paperplanes.de"
+    s.homepage = "http://github.com/mattmatt/acts_as_solr"
+    s.description = "This gem adds full text search capabilities and many other nifty features from Apache�s Solr to any Rails model. I'm currently rearranging the test suite to include a real unit test suite, and adding a few features I need myself."
+    s.authors = ["Mathias Meyer, Joel Duffin, Justin Ball"]
+    s.rubyforge_project = 'muck-solr'
+    s.files =  FileList["[A-Z]*", "{bin,generators,config,lib,solr}/**/*"] +
+      FileList["test/**/*"].reject {|f| f.include?("test/log")}.reject {|f| f.include?("test/tmp")}
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+# rubyforge tasks
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/muck-solr/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/TESTING_THE_PLUGIN

@@ -0,0 +1,25 @@
+acts_as_solr comes with a quick and fast unit test suite, and with a longer-running
+functional test suite, the latter testing the actual integration with Solr.
+
+The unit test suite is written using Shoulda, so make sure you have a recent version
+installed.
+
+Running `rake test` or just `rake` will run both test suites. Use `rake test:unit` to
+just run the unit test suite.
+ 
+== How to run functional tests for this plugin:
+To run the acts_as_solr's plugin tests run the following steps:
+
+- create a MySQL database called "actsassolr_test" (if you want to use MySQL)
+
+- create a new Rails project, if needed (the plugin can only be tested from within a Rails project); move/checkout acts_as_solr into its vendor/plugins/, as usual
+
+- copy vendor/plugins/acts_as_solr/config/solr.yml to config/ (the Rails config folder)
+
+- rake solr:start RAILS_ENV=test
+
+- rake test:functional (Accepts the following arguments: DB=sqlite|mysql and MYSQL_USER=user)
+
+== Troubleshooting:
+If for some reason the tests don't run and you get MySQL errors, make sure you edit the MYSQL_USER entry under
+config/environment.rb. It's recommended to create or use a MySQL user with no password.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 4

data/config/solr.yml

@@ -0,0 +1,15 @@
+# Config file for the acts_as_solr plugin.
+#
+# If you change the host or port number here, make sure you update 
+# them in your Solr config file
+
+development:
+  url: http://127.0.0.1:8982/solr
+  
+production:
+  url: http://127.0.0.1:8983/solr
+  jvm_options: -server -d64 -Xmx1024M -Xms64M
+
+test:
+  url: http://127.0.0.1:8981/solr
+

data/config/solr_environment.rb

@@ -0,0 +1,32 @@
+ENV['RAILS_ENV']  = (ENV['RAILS_ENV'] || 'development').dup
+# RAILS_ROOT isn't defined yet, so figure it out.
+require "uri"
+require "fileutils"
+dir = File.dirname(__FILE__)
+SOLR_PATH = File.expand_path("#{dir}/../solr") unless defined? SOLR_PATH
+
+RAILS_ROOT = File.expand_path("#{File.dirname(__FILE__)}/../test") unless defined? RAILS_ROOT
+unless defined? SOLR_LOGS_PATH
+  SOLR_LOGS_PATH = ENV["SOLR_LOGS_PATH"] || "#{RAILS_ROOT}/log"
+end
+unless defined? SOLR_PIDS_PATH
+  SOLR_PIDS_PATH = ENV["SOLR_PIDS_PATH"] || "#{RAILS_ROOT}/tmp/pids"
+end
+unless defined? SOLR_DATA_PATH
+  SOLR_DATA_PATH = ENV["SOLR_DATA_PATH"] || "#{RAILS_ROOT}/solr/#{ENV['RAILS_ENV']}"
+end
+
+unless defined? SOLR_PORT
+  config = YAML::load_file(RAILS_ROOT+'/config/solr.yml')
+  raise("No solr environment defined for RAILS_ENV the #{ENV['RAILS_ENV'].inspect}") unless config[ENV['RAILS_ENV']]
+  SOLR_PORT = ENV['PORT'] || URI.parse(config[ENV['RAILS_ENV']]['url']).port
+end
+
+SOLR_JVM_OPTIONS = config[ENV['RAILS_ENV']]['jvm_options'] unless defined? SOLR_JVM_OPTIONS
+
+if ENV["ACTS_AS_SOLR_TEST"]
+  require "activerecord"
+  DB = (ENV['DB'] ? ENV['DB'] : 'sqlite') unless defined?(DB)
+  MYSQL_USER = (ENV['MYSQL_USER'].nil? ? 'root' : ENV['MYSQL_USER']) unless defined? MYSQL_USER
+  require File.join(File.dirname(File.expand_path(__FILE__)), '..', 'test', 'db', 'connections', DB, 'connection.rb')
+end

data/lib/acts_as_solr.rb

@@ -0,0 +1,65 @@
+# Copyright (c) 2006 Erik Hatcher, Thiago Jackiw
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require 'active_record'
+require 'rexml/document'
+require 'net/http'
+require 'yaml'
+require 'time'
+require 'erb'
+require 'rexml/xpath'
+
+require File.dirname(__FILE__) + '/solr'
+require File.dirname(__FILE__) + '/acts_as_solr/acts_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/common_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/parser_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/class_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/instance_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/common_methods'
+require File.dirname(__FILE__) + '/acts_as_solr/deprecation'
+require File.dirname(__FILE__) + '/acts_as_solr/search_results'
+require File.dirname(__FILE__) + '/acts_as_solr/lazy_document'
+module ActsAsSolr
+  
+  class Post    
+    def self.execute(request, core = nil)
+      begin
+        if File.exists?(RAILS_ROOT+'/config/solr.yml')
+          config = YAML::load_file(RAILS_ROOT+'/config/solr.yml')
+          url = config[ENV['RAILS_ENV']]['url']
+          # for backwards compatibility
+          url ||= "http://#{config[ENV['RAILS_ENV']]['host']}:#{config[ENV['RAILS_ENV']]['port']}/#{config[ENV['RAILS_ENV']]['servlet_path']}"
+        else
+          url = 'http://localhost:8982/solr'
+        end
+        url += "/" + core if !core.nil?
+        connection = Solr::Connection.new(url)
+        return connection.send(request)
+      rescue 
+        raise "Couldn't connect to the Solr server at #{url}. #{$!}"
+        false
+      end
+    end
+  end
+  
+end
+
+# reopen ActiveRecord and include the acts_as_solr method
+ActiveRecord::Base.extend ActsAsSolr::ActsMethods

data/lib/acts_as_solr/acts_methods.rb

@@ -0,0 +1,352 @@
+module ActsAsSolr #:nodoc:
+  
+  module ActsMethods
+    
+    # declares a class as solr-searchable
+    # 
+    # ==== options:
+    # fields:: This option can be used to specify only the fields you'd
+    #          like to index. If not given, all the attributes from the 
+    #          class will be indexed. You can also use this option to 
+    #          include methods that should be indexed as fields
+    # 
+    #           class Movie < ActiveRecord::Base
+    #             acts_as_solr :fields => [:name, :description, :current_time]
+    #             def current_time
+    #               Time.now.to_s
+    #             end
+    #           end
+    #          
+    #          Each field passed can also be a hash with the value being a field type
+    # 
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => :range_float}]
+    #             def current_time
+    #               Time.now
+    #             end
+    #           end
+    # 
+    #          The field types accepted are:
+    # 
+    #          :float:: Index the field value as a float (ie.: 12.87)
+    #          :integer:: Index the field value as an integer (ie.: 31)
+    #          :boolean:: Index the field value as a boolean (ie.: true/false)
+    #          :date:: Index the field value as a date (ie.: Wed Nov 15 23:13:03 PST 2006)
+    #          :string:: Index the field value as a text string, not applying the same indexing
+    #                    filters as a regular text field
+    #          :range_integer:: Index the field value for integer range queries (ie.:[5 TO 20])
+    #          :range_float:: Index the field value for float range queries (ie.:[14.56 TO 19.99])
+    # 
+    #          Setting the field type preserves its original type when indexed
+    # 
+    #          The field may also be passed with a hash value containing options
+    #
+    #          class Author < ActiveRecord::Base
+    #            acts_as_solr :fields => [{:full_name => {:type => :text, :as => :name}}]
+    #            def full_name
+    #              self.first_name + ' ' + self.last_name
+    #            end
+    #          end
+    #
+    #          The options accepted are:
+    #
+    #          :type:: Index the field using the specified type
+    #          :as:: Index the field using the specified field name
+    #
+    # additional_fields:: This option takes fields to be include in the index
+    #                     in addition to those derived from the database. You
+    #                     can also use this option to include custom fields 
+    #                     derived from methods you define. This option will be
+    #                     ignored if the :fields option is given. It also accepts
+    #                     the same field types as the option above
+    # 
+    #                      class Movie < ActiveRecord::Base
+    #                       acts_as_solr :additional_fields => [:current_time]
+    #                       def current_time
+    #                         Time.now.to_s
+    #                       end
+    #                      end
+    # 
+    # exclude_fields:: This option taks an array of fields that should be ignored from indexing:
+    # 
+    #                    class User < ActiveRecord::Base
+    #                      acts_as_solr :exclude_fields => [:password, :login, :credit_card_number]
+    #                    end
+    # 
+    # include:: This option can be used for association indexing, which 
+    #           means you can include any :has_one, :has_many, :belongs_to 
+    #           and :has_and_belongs_to_many association to be indexed:
+    # 
+    #            class Category < ActiveRecord::Base
+    #              has_many :books
+    #              acts_as_solr :include => [:books]
+    #            end
+    # 
+    #           Each association may also be specified as a hash with an option hash as a value
+    #
+    #           class Book < ActiveRecord::Base
+    #             belongs_to :author
+    #             has_many :distribution_companies
+    #             has_many :copyright_dates
+    #             has_many :media_types
+    #             acts_as_solr(
+    #               :fields => [:name, :description],
+    #               :include => [
+    #                 {:author => {:using => :fullname, :as => :name}},
+    #                 {:media_types => {:using => lambda{|media| type_lookup(media.id)}}}
+    #                 {:distribution_companies => {:as => :distributor, :multivalued => true}},
+    #                 {:copyright_dates => {:as => :copyright, :type => :date}}
+    #               ]
+    #             ]
+    #
+    #           The options accepted are:
+    #
+    #           :type:: Index the associated objects using the specified type
+    #           :as:: Index the associated objects using the specified field name
+    #           :using:: Index the associated objects using the value returned by the specified method or proc.  If a method
+    #                    symbol is supplied, it will be sent to each object to look up the value to index; if a proc is
+    #                    supplied, it will be called once for each object with the object as the only argument
+    #           :multivalued:: Index the associated objects using one field for each object rather than joining them
+    #                          all into a single field
+    #
+    # facets:: This option can be used to specify the fields you'd like to
+    #          index as facet fields
+    # 
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :facets => [:category, :manufacturer]  
+    #           end
+    # 
+    # boost:: You can pass a boost (float) value that will be used to boost the document and/or a field. To specify a more
+    #         boost for the document, you can either pass a block or a symbol. The block will be called with the record
+    #         as an argument, a symbol will result in the according method being called:
+    # 
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => 5.0}}], :boost => 10.0
+    #           end
+    # 
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => 5.0}}], :boost => proc {|record| record.id + 120*37}
+    #           end
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => :price_rating}}], :boost => 10.0
+    #           end
+    #
+    # if:: Only indexes the record if the condition evaluated is true. The argument has to be 
+    #      either a symbol, string (to be eval'ed), proc/method, or class implementing a static 
+    #      validation method. It behaves the same way as ActiveRecord's :if option.
+    # 
+    #        class Electronic < ActiveRecord::Base
+    #          acts_as_solr :if => proc{|record| record.is_active?}
+    #        end
+    # 
+    # offline:: Assumes that your using an outside mechanism to explicitly trigger indexing records, e.g. you only
+    #           want to update your index through some asynchronous mechanism. Will accept either a boolean or a block
+    #           that will be evaluated before actually contacting the index for saving or destroying a document. Defaults
+    #           to false. It doesn't refer to the mechanism of an offline index in general, but just to get a centralized point
+    #           where you can control indexing. Note: This is only enabled for saving records. acts_as_solr doesn't always like
+    #           it, if you have a different number of results coming from the database and the index. This might be rectified in
+    #           another patch to support lazy loading.
+    #
+    #             class Electronic < ActiveRecord::Base
+    #               acts_as_solr :offline => proc {|record| record.automatic_indexing_disabled?}
+    #             end
+    #
+    # auto_commit:: The commit command will be sent to Solr only if its value is set to true:
+    # 
+    #                 class Author < ActiveRecord::Base
+    #                   acts_as_solr :auto_commit => false
+    #                 end
+    # 
+    def acts_as_solr(options={}, solr_options={}, &deferred_solr_configuration)
+
+      extend ClassMethods
+      include InstanceMethods
+      include CommonMethods
+      include ParserMethods
+
+      define_solr_configuration_methods
+
+      after_save    :solr_save
+      after_destroy :solr_destroy
+
+      if deferred_solr_configuration
+        self.deferred_solr_configuration = deferred_solr_configuration
+      else
+        process_acts_as_solr(options, solr_options)
+      end
+    end
+
+    def process_acts_as_solr(options, solr_options)
+      process_solr_options(options, solr_options)
+    end
+
+    def define_solr_configuration_methods
+      # I'd like to use cattr_accessor, but it does not support lazy loaders and delegation to the class in the instance methods.
+      # TODO: Reconcile with cattr_accessor, or a more appropriate method.
+      class_eval(<<-EOS, __FILE__, __LINE__)
+      @@configuration = nil unless defined?(@@configuration)
+      @@solr_configuration = nil unless defined?(@@solr_configuration)
+      @@deferred_solr_configuration = nil unless defined?(@@deferred_solr_configuration)
+      
+      def self.configuration
+        return @@configuration if @@configuration
+        process_deferred_solr_configuration
+        @@configuration
+      end
+      def configuration
+        self.class.configuration
+      end
+      def self.configuration=(value)
+        @@configuration = value
+      end
+      def configuration=(value)
+        self.class.configuration = value
+      end
+
+      def self.solr_configuration
+        return @@solr_configuration if @@solr_configuration
+        process_deferred_solr_configuration
+        @@solr_configuration
+      end
+      def solr_configuration
+        self.class.solr_configuration
+      end
+      def self.solr_configuration=(value)
+        @@solr_configuration = value
+      end
+      def solr_configuration=(value)
+        self.class.solr_configuration = value
+      end
+
+      def self.deferred_solr_configuration
+        return @@deferred_solr_configuration if @@deferred_solr_configuration
+        @@deferred_solr_configuration
+      end
+      def deferred_solr_configuration
+        self.class.deferred_solr_configuration
+      end
+      def self.deferred_solr_configuration=(value)
+        @@deferred_solr_configuration = value
+      end
+      def deferred_solr_configuration=(value)
+        self.class.deferred_solr_configuration = value
+      end
+      EOS
+    end
+
+    def process_deferred_solr_configuration
+      return unless deferred_solr_configuration
+      options, solr_options = deferred_solr_configuration.call
+      self.deferred_solr_configuration = nil
+      self.process_solr_options(options, solr_options)
+    end
+
+    def process_solr_options(options={}, solr_options={})
+      self.configuration = {
+        :fields => nil,
+        :additional_fields => nil,
+        :exclude_fields => [],
+        :auto_commit => true,
+        :include => nil,
+        :facets => nil,
+        :boost => nil,
+        :if => "true",
+        :offline => false
+      }
+      self.solr_configuration = {
+        :type_field => "type_s",
+        :primary_key_field => "pk_i",
+        :default_boost => 1.0
+      }
+
+      configuration.update(options) if options.is_a?(Hash)
+      solr_configuration.update(solr_options) if solr_options.is_a?(Hash)
+      Deprecation.validate_index(configuration)
+
+      configuration[:solr_fields] = {}
+      configuration[:solr_includes] = {}
+
+      if configuration[:fields].respond_to?(:each)
+        process_fields(configuration[:fields])
+      else
+        process_fields(self.new.attributes.keys.map { |k| k.to_sym })
+        process_fields(configuration[:additional_fields])
+      end
+
+      if configuration[:include].respond_to?(:each)
+        process_includes(configuration[:include])
+      end
+    end
+
+    private
+
+    def get_field_value(field)
+      field_name, options = determine_field_name_and_options(field)
+      configuration[:solr_fields][field_name] = options
+      
+      define_method("#{field_name}_for_solr".to_sym) do
+        begin
+          value = self[field_name] || self.instance_variable_get("@#{field_name.to_s}".to_sym) || self.send(field_name.to_sym)
+          case options[:type] 
+            # format dates properly; return nil for nil dates 
+            when :date
+              value ? (value.respond_to?(:utc) ? value.utc : value).strftime("%Y-%m-%dT%H:%M:%SZ") : nil 
+            else value
+          end
+        rescue
+          puts $!
+          logger.debug "There was a problem getting the value for the field '#{field_name}': #{$!}"
+          value = ''
+        end
+      end
+    end
+    
+    def process_fields(raw_field)
+      if raw_field.respond_to?(:each)
+        raw_field.each do |field|
+          next if configuration[:exclude_fields].include?(field)
+          get_field_value(field)
+        end                
+      end
+    end
+    
+    def process_includes(includes)
+      if includes.respond_to?(:each)
+        includes.each do |assoc|
+          field_name, options = determine_field_name_and_options(assoc)
+          configuration[:solr_includes][field_name] = options
+        end
+      end
+    end
+
+    def determine_field_name_and_options(field)
+      if field.is_a?(Hash)
+        name = field.keys.first
+        options = field.values.first
+        if options.is_a?(Hash)
+          [name, {:type => type_for_field(field)}.merge(options)]
+        else
+          [name, {:type => options}]
+        end
+      else
+        [field, {:type => type_for_field(field)}]
+      end
+    end
+    
+    def type_for_field(field)
+      if configuration[:facets] && configuration[:facets].include?(field)
+        :facet
+      elsif column = columns_hash[field.to_s]
+        case column.type
+        when :string then :text
+        when :datetime then :date
+        when :time then :date
+        else column.type
+        end
+      else
+        :text
+      end
+    end
+  end
+end