gsolr 0.12.2

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in gsolr.gemspec
+gemspec
+
+# gem 'builder'
+
+group :test do
+  gem 'rspec'
+  gem 'rspec-core'
+end

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    gsolr (0.0.1)
+      json (~> 1.4.6)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    json (1.4.6)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  gsolr!
+  json (~> 1.4.6)
+  rspec
+  rspec-core

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2008-2010 Matt Mitchell
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,160 @@
+# GSolr
+
+A simple, extensible Ruby client for the Solr interface.  Capable of talking to Solr and to Riak.
+
+## Installation:
+    sudo gem install gsolr
+
+## Example:
+    require 'rubygems'
+    require 'gsolr'
+    solr      = GSolr.connect :url => "http://solrserver.com"
+    
+    # send a request to /select
+    response  = gsolr.select :q=>'*:*'
+    
+    # send a request to a custom request handler; /catalog
+    response  = gsolr.request '/catalog', :q=>'*:*'
+    
+    # alternative to above:
+    response  = gsolr.catalog :q=>'*:*'
+
+## Querying
+Use the #select method to send requests to the /select handler:
+
+    response  = solr.select {
+                  :q=>'washington',
+                  :start=>0,
+                  :rows=>10
+                }
+
+The params sent into the method are sent to Solr as-is. The one exception is if a value is an array. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:
+    
+    solr.select {
+      :q  =>  'roses',
+      :fq =>  ['red', 'violet']
+    }
+
+The above statement generates this Solr query:
+    
+    .../?q=roses&fq=red&fq=violet
+
+Use the #request method for a custom request handler path:
+
+    response = solr.request '/documents', :q=>'test'
+
+A shortcut for the above example use a method call instead:
+
+    response = solr.documents :q=>'test'
+
+
+## Updating Solr
+Updating uses native Ruby structures. Hashes are used for single documents and arrays are used for a collection of documents (hashes). These structures get turned into simple XML "messages". Raw XML strings can also be used.
+
+Raw XML via  #update
+
+    solr.update '</commit>'
+    solr.update '</optimize>'
+
+Single document via #add
+
+    solr.add {
+      :id     =>  1,
+      :price  =>  1.00
+    }
+
+Multiple documents via #add
+
+    documents = [{
+        :id     =>  1,
+        :price  =>  1.00
+      }, {
+        :id     =>  2,
+        :price  =>  10.50
+    }]
+    
+    solr.add documents
+
+When adding, you can also supply "add" xml element attributes and/or a block for manipulating other "add" related elements (docs and fields) when using the #add method:
+    
+    add_doc   = {:id=>1, :price=>1.00}
+    add_attr  = {:allowDups=>false, :commitWithin=>10.0}
+    
+    solr.add(add_doc, add_attr) do |doc|
+      # boost each document
+      doc.attrs[:boost] = 1.5
+      # boost the price field:
+      doc.field_by_name(:price).attrs[:boost] = 2.0
+    end
+
+Delete by id
+
+    solr.delete_by_id 1
+
+or an array of ids
+
+    solr.delete_by_id [1, 2, 3, 4]
+
+Delete by query:
+
+    solr.delete_by_query 'price:1.00'
+
+Delete by array of queries
+
+    solr.delete_by_query ['price:1.00', 'price:10.00']
+
+Commit & optimize shortcuts
+
+    solr.commit
+    solr.optimize
+
+## Response Formats
+The default response format is Ruby. When the :wt param is set to :ruby, the response is eval'd resulting in a Hash. You can get a raw response by setting the :wt to "ruby" - notice, the string -- not a symbol. GSolr will eval the Ruby string ONLY if the :wt value is :ruby. All other response formats are available as expected, :wt=>'xml' etc..
+
+### Evaluated Ruby (default)
+
+    solr.select(:wt=>:ruby) # notice :ruby is a Symbol
+
+### Raw Ruby
+
+    solr.select(:wt=>'ruby') # notice 'ruby' is a String
+
+### XML:
+
+    solr.select(:wt=>:xml)
+
+### JSON:
+
+    solr.select(:wt=>:json)
+
+You can access the original request context (path, params, url etc.) by calling the #raw method:
+
+    response = solr.select :q=>'*:*'
+
+    response.raw[:status_code]
+    response.raw[:body]
+    response.raw[:url]
+
+The raw is a hash that contains the generated params, url, path, post data, headers etc., very useful for debugging and testing.
+
+## Related Resources & Projects
+* The Apache Solr project
+  * [Solr](http://lucene.apache.org/solr/)
+* The original Solr Ruby Gem
+  * [solr-ruby](http://wiki.apache.org/solr/solr-ruby)
+* The RSolr Gem, from which this was hijacked
+  * [RSolr](https://github.com/mwmitchell/rsolr)
+
+## Note on Patches/Pull Requests
+* Fork the project.
+* Add tests for your contribution.
+* Write your contribution.
+* Commit only that contribution. Changes to rakefile, version, or history should be done in a respective commit.
+* Send a pull request.
+
+## Contributors (to the RSolr project, who therefore contributed to this)
+* mperham
+* Mat Brown
+* shairontoledo
+* Matthew Rudy
+* Fouad Mardini

data/Rakefile

@@ -0,0 +1,40 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'bundler'
+
+require 'rake'
+require 'rake/testtask'
+
+require 'rake/gempackagetask'
+
+gemspec = eval File.read('gsolr.gemspec')
+
+# Gem packaging tasks
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+task :gem => :gemspec
+
+desc %{Build the gemspec file.}
+task :gemspec do
+  gemspec.validate
+end
+
+desc %{Release the gem to RubyGems.org}
+task :release => :gem do
+  system "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+
+ENV['RUBYOPT'] = '-W1'
+ 
+task :environment do
+  require File.dirname(__FILE__) + '/lib/gsolr'
+end
+ 
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+task :default => ['spec:api']

data/gsolr.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "gsolr/version"
+
+Gem::Specification.new do |s|
+  s.name        = "gsolr"
+  s.version     = Gsolr::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Scott Gonyea"]
+  s.email       = ["me@sgonyea.com"]
+  s.homepage    = "http://rubygems.org/gems/gsolr"
+  s.summary     = %q{Generic Solr Client}
+  s.description = %q{This is a generic solr client, capable of talking to Solr, as well as Riak}
+
+  s.rubyforge_project = "gsolr"
+
+  s.add_dependency('json', '~>1.4.6')
+  
+  s.add_development_dependency "rspec"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/gsolr/client.rb

@@ -0,0 +1,121 @@
+module GSolr
+  class Client
+
+    attr_reader :connection
+
+    # "connection" is instance of:
+    #   GSolr::Adapter::HTTP
+    #   GSolr::Adapter::Direct (jRuby only)
+    # or any other class that uses the connection "interface"
+    def initialize(connection)
+      @connection = connection
+    end
+
+    # Send a request to a request handler using the method name.
+    # Also proxies to the #paginate method if the method starts with "paginate_"
+    def method_missing(method_name, *args, &blk)
+      request("/#{method_name}", *args, &blk)
+    end
+
+    # sends data to the update handler
+    # data can be a string of xml, or an object that returns xml from its #to_xml method
+    def update(data, params={})
+      request '/update', params, data
+    end
+
+    # send request solr
+    # params is hash with valid solr request params (:q, :fl, :qf etc..)
+    #   if params[:wt] is not set, the default is :ruby
+    #   if :wt is something other than :ruby, the raw response body is used
+    #   otherwise, a simple Hash is returned
+    #   NOTE: to get raw ruby, use :wt=>'ruby' <- a string, not a symbol like :ruby  
+    #
+    def request(path, params={}, *extra)
+      response = @connection.request(path, map_params(params), *extra)
+      adapt_response(response)
+    end
+
+    # 
+    # single record:
+    # solr.update(:id=>1, :name=>'one')
+    #
+    # update using an array
+    # solr.update([{:id=>1, :name=>'one'}, {:id=>2, :name=>'two'}])
+    #
+    def add(doc, &block)
+      update message.add(doc, &block)
+    end
+
+    # send </commit>
+    def commit
+      update message.commit
+    end
+
+    # send </optimize>
+    def optimize
+      update message.optimize
+    end
+
+    # send </rollback>
+    # NOTE: solr 1.4 only
+    def rollback
+      update message.rollback
+    end
+
+    # Delete one or many documents by id
+    #   solr.delete_by_id 10
+    #   solr.delete_by_id([12, 41, 199])
+    def delete_by_id(id)
+      update message.delete_by_id(id)
+    end
+
+    # delete one or many documents by query
+    #   solr.delete_by_query 'available:0'
+    #   solr.delete_by_query ['quantity:0', 'manu:"FQ"']
+    def delete_by_query(query)
+      update message.delete_by_query(query)
+    end
+
+    # shortcut to GSolr::Message::Generator
+    def message *opts
+      @message ||= GSolr::Message::Generator.new
+    end
+
+    protected
+
+    # sets default params etc.. - could be used as a mapping hook
+    # type of request should be passed in here? -> map_params(:query, {})
+    def map_params(params)
+      params||={}
+      {:wt=>:json}.merge(params)
+    end
+
+    # "connection_response" must be a hash with the following keys:
+    #   :params - a sub hash of standard solr params
+    #   : body - the raw response body from the solr server
+    # This method will evaluate the :body value if the params[:wt] == :ruby
+    # otherwise, the body is returned
+    # The return object has a special method attached called #raw
+    # This method gives you access to the original response from the connection,
+    # so you can access things like the actual :url sent to solr,
+    # the raw :body, original :params and original :data
+    def adapt_response(connection_response)
+      data = connection_response[:body]
+
+      # if the wt is :ruby, evaluate the ruby string response
+      if connection_response[:params][:wt] == :ruby
+        data = Kernel.eval(data)
+      end
+
+      # attach a method called #raw that returns the original connection response value
+      def data.raw
+        @raw
+      end
+
+      data.send(:instance_variable_set, '@raw', connection_response)
+
+      return data
+    end
+
+  end # class Client
+end # module GSolr

data/lib/gsolr/connection/net_http.rb

@@ -0,0 +1,56 @@
+require 'net/http'
+
+#
+# Connection for standard HTTP Solr server
+#
+module GSolr
+  module Connection
+    class NetHttp
+
+      include GSolr::Connection::Requestable
+
+      def connection
+        @connection ||= Net::HTTP.new(@uri.host, @uri.port)
+      end
+
+      def get(path, params={})
+        url = self.build_url path, params
+        net_http_response = self.connection.get url
+        create_http_context net_http_response, url, path, params
+      end
+
+      def post(path, data, params={}, headers={})
+        url = self.build_url path, params
+        net_http_response = self.connection.post url, data, headers
+        create_http_context net_http_response, url, path, params, data, headers
+      end
+
+      def create_http_context(net_http_response, url, path, params, data=nil, headers={})
+        full_url  = "#{@uri.scheme}://#{@uri.host}"
+
+        full_url += ":#{@uri.port}" if @uri.port
+
+        full_url += url
+
+        return {
+          :status_code  =>  net_http_response.code.to_i,
+          :url          =>  full_url,
+          :body         =>  encode_utf8(net_http_response.body),
+          :path         =>  path,
+          :params       =>  params,
+          :data         =>  data,
+          :headers      =>  headers,
+          :message      =>  net_http_response.message
+        }
+      end
+
+      # accepts a path/string and optional hash of query params
+      def build_url(path, params={})
+        full_path = @uri.path + path
+
+        super full_path, params, @uri.query
+      end
+
+    end # class NetHttp
+  end # module Connection
+end # module GSolr

data/lib/gsolr/connection/requestable.rb

@@ -0,0 +1,48 @@
+# A module that defines the interface and top-level logic for http based connection classes.
+module GSolr
+  module Connection
+    module Requestable
+
+      include GSolr::Connection::Utils
+
+      attr_reader :opts, :uri
+
+      # opts can have:
+      #   :url => 'http://localhost:8080/solr'
+      def initialize(opts={})
+        opts[:url]  ||= 'http://127.0.0.1:8983/solr'
+        @opts         = opts
+        @uri          = URI.parse opts[:url]
+      end
+
+      # send a request to the connection
+      # request '/select', :q=>'*:*'
+      #
+      # request '/update', {:wt=>:xml}, '</commit>'
+      # 
+      # force a post where the post body is the param query
+      # request '/update', "<optimize/>", :method=>:post
+      #
+      def request(path, params={}, *extra)
+        opts = extra[-1].kind_of?(Hash) ? extra.pop : {}
+        data = extra[0]
+        # force a POST, use the query string as the POST body
+        if opts[:method] == :post and data.to_s.empty?
+          http_context = self.post(path, hash_to_query(params), {}, {'Content-Type' => 'application/x-www-form-urlencoded'})
+        else
+          if data
+            # standard POST, using "data" as the POST body
+            http_context = self.post(path, data, params, {"Content-Type" => 'text/xml; charset=utf-8'})
+          else
+            # standard GET
+            http_context = self.get(path, params)
+          end
+        end
+
+        raise GSolr::RequestError.new("Solr Response: #{http_context[:message]}") unless http_context[:status_code] == 200
+
+        return http_context
+      end
+    end # module Requestable
+  end # module Connection
+end # module GSolr

data/lib/gsolr/connection/utils.rb

@@ -0,0 +1,82 @@
+# Helpful utility methods for building queries to a Solr server
+# This includes helpers that the Direct connection can use.
+module GSolr
+  module Connection
+    module Utils
+      # Performs URI escaping so that you can construct proper
+      # query strings faster.  Use this rather than the cgi.rb
+      # version since it's faster.  (Stolen from Rack).
+      def escape(s)
+        s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
+          #'%'+$1.unpack('H2'*$1.size).join('%').upcase
+          '%'+$1.unpack('H2'*bytesize($1)).join('%').upcase
+        }.tr(' ', '+')
+      end
+  
+      # encodes the string as utf-8 in Ruby 1.9
+      # returns the unaltered string in Ruby 1.8
+      def encode_utf8(string)
+        (string.respond_to?(:force_encoding) and string.respond_to?(:encoding)) ?
+          string.force_encoding(Encoding::UTF_8) : string
+      end
+  
+      # Return the bytesize of String; uses String#length under Ruby 1.8 and
+      # String#bytesize under 1.9.
+      if ''.respond_to?(:bytesize)
+        def bytesize(string)
+          string.bytesize
+        end
+      else
+        def bytesize(string)
+          string.size
+        end
+      end
+  
+      # creates and returns a url as a string
+      # "url" is the base url
+      # "params" is an optional hash of GET style query params
+      # "string_query" is an extra query string that will be appended to the 
+      # result of "url" and "params".
+      def build_url(url='', params={}, string_query='')
+        queries = [string_query, hash_to_query(params)]
+
+        queries.delete_if{|q_elem|
+          q_elem.to_s.empty?
+        }
+
+        url += "?#{queries.join('&')}" unless queries.empty?
+
+        return url
+      end
+
+      # converts a key value pair to an escaped string:
+      # Example:
+      # build_param(:id, 1) == "id=1"
+      def build_param(k,v)
+        "#{escape(k)}=#{escape(v)}"
+      end
+
+      #
+      # converts hash into URL query string, keys get an alpha sort
+      # if a value is an array, the array values get mapped to the same key:
+      #   hash_to_query(:q=>'blah', :fq=>['blah', 'blah'], :facet=>{:field=>['location_facet', 'format_facet']})
+      # returns:
+      #   ?q=blah&fq=blah&fq=blah&facet.field=location_facet&facet.field=format.facet
+      #
+      # if a value is empty/nil etc., it is not added
+      def hash_to_query(params)
+        mapped  = params.map do |key, val|
+                    next if val.to_s.empty?
+
+                    if val.class == Array
+                      hash_to_query(v.map { |elem| [key, elem] })
+                    else
+                      build_param key, val
+                    end
+                  end
+
+        mapped.compact.join("&")
+      end
+    end # module Utils
+  end # module Connection
+end # module GSolr

data/lib/gsolr/connection.rb

@@ -0,0 +1,9 @@
+require 'uri'
+
+module GSolr
+  module Connection
+    autoload :NetHttp,      'gsolr/connection/net_http'
+    autoload :Utils,        'gsolr/connection/utils'
+    autoload :Requestable,  'gsolr/connection/requestable'
+  end
+end

data/lib/gsolr/message/document.rb

@@ -0,0 +1,52 @@
+# A class that represents a "doc" xml element for a solr update
+module GSolr
+  module Message
+    class Document
+
+      # "attrs" is a hash for setting the "doc" xml attributes
+      # "fields" is an array of Field objects
+      attr_accessor :attrs, :fields
+
+      # "doc_hash" must be a Hash/Mash object
+      # If a value in the "doc_hash" is an array,
+      # a field object is created for each value...
+      def initialize(doc_hash = {})
+        @fields = []
+        doc_hash.each_pair do |field,values|
+          # create a new field for each value (multi-valued)
+          # put non-array values into an array
+          values = [values] unless values.is_a?(Array)
+          values.each do |v|
+            next if v.to_s.empty?
+            @fields << GSolr::Message::Field.new({:name=>field}, v.to_s)
+          end
+        end
+        @attrs={}
+      end
+
+      # returns an array of fields that match the "name" arg
+      def fields_by_name(name)
+        @fields.select{|f|f.name==name}
+      end
+
+      # returns the *first* field that matches the "name" arg
+      def field_by_name(name)
+        @fields.detect{|f|f.name==name}
+      end
+
+      #
+      # Add a field value to the document. Options map directly to
+      # XML attributes in the Solr <field> node.
+      # See http://wiki.apache.org/solr/UpdateXmlMessages#head-8315b8028923d028950ff750a57ee22cbf7977c6
+      #
+      # === Example:
+      #
+      #   document.add_field('title', 'A Title', :boost => 2.0)
+      #
+      def add_field(name, value, options = {})
+        @fields << GSolr::Message::Field.new(options.merge({:name=>name}), value)
+      end
+
+    end # class Document
+  end # module Message
+end # module GSolr

data/lib/gsolr/message/field.rb

@@ -0,0 +1,23 @@
+# A class that represents a "doc"/"field" xml element for a solr update
+module GSolr
+  module Message
+    class Field
+
+      # "attrs" is a hash for setting the "doc" xml attributes
+      # "value" is the text value for the node
+      attr_accessor :attrs, :value
+
+      # "attrs" must be a hash
+      # "value" should be something that responds to #_to_s
+      def initialize(attrs, value)
+        @attrs = attrs
+        @value = value
+      end
+
+      # the value of the "name" attribute
+      def name
+        @attrs[:name]
+      end
+    end # class Field
+  end # module Message
+end # module GSolr