mongo 0.18.2 → 0.18.3

data/lib/mongo/types/objectid.rb

@@ -14,13 +14,13 @@
 # limitations under the License.
 # ++
 
-require 'mutex_m'
+require 'thread'
 require 'socket'
 require 'digest/md5'
 
 module Mongo
 
-  # Representation of an ObjectId for Mongo.
+  # ObjectID class for documents in MongoDB.
   class ObjectID
     # This is the legacy byte ordering for Babble. Versions of the Ruby
     # driver prior to 0.14 used this byte ordering when converting ObjectID
@@ -30,11 +30,20 @@ module Mongo
     # with ObjectID#legacy_string_convert
     BYTE_ORDER = [7, 6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8]
 
-    LOCK = Object.new
-    LOCK.extend Mutex_m
-
+    @@lock  = Mutex.new
     @@index = 0
 
+    # Create a new object id. If no parameter is given, an id corresponding
+    # to the ObjectID BSON data type will be created. This is a 12-byte value 
+    # consisting of a 4-byte timestamp, a 3-byte machine id, a 2-byte process id,
+    # and a 3-byte counter.
+    #
+    # @param [Array] data should be an array of bytes. If you want
+    #   to generate a standard MongoDB object id, leave this argument blank.
+    def initialize(data=nil)
+      @data = data || generate
+    end
+
     def self.legal?(str)
       len = BYTE_ORDER.length * 2
       str =~ /([0-9a-f]+)/i
@@ -42,33 +51,61 @@ module Mongo
       str && str.length == len && match == str
     end
 
+    # Create an object id from the given time. This is useful for doing range
+    # queries; it works because MongoDB's object ids begin
+    # with a timestamp.
+    #
+    # @param [Time] time a utc time to encode as an object id.
+    #
+    # @return [Mongo::ObjectID]
+    #
+    # @example Return all document created before Jan 1, 2010.
+    #   time = Time.utc(2010, 1, 1)
+    #   time_id = ObjectID.from_time(time)
+    #   collection.find({'_id' => {'$lt' => time_id}})
+    def self.from_time(time)
+      self.new([time.to_i,0,0].pack("NNN").unpack("C12"))
+    end
+
     # Adds a primary key to the given document if needed.
+    #
+    # @param [Hash] doc a document requiring an _id.
+    #
+    # @return [Mongo::ObjectID, Object] returns a newly-created or 
+    #   current _id for the given document.
     def self.create_pk(doc)
       doc.has_key?(:_id) || doc.has_key?('_id') ? doc : doc.merge!(:_id => self.new)
     end
 
-    # +data+ is an array of bytes. If nil, a new id will be generated.
-    def initialize(data=nil)
-      @data = data || generate
-    end
-
-    def eql?(other)
-      @data == other.instance_variable_get("@data")
+    # Check equality of this object id with another.
+    #
+    # @param [Mongo::ObjectID] object_id
+    def eql?(object_id)
+      @data == object_id.instance_variable_get("@data")
     end
     alias_method :==, :eql?
 
-    # Returns a unique hashcode for the object.
+    # Get a unique hashcode for this object.
     # This is required since we've defined an #eql? method.
+    #
+    # @return [Integer]
     def hash
       @data.hash
     end
 
+    # Get an array representation of the object id.
+    #
+    # @return [Array]
     def to_a
       @data.dup
     end
 
     # Given a string representation of an ObjectID, return a new ObjectID
     # with that value.
+    #
+    # @param [String] str
+    #
+    # @return [Mongo::ObjectID]
     def self.from_string(str)
       raise InvalidObjectID, "illegal ObjectID format" unless legal?(str)
       data = []
@@ -78,11 +115,13 @@ module Mongo
       self.new(data)
     end
 
+    # @deprecated
     # Create a new ObjectID given a string representation of an ObjectID
     # using the legacy byte ordering. This method may eventually be
     # removed. If you are not sure that you need this method you should be
     # using the regular from_string.
     def self.from_string_legacy(str)
+      warn "Support for legacy object ids has been DEPRECATED."
       raise InvalidObjectID, "illegal ObjectID format" unless legal?(str)
       data = []
       BYTE_ORDER.each_with_index { |string_position, data_index|
@@ -91,6 +130,9 @@ module Mongo
       self.new(data)
     end
 
+    # Get a string representation of this object id.
+    #
+    # @return [String]
     def to_s
       str = ' ' * 24
       12.times do |i|
@@ -98,13 +140,22 @@ module Mongo
       end
       str
     end
+    alias_method :inspect, :to_s
+
+    # Convert to MongoDB extended JSON format. Since JSON includes type information,
+    # but lacks an ObjectID type, this JSON format encodes the type using an $id key.
+    #
+    # @return [String] the object id represented as MongoDB extended JSON.
+    def to_json(escaped=false)
+      "{\"$oid\": \"#{to_s}\"}"
+    end
 
-    def inspect; to_s; end
-
+    # @deprecated
     # Get a string representation of this ObjectID using the legacy byte
     # ordering. This method may eventually be removed. If you are not sure
     # that you need this method you should be using the regular to_s.
     def to_s_legacy
+      warn "Support for legacy object ids has been DEPRECATED."
       str = ' ' * 24
       BYTE_ORDER.each_with_index { |string_position, data_index|
         str[string_position * 2, 2] = '%02x' % @data[data_index]
@@ -112,11 +163,13 @@ module Mongo
       str
     end
 
+    # @deprecated
     # Convert a string representation of an ObjectID using the legacy byte
     # ordering to the proper byte ordering. This method may eventually be
     # removed. If you are not sure that you need this method it is probably
     # unnecessary.
     def self.legacy_string_convert(str)
+      warn "Support for legacy object ids has been DEPRECATED."
       legacy = ' ' * 24
       BYTE_ORDER.each_with_index do |legacy_pos, pos|
         legacy[legacy_pos * 2, 2] = str[pos * 2, 2]
@@ -124,10 +177,13 @@ module Mongo
       legacy
     end
 
-    # Returns the utc time at which this ObjectID was generated. This may
-    # be used in lieu of a created_at timestamp.
+    # Return the UTC time at which this ObjectID was generated. This may
+    # be used in lieu of a created_at timestamp since this information
+    # is always encoded in the object id.
+    #
+    # @return [Time] the time at which this object was created.
     def generation_time
-      Time.at(@data.pack("C4").unpack("N")[0])
+      Time.at(@data.pack("C4").unpack("N")[0]).utc
     end
 
     private
@@ -155,9 +211,9 @@ module Mongo
     end
 
     def get_inc
-      LOCK.mu_synchronize {
+      @@lock.synchronize do
         @@index = (@@index + 1) % 0xFFFFFF
-      }
+      end
     end
   end
 end

data/lib/mongo/types/regexp_of_holding.rb

@@ -24,14 +24,19 @@ module Mongo
   # Note that you do not have to use this class at all if you wish to
   # store regular expressions in Mongo. The Mongo and Ruby regex option
   # flags are the same. Storing regexes is discouraged, in any case.
+  # 
+  # @deprecated
   class RegexpOfHolding < Regexp
 
     attr_accessor :extra_options_str
 
+    # @deprecated we're no longer supporting this.
     # +str+ and +options+ are the same as Regexp. +extra_options_str+
     # contains all the other flags that were in Mongo but we do not use or
     # understand.
     def initialize(str, options, extra_options_str)
+      warn "RegexpOfHolding is deprecated; the modifiers i, m, and x will be stored automatically as BSON." +
+        "If you're only storing the options i, m, and x, you can safely ignore this message."
       super(str, options)
       @extra_options_str = extra_options_str
     end

data/lib/mongo/util/bson_ruby.rb

@@ -163,6 +163,10 @@ class BSON_RUBY
       serialize_null_element(@buf, k)
     when CODE_W_SCOPE
       serialize_code_w_scope(@buf, k, v)
+    when MAXKEY
+      serialize_max_key_element(@buf, k)
+    when MINKEY
+      serialize_min_key_element(@buf, k)
     else
       raise "unhandled type #{type}"
     end
@@ -234,6 +238,12 @@ class BSON_RUBY
         key = deserialize_cstr(@buf)
         doc[key] = [deserialize_number_int_data(@buf),
                     deserialize_number_int_data(@buf)]
+      when MAXKEY
+        key = deserialize_cstr(@buf)
+        doc[key] = MaxKey.new
+      when MINKEY, 255 # This is currently easier than unpack the type byte as an unsigned char.
+        key = deserialize_cstr(@buf)
+        doc[key] = MinKey.new
       when EOO
         break
       else
@@ -466,6 +476,16 @@ class BSON_RUBY
     self.class.serialize_cstr(buf, options_str.split(//).sort.uniq.join)
   end
 
+  def serialize_max_key_element(buf, key)
+    buf.put(MAXKEY)
+    self.class.serialize_key(buf, key)
+  end
+
+  def serialize_min_key_element(buf, key)
+    buf.put(MINKEY)
+    self.class.serialize_key(buf, key)
+  end
+
   def serialize_oid_element(buf, key, val)
     buf.put(OID)
     self.class.serialize_key(buf, key)
@@ -529,7 +549,7 @@ class BSON_RUBY
       NULL
     when Integer
       NUMBER_INT
-    when Numeric
+    when Float
       NUMBER
     when ByteBuffer
       BINARY
@@ -553,8 +573,22 @@ class BSON_RUBY
       OBJECT
     when Symbol
       SYMBOL
+    when MaxKey
+      MAXKEY
+    when MinKey
+      MINKEY
+    when Numeric
+      raise InvalidDocument, "Cannot serialize the Numeric type #{o.class} as BSON; only Fixum, Bignum, and Float are supported."
+    when Date, DateTime
+      raise InvalidDocument, "#{o.class} is not currently supported; " +
+        "use a UTC Time instance instead."
     else
-      raise InvalidDocument, "Unknown type of object: #{o.class.name}"
+      if defined?(ActiveSupport::TimeWithZone) && o.is_a?(ActiveSupport::TimeWithZone)
+        raise InvalidDocument, "ActiveSupport::TimeWithZone is not currently supported; " +
+                               "use a UTC Time instance instead."
+      else
+        raise InvalidDocument, "Cannot serialize #{o.class} as a BSON type; it either isn't supported or won't translate to BSON."
+      end
     end
   end
 

data/lib/mongo/util/byte_buffer.rb

@@ -17,6 +17,20 @@
 # A byte buffer.
 class ByteBuffer
 
+  # Commonly-used integers.
+  INT_LOOKUP = {
+    0    => [0, 0, 0, 0],
+    1    => [1, 0, 0, 0],
+    2    => [2, 0, 0, 0],
+    3    => [3, 0, 0, 0],
+    4    => [4, 0, 0, 0],
+    2001 => [209, 7, 0, 0],
+    2002 => [210, 7, 0, 0],
+    2004 => [212, 7, 0, 0],
+    2005 => [213, 7, 0, 0],
+    2006 => [214, 7, 0, 0]
+  }
+
   attr_reader :order
 
   def initialize(initial_data=[])
@@ -100,8 +114,10 @@ class ByteBuffer
   end
 
   def put_int(i, offset=nil)
-    a = []
-    [i].pack(@int_pack_order).each_byte { |b| a << b }
+    unless a = INT_LOOKUP[i]
+      a = []
+      [i].pack(@int_pack_order).each_byte { |b| a << b }
+    end
     put_array(a, offset)
   end
 

data/lib/mongo/util/conversions.rb

@@ -19,8 +19,8 @@ module Mongo #:nodoc:
   # objects to mongo-friendly parameters.
   module Conversions
 
-    ASCENDING  = ["ascending", "asc", "1"]
-    DESCENDING = ["descending", "desc", "-1"]
+    ASCENDING_CONVERSION  = ["ascending", "asc", "1"]
+    DESCENDING_CONVERSION = ["descending", "desc", "-1"]
 
     # Converts the supplied +Array+ to a +Hash+ to pass to mongo as
     # sorting parameters. The returned +Hash+ will vary depending 
@@ -76,11 +76,12 @@ module Mongo #:nodoc:
     # If the value is invalid then an error will be raised.
     def sort_value(value)
       val = value.to_s.downcase
-      return 1 if ASCENDING.include?(val)
-      return -1 if DESCENDING.include?(val)
+      return 1 if ASCENDING_CONVERSION.include?(val)
+      return -1 if DESCENDING_CONVERSION.include?(val)
       raise InvalidSortValueError.new(
         "#{self} was supplied as a sort direction when acceptable values are: " +
-        "Mongo::ASCENDING, 'ascending', 'asc', :ascending, :asc, 1, Mongo::DESCENDING, 'descending', 'desc', :descending, :desc, -1.")
+        "Mongo::ASCENDING, 'ascending', 'asc', :ascending, :asc, 1, Mongo::DESCENDING, " +
+        "'descending', 'desc', :descending, :desc, -1.")
     end
   end
 end

data/lib/mongo/util/ordered_hash.rb

@@ -88,6 +88,8 @@ class OrderedHash < Hash
       super(other)
     end
 
+    alias :update :merge!
+
     def inspect
       str = '{'
       str << (@ordered_keys || []).collect { |k| "\"#{k}\"=>#{self.[](k).inspect}" }.join(", ")
@@ -118,7 +120,7 @@ class OrderedHash < Hash
         code = 37 * code + key.hash
         code = 37 * code + value.hash
       end
-      code
+      code & 0x7fffffff
     end
 
     def eql?(o)

data/lib/mongo/util/support.rb

@@ -13,8 +13,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ++
+
+#:nodoc:
 class Object
 
+  #:nodoc:
   def returning(value)
     yield value
     value

data/lib/mongo/util/xml_to_ruby.rb

@@ -17,6 +17,7 @@
 require 'rexml/document'
 require 'mongo'
 
+# @deprecated
 # Converts a .xson file (an XML file that describes a Mongo-type document) to
 # an OrderedHash.
 class XMLToRuby
@@ -24,6 +25,7 @@ class XMLToRuby
   include Mongo
 
   def xml_to_ruby(io)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     doc = REXML::Document.new(io)
     doc_to_ruby(doc.root.elements['doc'])
   end
@@ -31,6 +33,7 @@ class XMLToRuby
   protected
 
   def element_to_ruby(e)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     type = e.name
     child = e.elements[1]
     case type
@@ -71,12 +74,14 @@ class XMLToRuby
   end
 
   def doc_to_ruby(element)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     oh = OrderedHash.new
     element.elements.each { |e| oh[e.attributes['name']] = element_to_ruby(e) }
     oh
   end
 
   def array_to_ruby(elements)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     a = []
     elements.each { |e|
       index_str = e.attributes['name']
@@ -86,6 +91,7 @@ class XMLToRuby
   end
 
   def regex_to_ruby(elements)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     pattern = elements['pattern'].text
     options_str = elements['options'].text || ''
 
@@ -97,6 +103,7 @@ class XMLToRuby
   end
 
   def dbref_to_ruby(elements)
+    warn "XMLToRuby is deprecated. The .xson format is not longer in use."
     ns = elements['ns'].text
     oid_str = elements['oid'].text
     DBRef.new(ns, ObjectID.from_string(oid_str))

data/test/test_bson.rb

@@ -1,5 +1,15 @@
 # encoding:utf-8
 require 'test/test_helper'
+require 'complex'
+require 'bigdecimal'
+require 'rational'
+
+# Need to simulating this class
+# without actually loading it.
+module ActiveSupport
+  class TimeWithZone
+  end
+end
 
 class BSONTest < Test::Unit::TestCase
 
@@ -181,6 +191,19 @@ class BSONTest < Test::Unit::TestCase
     end
   end
 
+  def test_exeption_on_using_unsupported_date_class
+    [DateTime.now, Date.today, ActiveSupport::TimeWithZone.new].each do |invalid_date|
+      doc = {:date => invalid_date}
+      begin
+      bson = BSON.serialize(doc)
+      rescue => e
+      ensure
+        assert_equal InvalidDocument, e.class
+        assert_match /UTC Time/, e.message
+      end
+    end
+  end
+
   def test_dbref
     oid = ObjectID.new
     doc = {}
@@ -293,6 +316,19 @@ class BSONTest < Test::Unit::TestCase
     end
   end
 
+  def test_invalid_numeric_types
+    [BigDecimal.new("1.0"), Complex(0, 1), Rational(2, 3)].each do |type|
+      doc = {"x" => type}
+      begin
+        BSON.serialize(doc)
+      rescue => e
+      ensure
+        assert_equal InvalidDocument, e.class
+        assert_match /Cannot serialize/, e.message
+      end
+    end
+  end
+
   def test_do_not_change_original_object
     val = OrderedHash.new
     val['not_id'] = 1
@@ -335,6 +371,18 @@ class BSONTest < Test::Unit::TestCase
     end
   end
 
+  def test_max_key
+    doc = {"a" => MaxKey.new}
+
+    assert_equal doc, BSON.deserialize(BSON.serialize(doc).to_a)
+  end
+
+  def test_min_key
+    doc = {"a" => MinKey.new}
+
+    assert_equal doc, BSON.deserialize(BSON.serialize(doc).to_a)
+  end
+
   def test_invalid_object
     o = Object.new
     assert_raise InvalidDocument do