jruby_streaming_update_solr_server 0.0.0 → 0.1.0

data/README.rdoc

@@ -1,16 +1,25 @@
 = jruby_streaming_update_solr_server
 
-Description goes here.
-
-== 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.
+Some syntactic sugar on top of the StreamingUpdateSolrServer as provided by the Apache
+Solr project, along with its most common argument, the SolrInputDocument. 
+
+Documentation can be generated with yard via the 'rake yard' action. 
+
+See the class files for more information, documentation, and examples.
+
+== What is this again?
+
+For users of Solr, there is a java class called StreamingUpdateSolrServer that allows you to easily 
+(and in a threaded manner) add documents (of class SolrInputDocument) 
+to a queue and have them automatically sent along to Solr by a user-configurable number of threads.
+
+These classes open up those Java classes to add some JRuby sugar and make it easy for you to
+construct Solr documents and send them to Solr all from within the comfort of the JRuby environment. 
+
+== WARNING: Program hangs on for 60 seconds!
+
+*WARNING*: After your program ends, the StreamingUpdateSolrServer object hangs on for a full minute, presumably
+the timeout of the underlying http client object. I haven't figure out how to change this yet.
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/lib/jruby_streaming_update_solr_server.rb

@@ -1,9 +1,88 @@
+if not defined? JRUBY_VERSION
+  raise "jruby streaming update solr server only runs under jruby"
+end
+
+# Load .jar files locally if they haven't already been pulled in.
+begin
+  include_class Java::OrgApacheSolrClientSolrjImpl::StreamingUpdateSolrServer
+  include_class Java::OrgApacheSolrCommon::SolrInputDocument
+rescue NameError  => e
+  jardir = File.join(File.dirname(__FILE__), '..', 'jars')
+  Dir.glob("#{jardir}/*.jar") do |x|
+    require x
+  end  
+  retry
+end
 
-include_class Java::OrgApacheSolrClientSolrjImpl::StreamingUpdateSolrServer
-include_class Java::OrgApacheSolrCommon::SolrInputDocument
+# Sugar on top of the org.apache.solr.client.solr.impl.StreamingUpdateSolrServer
+# 
+# Note that several important methods, new and commit, are direct from the java and hence
+# not represented here where I'm just opening up the class to add some sugar. Full documentation
+# for the raw java methods is available at 
+# http://lucene.apache.org/solr/api/org/apache/solr/client/solrj/impl/StreamingUpdateSolrServer.html
+#
+# A quick look at important java methods you can call:
+# 
+# <b>suss = StreamingUpdateSolrServer.new(solrURL, queueSize, numberOfThreads)</b>
+#   The constructor.
+#
+#   [String] solrURL The URL to your solr instance (i.e., http://solr-machine:port/solr)
+#   [Integer] queueSize The size of the queue from which consumer threads will pull
+#     documents ready to be added to Solr and actually do the sending.
+#   [Integer] numberOfThreads The number of consumer threads to do the sending-to-Solr
+# 
+# <b>suss.commit</b>
+#   Send the commit to the solr server
+#   
+# <b>suss.optimize</b>
+#   Send the optimize commnd to the Solr server
+#
+# <b>suss.deleteById(id)</b>
+#
+# <b>suss.deleteById([id1, id2, id3, ...])</b>
+#   Delete the given ID or IDs
+#
+# <b>suss.deleteByQuery(query)</b>
+#   Delete everything that matches +query+
+#   [String] query A valid solr query. Everything that matches will be deleted. So, you can ditch
+#     it all by sending, e.g., '*:*'
+#
+# @author Bill Dueber
 
 class  StreamingUpdateSolrServer
-  alias_method :susadd, :add 
+
+  # Hang onto the java #add for internal use
+  alias_method :sussadd, :add 
+  
+  # Add a document to the SUSS 
+  # @param [SolrInputDocument, #each_pair] doc The SolrInputDocument or hash (or hash-like object
+  # that responds to #each_pair) to add. The latter must be of the form solrfield => value or
+  # solrfield => [list, of, values]. They keys can be either symbols or strings.
+  #
+  # @example Create and add a SolrInputDocument
+  #   url = 'http://solrmachine:port/solr' # URL to solr
+  #   queuesize = 10 # Size of producer cache 
+  #   threads = 2 # Number of consumer threads to push docs from queue to solr
+  #
+  #   suss = StreamingUpdateSolrServer.new(url,queuesize,threads)
+  #
+  #   doc = SolrInputDocument.new
+  #   doc << ['title', 'This is the title']
+  #   doc << ['id', 1]
+  #   suss.add doc  # or suss << doc
+  #   # repeat as desired
+  #   suss.commit
+  #
+  # @example Create and add as a hash
+  #   # The "hash" just needs to be an object that responds to each_pair with field,value(s)
+  #   suss = StreamingUpdateSolrServer.new(url,queuesize,threads)
+  #   doc = {}
+  #   doc['title'] = This is the title'
+  #   doc[:id] = 1 # Can also take symbols instead of strings if you like
+  #   doc[:author] = ['Bill', 'Mike']
+  #   suss << doc
+  #   # repeat as desired
+  #   suss.commit
   
   def add doc
     if doc.is_a? org.apache.solr.common.SolrInputDocument
@@ -13,9 +92,9 @@ class  StreamingUpdateSolrServer
       doc.each_pair do |f,v|
         newdoc << [f,v]
       end
-      susadd newdoc
+      sussadd newdoc
     else
-      puts "ERROR: Need to pass either a org.apache.solr.common.SolrInputDocument or a hash"
+      raise ArgumentError "Need to pass either an org.apache.solr.common.SolrInputDocument or a hash"
     end
   end
   
@@ -23,8 +102,25 @@ class  StreamingUpdateSolrServer
   
 end
 
+# Add some sugar to the SolrInputDocument
+#
+# @author Bill Dueber
 
 class SolrInputDocument
+  
+  # Add a field and value(s) to the document. This is strictly additive; nothing is replaced or removed
+  #
+  # @param [Array<Symbol, String>] fv A two-element array of the form [field, value] or [field, [value1, value2, ...]]
+  # The field name (i.e., fv[0]) is the Solr field name as specified in schema.xml and
+  # must be either a string or a symbol
+  # @return [Array<String>] the list of current values for the field in fv[0]
+  #
+  # @example Add some fields
+  #  doc = SolrInputDocument.new
+  #  doc << ['title', 'Mein Kopf'] #=> ['Mein Kopf']
+  #  doc << ['title', 'My Head!']  #=> ['Mein Kopf', 'My Head!']
+  #  doc << ['author', ['Bill', 'Mike', 'Molly']] #=> ['Bill', 'Mike', 'Molly']
+  
   def << fv
     field = fv[0]
     value = fv[1]
@@ -41,6 +137,14 @@ class SolrInputDocument
     self[field]
   end
   
+  
+  # Get a list of the currently-set values for the passed field
+  #
+  # Note that this will always return either nil (not found) or an array, even of one element
+  #
+  # @param [String, Symbol] field The field whose values you want (as String or Symbol)
+  # @return [Array<String>] An array of values (or nil on not found)
+  #
   def [] field
     if field.is_a?(Symbol)
       field = field.to_s
@@ -52,10 +156,25 @@ class SolrInputDocument
     if v.class == Java::JavaUtil::ArrayList
       return v.to_a
     else 
-      return v
+      return [v]
     end
   end
   
+  # Set the value(s) for the given field, destroying any values that were already in there
+  #
+  # Note that this is destructive; see #<< to add multiple values to a field
+  #
+  # @param [String, Symbol] field The solr field you're setting the value of
+  # @param [String, Array<String>] value The value or array of values to set
+  # @return [Array<String>] The list of values (i.e., either +value+ or +[value]+)
+  #
+  # @example
+  #  doc = SolrInputDocument.new
+  #  doc[:id] = 1 #=> [1]
+  #  doc[:author] = 'Mike' #=> ['Mike']
+  #  doc[:author] = 'Bill' #=> ['Bill']
+  #  doc[:author] #=> ['Bill']
+  
   def []= field, value
     if field.is_a?(Symbol)
       field = field.to_s
@@ -64,8 +183,29 @@ class SolrInputDocument
     self[field]
   end
   
+  
+  # Add keys and values from a hash or hash-like object to the document without removing any
+  # already-added values.
+  #
+  # @param [#each_pair] h A set of field=>value pairs, probably in a Hash. Can be either 
+  # field=>value or field=>[list,of,values]
+  #
+  # @example Merge a hash into an existing document
+  #   doc = SolrInputDocument.new
+  #   doc << [:author, 'Bill']
+  #   h = {}
+  #   h['author'] = 'Mike'
+  #   h['id'] = 1
+  #   h[:copies] = ['Grad reference', 'Long-term storage']
+  #   doc.merge! h
+  #   doc[:id] #=> 1
+  #   doc[:author] #=> ['Bill', 'Mike']
+  #   doc[:copies] #=> ['Grad reference', 'Long-term storage']
+  
   def merge! h
-    # throw an error unless h.respond_to?(:each_pair)
+    unless h.respond_to? :each_pair
+      raise ArgumentError, "Argument must respond to #each_pair"
+    end
     h.each_pair do |k,v|
       self << [k,v]
     end
@@ -73,5 +213,3 @@ class SolrInputDocument
 end
 
 
-
-

data/test/test_jruby_streaming_update_solr_server.rb

@@ -1,7 +1,39 @@
 require 'helper'
 
 class TestJrubyStreamingUpdateSolrServer < Test::Unit::TestCase
-  should "probably rename this file and start testing for real" do
-    flunk "hey buddy, you should probably rename this file and start testing for real"
+  should "Write some tests, but don't know how to mock up a solr server" do
+    assert_equal 1, 1
   end
+
+  should "Report nil for a document that doesn't include a field" do 
+    doc = SolrInputDocument.new
+    assert_equal nil, doc[:notinthere]
+  end
+  
+  should "Return single and multiple values in arrays" do
+    doc = SolrInputDocument.new
+    doc << [:id, 1]
+    assert_equal [1], doc[:id]
+    doc << [:id, 2]
+    assert_equal [1,2], doc[:id]
+  end
+  
+  should "Add items in hash via merge!" do
+    doc = SolrInputDocument.new
+    doc << [:id, 1]
+    h = {:id => 2, :name => 'Bill'}
+    doc.merge! h
+    assert_equal [1,2], doc[:id]
+    assert_equal ['Bill'], doc[:name]
+  end
+  
+  should "Destroy existing items via []=" do
+    doc = SolrInputDocument.new
+    doc[:id] = 1
+    assert_equal [1], doc[:id]
+    doc[:id] = 2
+    assert_equal [2], doc[:id]
+  end    
+    
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jruby_streaming_update_solr_server
 version: !ruby/object:Gem::Version 
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
   - Bill Dueber
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-06 00:00:00 -05:00
+date: 2010-02-12 00:00:00 -05:00
 default_executable: 
 dependencies: 
   - !ruby/object:Gem::Dependency 
@@ -48,6 +48,12 @@ files:
   - README.rdoc
   - Rakefile
   - VERSION
+  - jars/apache-solr-solrj-1.5-dev.jar
+  - jars/commons-codec-1.3.jar
+  - jars/commons-httpclient-3.1.jar
+  - jars/commons-logging-1.1.1.jar
+  - jars/slf4j-api-1.5.5.jar
+  - jars/slf4j-jdk14-1.5.5 2.jar
   - lib/jruby_streaming_update_solr_server.rb
   - test/helper.rb
   - test/test_jruby_streaming_update_solr_server.rb