bson 1.12.5-java → 2.0.0-java

data/lib/bson/registry.rb

@@ -0,0 +1,70 @@
+# Copyright (C) 2009-2013 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 BSON
+
+  # Provides constant values for each to the BSON types and mappings from raw
+  # bytes back to these types.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Registry
+    extend self
+
+    # A Mapping of all the BSON types to their corresponding Ruby classes.
+    #
+    # @since 2.0.0
+    MAPPINGS = {}
+
+    # Get the class for the single byte identifier for the type in the BSON
+    # specification.
+    #
+    # @example Get the type for the byte.
+    #   BSON::Registry.get("\x01")
+    #
+    # @return [ Class ] The corresponding Ruby class for the type.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def get(byte)
+      MAPPINGS.fetch(byte)
+    end
+
+    # Register the Ruby type for the corresponding single byte.
+    #
+    # @example Register the type.
+    #   BSON::Registry.register("\x01", Float)
+    #
+    # @param [ String ] byte The single byte.
+    # @param [ Class ] The class the byte maps to.
+    #
+    # @return [ Class ] The class.
+    #
+    # @since 2.0.0
+    def register(byte, type)
+      MAPPINGS.store(byte, type)
+      define_type_reader(type)
+    end
+
+    private
+
+    def define_type_reader(type)
+      type.module_eval <<-MOD
+        def bson_type; BSON_TYPE; end
+      MOD
+    end
+  end
+end

data/lib/bson/specialized.rb

@@ -0,0 +1,74 @@
+# Copyright (C) 2009-2013 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 BSON
+
+  # Provides behaviour to special values that exist in the BSON spec that don't
+  # have a native type, like $minKey and $maxKey.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Specialized
+
+    # Determine if the min key is equal to another object.
+    #
+    # @example Check min key equality.
+    #   BSON::MinKey.new == object
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      self.class == other.class
+    end
+
+    # Encode the min key - has no value since it only needs the type and field
+    # name when being encoded.
+    #
+    # @example Encode the min key value.
+    #   min_key.to_bson
+    #
+    # @return [ String ] An empty string.
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encoded
+    end
+
+    private
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Deserialize MinKey from BSON.
+      #
+      # @param [ BSON ] bson The encoded MinKey.
+      #
+      # @return [ MinKey ] The decoded MinKey.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        new
+      end
+    end
+  end
+end

data/lib/bson/string.rb

@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2009-2013 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 BSON
+
+  # Injects behaviour for encoding and decoding string values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module String
+    include Encodable
+
+    # A string is type 0x02 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 2.chr.force_encoding(BINARY).freeze
+
+    # Get the string as encoded BSON.
+    #
+    # @example Get the string as encoded BSON.
+    #   "test".to_bson
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encode_with_placeholder_and_null(STRING_ADJUST, encoded) do |encoded|
+        to_bson_string(encoded)
+      end
+    end
+
+    # Get the string as a BSON key name encoded C string with checking for special characters.
+    #
+    # @example Get the string as key name.
+    #   "test".to_bson_key
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_key(encoded = ''.force_encoding(BINARY))
+      to_bson_cstring(encoded)
+    end
+
+    # Get the string as an encoded C string.
+    #
+    # @example Get the string as an encoded C string.
+    #   "test".to_bson_cstring
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_cstring(encoded = ''.force_encoding(BINARY))
+      check_for_illegal_characters!
+      to_bson_string(encoded) << NULL_BYTE
+    end
+
+    # Convert the string to an object id. This will only work for strings of size
+    # 12.
+    #
+    # @example Convert the string to an object id.
+    #   string.to_bson_object_id
+    #
+    # @note This is used for repairing legacy bson data.
+    #
+    # @raise [ InvalidObjectId ] If the string is not 12 elements.
+    #
+    # @return [ String ] The raw object id bytes.
+    #
+    # @since 2.0.0
+    def to_bson_object_id
+      ObjectId.repair(self)
+    end
+
+    # Convert the string to a UTF-8 string then force to binary. This is so
+    # we get errors for strings that are not UTF-8 encoded.
+    #
+    # @example Convert to valid BSON string.
+    #   "Straße".to_bson_string
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The binary string.
+    #
+    # @since 2.0.0
+    def to_bson_string(encoded = ''.force_encoding(BINARY))
+      begin
+        to_utf8_binary(encoded)
+      rescue EncodingError
+        data = dup.force_encoding(UTF8)
+        raise unless data.valid_encoding?
+        encoded << data.force_encoding(BINARY)
+      end
+    end
+
+    # Convert the string to a hexidecimal representation.
+    #
+    # @example Convert the string to hex.
+    #   "\x01".to_hex_string
+    #
+    # @return [ String ] The string as hex.
+    #
+    # @since 2.0.0
+    def to_hex_string
+      unpack("H*")[0]
+    end
+
+    # Take the binary string and return a UTF-8 encoded string.
+    #
+    # @example Convert from a BSON string.
+    #   "\x00".from_bson_string
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The UTF-8 string.
+    #
+    # @since 2.0.0
+    def from_bson_string
+      force_encoding(UTF8)
+    end
+
+    # Set four bytes for int32 in a binary string and return it.
+    #
+    # @example Set int32 in a BSON string.
+    #   "".set_int32(pos, int32)
+    #
+    # @param [ Fixnum ] The position to set.
+    # @param [ Fixnum ] The int32 value.
+    #
+    # @return [ String ] The binary string.
+    #
+    # @since 2.0.0
+    def set_int32(pos, int32)
+      self[pos, 4] = [ int32 ].pack(Int32::PACK)
+    end
+
+    private
+
+    def to_utf8_binary(encoded)
+      encoded << encode(UTF8).force_encoding(BINARY)
+    end
+
+    module ClassMethods
+
+      # Deserialize a string from BSON.
+      #
+      # @param [ BSON ] bson The bson representing a string.
+      #
+      # @return [ Regexp ] The decoded string.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        bson.read(Int32.from_bson(bson)).from_bson_string.chop!
+      end
+    end
+
+    private
+
+    def check_for_illegal_characters!
+      if include?(NULL_BYTE)
+        raise(ArgumentError, "Illegal C-String '#{self}' contains a null byte.")
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::String)
+  end
+
+  # Enrich the core String class with this module.
+  #
+  # @since 2.0.0
+  ::String.send(:include, String)
+  ::String.send(:extend, String::ClassMethods)
+end

data/lib/bson/symbol.rb

@@ -0,0 +1,87 @@
+# Copyright (C) 2009-2013 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 BSON
+
+  # Injects behaviour for encoding and decoding symbol values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @note Symbols are deprecated in the BSON spec, but they are still
+  #   currently supported here for backwards compatibility.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Symbol
+
+    # A symbol is type 0x0E in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 14.chr.force_encoding(BINARY).freeze
+
+    # Get the symbol as encoded BSON.
+    #
+    # @example Get the symbol as encoded BSON.
+    #   :test.to_bson
+    #
+    # @return [ Symbol ] The encoded symbol.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      to_s.to_bson(encoded)
+    end
+
+    # Get the symbol as a BSON key name encoded C symbol.
+    #
+    # @example Get the symbol as a key name.
+    #   :test.to_bson_key
+    #
+    # @return [ String ] The encoded symbol as a BSON key.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_key(encoded = ''.force_encoding(BINARY))
+      to_s.to_bson_key(encoded)
+    end
+
+    module ClassMethods
+      # Deserialize a symbol from BSON.
+      #
+      # @param [ BSON ] bson The bson representing a symbol.
+      #
+      # @return [ Regexp ] The decoded symbol.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        bson.read(Int32.from_bson(bson)).from_bson_string.chop!.intern
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Symbol)
+  end
+
+  # Enrich the core Symbol class with this module.
+  #
+  # @since 2.0.0
+  ::Symbol.send(:include, Symbol)
+  ::Symbol.send(:extend, Symbol::ClassMethods)
+end

data/lib/bson/time.rb

@@ -0,0 +1,72 @@
+# Copyright (C) 2009-2013 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 BSON
+
+  # Injects behaviour for encoding and decoding time values to
+  # and from raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Time
+
+    # A time is type 0x09 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 9.chr.force_encoding(BINARY).freeze
+
+    # Get the time as encoded BSON.
+    #
+    # @example Get the time as encoded BSON.
+    #   Time.new(2012, 1, 1, 0, 0, 0).to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encoded << [ (to_f * 1000.0).to_i ].pack(Int64::PACK)
+    end
+
+    module ClassMethods
+
+      # Deserialize UTC datetime from BSON.
+      #
+      # @param [ BSON ] bson The bson representing UTC datetime.
+      #
+      # @return [ Time ] The decoded UTC datetime.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        seconds, fragment = Int64.from_bson(bson).divmod(1000)
+        at(seconds, fragment * 1000).utc
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Time)
+  end
+
+  # Enrich the core Time class with this module.
+  #
+  # @since 2.0.0
+  ::Time.send(:include, Time)
+  ::Time.send(:extend, Time::ClassMethods)
+end