rsolr 0.9.6

data/CHANGES.txt

@@ -0,0 +1,228 @@
+0.9.6 - September 9, 2009
+  Added ability to create direct connections from existing Java::OrgApacheSolrCore::SolrCore
+  Added ability to send queries using POST
+  - solr.request '/select', :q=>'*:*', :method=>:post
+
+0.9.5 - September 4, 2009
+  Removed Array #extract_options!
+  Removed the Connection #send_request method (now #request)
+  Removed the Connection #select method -- still works, but this now ends up calling Connection #method_missing
+  Removed HTTPClient::Connector
+    - HTTPClient now uses a method called #connect (like RSolr.connect)
+    - This method accepts 1 or 2 args, see the #connect method comments
+  Changed the way the HTTP client adapter is set. Now just pass in when connecting:
+    - RSolr.connect(:http, :adapter=>curb, :url=>'http://solr.com')
+  Moved Message::Builders to Message::Adapter
+  Made Connection a module and moved class methods to "Base" class
+  Made HTTPClient a module and moved class methods to "Base" class
+  Removed the "adapter.rb" files -- Adapter modules are defined in the parent module file.
+  Moved Message module/singleton functionality to Message::Builder class
+  XML message adapter API change: no longer a singleton, must instantiate Message::Builder
+  Made RSolr::Connection #message public -- can change the adapter as needed; connection.message.adapter = RSolr::Message::Adapter::LibXML.new
+  More tests for HTTPClient::Util
+  Simplified url/query building in HTTPClient::Util
+  Updated tests accordingly
+
+0.9.1 - July 22, 2009
+  Added LibXml builder support (Thanks to Mat Brown - github.com/outoftime)
+
+0.9.0 - July 17, 2009
+  Added ability to use DirectSolrConnection instance when connecting
+  Loading Java classes using full package name
+
+0.8.9 - June 30, 2009
+  Deprecated hash syntax fix from outoftime/rsolr (Mat Brown)
+
+0.8.8 - May 6, 2009
+  Added method :request to RSolr::Connection
+    - this method is an alias for send_request
+
+0.8.7 - May 6, 2009
+  Added method_missing to RSolr::Connection, which sets the request handler path,
+  based on the method name:
+	# this sends a request like: /music_library?q=>coltrane
+	solr.music_library :q=>'coltrane'
+  Removed the core_ext file, put the Array extension code directly into rsolr.rb
+
+0.8.6 - April 25, 2009
+  Removed the Mash stuff -- which means the response keys from solr are only accessable using String based keys.
+  Use RSolr::Ext if you want more magic.
+
+0.8.5 - April 7, 2009
+  The RSolr::Message #add method now accepts a single Message::Document or an array of Message::Document objects
+  The Message::Document class has a new method: #add_field
+  Tests added for both changes
+  Permissions of files changed to non-executable
+  -- the above changes were made by Mat Brown, thank you Mat!
+  Added CannedSolrResponse module for mocks in the specs... not used yet
+
+0.8.4 - April 3, 2009
+  New test suite using RSpec and mocks coming. Run "rake spec"
+    - added specs for RSolr and RSolr::Connection
+
+0.8.3 - April 3, 2009
+  RSolr::Connection
+    - removed the block functionality of send_request and related methods
+      - this was used to gain access to the raw adapter response
+    - added #adapter_response method to all response objects
+      - this is used to get access to the original adapter response:
+        response = rsolr.select(:q=>'test')
+        response.adapter_response[:status_code]
+
+0.8.2 - March 24, 2009
+  Changed RSolr.connect method to accept one options hash argument
+    - This hash gets passed to the Connection object and the adapter
+  Updated tests, examples and README.rdoc to reflect this change
+  Bumped the version up in gemspec and the RSolr module
+
+0.8.1 - March 12, 2009
+  Added RSolr.escape and RSolr::Connection.new.escape
+    - tests in rsolr_test
+  Added ability to set doc and field attributes when adding documents via Message.add
+
+0.8.0 - March 6, 2009
+  Removed all response wrapper classes (now returning a simple hash for ruby responses)
+  Removed RSolr::Query - this library needs an external partner lib, RSolrExt etc..
+  changed query method to select
+  added send_request method to Connection for custom requests:
+    send_request '/my-handler', {:start=>0}, post_data=nil
+  moved Connection::Base to Connection
+  moved Connection::Adapter::* to Adapter::*
+  
+0.7.1 - February 27, 2009
+  Added simple query helper module -> RSolr::Query
+  Added tests for RSolr::Query
+  Modified Test::Unit::TestCase in test/test_helpers.rb
+
+0.7.0 - February 20, 2009
+  Removed all param mapping behavior, code and tests
+   - this stuff just gunks up rsolr and should be in an extension of some sort
+  Can now specify the request handler in all RSolr::Connection::Base methods as the first argument:
+    - solr.query 'select', :q=>'ipod'
+    - solr.query 'catalog', :q=>'humphry'
+    - solr.query :q=>'big' # defaults to the /select handler
+
+0.6.9 - January 29, 2009
+	Simplified facet response methods
+	Main facet method is called #facets
+	  - returns an array of Response::Facet instances
+	  - each Facet instance has field and values attributes
+	  -- the values attribute is an array with FacetValue instances which have @value and @hits
+	Added ability to set Connection::Base @param_adapters using :dismax or :standard
+	  instead of full class constant
+	  updated comments for #search method
+	Updated tests
+	Bumped up version
+
+0.6.8 - January 28, 2009
+	New method added to RSolr::Connection::Base - #find_values_for_facet
+	This method searches for facet values only, and sets the :rows param to 0
+	- returns an RSolr::Response::Query::Base instance
+	Example:
+		search_params[:facets][:offset]=0
+		search_params[:facets][:limit]=5
+		response = solr.search_facet_by_name(:language_facet, search_params)
+
+0.6.7 - January 27, 2009
+	The Symbol extension in core_ext.rb was cause for some REALLY painful debuging - so I removed it :(
+	This means no more :q.alt or :facet.field until RSolr gets a really nice query-builder module happening.
+
+0.6.6 - January 26, 2009
+	Added #get method helper to RSolr::Response::Query::DocExt
+	# doc.get(key, opts)
+	# key is the name of the field
+	# opts is a hash with the following valid keys:
+	#  - :sep - a string used for joining multivalued field values
+	#  - :default - a value to return when the key doesn't exist
+	# if :sep is nil and the field is a multivalued field, the array is returned
+
+0.6.5 - January 26, 2009
+	Removed to_mash everywhere, except for usage in RSolr::Response
+	Added a #close method to the Direct adapter
+		- this closes the connection and sets the @connection variable to nil
+	Removed to_mash in RSolr::Connection::Base
+	Changed RSolr::Response::Query::Doc to DocExt
+		- this no longer extends Mash
+		- each doc in the response now uses the #extend method to mixin the new DocExt module
+	Added #teardown method in direct connection test, this method closes the connection
+	Updated the connection test methods a bit
+
+0.6.4 - January 26, 2009
+	Updated the mapping output for the :filters and :phrase_filters (when using the #search method)
+		- now sending multiple fq's instead of one
+	Updated mapping tests
+
+0.6.3 - January 21, 2009
+	Added a new param mapping module: RSolr::Connection::ParamMapping
+	Mapping only for fields that need conversion/escaping or nested (facet.*) etc.
+	This new module can be activated by using the #search method
+	New tests for ParamMapping
+
+0.6.2 - January 14, 2009
+	Removed mapping and indexer modules -- seems to me that a general purpose mapping library
+	would be more valuable than an embedded module in RSolr ( RMapper ?)
+	This helps lighten RSolr a bit too
+	
+0.6.1 - January 13, 2009
+	Removed SearchExt and mapping until this library gets some real use
+	The only param mapping now is for :page and :per_page via the #search method
+	The Connection::Base #query method does NO mapping now
+	
+0.6.0 - January 9, 2009
+	Removed first argument from RSolr.connect, the "adapter_name"
+		The adapter is now set using the :adapter key when passing in options to RSolr.connect:
+		s = RSolr.connect(:adapter=>:direct)
+	
+0.5.9 - January 7, 2009
+	Finally brought in the ExtLib Mash classes for incoming params and response hashes from solr
+	  - this gives the ability to access/set values for hashes using strings OR symbols (HashWithIndifferentAccess)
+	Organized response tests
+	Added more response tests
+	Simplified the RSolr::Response::Base class by supporting only raw/string ruby input
+	Added method to Response::IndexInfo for grabbing a Solr field list
+	
+0.5.7 - January 5, 2009
+	Changed name from Solr to RSolr, changed all references to Solr to RSolr
+	Added new tests for RSolr::Mapper and RSolr::Message
+	
+0.5.6 - December 30, 2008
+	solr.gemspec cleanedup thanks to shairontoledo on github! :)
+	Added Solr::Response::Query::Facet module with helpers from the delsolr project
+		Also added test stub in test/connection/search_ext_test_methods.rb
+	Fixed pagination math errors
+	Added new SearchExt helper field: :phrase_filters
+		This will add quoted values to the :filters (fq solr param) hash for doing easier facet requests
+	
+	Be sure to check out the new demo app: http://github.com/mwmitchell/consuminator/tree/master
+	
+0.5.5 - December 29, 2008
+	Fixed bug where accessing a field by method name failed:
+		docs.each do |doc|
+			doc.timestamp
+		end
+	Fixed bug where using the #has? method on a doc failed:
+		docs.each do |doc|
+			doc.has?('timestamp')
+		end
+	Removed invalid autoload in Solr module
+	Fixed spelling error in Solr::Connection::SearchExt (thanks to matthewrudy)
+	
+0.5.4 - December 29, 2008
+	Re-organized the main Solr adapters, they're now in Solr::Connection::Adapter instead of Solr::Adapter
+	All responses from HTTPClient and Connection::Adapter::Direct return a hash with the following keys:
+		:status_code
+		:body
+		:params
+		:url
+		:path
+		:headers
+		:data
+	This hash is now available in the solr response objects as #source - this will be useful in testing and debugging by allowing you to see the generated params and queries... example:
+		response = Solr.query(:q=>'*:*')
+		response.source[:params]
+		response.source[:body]
+		response.source[:url]
+	Added MultiValue field support in Solr::Message, thanks to Fouad Mardini
+	Bug in Solr::Connection::SearchExt where the :q params was not getting generated - fixed by Fouad Mardini
+	Organized tests a bit, moved connection tests into test/connection
+	Fixed a bug in Solr::Connection::Adapter::HTTP where invalid HTTP POST headers were being generated

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2008-2009 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.rdoc

@@ -0,0 +1,148 @@
+=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.
+
+== Installation:
+  gem sources -a http://gems.github.com
+  sudo gem install mwmitchell-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
+
+== Simple usage:
+  require 'rubygems'
+  require 'rsolr'
+  solr = RSolr.connect :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=>'*:*'
+  
+To use a DirectSolrConnection (no http) in JRuby:
+  
+  solr = RSolr.connect(:direct,
+    :home_dir=>'/path/to/solr/home',
+    :dist_dir=>'/path/to/solr/distribution'
+  )
+
+For more information about DirecSolrConnection, see the {API}[http://lucene.apache.org/solr/api/org/apache/solr/servlet/DirectSolrConnection.html].
+
+
+== 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 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:
+  response = solr.documents :q=>'test'
+
+
+== 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.
+
+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:
+  
+  doc = {:id=>1, :price=>1.00}
+  add_attributes = {:allowDups=>false, :commitWithin=>10.0}
+  solr.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
+
+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
+
+===XML Builders for RSolr
+As of version 0.9.1, RSolr can use LibXml to create the update messages sent to solr. To switch from Builder to LibXml, set the RSolr::Message.builder like:
+  solr = RSolr.connect
+  solr.message.adapter = RSolr::Message::Adapter::Libxml.new
+
+
+== 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
+
+===XML:
+  solr.select(:wt=>:xml)
+===JSON:
+  solr.select(:wt=>:json)
+
+You can access the original request context (path, params, url etc.) by calling the #adapter_response method:
+  response = solr.select :q=>'*:*'
+  response.adapter_response[:status_code]
+  response.adapter_response[:body]
+  response.adapter_response[:url]
+
+The adapter_response is a hash that contains the generated params, url, path, post data, headers etc., very useful for debugging and testing.
+
+
+== HTTP Client Adapter
+You can specify the http client adapter:
+  :net_http     uses the standard Net::HTTP library
+  :curb         uses the C based "curl" library
+
+NOTE: The Net::Http is the default adapter.
+
+Example:
+  
+  RSolr.connect(:adapter => :curb)
+  RSolr.connect(:adapter => :net_http)
+
+Intereseting read about Ruby's Net::HTTP library:
+http://apocryph.org/2008/11/09/more_indepth_analysis_ruby_http_client_performance
+
+NOTE: You can't use the :curb adapter under jRuby. To install curb:
+  
+  sudo gem install curb

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+namespace :rsolr do
+  
+  desc "Starts the HTTP server used for running HTTP connection tests"
+  task :start_test_server do
+    system "cd apache-solr/example; java -jar start.jar"
+  end
+  
+end
+
+task :default => [:test_units]
+
+# rake package
+
+require 'rubygems'
+require 'rake/gempackagetask'
+raw_spec = File.read 'rsolr.gemspec'
+spec = eval(raw_spec)
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+end
+
+desc "Run basic tests"
+Rake::TestTask.new("test_units") { |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+  t.warning = true
+  t.libs << "test"
+}
+
+require 'spec/rake/spectask'
+
+desc "Run specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.libs += ["lib", "spec"]
+end
+
+desc 'Run specs' # this task runs each test in its own process
+task :specs do
+  require 'rubygems'
+  require 'facets/more/filelist' unless defined?(FileList)
+  files = FileList["**/*_spec.rb"]
+  p files.to_a
+  files.each do |filename|
+    system "cd #{File.dirname(filename)} && ruby #{File.basename(filename)}"
+  end
+end
+
+desc "Run specs"
+Rake::TestTask.new("specs") { |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+  t.warning = true
+  t.libs += ["lib", "spec"]
+}
+
+# Clean house
+desc 'Clean up tmp files.'
+task :clean do |t|
+  FileUtils.rm_rf "doc"
+  FileUtils.rm_rf "pkg"
+end
+
+# Rdoc
+desc 'Generate documentation for the rsolr gem.'
+Rake::RDocTask.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