object_id_gem 1.0.6

data/lib/objectid_columns/active_record/base.rb

@@ -0,0 +1,33 @@
+require 'objectid_columns'
+require 'active_support'
+require 'objectid_columns/has_objectid_columns'
+
+module ObjectidColumns
+  module ActiveRecord
+    # This module gets included into ActiveRecord::Base when ObjectidColumns loads. It is just a "trampoline" -- the
+    # first time you call one of its methods, it includes ObjectidColumns::HasObjectidColumns into your model, and
+    # then re-calls the method. (This looks like infinite recursion, but isn't, because once we include the module,
+    # its implementation takes precedence over ours -- because we will always be a module earlier on the inheritance
+    # chain, since we by definition were included before ObjectidColumns::HasObjectidColumns.)
+    module Base
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Do we have any ObjectId columns? This is always false -- once we include ObjectidColumns::HasObjectidColumns,
+        # its implementation (which just returns 'true') takes precedence.
+        def has_objectid_columns?
+          false
+        end
+
+        # These are our "trampoline" methods -- the methods that you should be able to call on an ActiveRecord class
+        # that has never had any ObjectidColumns-related methods called on it before, that bootstrap the process.
+        [ :has_objectid_columns, :has_objectid_column, :has_objectid_primary_key ].each do |method_name|
+          define_method(method_name) do |*args|
+            include ::ObjectidColumns::HasObjectidColumns
+            send(method_name, *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/objectid_columns/active_record/relation.rb

@@ -0,0 +1,40 @@
+require 'objectid_columns'
+
+module ObjectidColumns
+  module ActiveRecord
+    # This module gets included into ActiveRecord::Relation; it is responsible for modifying the behavior of +where+.
+    # Note that when you call +where+ directly on an ActiveRecord class, it (through various AR magic) ends up calling
+    # ActiveRecord::Relation#where, so this takes care of that, too.
+    module Relation
+      extend ActiveSupport::Concern
+
+      # There is really only one case where we can transparently modify queries -- where you're using hash syntax:
+      #
+      #     model.where(:foo_oid => <objectID>)
+      #
+      # If you're using SQL string syntax:
+      #
+      #     model.where("foo_oid = ?", <objectID>)
+      #
+      # ...then there's no way to reliably determine what should be converted as an ObjectId (and, critically, to what
+      # format -- hex or binary -- we should convert it). As such, we leave the responsibility for that case up to
+      # the user.
+      def where(*args)
+        # Bail out if we don't have any ObjectId columns
+        return super(*args) unless respond_to?(:has_objectid_columns?) && has_objectid_columns?
+        # Bail out if we're not using the Hash form
+        return super(*args) unless args.length == 1 && args[0].kind_of?(Hash)
+
+        query = { }
+        args[0].each do |key, value|
+          # #translate_objectid_query_pair is a method defined on the ObjectidColumns::ObjectidColumnsManager, and is
+          # called via the delegation defined in ObjectidColumns::HasObjectidColumns.
+          (key, value) = translate_objectid_query_pair(key, value)
+          query[key] = value
+        end
+
+        super(query)
+      end
+    end
+  end
+end

data/lib/objectid_columns/arel/visitors/to_sql.rb

@@ -0,0 +1,88 @@
+require 'active_support'
+
+module ObjectidColumns
+  module Arel
+    module Visitors
+      # This module gets mixed into Arel::Visitors::ToSql, which is the class that the Arel gem (which is really the
+      # backbone of ActiveRecord's query language) uses to generate SQL. This teaches Arel what to do when it bumps
+      # into an object of a BSON ID class -- _i.e._, how to convert it to a SQL literal.
+      #
+      # How this works depends on which version of ActiveRecord -- and therefore AREL -- you're using:
+      #
+      # * In Arel 4.x, the #visit... methods get called with two arguments. The first is the actual BSON ID that needs
+      #   to be converted; the second provides context. From the second parameter, we can get the table name and
+      #   column name. We use this to get a hold of the ObjectidColumnsManager via its class method .for_table, and,
+      #   from there, a converted, valid value for the column in question (whether hex or binary).
+      # * In Arel 2.x (AR 3.0.x) and 3.x, we have to monkeypatch the #visit_Arel_Attributes_Attribute method -- it
+      #   already picks up and stashes away the .last_column, but we need to add the .last_relation, too.
+      #
+      module ToSql
+        extend ActiveSupport::Concern
+
+        require 'arel'
+        if ::Arel::VERSION =~ /^[23]\./
+          def visit_Arel_Attributes_Attribute_with_objectid_columns(o, *args)
+            out = visit_Arel_Attributes_Attribute_without_objectid_columns(o, *args)
+            self.last_relation = o.relation
+            out
+          end
+
+          included do
+            alias_method_chain :visit_Arel_Attributes_Attribute, :objectid_columns
+
+            alias :visit_Arel_Attributes_Integer :visit_Arel_Attributes_Attribute_with_objectid_columns
+            alias :visit_Arel_Attributes_Float :visit_Arel_Attributes_Attribute_with_objectid_columns
+            alias :visit_Arel_Attributes_Decimal :visit_Arel_Attributes_Attribute_with_objectid_columns
+            alias :visit_Arel_Attributes_String :visit_Arel_Attributes_Attribute_with_objectid_columns
+            alias :visit_Arel_Attributes_Time :visit_Arel_Attributes_Attribute_with_objectid_columns
+            alias :visit_Arel_Attributes_Boolean :visit_Arel_Attributes_Attribute_with_objectid_columns
+
+            attr_accessor :last_relation
+          end
+        end
+
+        def visit_BSON_ObjectId(o, a = nil)
+          column = if a then column_for(a) else last_column end
+          relation = if a then a.relation else last_relation end
+
+          return quote(o.to_s) unless column && relation
+
+          quote(bson_objectid_value_from_parameter(o, column, relation), column)
+        end
+
+        alias_method :visit_Moped_BSON_ObjectId, :visit_BSON_ObjectId
+
+        private
+        def bson_objectid_value_from_parameter(o, column, relation)
+          column_name = column.name
+
+          manager = ObjectidColumns::ObjectidColumnsManager.for_table(relation.name)
+          unless manager
+            raise %{ObjectidColumns: You're trying to evaluate a SQL statement (in Arel, probably via ActiveRecord)
+that contains a BSON ObjectId value -- you're trying to use the value '#{o}'
+(of class #{o.class.name}) with column #{column_name.inspect} of table
+#{relation.name.inspect}. However, we can't find any record of any ObjectId
+columns being declared for that table anywhere.
+
+As a result, we don't know whether this column should be treated as a binary or
+a hexadecimal ObjectId, and hence don't know how to transform this value properly.}
+          end
+
+          unless manager.is_objectid_column?(column_name)
+            raise %{ObjectidColumns: You're trying to evaluate a SQL statement (in Arel, probably via ActiveRecord)
+that contains a BSON ObjectId value -- you're trying to use the value '#{o}'
+(of class #{o.class.name}) with column #{column_name.inspect} of table
+#{relation.name.inspect}.
+
+While we can find a record of some ObjectId columns being declared for
+that table, they don't appear to include #{column_name.inspect}. As such,
+we don't know whether this column should be treated as a binary or a hexadecimal
+ObjectId, and hence don't know how to transform this value properly.}
+          end
+
+          manager.to_valid_value_for_column(column_name, o)
+        end
+      end
+    end
+  end
+end

data/lib/objectid_columns/dynamic_methods_module.rb

@@ -0,0 +1,127 @@
+module ObjectidColumns
+  # A DynamicMethodsModule is used to add dynamically-generated methods to an existing class.
+  #
+  # Why do we need a module to do that? Why can't we simply call #define_method on the class itself?
+  #
+  # We could. However, if you do that, a few problems crop up:
+  #
+  # * There is no precendence that you can control. If you define a method +:foo+ on class Bar, then that method is
+  #   always run when an instance of that class is sent the message +:foo+. The only way to change the behavior of
+  #   that class is to completely redefine that method, which brings us to the second problem...
+  # * Overriding and +super+ doesn't work. That is, you can't override such a method and call the original method
+  #   using +super+. You're reduced to using +alias_method_chain+, which is a mess.
+  # * There's no namespacing at all -- at runtime, it's not even remotely clear where these methods are coming from.
+  # * Finally, if you're living in a dynamic environment -- like Rails' development mode, where classes get reloaded
+  #   very frequently -- once you define a method, it is likely to be forever defined. You have to write code to keep
+  #   track of what you've defined, and remove it when it's no longer present.
+  #
+  # A DynamicMethodsModule fixes these problems. It's little more than a Module that lets you define methods (and
+  # helpfully makes #define_method +public+ to help), but it also will include itself into a target class and bind
+  # itself to a constant in that class (which magically gives the module a name, too). Further, it also keeps track
+  # of which methods you've defined, and can remove them all with #remove_all_methods!. This allows you to construct
+  # a much more reliable paradigm: instead of trying to figure out what methods you should remove and add when things
+  # change, you can just call #remove_all_methods! and then redefine whatever methods _currently_ should exist.
+  #
+  # A DynamicMethodsModule also supports class methods; if you define a method with #define_class_method, it will be
+  # added to a module that the target class has called +extend+ on (rather than +include+), and hence will show up as
+  # a class method on that class. This is useful for the exact same reasons as the base DynamicMethodsModule; it allows
+  # for precedence control, use of +super+, namespacing, and dynamism.
+  class DynamicMethodsModule < ::Module
+    # Creates a new instance. +target_class+ is the Class into which this module should include itself; +name+ is the
+    # name to which it should bind itself. (This will be bound as a constant inside that class, not at top-level on
+    # Object; so, for example, if +target_class+ is +User+ and +name+ is +Foo+, then this module will end up named
+    # +User::Foo+, not simply +Foo+.)
+    #
+    # If passed a block, the block will be evaluated in the context of this module, just like Module#new. Note that
+    # you <em>should not</em> use this to define methods that you want #remove_all_methods!, below, to remove; it
+    # won't work. Any methods you add in this block using normal +def+ will persist, even through #remove_all_methods!.
+    def initialize(target_class, name, &block)
+      raise ArgumentError, "Target class must be a Class, not: #{target_class.inspect}" unless target_class.kind_of?(Class)
+      raise ArgumentError, "Name must be a Symbol or String, not: #{name.inspect}" unless name.kind_of?(Symbol) || name.kind_of?(String)
+
+      @target_class = target_class
+      @name = name.to_sym
+
+      # Unfortunately, there appears to be no way to "un-include" a Module in Ruby -- so we have no way of replacing
+      # an existing DynamicMethodsModule on the target class, which is what we'd really like to do in this situation.
+
+      # Sigh. From the docs for Method#arity:
+      #
+      # "For Ruby methods that take a variable number of arguments, returns -n-1, where n is the number of required
+      # arguments. For methods written in C, returns -1 if the call takes a variable number of arguments."
+      #
+      # It turns out that .const_defined? is written in C, which means it returns -1 if it takes a variable number of
+      # arguments. So we can't check for arity.abs >= 2 here, but rather must look for <= -1...
+      if @target_class.method(:const_defined?).arity <= -1
+        if @target_class.const_defined?(@name, false)
+          existing = @target_class.const_get(@name, false)
+
+          if existing && existing != self
+            raise NameError, %{You tried to define a #{self.class.name} named #{name.inspect} on class #{target_class.name},
+  but that class already has a constant named #{name.inspect}: #{existing.inspect}}
+          end
+        end
+      else
+        # So...in Ruby 1.8.7, .const_defined? and .const_get don't accept the second parameter, which tells you whether
+        # to search superclass constants as well. But, amusingly, we're not only not stuck, this is fine: in Ruby
+        # 1.8.7, constant lookup doesn't search superclasses, either -- so we're OK.
+        if @target_class.const_defined?(@name)
+          existing = @target_class.const_get(@name)
+
+          if existing && existing != self
+            raise NameError, %{You tried to define a #{self.class.name} named #{name.inspect} on class #{target_class.name},
+  but that class already has a constant named #{name.inspect}: #{existing.inspect}}
+          end
+        end
+      end
+
+
+      @class_methods_module = Module.new
+      (class << @class_methods_module; self; end).send(:public, :private)
+      @target_class.const_set("#{@name}ClassMethods", @class_methods_module)
+      @target_class.send(:extend, @class_methods_module)
+
+      @target_class.const_set(@name, self)
+      @target_class.send(:include, self)
+
+      @methods_defined = { }
+      @class_methods_defined = { }
+
+      super(&block)
+    end
+
+    # Removes all methods that have been defined on this module using #define_method, below. (If you use some other
+    # mechanism to define a method on this DynamicMethodsModule, then it will not be removed when this method is
+    # called.)
+    def remove_all_methods!
+      instance_methods.each do |method_name|
+        # Important -- we use Class#remove_method, not Class#undef_method, which does something that's different in
+        # some important ways.
+        remove_method(method_name) if @methods_defined[method_name.to_sym]
+      end
+
+      @class_methods_module.instance_methods.each do |method_name|
+        @class_methods_module.send(:remove_method, method_name) if @class_methods_defined[method_name]
+      end
+    end
+
+    # Defines a method. Works identically to Module#define_method, except that it's +public+ and #remove_all_methods!
+    # will remove the method.
+    def define_method(name, &block)
+      name = name.to_sym
+      super(name, &block)
+      @methods_defined[name] = true
+    end
+
+    # Defines a class method.
+    def define_class_method(name, &block)
+      @class_methods_module.send(:define_method, name, &block)
+    end
+
+    # Makes it so you can say, for example:
+    #
+    #     my_dynamic_methods_module.define_method(:foo) { ... }
+    #     my_dynamic_methods_module.private(:foo)
+    public :private # teehee
+  end
+end

data/lib/objectid_columns/extensions.rb

@@ -0,0 +1,41 @@
+# This file adds very useful convenience methods to certain classes:
+
+# To each of the BSON classes, we add:
+#
+# * #to_binary, which returns a String containing a pure-binary (12-byte) representation of the ObjectId; and
+# * #to_bson_id, which simply returns +self+ -- this is so we can call this method on any object passed in where we're
+#   expecting an ObjectId, and, if you're already supplying an ObjectId object, it will just work.
+ObjectidColumns.available_objectid_columns_bson_classes.each do |klass|
+  klass.class_eval do
+    def to_binary
+      [ to_s ].pack("H*")
+    end
+
+    def to_bson_id
+      self
+    end
+  end
+end
+
+# To String, we add #to_bson_id. This method knows how to convert a String that is in either the hex or pure-binary
+# forms to an actual ObjectId object. Note that we use the method ObjectidColumns.construct_objectid to actually create
+# the object; this way, it will follow any preference for exactly what BSON class to use that's set there.
+#
+# If your String is in binary form, it must have its encoding set to Encoding::BINARY (which is aliased to
+# Encoding::ASCII_8BIT); if it's not in this encoding, it may well be coming from a source that doesn't support
+# transparent binary data (for example, UTF-8 doesn't -- certain byte combinations are illegal in UTF-8 and will cause
+# string manipulation to fail), which is a real problem.
+String.class_eval do
+  BSON_HEX_ID_REGEX = /^[0-9a-f]{24}$/i
+
+  def to_bson_id
+    if self =~ BSON_HEX_ID_REGEX
+      ObjectidColumns.construct_objectid(self)
+    elsif length == 12 && ((! respond_to?(:encoding)) || (encoding == Encoding::BINARY)) # :respond_to? is for Ruby 1.8.7 support
+      ObjectidColumns.construct_objectid(unpack("H*").first)
+    else
+      encoding_string = respond_to?(:encoding) ? ", in encoding #{encoding.inspect}" : ""
+      raise ArgumentError, "#{inspect} does not seem to be a valid BSON ID; it is in neither the valid hex (exactly 24 hex characters, any encoding) nor the valid binary (12 characters, binary/ASCII-8BIT encoding) form. It is #{length} characters long#{encoding_string}"
+    end
+  end
+end

data/lib/objectid_columns/has_objectid_columns.rb

@@ -0,0 +1,47 @@
+require 'active_support'
+require 'active_support/core_ext/object'
+require 'objectid_columns/objectid_columns_manager'
+
+module ObjectidColumns
+  # This module gets mixed into an ActiveRecord class when you say +has_objectid_column(s)+ or
+  # +has_objectid_primary_key+. It delegates everything it does to the ObjectidColumnsManager; we do it this way so
+  # that we can define all kinds of helper methods on the ObjectidColumnsManager without polluting the method
+  # namespace on the actual ActiveRecord class.
+  module HasObjectidColumns
+    extend ActiveSupport::Concern
+
+    # Reads the current value of the given +column_name+ (which must be an ObjectId column) as an ObjectId object.
+    def read_objectid_column(column_name)
+      self.class.objectid_columns_manager.read_objectid_column(self, column_name)
+    end
+
+    # Writes a new value to the given +column_name+ (which must be an ObjectId column), accepting a String (in either
+    # hex or binary formats) or an ObjectId object, and transforming it to whatever storage format is correct for
+    # that column.
+    def write_objectid_column(column_name, new_value)
+      self.class.objectid_columns_manager.write_objectid_column(self, column_name, new_value)
+    end
+
+    # Called as a +before_create+ hook, if (and only if) this class has declared +has_objectid_primary_key+ -- sets
+    # the primary key to a newly-generated ObjectId, unless it has one already.
+    def assign_objectid_primary_key
+      self.class.objectid_columns_manager.assign_objectid_primary_key(self)
+    end
+
+    module ClassMethods
+      # Does this class have any ObjectId columns? It does if this module has been included, since it only gets included
+      # if you declare an ObjectId column.
+      def has_objectid_columns?
+        true
+      end
+
+      # Delegate all of the interesting work to the ObjectidColumnsManager.
+      delegate :has_objectid_columns, :has_objectid_column, :has_objectid_primary_key,
+        :translate_objectid_query_pair, :to => :objectid_columns_manager
+
+      def objectid_columns_manager
+        @objectid_columns_manager ||= ::ObjectidColumns::ObjectidColumnsManager.new(self)
+      end
+    end
+  end
+end

data/lib/objectid_columns/objectid_columns_manager.rb

@@ -0,0 +1,451 @@
+require 'objectid_columns/dynamic_methods_module'
+
+module ObjectidColumns
+  # The ObjectidColumnsManager does all the real work of the ObjectidColumns gem, in many ways -- it takes care of
+  # reading ObjectId values and transforming them to objects, transforming supplied data to the right format when
+  # writing them, handling primary-key definitions and queries.
+  #
+  # This is a separate class, rather than being mixed into the actual ActiveRecord class, so that we can add methods
+  # and define constants here without polluting the namespace of the underlying class.
+  class ObjectidColumnsManager
+    # NOTE: These constants are used in a metaprogrammed fashion in #has_objectid_columns, below. If you rename them,
+    # you must change that, too.
+    BINARY_OBJECTID_LENGTH = 12
+    STRING_OBJECTID_LENGTH = 24
+
+    # Creates a new instance. There should only ever be a single instance for a given ActiveRecord class, accessible
+    # via ObjectidColumns::HasObjectidColumns.objectid_columns_manager.
+    def initialize(active_record_class)
+      raise ArgumentError, "You must supply a Class, not: #{active_record_class.inspect}" unless active_record_class.kind_of?(Class)
+      raise ArgumentError, "You must supply a Class that's a descendant of ActiveRecord::Base, not: #{active_record_class.inspect}" unless superclasses(active_record_class).include?(::ActiveRecord::Base)
+
+      @active_record_class = active_record_class
+      @oid_columns = { }
+
+      # We use a DynamicMethodsModule to add our magic to the target ActiveRecord class, rather than just defining
+      # methods directly on the class, for a number of very good reasons -- see the class comment on
+      # DynamicMethodsModule for more information.
+      @dynamic_methods_module = ObjectidColumns::DynamicMethodsModule.new(active_record_class, :ObjectidColumnsDynamicMethods)
+
+      self.class.register_for_table(active_record_class.table_name, self)
+    end
+
+    class << self
+      # ObjectidColumns::Arel::Visitors::ToSql needs to be able to figure out whether an ObjectId column is of binary
+      # or text format, in order to properly transform/quote the value it has. However, by the time the code gets there,
+      # we no longer have access to the ActiveRecord model at all. So, instead, we need an entry point to be able to
+      # find the ObjectidColumnsManager for a table by name. That's .for_table, below; this is the method called at
+      # the end of the constructor of every ObjectidColumnsManager, registering the instance by table name.
+      def register_for_table(table_name, instance)
+        @_registered_instances ||= { }
+        @_registered_instances[table_name] = instance
+      end
+
+      # See above. Given a table name, this returns the ObjectidColumnsManager for it, or +nil+ if none has been
+      # defined for that table.
+      def for_table(table_name)
+        @_registered_instances[table_name]
+      end
+    end
+
+    # This method basically says: does our +active_record_class+ have a primary key defined, for real? There are two
+    # reasons this is anything more than (<tt>!! active_record_class.primary_key</tt>):
+    #
+    # * In earlier versions of ActiveRecord (like 3.0.x), this will return +id+ even if you haven't set it and there is
+    #   no column named +id+.
+    # * The +composite_primary_keys+ gem can make this an array instead.
+    def activerecord_class_has_no_real_primary_key?
+      (! active_record_class.primary_key) ||
+        (active_record_class.primary_key == [ ]) ||
+        ( ([ [ 'id' ], [ :id ] ].include?(Array(active_record_class.primary_key))) &&
+          (! active_record_class.columns_hash.has_key?('id')) &&
+          (! active_record_class.columns_hash.has_key?(:id)))
+    end
+
+    # If you haven't specified a primary key on your model (using <tt>self.primary_key=</tt>), and you call
+    # +has_objectid_primary_key+, we want to tell the ActiveRecord model that that's the new primary key. This takes
+    # care of that, and handles the fact that this may be a composite primary key, too.
+    def set_primary_key_from!(primary_keys)
+      if primary_keys.length > 1
+        active_record_class.primary_key = primary_keys.map(&:to_s)
+      elsif primary_keys.length == 1
+        active_record_class.primary_key = primary_keys[0].to_s
+      else
+        # nothing here; we handle this elsewhere
+      end
+    end
+
+    # Assigns a new ObjectId primary key to a brand-new model that's about to be created, if needed. This handles
+    # composite primary keys correctly.
+    def assign_objectid_primary_key(model)
+      Array(model.class.primary_key).each do |pk_column|
+        if is_objectid_column?(pk_column) && model[pk_column].blank?
+          model.send("#{pk_column}=", ObjectidColumns.new_objectid)
+        end
+      end
+    end
+
+    # Given a model, returns the correct value for #id. This takes into account composite primary keys where some
+    # columns may be ObjectId columns and some may not.
+    def read_objectid_primary_key(model)
+      pks = Array(model.class.primary_key)
+      out = [ ]
+      pks.each do |pk_column|
+        out << if is_objectid_column?(pk_column)
+          read_objectid_column(model, pk_column)
+        else
+          model[pk_column]
+        end
+      end
+      out = out[0] if out.length == 1
+      out
+    end
+
+    # Given a model, stores a new value for #id. This takes into account composite primary keys where some
+    # columns may be ObjectId columns and some may not.
+    def write_objectid_primary_key(model, new_value)
+      pks = Array(model.class.primary_key)
+      if pks.length == 1
+        write_objectid_column(model, pks[0], new_value)
+      else
+        pks.each_with_index do |pk_column, index|
+          value = new_value[index]
+          if is_objectid_column?(pk_column)
+            write_objectid_column(model, pk_column, value)
+          else
+            model[pk_column] = value
+          end
+        end
+      end
+    end
+
+    # Implements .find or .find_by_id for classes that have a primary key that has at least one ObjectId column in it;
+    # this takes care of handling both normal primary keys and composite primary keys.
+    def find_or_find_by_id(*args)
+      primary_key = active_record_class.primary_key
+      pk_length = primary_key.kind_of?(Array) ? primary_key.length : 1
+
+      # If we just have a single primary key, we flatten any input, just because that's exactly what base
+      # ActiveRecord does...
+      if pk_length == 1
+        args = args.flatten
+        args = args.map { |x| to_valid_value_for_column(primary_key, x) if x }
+        yield(*args)
+      else
+        # composite_primary_keys, however, requires that you pass each key as a single, separate argument to .find or
+        # .find_by_id; we transform them here.
+        keys = args.map do |key|
+          new_key = [ ]
+          key.each_with_index do |key_component, index|
+            column = primary_key[index]
+            new_key << if is_objectid_column?(column)
+              to_valid_value_for_column(column, key_component) if key_component
+            else
+              key_component
+            end
+          end
+          new_key
+        end
+        yield(*keys)
+      end
+    end
+
+    # Declares that this class is using an ObjectId as its primary key. Ordinarily, this requires no arguments;
+    # however, if your primary key is not named +id+ and you have not yet told ActiveRecord this (using
+    # <tt>self.primary_key = :foo</tt>), then you must pass the name of the primary-key column.
+    #
+    # Note that, unlike normal database-generated primary keys, this will cause us to auto-generate an ObjectId
+    # primary key value for a new record just before saving it to the database (ActiveRecord's +before_create hook).
+    # ObjectIds are safe to generate client-side, and very difficult to properly generate server-side in a relational
+    # database. However, we will respect (and not overwrite) any primary key already assigned to the record before it's
+    # saved, so if you want to assign your own ObjectId primary keys, you can.
+    #
+    # This method handles composite primary keys, as provided by the +composite_primary_keys+ gem, correctly.
+    def has_objectid_primary_key(*primary_keys_that_are_objectid_columns)
+      return unless active_record_class.table_exists?
+
+      # First, normalize our set of primary keys that are ObjectId columns...
+      primary_keys_that_are_objectid_columns = primary_keys_that_are_objectid_columns.compact.map(&:to_s).uniq
+
+      # Now, see what all the primary keys are. If the user hasn't specified any primary keys on the class at all yet,
+      # but has told us what they are, then we need to tell ActiveRecord what they are.
+      all_primary_keys = if activerecord_class_has_no_real_primary_key?
+        set_primary_key_from!(primary_keys_that_are_objectid_columns)
+        primary_keys_that_are_objectid_columns
+      else
+        Array(active_record_class.primary_key)
+      end
+      # Normalize the set of all primary keys.
+      all_primary_keys = all_primary_keys.compact.map(&:to_s).uniq
+
+      # Let's make sure we have a primary key...
+      raise ArgumentError, "Class #{active_record_class.name} has no primary key set, and you haven't supplied one to #has_objectid_primary_key" if all_primary_keys.empty?
+
+      # If you didn't specify any ObjectId columns explicitly, use what we know about the class to figure out which
+      # ones you mean.
+      if primary_keys_that_are_objectid_columns.empty?
+        if all_primary_keys.length == 1
+          primary_keys_that_are_objectid_columns = all_primary_keys
+        else
+          primary_keys_that_are_objectid_columns = autodetect_columns_from(all_primary_keys, true)
+        end
+      end
+
+      # Make sure we have at least one ObjectId primary key, if we're in this method.
+      raise "Class #{active_record_class.name} has no columns in its primary key that qualify as object IDs automatically; you must specify their names explicitly." if primary_keys_that_are_objectid_columns.empty?
+
+      # Make sure all the columns the user named actually exist as columns on the model.
+      missing = primary_keys_that_are_objectid_columns.select { |c| ! active_record_class.columns_hash.has_key?(c) }
+      raise "The following primary-key column(s) do not appear to actually exist on #{active_record_class.name}: #{missing.inspect}; we have these columns: #{active_record_class.columns_hash.keys.inspect}" unless missing.empty?
+
+      # Declare our primary-key column as an ObjectId column.
+      has_objectid_column *primary_keys_that_are_objectid_columns
+
+      # Override #id and #id= to do the right thing...
+      dynamic_methods_module.define_method("id") do
+        self.class.objectid_columns_manager.read_objectid_primary_key(self)
+      end
+      dynamic_methods_module.define_method("id=") do |new_value|
+        self.class.objectid_columns_manager.write_objectid_primary_key(self, new_value)
+      end
+
+      # Allow us to autogenerate the primary key, if needed, on save.
+      active_record_class.send(:before_create, :assign_objectid_primary_key)
+
+      # Override a couple of methods that, if you're using an ObjectId column as your primary key, need overriding. ;)
+      [ :find, :find_by_id ].each do |class_method_name|
+        @dynamic_methods_module.define_class_method(class_method_name) do |*args, &block|
+          objectid_columns_manager.find_or_find_by_id(*args) { |*new_args| super(*new_args, &block) }
+        end
+      end
+    end
+
+    # Declares one or more columns as containing ObjectId values. After this call, they can be written using a String
+    # in hex or binary formats, or an ObjectId object; they will return ObjectId objects for values, and can be queried
+    # using any of the above (as long as you use the <tt>where(:foo_oid => ...)</tt> Hash-style syntax).
+    #
+    # If you don't pass in any column names, this will look for columns that end in +_oid+ and assume those are
+    # ObjectId columns.
+    def has_objectid_columns(*columns)
+      return unless active_record_class.table_exists?
+
+      # Autodetect columns ending in +_oid+ if needed
+      columns = autodetect_columns_from(active_record_class.columns_hash.keys) if columns.length == 0
+
+      columns = columns.map { |c| c.to_s.strip.downcase.to_sym }
+      columns.each do |column_name|
+        # Go fetch the column object from the ActiveRecord class, and make sure it's present and of the right type.
+        column_object = active_record_class.columns.detect { |c| c.name.to_s == column_name.to_s }
+
+        unless column_object
+          raise ArgumentError, "#{active_record_class.name} doesn't seem to have a column named #{column_name.inspect} that we could make an ObjectId column; did you misspell it? It has columns: #{active_record_class.columns.map(&:name).inspect}"
+        end
+
+        unless [ :string, :binary ].include?(column_object.type)
+          raise ArgumentError, "#{active_record_class.name} has a column named #{column_name.inspect}, but it is of type #{column_object.type.inspect}; we can only make ObjectId columns out of :string or :binary columns"
+        end
+
+        # Is the column long enough to contain the data we'll need to put in it?
+        required_length = self.class.const_get("#{column_object.type.to_s.upcase}_OBJECTID_LENGTH")
+        # The ||= is in case there's no limit on the column at all -- for example, PostgreSQL +bytea+ columns
+        # behave this way.
+        unless (column_object.limit || required_length + 1) >= required_length
+          raise ArgumentError, "#{active_record_class.name} has a column named #{column_name.inspect} of type #{column_object.type.inspect}, but it is of length #{column_object.limit}, which is too short to contain an ObjectId of this format; it must be of length at least #{required_length}"
+        end
+
+        # Define reader and writer methods that just call through to ObjectidColumns::HasObjectidColumns (which, in
+        # turn, just delegates the call back to this object -- the #read_objectid_column method below; the one on
+        # HasObjectidColumns just passes through the model object itself).
+        cn = column_name
+        dynamic_methods_module.define_method(column_name) do
+          read_objectid_column(cn)
+        end
+
+        dynamic_methods_module.define_method("#{column_name}=") do |x|
+          write_objectid_column(cn, x)
+        end
+
+        # Store away the fact that we've done this.
+        @oid_columns[column_name] = column_object.type
+      end
+    end
+
+    # Called from ObjectidColumns::HasObjectidColumns#read_objectid_column -- given a model and a column name (which
+    # must be an ObjectId column), returns the data in it, as an ObjectId.
+    def read_objectid_column(model, column_name)
+      column_name = column_name.to_s
+      value = model[column_name]
+      return value unless value # in case it's nil
+      return value if ObjectidColumns.is_valid_bson_object?(value) # we can get this when reading the 'id' pseudocolumn
+
+      # If it's not nil, the database should always be giving us back a String...
+      unless value.kind_of?(String)
+        raise "When trying to read the ObjectId column #{column_name.inspect} on #{active_record_class.name} ID=#{model.id.inspect}, we got the following data from the database; we expected a String: #{value.inspect}"
+      end
+
+      # ugh...ActiveRecord 3.1.x can return this in certain circumstances
+      return nil if value.length == 0
+
+      # In many databases, if you have a column that is, _e.g._, BINARY(16), and you only store twelve bytes in it,
+      # you get back all 16 anyway, with 0x00 bytes at the end. Converting this to an ObjectId will fail, so we make
+      # sure we chop those bytes off. (Note that while String#strip will, in fact, remove these bytes too, it is not
+      # safe: if the ObjectId itself ends in one or more 0x00 bytes, then these will get incorrectly removed.)
+      case type = objectid_column_type(column_name)
+      when :binary then value = value[0..(BINARY_OBJECTID_LENGTH - 1)]
+      when :string then value = value[0..(STRING_OBJECTID_LENGTH - 1)]
+      else unknown_type(type)
+      end
+
+      # +lib/objectid_columns/extensions.rb+ adds this method to String.
+      value.to_bson_id
+    end
+
+    # Called from ObjectidColumns::HasObjectidColumns#write_objectid_column -- given a model, a column name (which must
+    # be an ObjectId column) and a new value, stores that value in the column.
+    def write_objectid_column(model, column_name, new_value)
+      column_name = column_name.to_s
+      if (! new_value)
+        model[column_name] = new_value
+      elsif new_value.respond_to?(:to_bson_id)
+        model[column_name] = to_valid_value_for_column(column_name, new_value)
+      else
+        raise ArgumentError, "When trying to write the ObjectId column #{column_name.inspect} on #{inspect}, we were passed the following value, which doesn't seem to be a valid BSON ID in any format: #{new_value.inspect}"
+      end
+    end
+
+    alias_method :has_objectid_column, :has_objectid_columns
+
+    # Given a value for an ObjectId column -- could be a String in either hex or binary formats, or an
+    # ObjectId object -- returns a String of the correct type for the given column (_i.e._, either the binary or hex
+    # String representation of an ObjectId, depending on the type of the underlying column).
+    def to_valid_value_for_column(column_name, value)
+      out = value.to_bson_id
+      unless ObjectidColumns.is_valid_bson_object?(out)
+        raise "We called #to_bson_id on #{value.inspect}, but it returned this, which is not a BSON ID object: #{out.inspect}"
+      end
+
+      case objectid_column_type(column_name)
+      when :binary then out = out.to_binary
+      when :string then out = out.to_s
+      else unknown_type(type)
+      end
+
+      out
+    end
+
+    # Given a key in a Hash supplied to +where+ for the given ActiveRecord class, returns a two-element Array
+    # consisting of the key and the proper value we should actually use to query on that column. If the key does not
+    # represent an ObjectID column, then this will just be exactly the data passed in; however, if it does represent
+    # an ObjectId column, then the value will be translated to whichever String format (binary or hex) that column is
+    # using.
+    #
+    # We use this in ObjectidColumns:;ActiveRecord::Relation#where to make the following work properly:
+    #
+    #     MyModel.where(:foo_oid => BSON::ObjectId('52ec126d78161f56d8000001'))
+    #
+    # This method is used to translate this to:
+    #
+    #     MyModel.where(:foo_oid => "52ec126d78161f56d8000001")
+    def translate_objectid_query_pair(query_key, query_value)
+      if (type = net_oid_columns[query_key.to_sym])
+
+        # Handle nil, false
+        if (! query_value)
+          [ query_key, query_value ]
+
+        # +lib/objectid_columns/extensions.rb+ adds String#to_bson_id
+        elsif query_value.respond_to?(:to_bson_id)
+          v = query_value.to_bson_id
+          v = case type
+          when :binary then v.to_binary
+          when :string then v.to_s
+          else unknown_type(type)
+          end
+          [ query_key, v ]
+
+        # Handle arrays of values
+        elsif query_value.kind_of?(Array)
+          array = query_value.map do |v|
+            translate_objectid_query_pair(query_key, v)[1]
+          end
+          [ query_key, array ]
+
+        # Um...what did you pass?
+        else
+          raise ArgumentError, "You're trying to constrain #{active_record_class.name} on column #{query_key.inspect}, which is an ObjectId column, but the value you passed, #{query_value.inspect}, is not a valid format for an ObjectId."
+        end
+      else
+        [ query_key, query_value ]
+      end
+    end
+
+    # Given the name of a column, tell whether or not it is an ObjectId column.
+    def is_objectid_column?(column_name)
+      net_oid_columns.has_key?(column_name.to_sym)
+    end
+
+    # Returns the same thing as +oid_columns+, except merges in the ActiveRecord class's superclass's columns, if
+    # any.
+    def net_oid_columns
+      out = { }
+      if (socm = superclass_objectid_columns_manager)
+        out = socm.net_oid_columns
+      end
+      out.merge(oid_columns)
+    end
+
+    private
+    attr_reader :active_record_class, :dynamic_methods_module, :oid_columns
+
+    # Given the name of a column -- which must be an ObjectId column -- returns its type, either +:binary+ or
+    # +:string+.
+    def objectid_column_type(column_name)
+      out = net_oid_columns[column_name.to_sym]
+      raise "Something is horribly wrong; #{column_name.inspect} is not an ObjectId column -- we have: #{net_oid_columns.keys.inspect}" unless out
+      out
+    end
+
+    # If our +@active_record_class+ has a superclass that in turn is using +objectid_columns+, returns the
+    # ObjectidColumnsManager for that class, if any.
+    def superclass_objectid_columns_manager
+      ar_superclass = @active_record_class.superclass
+      ar_superclass.objectid_columns_manager if ar_superclass.respond_to?(:objectid_columns_manager)
+    end
+
+    # Raises an exception -- used for +case+ statements where we switch on the type of the column. Useful so that if,
+    # in the future, we support a new column type, we won't forget to add a case for it in various places.
+    def unknown_type(type)
+      raise "Bug in ObjectidColumns in this method -- type #{type.inspect} does not have a case here."
+    end
+
+    # What's the entire superclass chain of the given class? Used in the constructor to make sure something is
+    # actually a descendant of ActiveRecord::Base.
+    def superclasses(klass)
+      out = [ ]
+      while (sc = klass.superclass)
+        out << sc
+        klass = sc
+      end
+      out
+    end
+
+    # If someone called +has_objectid_columns+ but didn't pass an argument, this method detects which columns we should
+    # automatically turn into ObjectId columns -- which means any columns ending in +_oid+, except for the primary key.
+    def autodetect_columns_from(column_names, allow_primary_key = false)
+      column_names = column_names.map(&:to_s)
+      out = column_names.select do |column_name|
+        column = active_record_class.columns_hash[column_name]
+        column && column.name =~ /_oid$/i
+      end
+
+      # Make sure we never, ever automatically make the primary-key column an ObjectId column.
+      out -= Array(active_record_class.primary_key).compact.map(&:to_s) unless allow_primary_key
+
+      unless out.length > 0
+        raise ArgumentError, "You didn't pass in the names of any ObjectId columns, and we couldn't find any columns ending in _oid to pick up automatically (primary key is always excluded). Either name some columns explicitly, or remove the has_objectid_columns call. We found columns named: #{column_names.inspect}"
+      end
+
+      out
+    end
+  end
+end