rsolr 1.0.0.beta4 → 1.0.0.beta5

data/README.rdoc

@@ -26,6 +26,14 @@ The code docs can be viewed here : http://rdoc.info/projects/mwmitchell/rsolr
   # 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.
+
 == Querying
 Use the #get / #post method to send search requests to the /select handler:
   response = solr.get 'select', :params => {
@@ -33,8 +41,10 @@ Use the #get / #post method to send search requests to the /select handler:
     :start=>0,
     :rows=>10
   }
+  response["response"]["docs"].each{|doc| puts doc["id"] }
 
-The :params sent into the method are sent to Solr as-is. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:
+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']}
 
@@ -42,6 +52,15 @@ The above statement generates this Solr query:
   
   select?q=roses&fq=red&fq=violet
 
+===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.
+
+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:
   
@@ -50,13 +69,32 @@ The RSolr::Client class also uses method_missing for setting the request handler
 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.post "select", :data => enormous_params_hash
+  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"}
+
+===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.
 
@@ -87,7 +125,7 @@ When adding, you can also supply "add" xml element attributes and/or a block for
 
 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
@@ -116,10 +154,6 @@ The default response format is Ruby. When the :wt param is set to :ruby, the res
 ===JSON:
   solr.get 'select', :params => {:wt => :json}
 
-==Http Request Methods: +get+, +post+, and +head+ 
-RSolr can send GET, POST and HEAD requests to Solr:
-  response = solr.head "admin"
-
 ==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

data/VERSION

@@ -1 +1 @@
-1.0.0.beta4
+1.0.0.beta5

data/lib/rsolr/pagination.rb

@@ -38,8 +38,8 @@ module RSolr::Pagination
     protected
     
     # Checks if the called method starts
-    # with "paginate_" and
-    # converts the paginate_* to the solr
+    # with "paginate_*" and
+    # converts the * to the solr
     # request path. It then calls paginate
     # with the appropriate arguments.
     # If the called method doesn't

data/lib/rsolr/xml.rb

@@ -74,7 +74,7 @@ module RSolr::Xml
     
     def build &block
       require 'builder'
-      b = ::Builder::XmlMarkup.new(:indent=>0, :margin=>0, :encoding => 'UTF-8')
+      b = ::Builder::XmlMarkup.new(:indent => 0, :margin => 0, :encoding => 'UTF-8')
       b.instruct!
       block_given? ? yield(b) : b
     end

data/spec/api/client_spec.rb

@@ -29,17 +29,16 @@ describe "RSolr::Client" do
 
   context "post" do
     include ClientHelper
-    it "should pass the expected params to the connection's #post method" do
+    it "should pass the expected params to the connection's #execute method" do
+      request_opts = {:data => "the data", :method=>:post, :headers => {"Content-Type" => "text/plain"}}
       client.connection.should_receive(:execute).
-        with(
-          client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/plain"}, :method=>:post, :data=>"the data"})
-        ).
-          and_return(
-            :body => "",
-            :status => 200,
-            :headers => {"Content-Type"=>"text/plain"}
-          )
-      client.post "update", :data => "the data", :method=>:post, :headers => {"Content-Type" => "text/plain"}
+        with(client, hash_including(request_opts)).
+        and_return(
+          :body => "",
+          :status => 200,
+          :headers => {"Content-Type"=>"text/plain"}
+        )
+      client.post "update", request_opts
     end
   end
   
@@ -55,15 +54,18 @@ describe "RSolr::Client" do
     it "should send xml to the connection's #post method" do
       client.connection.should_receive(:execute).
         with(
-          client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/xml"}, :method=>:post, :data=>"<xml/>"})
+          client, hash_including({
+            :path => "update",
+            :headers => {"Content-Type"=>"text/xml"},
+            :method => :post,
+            :data => "<xml/>"
+          })
         ).
           and_return(
             :body => "",
             :status => 200,
             :headers => {"Content-Type"=>"text/xml"}
           )
-      # the :xml attr is lazy loaded... so load it up first
-      client.xml
       client.xml.should_receive(:add).
         with({:id=>1}, {:commitWith=>10}).
           and_return("<xml/>")
@@ -76,7 +78,12 @@ describe "RSolr::Client" do
     it "should send data to the connection's #post method" do
       client.connection.should_receive(:execute).
         with(
-          client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/xml"}, :method=>:post, :data=>"<optimize/>"})
+          client, hash_including({
+            :path => "update",
+            :headers => {"Content-Type"=>"text/xml"},
+            :method => :post,
+            :data => "<optimize/>"
+          })
         ).
           and_return(
             :body => "",
@@ -93,7 +100,12 @@ describe "RSolr::Client" do
       it "should send a #{meth} message to the connection's #post method" do
         client.connection.should_receive(:execute).
           with(
-            client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/xml"}, :method=>:post, :data=>"<?xml version=\"1.0\" encoding=\"UTF-8\"?><#{meth}/>"})
+            client, hash_including({
+              :path => "update",
+              :headers => {"Content-Type"=>"text/xml"},
+              :method => :post,
+              :data => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><#{meth}/>"
+            })
           ).
             and_return(
               :body => "",
@@ -110,7 +122,12 @@ describe "RSolr::Client" do
     it "should send data to the connection's #post method" do
       client.connection.should_receive(:execute).
         with(
-          client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/xml"}, :method=>:post, :data=>"<?xml version=\"1.0\" encoding=\"UTF-8\"?><delete><id>1</id></delete>"})
+          client, hash_including({
+            :path => "update",
+            :headers => {"Content-Type"=>"text/xml"},
+            :method => :post,
+            :data => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><delete><id>1</id></delete>"
+          })
         ).
           and_return(
             :body => "",
@@ -126,7 +143,12 @@ describe "RSolr::Client" do
     it "should send data to the connection's #post method" do
       client.connection.should_receive(:execute).
         with(
-          client, hash_including({:path => "update", :headers=>{"Content-Type"=>"text/xml"}, :method=>:post, :data=>"<?xml version=\"1.0\" encoding=\"UTF-8\"?><delete><query fq=\"category:&quot;trash&quot;\"/></delete>"})
+          client, hash_including({
+            :path => "update",
+            :headers => {"Content-Type"=>"text/xml"},
+            :method => :post,
+            :data => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><delete><query fq=\"category:&quot;trash&quot;\"/></delete>"
+          })
         ).
           and_return(
             :body => "",
@@ -142,18 +164,16 @@ describe "RSolr::Client" do
     it 'should not try to evaluate ruby when the :qt is not :ruby' do
       body = '{:time=>"NOW"}'
       result = client.adapt_response({:params=>{}}, {:status => 200, :body => body, :headers => {}})
-      result.should be_a(String)
       result.should == body
     end
     
     it 'should evaluate ruby responses when the :wt is :ruby' do
       body = '{:time=>"NOW"}'
       result = client.adapt_response({:params=>{:wt=>:ruby}}, {:status => 200, :body => body, :headers => {}})
-      result.should be_a(Hash)
       result.should == {:time=>"NOW"}
     end
     
-    it "ought raise a RSolr::Error::InvalidRubyResponse when the ruby is indeed frugged" do
+    it "ought raise a RSolr::Error::InvalidRubyResponse when the ruby is indeed frugged, or even fruggified" do
       lambda {
         client.adapt_response({:params=>{:wt => :ruby}}, {:status => 200, :body => "<woops/>", :headers => {}})
       }.should raise_error RSolr::Error::InvalidRubyResponse
@@ -164,7 +184,12 @@ describe "RSolr::Client" do
   context "build_request" do
     include ClientHelper
     it 'should return a request context array' do
-      result = client.build_request 'select', :method => :post, :params => {:q=>'test', :fq=>[0,1]}, :data => "data", :headers => {}
+      result = client.build_request('select',
+        :method => :post,
+        :params => {:q=>'test', :fq=>[0,1]},
+        :data => "data",
+        :headers => {}
+      )
       [/fq=0/, /fq=1/, /q=test/, /wt=ruby/].each do |pattern|
         result[:query].should match pattern
       end
@@ -173,7 +198,11 @@ describe "RSolr::Client" do
     end
     
     it "should set the Content-Type header to application/x-www-form-urlencoded if a hash is passed in to the data arg" do
-      result = client.build_request 'select', :method => :post, :data => {:q=>'test', :fq=>[0,1]}, :headers => {}
+      result = client.build_request('select',
+        :method => :post,
+        :data => {:q=>'test', :fq=>[0,1]},
+        :headers => {}
+      )
       result[:query].should == "wt=ruby"
       [/fq=0/, /fq=1/, /q=test/].each do |pattern|
         result[:data].should match pattern

data/spec/api/connection_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+describe "RSolr::Connection" do
+  
+  # context "execute" do
+  #   c = RSolr::Connection.new
+  #   base_url = "http://localhost:8983/solr"
+  #   client = RSolr::Client.new c, :url => base_url
+  #   c.execute client, {:method => :get, :uri => URI.parse(base_url + "/select")}
+  # end
+  
+end

data/spec/api/pagination_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+describe "RSolr::Pagination" do
+  
+end

data/spec/api/rsolr_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+describe "RSolr" do
+  
+  it "has a version that can be read via #version or VERSION" do
+    RSolr.version.should == RSolr::VERSION
+  end
+  
+  it "can escape" do
+    RSolr.should be_a(RSolr::Char)
+    RSolr.escape("this string").should == "this\\ string"
+  end
+  
+  context "connect" do
+    it "should return a RSolr::Client instance" do
+      RSolr.connect.should be_a(RSolr::Client)
+    end
+  end
+  
+end

metadata

@@ -6,8 +6,8 @@ version: !ruby/object:Gem::Version
   - 1
   - 0
   - 0
-  - beta4
-  version: 1.0.0.beta4
+  - beta5
+  version: 1.0.0.beta5
 platform: ruby
 authors: 
 - Matt Mitchell
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-17 00:00:00 -04:00
+date: 2010-10-28 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -88,8 +88,10 @@ summary: A Ruby client for Apache Solr
 test_files: 
 - spec/api/char_spec.rb
 - spec/api/client_spec.rb
+- spec/api/connection_spec.rb
 - spec/api/error_spec.rb
-- spec/api/http_spec.rb
+- spec/api/pagination_spec.rb
+- spec/api/rsolr_spec.rb
 - spec/api/uri_spec.rb
 - spec/api/xml_spec.rb
 - spec/spec_helper.rb

data/spec/api/http_spec.rb

@@ -1,4 +0,0 @@
-require 'spec_helper'
-describe "RSolr::Http" do
-  
-end