bson 1.12.5-java → 2.0.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01ad7308ec0a814e717219df3f2c8740b5f72d46
-  data.tar.gz: 07588d4b17b511b33d0bab4cf8990d84d7878e6c
+  metadata.gz: adc9440ef40323da8c8098642b894593864cd07d
+  data.tar.gz: 1618998d46b189ff41371626e91e6e236dddd850
 SHA512:
-  metadata.gz: fbc4f3ea261b682700b87d04170e11bba3a3998e5bf1df3a001cb9e141f5eb8bd6550649b742decb653c2ebd651866a821d13790ab8c7dedc001945e32682ce8
-  data.tar.gz: cc54f36478149b4ab24a1cd9b77355f6480452fa98a2406bae42aec5fbfa1c16bc1ccb98ddde2e3a7fa696317c3129cfb9df14a889c0801a60b95ce53404f1e2
+  metadata.gz: 8c48f605a15889ccbf0293bb0483a200ec300749b18e3239c3f12b0ff118e52582fe696f3e243323ece726ffe2344669ca78af41d20a8f36b025bb6cf1f73d3d
+  data.tar.gz: d1284a224eb9ddd3bb9557aa33d88d328538adc44c64a622f5ed0f1f9a305023cd399bf3b2c1ce60549bfe80529a4abfef5bdce73654e52c1caac4328b83c6ff

data/CHANGELOG.md

@@ -0,0 +1,80 @@
+BSON Changelog
+==============
+
+## 2.0.0
+
+### Backwards Incompatible Changes
+
+* `BSON::DEFAULT_MAX_BSON_SIZE` has been removed, as the BSON specification does not
+  provide an upper limit on how large BSON documents can be.
+
+* `BSON.serialize` is no longer the entry point to serialize a BSON document into its
+  raw bytes.
+
+      For Ruby runtimes that support ordered hashes, you may simply call `to_bson` on
+      the hash instance (Alternatively a `BSON::Document` is also a hash:
+
+        { key: "value" }.to_bson
+        BSON::Document[:key, "value"].to_bson
+
+      For Ruby runtimes that do not support ordered hashes, then you must instantiate
+      an instance of a `BSON::Document` (which is a subclass of hash) and call `to_bson`
+      on that, since the BSON specification guarantees order of the fields:
+
+        BSON::Document[:key, "value"].to_bson
+
+* `BSON.deserialize` is no longer the entry point for raw byte deserialization into
+  a document.
+
+      For Ruby runtimes that support ordered hashes, you may simply call `from_bson` on
+      the `Hash` class if you want a `Hash` instance, or on `BSON::Document` if you
+      want an instance of that. The input must be a `StringIO` object:
+
+        Hash.from_bson(stringio)
+        BSON::Document.from_bson(stringio)
+
+      For Ruby runtimes that do not support ordered hashes, then `from_bson` must be
+      called on `BSON::Document` in order to guarantee order:
+
+        BSON::Document.from_bson(stringio)
+
+* Calling `to_json` on custom BSON objects now outputs different results from before, and
+  conforms the BSON specification:
+
+    - `BSON::Binary`: `{ "$binary" : "\x01", "$type" : "md5" }`
+    - `BSON::Code`: `{ "$code" : "this.v = 5 }`
+    - `BSON::CodeWithScope`: `{ "$code" : "this.v = value", "$scope" : { v => 5 }}`
+    - `BSON::MaxKey`: `{ "$maxKey" : 1 }`
+    - `BSON::MinKey`: `{ "$minKey" : 1 }`
+    - `BSON::ObjectId`: `{ "$oid" : "4e4d66343b39b68407000001" }`
+    - `BSON::Timestamp`: `{ "t" : 5, "i" : 30 }`
+    - `Regexp`: `{ "$regex" : "[abc]", "$options" : "i" }`
+
+### New Features
+
+* All Ruby objects that have a corresponding object defined in the BSON specification
+  can now have `to_bson` called on them to get the raw BSON bytes. These objects include:
+
+    - `Array`
+    - `FalseClass`
+    - `Float`
+    - `Hash`
+    - `Integer`
+    - `NilClass`
+    - `Regexp`
+    - `String`
+    - `Symbol` (deprecated)
+    - `Time`
+    - `TrueClass`
+
+* Custom types specific to the BSON specification that have Ruby objects defined for them
+  may also have `to_bson` called on them to get the raw bytes. These types are:
+
+    - `BSON::Binary`
+    - `BSON::Code`
+    - `BSON::CodeWithScope`
+    - `BSON::MaxKey`
+    - `BSON::MinKey`
+    - `BSON::ObjectId`
+    - `BSON::Timestamp`
+    - `BSON::Undefined`

data/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+Contributing
+============
+
+Code Conventions
+----------------
+
+Code style should fall in line with the style guide outlined by
+[Github](https://github.com/styleguide/ruby)
+
+Testing
+-------
+
+Bug fixes and new features should always have the appropriate specs, and the
+specs should follow the following guidelines:
+
+- Prefer `let` and `let!` over the use of instance variables and `subject`.
+- Prefer `expect(...).to eq(...) syntax over `...should eq(...)`.
+- Use shared examples to reduce duplication.
+- Use `describe "#method"` for instance method specs.
+- Use `describe ".method"` for class method specs.
+- Use `context` blocks to set up conditions.
+- Always provide descriptive specifications via `it`.
+
+Specs can be automatically run with Guard, via `bundle exec guard`
+
+Before commiting, run `rake` to ensure all specs pass with both pure Ruby and
+the native extensions.
+
+Git Etiquette
+-------------
+
+Please follow the commit message guidelines as outlined
+[in this blog post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+
+If the commit fixes a bug, please add the JIRA number on the last line:
+
+```
+[ close RUBY-492 ]
+```
+
+Please ensure that only one feature/bug fix is in each pull request, and
+that it is squashed into a single commit.

data/NOTICE

@@ -0,0 +1,2 @@
+Ruby BSON
+Copyright (C) 2009-2013 MongoDB, Inc.

data/README.md

@@ -0,0 +1,190 @@
+BSON [![Build Status](https://secure.travis-ci.org/mongodb/bson-ruby.png?branch=master&.png)](http://travis-ci.org/mongodb/bson-ruby) [![Code Climate](https://codeclimate.com/github/mongodb/bson-ruby.png)](https://codeclimate.com/github/mongodb/bson-ruby) [![Coverage Status](https://coveralls.io/repos/mongodb/bson-ruby/badge.png?branch=master)](https://coveralls.io/r/mongodb/bson-ruby?branch=master)
+====
+
+An implementation of the BSON specification in Ruby.
+
+Compatibility
+-------------
+
+BSON is tested against MRI (1.8.7+), JRuby (1.5.0+), Rubinius (2.0.0+), and REE.
+
+Installation
+------------
+
+With bundler, add the `bson` gem to your `Gemfile`. As of 2.0.0 native extensions
+are bundled with the `bson` gem and `bson_ext` is no longer needed.
+
+```ruby
+gem "bson", "~> 2.0"
+```
+
+Require the `bson` gem in your application.
+
+```ruby
+require "bson"
+```
+
+Usage
+-----
+
+### BSON Serialization
+
+Getting a Ruby object's raw BSON representation is done by calling `to_bson`
+on the Ruby object. For example:
+
+```ruby
+"Shall I compare thee to a summer's day".to_bson
+1024.to_bson
+```
+
+Generating an object from BSON is done via calling `from_bson` on the class
+you wish to instantiate and passing it the `StringIO` bytes.
+
+```ruby
+String.from_bson(string_io)
+Int32.from_bson(string_io)
+```
+
+Core Ruby object's that have representations in the BSON specification and
+will have a `to_bson` method defined for them are:
+
+- `Array`
+- `FalseClass`
+- `Float`
+- `Hash`
+- `Integer`
+- `NilClass`
+- `Regexp`
+- `String`
+- `Symbol` (deprecated)
+- `Time`
+- `TrueClass`
+
+In addition to the core Ruby objects, BSON also provides some special types
+specific to the specification:
+
+#### `BSON::Binary`
+
+This is a representation of binary data, and must provide the raw data and
+a subtype when constructing.
+
+```ruby
+BSON::Binary.new(binary_data, :md5)
+```
+
+Valid subtypes are: `:generic`, `:function`, `:old`, `:uuid_old`, `:uuid`,
+`:md5`, `:user`.
+
+#### `BSON::Code`
+
+Represents a string of Javascript code.
+
+```ruby
+BSON::Code.new("this.value = 5;")
+```
+
+#### `BSON::CodeWithScope`
+
+Represents a string of Javascript code with a hash of values.
+
+```ruby
+BSON::CodeWithScope.new("this.value = age;", age: 5)
+```
+
+#### `BSON::Document`
+
+This is a special ordered hash for use with Ruby below 1.9, and is simply
+a subclass of a Ruby hash in 1.9 and higher.
+
+```ruby
+BSON::Document[:key, "value"]
+BSON::Document.new
+```
+
+#### `BSON::MaxKey`
+
+Represents a value in BSON that will always compare higher to another value.
+
+```ruby
+BSON::MaxKey.new
+```
+
+#### `BSON::MinKey`
+
+Represents a value in BSON that will always compare lower to another value.
+
+```ruby
+BSON::MinKey.new
+```
+
+#### `BSON::ObjectId`
+
+Represents a 12 byte unique identifier for an object on a given machine.
+
+```ruby
+BSON::ObjectId.new
+```
+
+#### `BSON::Timestamp`
+
+Represents a special time with a start and increment value.
+
+```ruby
+BSON::Timestamp.new(5, 30)
+```
+
+#### `BSON::Undefined`
+
+Represents a placeholder for a value that was not provided.
+
+```ruby
+BSON::Undefined.new
+```
+
+### JSON Serialization
+
+Some BSON types have special representations in JSON. These are as follows
+and will be automatically serialized in the form when calling `to_json` on
+them.
+
+- `BSON::Binary`: `{ "$binary" : "\x01", "$type" : "md5" }`
+- `BSON::Code`: `{ "$code" : "this.v = 5 }`
+- `BSON::CodeWithScope`: `{ "$code" : "this.v = value", "$scope" : { v => 5 }}`
+- `BSON::MaxKey`: `{ "$maxKey" : 1 }`
+- `BSON::MinKey`: `{ "$minKey" : 1 }`
+- `BSON::ObjectId`: `{ "$oid" : "4e4d66343b39b68407000001" }`
+- `BSON::Timestamp`: `{ "t" : 5, "i" : 30 }`
+- `Regexp`: `{ "$regex" : "[abc]", "$options" : "i" }`
+
+API Documentation
+-----------------
+
+The [API Documentation](http://rdoc.info/github/mongodb/bson-ruby/master/frames) is
+located at rdoc.info.
+
+BSON Specification
+------------------
+
+The [BSON specification](http://bsonspec.org) is at bsonspec.org.
+
+Versioning
+----------
+
+As of 2.0.0, this project adheres to the [Semantic Versioning Specification](http://semver.org/).
+
+License
+-------
+
+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.

data/Rakefile

@@ -0,0 +1,109 @@
+# 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.
+
+require "bundler"
+Bundler.setup
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __FILE__))
+
+require "rake"
+require "rake/extensiontask"
+require "rspec/core/rake_task"
+
+def jruby?
+  defined?(JRUBY_VERSION)
+end
+
+if jruby?
+  require "rake/javaextensiontask"
+  Rake::JavaExtensionTask.new do |ext|
+    ext.name = "bson-ruby"
+    ext.ext_dir = "src"
+    ext.lib_dir = "lib"
+  end
+else
+  require "rake/extensiontask"
+  Rake::ExtensionTask.new do |ext|
+    ext.name = "native"
+    ext.ext_dir = "ext/bson"
+    ext.lib_dir = "lib"
+  end
+end
+
+require "bson/version"
+
+def extension
+  RUBY_PLATFORM =~ /darwin/ ? "bundle" : "so"
+end
+
+if RUBY_VERSION < "1.9"
+  require "perf/bench"
+else
+  require_relative "perf/bench"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:rspec)
+
+if jruby?
+  task :build => [ :clean_all, :compile ] do
+    system "gem build bson.gemspec"
+  end
+else
+  task :build => :clean_all do
+    system "gem build bson.gemspec"
+  end
+end
+
+task :clean_all => :clean do
+  begin
+    Dir.chdir(Pathname(__FILE__).dirname + "lib") do
+      `rm native.#{extension}`
+      `rm native.o`
+      `rm bson-ruby.jar`
+    end
+  rescue Exception => e
+    puts e.message
+  end
+end
+
+# Run bundle exec rake release with mri and jruby.
+task :release => :build do
+  system "git tag -a v#{BSON::VERSION} -m 'Tagging release: #{BSON::VERSION}'"
+  system "git push --tags"
+  if jruby?
+    system "gem push bson-#{BSON::VERSION}-java.gem"
+    system "rm bson-#{BSON::VERSION}-java.gem"
+  else
+    system "gem push bson-#{BSON::VERSION}.gem"
+    system "rm bson-#{BSON::VERSION}.gem"
+  end
+end
+
+namespace :benchmark do
+
+  task :ruby => :clean_all do
+    puts "Benchmarking pure Ruby..."
+    require "bson"
+    benchmark!
+  end
+
+  task :native => :compile do
+    puts "Benchmarking with native extensions..."
+    require "bson"
+    benchmark!
+  end
+end
+
+task :default => [ :clean_all, :spec, :compile, :rspec ]

data/lib/bson.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2009-2013 MongoDB, Inc.
+# 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.
@@ -12,102 +12,75 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-module BSON
-  DEFAULT_MAX_BSON_SIZE = 4 * 1024 * 1024
+require "bson/environment"
 
-  def self.serialize(obj, check_keys=false, move_id=false)
-    BSON_CODER.serialize(obj, check_keys, move_id)
-  end
+# The core namespace for all BSON related behaviour.
+#
+# @since 0.0.0
+module BSON
 
-  def self.deserialize(buf=nil, opts={})
-    BSON_CODER.deserialize(buf, opts)
-  end
+  # Constant for binary string encoding.
+  #
+  # @since 2.0.0
+  BINARY = "BINARY".freeze
 
-  # Reads a single BSON document from an IO object.
-  # This method is used in the executable b2json, bundled with
-  # the bson gem, for reading a file of bson documents.
+  # Constant for bson types that don't actually serialize a value.
   #
-  # @param [IO] io an io object containing a bson object.
+  # @since 2.0.0
+  NO_VALUE = "".force_encoding(BINARY).freeze
+
+  # Constant for a null byte (0x00).
   #
-  # @return [ByteBuffer]
-  def self.read_bson_document(io)
-    bytebuf = BSON::ByteBuffer.new
-    sz = io.read(4).unpack("V")[0]
-    bytebuf.put_int(sz)
-    bytebuf.put_array(io.read(sz-4).unpack("C*"))
-    bytebuf.rewind
-    return BSON.deserialize(bytebuf)
-  end
+  # @since 2.0.0
+  NULL_BYTE = 0.chr.force_encoding(BINARY).freeze
 
-  def self.extension?
-    !((ENV.key?('BSON_EXT_DISABLED') && RUBY_PLATFORM =~ /java/) ||
-      (ENV.key?('BSON_EXT_DISABLED') || "\x01\x00\x00\x00".unpack("i")[0] != 1))
-  end
+  # Constant for UTF-8 string encoding.
+  #
+  # @since 2.0.0
+  UTF8 = "UTF-8".freeze
 end
 
-begin
-  # Skips loading extensions if one of the following is true:
-  # 1) JRuby and BSON_EXT_DISABLED is set.
-  #     -OR-
-  # 2) Ruby MRI and big endian or BSON_EXT_DISABLED is set.
-  raise LoadError unless BSON.extension?
+require "bson/registry"
+require "bson/specialized"
+require "bson/json"
+require "bson/int32"
+require "bson/int64"
+require "bson/integer"
+require "bson/encodable"
+require "bson/array"
+require "bson/binary"
+require "bson/boolean"
+require "bson/code"
+require "bson/code_with_scope"
+require "bson/document"
+require "bson/false_class"
+require "bson/float"
+require "bson/hash"
+require "bson/max_key"
+require "bson/min_key"
+require "bson/nil_class"
+require "bson/object_id"
+require "bson/regexp"
+require "bson/string"
+require "bson/symbol"
+require "bson/time"
+require "bson/timestamp"
+require "bson/true_class"
+require "bson/undefined"
+require "bson/version"
 
-  if RUBY_PLATFORM =~ /java/
-    require 'bson/bson_java'
-    module BSON
-      BSON_CODER = BSON_JAVA
-    end
+# If we are using JRuby, attempt to load the Java extensions, if we are using
+# MRI or Rubinius, attempt to load the C extenstions. If either of these fail,
+# we revert back to a pure Ruby implementation of the Buffer class.
+#
+# @since 2.0.0
+begin
+  if BSON::Environment.jruby?
+    require "bson-ruby.jar"
+    org.bson.NativeService.new.basicLoad(JRuby.runtime)
   else
-    require 'bson_ext/cbson'
-    raise LoadError unless defined?(CBson::VERSION)
-    require 'bson/bson_c'
-    module BSON
-      BSON_CODER = BSON_C
-    end
+    require "native"
   end
 rescue LoadError
-  require 'bson/bson_ruby'
-  module BSON
-    BSON_CODER = BSON_RUBY
-  end
-
-  if RUBY_PLATFORM =~ /java/
-    unless ENV['TEST_MODE']
-      warn <<-NOTICE
-      ** Notice: The BSON extension was not loaded. **
-
-      For optimal performance, use of the BSON extension is recommended. To
-      enable the extension make sure ENV['BSON_EXT_DISABLED'] is not set.
-      NOTICE
-    end
-  else
-    unless ENV['TEST_MODE']
-      warn <<-NOTICE
-      ** Notice: The native BSON extension was not loaded. **
-
-      For optimal performance, use of the BSON extension is recommended.
-
-      To enable the extension make sure ENV['BSON_EXT_DISABLED'] is not set
-      and run the following command:
-
-        gem install bson_ext
-
-      If you continue to receive this message after installing, make sure that
-      the bson_ext gem is in your load path.
-      NOTICE
-    end
-  end
+  $stderr.puts("BSON is using the pure Ruby implementation.")
 end
-
-require 'base64'
-require 'bson/bson_ruby'
-require 'bson/byte_buffer'
-require 'bson/exceptions'
-require 'bson/ordered_hash'
-require 'bson/types/binary'
-require 'bson/types/code'
-require 'bson/types/dbref'
-require 'bson/types/min_max_keys'
-require 'bson/types/regex'
-require 'bson/types/object_id'
-require 'bson/types/timestamp'