rsolr 0.12.0 → 2.6.0

data/README.rdoc

@@ -1,63 +1,131 @@
 =RSolr
 
-A Ruby client for Apache Solr. RSolr has been developed to be simple and extendable. It features transparent JRuby DirectSolrConnection support and a simple Hash-in, Hash-out architecture.
+A simple, extensible Ruby client for Apache Solr.
+
+==Documentation
+The code docs http://www.rubydoc.info/gems/rsolr
 
 == Installation:
-  gem sources -a http://gemcutter.org
-  sudo gem install rsolr
+  gem install rsolr
 
-==Related Resources & Projects
-* {Solr}[http://lucene.apache.org/solr/]
-* {RSolr Google Group}[http://groups.google.com/group/rsolr]
-* {RSolr::Ext}[http://github.com/mwmitchell/rsolr-ext] -- an extension kit for RSolr
-* {Sunspot}[http://github.com/outoftime/sunspot] -- an awesome Solr DSL, built with RSolr
-* {Blacklight}[http://blacklightopac.org] -- a next generation Library OPAC, built with RSolr
-* {solr-ruby}[http://wiki.apache.org/solr/solr-ruby] -- the original Solr Ruby Gem
-* {java_bin}[http://github.com/kennyj/java_bin] -- Provides javabin/binary parsing for Ruby
-
-== Simple usage:
-  require 'rubygems'
+== Example:
   require 'rsolr'
-  solr = RSolr.connect :url=>'http://solrserver.com'
-  
+
+  # Direct connection
+  solr = RSolr.connect :url => 'http://solrserver.com'
+
+  # Connecting over a proxy server
+  solr = RSolr.connect :url => 'http://solrserver.com', :proxy=>'http://user:pass@proxy.example.com:8080'
+
+  # Using an alternate Faraday adapter
+  solr = RSolr.connect :url => 'http://solrserver.com', :adapter => :em_http
+
+  # Using a custom Faraday connection
+  conn = Faraday.new do |faraday|
+    faraday.response :logger                  # log requests to STDOUT
+    faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
+  end
+  solr = RSolr.connect conn, :url => 'http://solrserver.com'
+
   # send a request to /select
-  response = rsolr.select :q=>'*:*'
-  
-  # send a request to a custom request handler; /catalog
-  response = rsolr.request '/catalog', :q=>'*:*'
-  
-  # alternative to above:
-  response = rsolr.catalog :q=>'*:*'
+  response = solr.get 'select', :params => {:q => '*:*'}
+
+  # send a request to /catalog
+  response = solr.get 'catalog', :params => {:q => '*:*'}
+
+When the Solr +:wt+ is +:ruby+, then the response will be a Hash. This Hash is the same object returned by Solr, but evaluated as Ruby. If the +:wt+ is not +:ruby+, then the response will be a String.
+
+The response also exposes 2 attribute readers (for any +:wt+ value), +:request+ and +:response+. Both are Hash objects with symbolized keys.
+
+The +:request+ attribute contains the original request context. You can use this for debugging or logging. Some of the keys this object contains are +:uri+, +:query+, +:method+ etc..
+
+The +:response+ attribute contains the original response. This object contains the +:status+, +:body+ and +:headers+ keys.
+
+== Request formats
+
+By default, RSolr uses the Solr JSON command format for all requests.
+
+  RSolr.connect :url => 'http://solrserver.com', update_format: :json # the default
+  # or
+  RSolr.connect :url => 'http://solrserver.com', update_format: :xml
+
+== Timeouts
+The read and connect timeout settings can be set when creating a new instance of RSolr, and will
+be passed on to underlying Faraday instance:
+
+  solr = RSolr.connect(:timeout => 120, :open_timeout => 120)
+
+== Retry 503s
+A 503 is usually a temporary error which RSolr may retry if requested. You may specify the number of retry attempts with the +:retry_503+ option.
+
+Only requests which specify a Retry-After header will be retried, after waiting the indicated retry interval, otherwise RSolr will treat the request as a 500. You may specify a maximum Retry-After interval to wait with the +:retry_after_limit+ option (default: one second).
+  solr = RSolr.connect(:retry_503 => 1, :retry_after_limit => 1)
+
+For additional control, consider using a custom Faraday connection (see above) using its `retry` middleware.
 
 == Querying
-Use the #select method to send requests to the /select handler:
-  response = solr.select({
+Use the #get / #post method to send search requests to the /select handler:
+  response = solr.get 'select', :params => {
     :q=>'washington',
     :start=>0,
     :rows=>10
-  })
+  }
+  response["response"]["docs"].each{|doc| puts doc["id"] }
 
-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 are generated for the Solr query. Example:
-  
-  solr.select :q=>'roses', :fq=>['red', 'violet']
+The +:params+ sent into the method are sent to Solr as-is, which is to say they are converted to Solr url style, but no special mapping is used.
+When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:
+
+  solr.get 'select', :params => {: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'
+  select?q=roses&fq=red&fq=violet
 
-A shortcut for the above example:
-  response = solr.documents :q=>'test'
+===Pagination
+To paginate through a set of Solr documents, use the paginate method:
+  solr.paginate 1, 10, "select", :params => {:q => "test"}
 
+The first argument is the current page, the second is how many documents to return for each page. In other words, "page" is the "start" Solr param and "per-page" is the "rows" Solr param.
 
-== Updating Solr
-Updating can be done using 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.
+The paginate method returns WillPaginate ready "docs" objects, so for example in a Rails application, paginating is as simple as:
+  <%= will_paginate @solr_response["response"]["docs"] %>
+
+===Method Missing
+The +RSolr::Client+ class also uses +method_missing+ for setting the request handler/path:
+
+  solr.paintings :params => {:q=>'roses', :fq=>['red', 'violet']}
+
+This is sent to Solr as:
+  paintings?q=roses&fq=red&fq=violet
+
+This works with pagination as well:
+
+  solr.paginate_paintings 1, 10, {:q=>'roses', :fq=>['red', 'violet']}
+
+===Using POST for Search Queries
+There may be cases where the query string is too long for a GET request. RSolr solves this issue by converting hash objects into form-encoded strings:
+  response = solr.music :data => {:q => "*:*"}
+
+The +:data+ hash is serialized as a form-encoded query string, and the correct content-type headers are sent along to Solr.
+
+===Sending HEAD Requests
+There may be cases where you'd like to send a HEAD request to Solr:
+  solr.head("admin/ping").response[:status] == 200
+
+==Sending HTTP Headers
+Solr responds to the request headers listed here: http://wiki.apache.org/solr/SolrAndHTTPCaches
+To send header information to Solr using RSolr, just use the +:headers+ option:
+  response = solr.head "admin/ping", :headers => {"Cache-Control" => "If-None-Match"}
 
-Raw XML via  #update
-  solr.update '</commit>'
-  solr.update '</optimize>'
+===Building a Request
++RSolr::Client+ provides a method for building a request context, which can be useful for debugging or logging etc.:
+  request_context = solr.build_request "select", :data => {:q => "*:*"}, :method => :post, :headers => {}
+
+To build a paginated request use build_paginated_request:
+  request_context = solr.build_paginated_request 1, 10, "select", ...
+
+== Updating Solr
+Updating is done using native Ruby objects. Hashes are used for single documents and arrays are used for a collection of documents (hashes). These objects get turned into simple XML "messages". Raw XML strings can also be used.
 
 Single document via #add
   solr.add :id=>1, :price=>1.00
@@ -66,17 +134,28 @@ 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:
-  
+The optional +:add_attributes+ hash can also be used to set Solr "add" document attributes:
+  solr.add documents, :add_attributes => {:commitWithin => 10}
+
+Raw commands via  #update
+  solr.update data: '<commit/>', headers: { 'Content-Type' => 'text/xml' }
+  solr.update data: { optimize: true }.to_json, headers: { 'Content-Type' => 'application/json' }
+
+When adding, you can also supply "add" xml element attributes and/or a block for manipulating other "add" related elements (docs and fields) by calling the +xml+ method directly:
+
   doc = {:id=>1, :price=>1.00}
-  add_attributes = {:allowDups=>false, :commitWithin=>10.0}
-  solr.add(doc, add_attributes) do |doc|
+  add_attributes = {:allowDups=>false, :commitWithin=>10}
+  add_xml = solr.xml.add(doc, add_attributes) do |doc|
     # boost each document
     doc.attrs[:boost] = 1.5
     # boost the price field:
     doc.field_by_name(:price).attrs[:boost] = 2.0
   end
 
+Now the "add_xml" object can be sent to Solr like:
+  solr.update :data => add_xml
+
+===Deleting
 Delete by id
   solr.delete_by_id 1
 or an array of ids
@@ -87,27 +166,62 @@ Delete by query:
 Delete by array of queries
   solr.delete_by_query ['price:1.00', 'price:10.00']
 
-Commit & optimize shortcuts
-  solr.commit
-  solr.optimize
+===Commit / Optimize
+  solr.commit, :commit_attributes => {}
+  solr.optimize, :optimize_attributes => {}
 
 == 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. RSolr 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
+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. RSolr 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:
+  solr.get 'select', :params => {:wt => :ruby} # notice :ruby is a Symbol
+===Raw Ruby:
+  solr.get 'select', :params => {:wt => 'ruby'} # notice 'ruby' is a String
 ===XML:
-  solr.select(:wt=>:xml)
-===JSON:
-  solr.select(:wt=>:json)
+  solr.get 'select', :params => {:wt => :xml}
+===JSON (default):
+  solr.get 'select', :params => {: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
+* {RSolr Google Group}[http://groups.google.com/group/rsolr] -- The RSolr discussion group
+* {rsolr-ext}[http://github.com/mwmitchell/rsolr-ext] -- An extension kit for RSolr
+* {rsolr-direct}[http://github.com/mwmitchell/rsolr-direct] -- JRuby direct connection for RSolr
+* {rsolr-nokogiri}[http://github.com/mwmitchell/rsolr-nokogiri] -- Gives RSolr Nokogiri for XML generation.
+* {SunSpot}[http://github.com/sunspot/sunspot] -- An awesome Solr DSL, built with RSolr
+* {Blacklight}[http://blacklightopac.org] -- A "next generation" Library OPAC, built with RSolr
+* {java_bin}[http://github.com/kennyj/java_bin] -- Provides javabin/binary parsing for RSolr
+* {Solr}[http://lucene.apache.org/solr/] -- The Apache Solr project
+* {solr-ruby}[http://wiki.apache.org/solr/solr-ruby] -- The original Solr Ruby Gem!
+
+== Note on Patches/Pull Requests
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+==Contributors
+* Nathan Witmer
+* Magnus Bergmark
+* shima
+* Randy Souza
+* Mat Brown
+* Jeremy Hinegardner
+* Denis Goeury
+* shairon toledo
+* Rob Di Marco
+* Peter Kieltyka
+* Mike Perham
+* Lucas Souza
+* Dmitry Lihachev
+* Antoine Latter
+* Naomi Dushay
+
+==Author
+
+Matt Mitchell <mailto:goodieboy@gmail.com>
+
+==Copyright
+
+Copyright (c) 2008-2010 Matt Mitchell. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+
+task default: ['spec']
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+# Rdoc
+require 'rdoc/task'
+
+desc 'Generate documentation for the rsolr gem.'
+RDoc::Task.new(:doc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'RSolr'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/rsolr/char.rb

@@ -0,0 +1,6 @@
+# :nodoc:
+module RSolr::Char
+  def self.included(*)
+    warn 'RSolr::Char is deprecated without replacement, and will be removed in RSolr 3.x'
+  end
+end