mongo 1.12.5 → 2.0.0

data/lib/mongo/event/server_added.rb

@@ -0,0 +1,53 @@
+
+# Copyright (C) 2014-2015 MongoDB, 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.
+
+module Mongo
+  module Event
+
+    # This handles host added events for server descriptions.
+    #
+    # @since 2.0.0
+    class ServerAdded
+
+      # @return [ Mongo::Cluster ] cluster The event publisher.
+      attr_reader :cluster
+
+      # Initialize the new host added event handler.
+      #
+      # @example Create the new handler.
+      #   ServerAdded.new(cluster)
+      #
+      # @param [ Mongo::Cluster ] cluster The cluster to publish from.
+      #
+      # @since 2.0.0
+      def initialize(cluster)
+        @cluster = cluster
+      end
+
+      # This event publishes an event to add the cluster and logs the
+      # configuration change.
+      #
+      # @example Handle the event.
+      #   server_added.handle('127.0.0.1:27018')
+      #
+      # @param [ Address ] address The added host.
+      #
+      # @since 2.0.0
+      def handle(address)
+        cluster.add(address)
+      end
+    end
+  end
+end

data/lib/mongo/event/server_removed.rb

@@ -0,0 +1,53 @@
+# Copyright (C) 2014-2015 MongoDB, 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.
+
+module Mongo
+  module Event
+
+    # This handles host removed events for server descriptions.
+    #
+    # @since 2.0.0
+    class ServerRemoved
+      include Loggable
+
+      # @return [ Mongo::Cluster ] cluster The event publisher.
+      attr_reader :cluster
+
+      # Initialize the new host removed event handler.
+      #
+      # @example Create the new handler.
+      #   ServerRemoved.new(cluster)
+      #
+      # @param [ Mongo::Cluster ] cluster The cluster to publish from.
+      #
+      # @since 2.0.0
+      def initialize(cluster)
+        @cluster = cluster
+      end
+
+      # This event publishes an event to remove from the cluster and logs the
+      # configuration change.
+      #
+      # @example Handle the event.
+      #   server_removed.handle('127.0.0.1:27018')
+      #
+      # @param [ Address ] address The removed host.
+      #
+      # @since 2.0.0
+      def handle(address)
+        cluster.remove(address)
+      end
+    end
+  end
+end

data/lib/mongo/event/subscriber.rb

@@ -0,0 +1,41 @@
+# Copyright (C) 2014-2015 MongoDB, 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.
+
+module Mongo
+  module Event
+
+    # Adds convenience methods for adding listeners to event publishers.
+    #
+    # @since 2.0.0
+    module Subscriber
+
+      # @return [ Event::Listeners ] event_listeners The listeners.
+      attr_reader :event_listeners
+
+      # Subscribe to the provided event.
+      #
+      # @example Subscribe to the event.
+      #   subscriber.subscribe_to('test', listener)
+      #
+      # @param [ String ] event The event.
+      # @param [ Object ] listener The event listener.
+      #
+      # @since 2.0.0
+      def subscribe_to(event, listener)
+        event_listeners.add_listener(event, listener)
+      end
+    end
+  end
+end
+

data/lib/mongo/event.rb

@@ -0,0 +1,40 @@
+# Copyright (C) 2014-2015 MongoDB, 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/event/listeners'
+require 'mongo/event/publisher'
+require 'mongo/event/subscriber'
+require 'mongo/event/primary_elected'
+require 'mongo/event/server_added'
+require 'mongo/event/server_removed'
+
+module Mongo
+  module Event
+
+    # When a server is elected primary.
+    #
+    # @since 2.0.0
+    PRIMARY_ELECTED = 'primary_elected'.freeze
+
+    # When a server is to be added to a cluster.
+    #
+    # @since 2.0.0
+    SERVER_ADDED = 'server_added'.freeze
+
+    # When a server is to be removed from a cluster.
+    #
+    # @since 2.0.0
+    SERVER_REMOVED = 'server_removed'.freeze
+  end
+end

data/lib/mongo/grid/file/chunk.rb

@@ -0,0 +1,184 @@
+# Copyright (C) 2014-2015 MongoDB, 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.
+
+module Mongo
+  module Grid
+    class File
+
+      # Encapsulates behaviour around GridFS chunks of file data.
+      #
+      # @since 2.0.0
+      class Chunk
+
+        # Name of the chunks collection.
+        #
+        # @since 2.0.0
+        COLLECTION = 'chunks'.freeze
+
+        # Default size for chunks of data.
+        #
+        # @since 2.0.0
+        DEFAULT_SIZE = (255 * 1024).freeze
+
+        # @return [ BSON::Document ] document The document to store for the
+        #   chunk.
+        attr_reader :document
+
+        # Check chunk equality.
+        #
+        # @example Check chunk equality.
+        #   chunk == other
+        #
+        # @param [ Object ] other The object ot compare to.
+        #
+        # @return [ true, false ] If the objects are equal.
+        #
+        # @since 2.0.0
+        def ==(other)
+          return false unless other.is_a?(Chunk)
+          document == other.document
+        end
+
+        # Get the BSON type for a chunk document.
+        #
+        # @example Get the BSON type.
+        #   chunk.bson_type
+        #
+        # @return [ Integer ] The BSON type.
+        #
+        # @since 2.0.0
+        def bson_type
+          BSON::Hash::BSON_TYPE
+        end
+
+        # Get the chunk data.
+        #
+        # @example Get the chunk data.
+        #   chunk.data
+        #
+        # @return [ BSON::Binary ] The chunk data.
+        #
+        # @since 2.0.0
+        def data
+          document[:data]
+        end
+
+        # Get the chunk id.
+        #
+        # @example Get the chunk id.
+        #   chunk.id
+        #
+        # @return [ BSON::ObjectId ] The chunk id.
+        #
+        # @since 2.0.0
+        def id
+          document[:_id]
+        end
+
+        # Get the files id.
+        #
+        # @example Get the files id.
+        #   chunk.files_id
+        #
+        # @return [ BSON::ObjectId ] The files id.
+        #
+        # @since 2.0.0
+        def files_id
+          document[:files_id]
+        end
+
+        # Get the chunk position.
+        #
+        # @example Get the chunk position.
+        #   chunk.n
+        #
+        # @return [ Integer ] The chunk position.
+        #
+        # @since 2.0.0
+        def n
+          document[:n]
+        end
+
+        # Create the new chunk.
+        #
+        # @example Create the chunk.
+        #   Chunk.new(document)
+        #
+        # @param [ BSON::Document ] document The document to create the chunk
+        #   from.
+        #
+        # @since 2.0.0
+        def initialize(document)
+          @document = BSON::Document.new(:_id => BSON::ObjectId.new).merge(document)
+        end
+
+        # Conver the chunk to BSON for storage.
+        #
+        # @example Convert the chunk to BSON.
+        #   chunk.to_bson
+        #
+        # @param [ String ] encoded The encoded data to append to.
+        #
+        # @return [ String ] The raw BSON data.
+        #
+        # @since 2.0.0
+        def to_bson(encoded = ''.force_encoding(BSON::BINARY))
+          document.to_bson(encoded)
+        end
+
+        class << self
+
+          # Takes an array of chunks and assembles them back into the full
+          # piece of raw data.
+          #
+          # @example Assemble the chunks.
+          #   Chunk.assemble(chunks)
+          #
+          # @param [ Array<Chunk> ] chunks The chunks.
+          #
+          # @return [ String ] The assembled data.
+          #
+          # @since 2.0.0
+          def assemble(chunks)
+            chunks.reduce(''){ |data, chunk| data << chunk.data.data }
+          end
+
+          # Split the provided data into multiple chunks.
+          #
+          # @example Split the data into chunks.
+          #   Chunks.split(data)
+          #
+          # @param [ String ] data The raw bytes.
+          # @param [ Metadata ] metadata The file metadata.
+          #
+          # @return [ Array<Chunk> ] The chunks of the data.
+          #
+          # @since 2.0.0
+          def split(data, metadata)
+            chunks, index, n = [], 0, 0
+            while index < data.length
+              bytes = data.slice(index, metadata.chunk_size)
+              metadata.md5.update(bytes)
+              chunk = Chunk.new(:data => BSON::Binary.new(bytes), :files_id => metadata.id, :n => n)
+              chunks.push(chunk)
+              index += bytes.length
+              n += 1
+            end
+            chunks
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/grid/file/metadata.rb

@@ -0,0 +1,229 @@
+# Copyright (C) 2014-2015 MongoDB, 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.
+
+module Mongo
+  module Grid
+    class File
+
+      # Encapsulates behaviour around GridFS file metadata.
+      #
+      # @since 2.0.0
+      class Metadata
+
+        # Name of the files collection.
+        #
+        # @since 2.0.0
+        COLLECTION = 'files'.freeze
+
+        # Mappings of user supplied fields to db specification.
+        #
+        # @since 2.0.0
+        MAPPINGS = {
+          :chunk_size => :chunkSize,
+          :content_type => :contentType,
+          :filename => :filename,
+          :_id => :_id,
+          :md5 => :md5,
+          :metadata => :metadata,
+          :upload_date => :uploadDate
+        }.freeze
+
+        # Default content type for stored files.
+        #
+        # @since 2.0.0
+        DEFAULT_CONTENT_TYPE = 'binary/octet-stream'.freeze
+
+        # @return [ BSON::Document ] document The file metadata document.
+        attr_reader :document
+
+        # Is this metadata equal to another?
+        #
+        # @example Check metadata equality.
+        #   metadata == other
+        #
+        # @param [ Object ] other The object to check against.
+        #
+        # @return [ true, false ] If the objects are equal.
+        #
+        # @since 2.0.0
+        def ==(other)
+          return false unless other.is_a?(Metadata)
+          document == other.document
+        end
+
+        # Get the BSON type for a metadata document.
+        #
+        # @example Get the BSON type.
+        #   metadata.bson_type
+        #
+        # @return [ Integer ] The BSON type.
+        #
+        # @since 2.0.0
+        def bson_type
+          BSON::Hash::BSON_TYPE
+        end
+
+        # Get the metadata chunk size.
+        #
+        # @example Get the chunk size.
+        #   metadata.chunk_size
+        #
+        # @return [ Integer ] The chunksize in bytes.
+        #
+        # @since 2.0.0
+        def chunk_size
+          document[:chunkSize]
+        end
+
+        # Get the metadata content type.
+        #
+        # @example Get the content type.
+        #   metadata.content_type
+        #
+        # @return [ String ] The content type.
+        #
+        # @since 2.0.0
+        def content_type
+          document[:contentType]
+        end
+
+        # Get the metadata filename.
+        #
+        # @example Get the filename.
+        #   metadata.filename
+        #
+        # @return [ String ] The filename.
+        def filename
+          document[:filename]
+        end
+
+        # Get the metadata id.
+        #
+        # @example Get the metadata id.
+        #   metadata.id
+        #
+        # @return [ BSON::ObjectId ] The metadata id.
+        #
+        # @since 2.0.0
+        def id
+          document[:_id]
+        end
+
+        # Create the new metadata document.
+        #
+        # @example Create the new metadata document.
+        #   Metadata.new(:filename => 'test.txt')
+        #
+        # @param [ BSON::Document ] document The document to create from.
+        #
+        # @since 2.0.0
+        def initialize(document)
+          @document = default_document.merge(Options::Mapper.transform(document, MAPPINGS))
+          @client_md5 = Digest::MD5.new
+        end
+
+        # Get a readable inspection for the object.
+        #
+        # @example Inspect the metadata.
+        #   metadata.inspect
+        #
+        # @return [ String ] The nice inspection.
+        #
+        # @since 2.0.0
+        def inspect
+          "#<Mongo::Grid::File::Metadata:0x#{object_id} chunk_size=#{chunk_size} " +
+            "filename=#{filename} content_type=#{content_type} id=#{id} md5=#{md5}>"
+        end
+
+        # Get the length of the document in bytes.
+        #
+        # @example Get the length
+        #   metadata.length
+        #
+        # @return [ Integer ] The length.
+        #
+        # @since 2.0.0
+        def length
+          document[:length]
+        end
+        alias :size :length
+
+        # Get the additional metadata.
+        #
+        # @example Get additional metadata.
+        #   metadata.metadata
+        #
+        # @return [ String ] The additional metadata.
+        #
+        # @since 2.0.0
+        def metadata
+          document[:metadata]
+        end
+
+        # Get the md5 hash.
+        #
+        # @example Get the md5 hash.
+        #   metadata.md5
+        #
+        # @return [ String ] The md5 hash as a string.
+        #
+        # @since 2.0.0
+        def md5
+          document[:md5] || @client_md5
+        end
+
+        # Conver the metadata to BSON for storage.
+        #
+        # @note If no md5 exists in the metadata (it was loaded from the server
+        #   and is not a new file) then we digest the md5 and set it.
+        #
+        # @example Convert the metadata to BSON.
+        #   metadata.to_bson
+        #
+        # @param [ String ] encoded The encoded data to append to.
+        #
+        # @return [ String ] The raw BSON data.
+        #
+        # @since 2.0.0
+        def to_bson(encoded = ''.force_encoding(BSON::BINARY))
+          document[:md5] ||= @client_md5.hexdigest
+          document.to_bson(encoded)
+        end
+
+        # Get the upload date.
+        #
+        # @example Get the upload date.
+        #   metadata.upload_date
+        #
+        # @return [ Time ] The upload date.
+        #
+        # @since 2.0.0
+        def upload_date
+          document[:uploadDate]
+        end
+
+        private
+
+        def default_document
+          BSON::Document.new(
+            :_id => BSON::ObjectId.new,
+            :chunkSize => Chunk::DEFAULT_SIZE,
+            :uploadDate => Time.now.utc,
+            :contentType => DEFAULT_CONTENT_TYPE
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mongo/grid/file.rb

@@ -0,0 +1,106 @@
+# Copyright (C) 2014-2015 MongoDB, 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/grid/file/chunk'
+require 'mongo/grid/file/metadata'
+
+module Mongo
+  module Grid
+
+    # A representation of a file in the database.
+    #
+    # @since 2.0.0
+    class File
+      extend Forwardable
+
+      # Delegate to metadata for convenience.
+      def_delegators :metadata, :chunk_size, :content_type, :filename, :id, :md5, :upload_date
+
+      # @return [ Array<Chunk> ] chunks The file chunks.
+      attr_reader :chunks
+
+      # @return [ IO ] data The raw datafor the file.
+      attr_reader :data
+
+      # @return [ Metadata ] metadata The file metadata.
+      attr_reader :metadata
+
+      # Check equality of files.
+      #
+      # @example Check the equality of files.
+      #   file == other
+      #
+      # @param [ Object ] other The object to check against.
+      #
+      # @return [ true, false ] If the objects are equal.
+      #
+      # @since 2.0.0
+      def ==(other)
+        return false unless other.is_a?(File)
+        chunks == other.chunks && data == other.data && metadata == other.metadata
+      end
+
+      # Initialize the file.
+      #
+      # @example Create the file.
+      #   Grid::File.new(data, :filename => 'test.txt')
+      #
+      # @param [ IO, Array<BSON::Document> ] data The file or IO object or
+      #   chunks.
+      # @param [ BSON::Document, Hash ] options The metadata options.
+      #
+      # @option options [ String ] :filename Required name of the file.
+      # @option options [ String ] :content_type The content type of the file.
+      # @option options [ String ] :metadata Optional file metadata.
+      # @option options [ Integer ] :chunk_size Override the default chunk
+      #   size.
+      #
+      # @since 2.0.0
+      def initialize(data, options = {})
+        @metadata = Metadata.new({ :length => data.length }.merge(options))
+        initialize_chunks!(data)
+      end
+
+      # Gets a pretty inspection of the file.
+      #
+      # @example Get the file inspection.
+      #   file.inspect
+      #
+      # @return [ String ] The file inspection.
+      #
+      # @since 2.0.0
+      def inspect
+        "#<Mongo::Grid::File:0x#{object_id} filename=#{filename}>"
+      end
+
+      private
+
+      # @note If we have provided an array of BSON::Documents to initialize
+      #   with, we have an array of chunk documents and need to create the
+      #   chunk objects and assemble the data. If we have an IO object, then
+      #   it's the original file data and we must split it into chunks and set
+      #   the original data itself.
+      def initialize_chunks!(value)
+        if value.is_a?(Array)
+          chks = value.map{ |doc| Chunk.new(doc) }
+          @chunks = chks
+          @data = Chunk.assemble(chks)
+        else
+          @chunks = Chunk.split(value, metadata)
+          @data = value
+        end
+      end
+    end
+  end
+end