mongo 0.1.0 → 0.15

data/lib/mongo/connection.rb

@@ -0,0 +1,151 @@
+# --
+# Copyright (C) 2008-2009 10gen Inc.
+#
+# 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.
+# ++
+
+require 'mongo/db'
+
+module Mongo
+
+  # A connection to MongoDB.
+  class Connection
+
+    DEFAULT_PORT = 27017
+
+    # Create a Mongo database server instance. You specify either one or a
+    # pair of servers. If one, you also say if connecting to a slave is
+    # OK. In either case, the host default is "localhost" and port default
+    # is DEFAULT_PORT.
+    #
+    # If you specify a pair, pair_or_host is a hash with two keys :left
+    # and :right. Each key maps to either
+    # * a server name, in which case port is DEFAULT_PORT
+    # * a port number, in which case server is "localhost"
+    # * an array containing a server name and a port number in that order
+    #
+    # +options+ are passed on to each DB instance:
+    #
+    # :slave_ok :: Only used if one host is specified. If false, when
+    #              connecting to that host/port a DB object will check to
+    #              see if the server is the master. If it is not, an error
+    #              is thrown.
+    #
+    # :auto_reconnect :: If a DB connection gets closed (for example, we
+    #                    have a server pair and saw the "not master"
+    #                    error, which closes the connection), then
+    #                    automatically try to reconnect to the master or
+    #                    to the single server we have been given. Defaults
+    #                    to +false+.
+    # :logger :: Optional Logger instance to which driver usage information
+    #            will be logged.
+    #
+    # Since that's so confusing, here are a few examples:
+    #
+    #  Connection.new                         # localhost, DEFAULT_PORT, !slave
+    #  Connection.new("localhost")            # localhost, DEFAULT_PORT, !slave
+    #  Connection.new("localhost", 3000)      # localhost, 3000, slave not ok
+    #  # localhost, 3000, slave ok
+    #  Connection.new("localhost", 3000, :slave_ok => true)
+    #  # localhost, DEFAULT_PORT, auto reconnect
+    #  Connection.new(nil, nil, :auto_reconnect => true)
+    #
+    #  # A pair of servers. DB will always talk to the master. On socket
+    #  # error or "not master" error, we will auto-reconnect to the
+    #  # current master.
+    #  Connection.new({:left  => ["db1.example.com", 3000],
+    #             :right => "db2.example.com"}, # DEFAULT_PORT
+    #            nil, :auto_reconnect => true)
+    #
+    #  # Here, :right is localhost/DEFAULT_PORT. No auto-reconnect.
+    #  Connection.new({:left => ["db1.example.com", 3000]})
+    #
+    # When a DB object first connects to a pair, it will find the master
+    # instance and connect to that one.
+    def initialize(pair_or_host=nil, port=nil, options={})
+      @pair = case pair_or_host
+               when String
+                 [[pair_or_host, port ? port.to_i : DEFAULT_PORT]]
+               when Hash
+                connections = []
+                connections << pair_val_to_connection(pair_or_host[:left])
+                connections << pair_val_to_connection(pair_or_host[:right])
+                connections
+               when nil
+                 [['localhost', DEFAULT_PORT]]
+               end
+
+      @options = options
+    end
+
+    # Return the Mongo::DB named +db_name+. The slave_ok and
+    # auto_reconnect options passed in via #new may be overridden here.
+    # See DB#new for other options you can pass in.
+    def db(db_name, options={})
+      DB.new(db_name, @pair, @options.merge(options))
+    end
+
+    # Returns a hash containing database names as keys and disk space for
+    # each as values.
+    def database_info
+      doc = single_db_command('admin', :listDatabases => 1)
+      h = {}
+      doc['databases'].each { |db|
+        h[db['name']] = db['sizeOnDisk'].to_i
+      }
+      h
+    end
+
+    # Returns an array of database names.
+    def database_names
+      database_info.keys
+    end
+
+    # Drops the database +name+.
+    def drop_database(name)
+      single_db_command(name, :dropDatabase => 1)
+    end
+
+    protected
+
+    # Turns an array containing a host name string and a
+    # port number integer into a [host, port] pair array.
+    def pair_val_to_connection(a)
+      case a
+      when nil
+        ['localhost', DEFAULT_PORT]
+      when String
+        [a, DEFAULT_PORT]
+      when Integer
+        ['localhost', a]
+      when Array
+        a
+      end
+    end
+
+    # Send cmd (a hash, possibly ordered) to the admin database and return
+    # the answer. Raises an error unless the return is "ok" (DB#ok?
+    # returns +true+).
+    def single_db_command(db_name, cmd)
+      db = nil
+      begin
+        db = db(db_name)
+        doc = db.db_command(cmd)
+        raise "error retrieving database info: #{doc.inspect}" unless db.ok?(doc)
+        doc
+      ensure
+        db.close if db
+      end
+    end
+  end
+end

data/lib/mongo/cursor.rb

@@ -1,229 +1,284 @@
-# --
 # Copyright (C) 2008-2009 10gen Inc.
 #
-# This program is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Affero General Public License, version 3, as
-# published by the Free Software Foundation.
+# 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
 #
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
-# for more details.
+#     http://www.apache.org/licenses/LICENSE-2.0
 #
-# You should have received a copy of the GNU Affero General Public License
-# along with this program. If not, see <http://www.gnu.org/licenses/>.
-# ++
+# 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.
 
 require 'mongo/message'
 require 'mongo/util/byte_buffer'
 require 'mongo/util/bson'
 
-module XGen
-  module Mongo
-    module Driver
-
-      # A cursor over query results. Returned objects are hashes.
-      class Cursor
-
-        include Enumerable
-
-        RESPONSE_HEADER_SIZE = 20
-
-        attr_reader :db, :collection, :query
-
-        def initialize(db, collection, query)
-          @db, @collection, @query = db, collection, query
-          @num_to_return = @query.number_to_return || 0
-          @cache = []
-          @closed = false
-          @can_call_to_a = true
-          @query_run = false
-        end
-
-        def closed?; @closed; end
-
-        # Set hint fields to use and return +self+. hint_fields may be a
-        # single field name, array of field names, or a hash whose keys will
-        # become the hint field names. May be +nil+. If no hint fields are
-        # specified, the ones in the collection are used if they exist.
-        def hint(hint_fields)
-          @hint_fields = case hint_fields
-                         when String
-                           [hint_fields]
-                         when Hash
-                           hint_fields.keys
-                         when nil
-                           nil
-                         else
-                           hint_fields.to_a
-                         end
-          self
-        end
-
-        # Return +true+ if there are more records to retrieve. We do not check
-        # @num_to_return; #each is responsible for doing that.
-        def more?
-          num_remaining > 0
-        end
-
-        # Return the next object. Raises an error if necessary.
-        def next_object
-          refill_via_get_more if num_remaining == 0
-          o = @cache.shift
-          raise o['$err'] if o && o['$err']
-          o
-        end
-
-        # Iterate over each object, yielding it to the given block. At most
-        # @num_to_return records are returned (or all of them, if
-        # @num_to_return is 0).
-        #
-        # If #to_a has already been called then this method uses the array
-        # that we store internally. In that case, #each can be called multiple
-        # times because it re-uses that array.
-        #
-        # You can call #each after calling #to_a (multiple times even, because
-        # it will use the internally-stored array), but you can't call #to_a
-        # after calling #each unless you also called it before calling #each.
-        # If you try to do that, an error will be raised.
-        def each
-          if @rows              # Already turned into an array
-            @rows.each { |row| yield row }
-          else
-            num_returned = 0
-            while more? && (@num_to_return <= 0 || num_returned < @num_to_return)
-              yield next_object()
-              num_returned += 1
-            end
-            @can_call_to_a = false
-          end
-        end
-
-        # Return all of the rows (up to the +num_to_return+ value specified in
-        # #new) as an array. Calling this multiple times will work fine; it
-        # always returns the same array.
-        #
-        # Don't use this if you're expecting large amounts of data, of course.
-        # All of the returned rows are kept in an array stored in this object
-        # so it can be reused.
-        #
-        # You can call #each after calling #to_a (multiple times even, because
-        # it will use the internally-stored array), but you can't call #to_a
-        # after calling #each unless you also called it before calling #each.
-        # If you try to do that, an error will be raised.
-        def to_a
-          return @rows if @rows
-          raise "can't call Cursor#to_a after calling Cursor#each" unless @can_call_to_a
-          @rows = []
-          num_returned = 0
-          while more? && (@num_to_return <= 0 || num_returned < @num_to_return)
-            @rows << next_object()
-            num_returned += 1
-          end
-          @rows
-        end
-
-        # Returns an explain plan record.
-        def explain
-          old_val = @query.explain
-          @query.explain = true
-
-          c = Cursor.new(@db, @collection, @query)
-          explanation = c.next_object
-          c.close
-
-          @query.explain = old_val
-          explanation
-        end
-
-        # Close the cursor.
-        def close
-          @db.send_to_db(KillCursorsMessage.new(@cursor_id)) if @cursor_id
-          @cache = []
-          @cursor_id = 0
-          @closed = true
-        end
-
-        protected
-
-        def read_all
-          read_message_header
-          read_response_header
-          read_objects_off_wire
-        end
-
-        def read_objects_off_wire
-          while doc = next_object_on_wire
-            @cache << doc
-          end
-        end
-
-        def read_message_header
-          MessageHeader.new.read_header(@db.socket)
-        end
-
-        def read_response_header
-          header_buf = ByteBuffer.new
-          header_buf.put_array(@db.socket.recv(RESPONSE_HEADER_SIZE).unpack("C*"))
-          raise "Short read for DB response header; expected #{RESPONSE_HEADER_SIZE} bytes, saw #{header_buf.length}" unless header_buf.length == RESPONSE_HEADER_SIZE
-          header_buf.rewind
-          @result_flags = header_buf.get_int
-          @cursor_id = header_buf.get_long
-          @starting_from = header_buf.get_int
-          @n_returned = header_buf.get_int
-          @n_remaining = @n_returned
-        end
-
-        def num_remaining
-          refill_via_get_more if @cache.length == 0
-          @cache.length
-        end
-
-        private
-
-        def next_object_on_wire
-          send_query_if_needed
-          # if @n_remaining is 0 but we have a non-zero cursor, there are more
-          # to fetch, so do a GetMore operation, but don't do it here - do it
-          # when someone pulls an object out of the cache and it's empty
-          return nil if @n_remaining == 0
-          object_from_stream
-        end
-
-        def refill_via_get_more
-          send_query_if_needed
-          return if @cursor_id == 0
-          @db.send_to_db(GetMoreMessage.new(@db.name, @collection.name, @cursor_id))
+module Mongo
+
+  # A cursor over query results. Returned objects are hashes.
+  class Cursor
+
+    include Enumerable
+
+    RESPONSE_HEADER_SIZE = 20
+
+    attr_reader :db, :collection, :query
+
+    # Create a new cursor.
+    #
+    # Should not be called directly by application developers.
+    def initialize(db, collection, query, admin=false)
+      @db, @collection, @query, @admin = db, collection, query, admin
+      @cache = []
+      @closed = false
+      @query_run = false
+    end
+
+    # Return the next object or nil if there are no more. Raises an error
+    # if necessary.
+    def next_object
+      refill_via_get_more if num_remaining == 0
+      o = @cache.shift
+
+      if o && o['$err']
+        err = o['$err']
+
+        # If the server has stopped being the master (e.g., it's one of a
+        # pair but it has died or something like that) then we close that
+        # connection. If the db has auto connect option and a pair of
+        # servers, next request will re-open on master server.
+        @db.close if err == "not master"
+
+        raise err
+      end
+
+      o
+    end
+
+    # Get the size of the results set for this query.
+    #
+    # Returns the number of objects in the results set for this query. Does
+    # not take limit and skip into account. Raises OperationFailure on a
+    # database error.
+    def count
+      command = OrderedHash["count", @collection.name,
+                            "query", @query.selector,
+                            "fields", @query.fields()]
+      response = @db.db_command(command)
+      return response['n'].to_i if response['ok'] == 1
+      return 0 if response['errmsg'] == "ns missing"
+      raise OperationFailure, "Count failed: #{response['errmsg']}"
+    end
+
+    # Sort this cursor's result
+    #
+    # Takes either a hash of field names as keys and 1/-1 as values; 1 ==
+    # ascending, -1 == descending, or array of field names (all assumed to be
+    # sorted in ascending order).
+    #
+    # Raises InvalidOperation if this cursor has already been used.
+    #
+    # This method overrides any sort order specified in the Collection#find
+    # method, and only the last sort applied has an effect
+    def sort(order)
+      check_modifiable
+      @query.order_by = order
+      self
+    end
+
+    # Limits the number of results to be returned by this cursor.
+    #
+    # Raises InvalidOperation if this cursor has already been used.
+    #
+    # This method overrides any limit specified in the Collection#find method,
+    # and only the last limit applied has an effect.
+    def limit(number_to_return)
+      check_modifiable
+      raise ArgumentError, "limit requires an integer" unless number_to_return.is_a? Integer
+
+      @query.number_to_return = number_to_return
+      self
+    end
+
+    # Skips the first +number_to_skip+ results of this cursor.
+    #
+    # Raises InvalidOperation if this cursor has already been used.
+    #
+    # This method overrides any skip specified in the Collection#find method,
+    # and only the last skip applied has an effect.
+    def skip(number_to_skip)
+      check_modifiable
+      raise ArgumentError, "skip requires an integer" unless number_to_skip.is_a? Integer
+
+      @query.number_to_skip = number_to_skip
+      self
+    end
+
+    # Iterate over each document in this cursor, yielding it to the given
+    # block.
+    #
+    # Iterating over an entire cursor will close it.
+    def each
+      num_returned = 0
+      while more? && (@query.number_to_return <= 0 || num_returned < @query.number_to_return)
+        yield next_object()
+        num_returned += 1
+      end
+    end
+
+    # Return all of the documents in this cursor as an array of hashes.
+    #
+    # Raises InvalidOperation if this cursor has already been used (including
+    # any previous calls to this method).
+    #
+    # Use of this method is discouraged - iterating over a cursor is much
+    # more efficient in most cases.
+    def to_a
+      raise InvalidOperation, "can't call Cursor#to_a on a used cursor" if @query_run
+      rows = []
+      num_returned = 0
+      while more? && (@query.number_to_return <= 0 || num_returned < @query.number_to_return)
+        rows << next_object()
+        num_returned += 1
+      end
+      rows
+    end
+
+    # Returns an explain plan record for this cursor.
+    def explain
+      limit = @query.number_to_return
+      @query.explain = true
+      @query.number_to_return = -limit.abs
+
+      c = Cursor.new(@db, @collection, @query)
+      explanation = c.next_object
+      c.close
+
+      @query.explain = false
+      @query.number_to_return = limit
+      explanation
+    end
+
+    # Close the cursor.
+    #
+    # Note: if a cursor is read until exhausted (read until OP_QUERY or
+    # OP_GETMORE returns zero for the cursor id), there is no need to
+    # close it by calling this method.
+    #
+    # Collection#find takes an optional block argument which can be used to
+    # ensure that your cursors get closed. See the documentation for
+    # Collection#find for details.
+    def close
+      @db.send_to_db(KillCursorsMessage.new(@cursor_id)) if @cursor_id
+      @cursor_id = 0
+      @closed = true
+    end
+
+    # Returns true if this cursor is closed, false otherwise.
+    def closed?; @closed; end
+
+    private
+
+    def read_all
+      read_message_header
+      read_response_header
+      read_objects_off_wire
+    end
+
+    def read_objects_off_wire
+      while doc = next_object_on_wire
+        @cache << doc
+      end
+    end
+
+    def read_message_header
+      MessageHeader.new.read_header(@db)
+    end
+
+    def read_response_header
+      header_buf = ByteBuffer.new
+      header_buf.put_array(@db.receive_full(RESPONSE_HEADER_SIZE).unpack("C*"))
+      raise "Short read for DB response header; expected #{RESPONSE_HEADER_SIZE} bytes, saw #{header_buf.length}" unless header_buf.length == RESPONSE_HEADER_SIZE
+      header_buf.rewind
+      @result_flags = header_buf.get_int
+      @cursor_id = header_buf.get_long
+      @starting_from = header_buf.get_int
+      @n_remaining = header_buf.get_int
+      if @n_received
+        @n_received += @n_remaining
+      else
+        @n_received = @n_remaining
+      end
+      if @query.number_to_return > 0 and @n_received >= @query.number_to_return
+        close()
+      end
+    end
+
+    def num_remaining
+      refill_via_get_more if @cache.length == 0
+      @cache.length
+    end
+
+    # Internal method, not for general use. Return +true+ if there are
+    # more records to retrieve. We do not check @query.number_to_return;
+    # #each is responsible for doing that.
+    def more?
+      num_remaining > 0
+    end
+
+    def next_object_on_wire
+      # if @n_remaining is 0 but we have a non-zero cursor, there are more
+      # to fetch, so do a GetMore operation, but don't do it here - do it
+      # when someone pulls an object out of the cache and it's empty
+      return nil if @n_remaining == 0
+      object_from_stream
+    end
+
+    def refill_via_get_more
+      if send_query_if_needed or @cursor_id == 0
+        return
+      end
+      @db._synchronize {
+        @db.send_to_db(GetMoreMessage.new(@admin ? 'admin' : @db.name, @collection.name, @cursor_id))
+        read_all
+      }
+    end
+
+    def object_from_stream
+      buf = ByteBuffer.new
+      buf.put_array(@db.receive_full(4).unpack("C*"))
+      buf.rewind
+      size = buf.get_int
+      buf.put_array(@db.receive_full(size - 4).unpack("C*"), 4)
+      @n_remaining -= 1
+      buf.rewind
+      BSON.new.deserialize(buf)
+    end
+
+    def send_query_if_needed
+      # Run query first time we request an object from the wire
+      if @query_run
+        false
+      else
+        @db._synchronize {
+          @db.send_query_message(QueryMessage.new(@admin ? 'admin' : @db.name, @collection.name, @query))
+          @query_run = true
           read_all
-        end
-
-        def object_from_stream
-          buf = ByteBuffer.new
-          buf.put_array(@db.socket.recv(4).unpack("C*"))
-          buf.rewind
-          size = buf.get_int
-          buf.put_array(@db.socket.recv(size-4).unpack("C*"), 4)
-          @n_remaining -= 1
-          buf.rewind
-          BSON.new(@db).deserialize(buf)
-        end
-
-        def send_query_if_needed
-          # Run query first time we request an object from the wire
-          unless @query_run
-            hints = @hint_fields || @collection.hint_fields
-            old_hints = @query.hint_fields
-            @query.hint_fields = hints
-            @db.send_query_message(QueryMessage.new(@db.name, @collection.name, @query))
-            @query_run = true
-            @query.hint_fields = old_hints
-            read_all
-          end
-        end
-
-        def to_s
-          "DBResponse(flags=#@result_flags, cursor_id=#@cursor_id, start=#@starting_from, n_returned=#@n_returned)"
-        end
+        }
+        true
+      end
+    end
+
+    def to_s
+      "DBResponse(flags=#@result_flags, cursor_id=#@cursor_id, start=#@starting_from)"
+    end
+
+    def check_modifiable
+      if @query_run || @closed
+        raise InvalidOperation, "Cannot modify the query once it has been run or closed."
       end
     end
   end