jonbell-mongo 1.3.1.2

data/docs/GridFS.md

@@ -0,0 +1,158 @@
+# GridFS in Ruby
+
+GridFS, which stands for "Grid File Store," is a specification for storing large files in MongoDB. It works by dividing a file into manageable chunks and storing each of those chunks as a separate document. GridFS requires two collections to achieve this: one collection stores each file's metadata (e.g., name, size, etc.) and another stores the chunks themselves. If you're interested in more details, check out the [GridFS Specification](http://www.mongodb.org/display/DOCS/GridFS+Specification).
+
+### The Grid class
+
+The [Grid class](Mongo/Grid.html) represents the core GridFS implementation. Grid gives you a simple file store, keyed on a unique ID. This means that duplicate filenames aren't a problem. To use the Grid class, first make sure you have a database, and then instantiate a Grid:
+
+
+    @db = Mongo::Connection.new.db('social_site')
+    @grid = Grid.new(@db)
+
+#### Saving files
+Once you have a Grid object, you can start saving data to it. The data can be either a string or an IO-like object that responds to a #read method:
+
+
+    # Saving string data
+    id = @grid.put("here's some string / binary data")
+
+    # Saving IO data and including the optional filename
+    image = File.open("me.jpg")
+    id2   = @grid.put(image, :filename => "me.jpg")
+
+
+Grid#put returns an object id, which you can use to retrieve the file:
+
+
+    # Get the string we saved
+    file = @grid.get(id)
+
+    # Get the file we saved
+    image = @grid.get(id2)
+
+
+#### File metadata
+
+There are accessors for the various file attributes:
+
+
+    image.filename
+    # => "me.jpg"
+
+    image.content_type
+    # => "image/jpg"
+
+    image.file_length
+    # => 502357
+
+    image.upload_date
+    # => Mon Mar 01 16:18:30 UTC 2010
+
+    # Read all the image's data at once
+    image.read
+
+    # Read the first 100k bytes of the image
+    image.read(100 * 1024)
+
+
+When putting a file, you can set many of these attributes and write arbitrary metadata:
+
+
+    # Saving IO data
+    file = File.open("me.jpg")
+    id2  = @grid.put(file, 
+             :filename     => "my-avatar.jpg" 
+             :content_type => "application/jpg", 
+             :_id          => 'a-unique-id-to-use-in-lieu-of-a-random-one',
+             :chunk_size   => 100 * 1024,
+             :metadata     => {'description' => "taken after a game of ultimate"})
+
+
+#### Safe mode
+
+A kind of safe mode is built into the GridFS specification. When you save a file, and MD5 hash is created on the server. If you save the file in safe mode, an MD5 will be created on the client for comparison with the server version. If the two hashes don't match, an exception will be raised.
+
+
+    image = File.open("me.jpg")
+    id2   = @grid.put(image, "my-avatar.jpg", :safe => true) 
+
+
+#### Deleting files
+
+Deleting a file is as simple as providing the id:
+
+
+    @grid.delete(id2)
+
+
+### The GridFileSystem class
+
+[GridFileSystem](http://api.mongodb.org/ruby/current/Mongo/GridFileSystem.html) is a light emulation of a file system and therefore has a couple of unique properties. The first is that filenames are assumed to be unique. The second, a consequence of the first, is that files are versioned. To see what this means, let's create a GridFileSystem instance:
+
+#### Saving files
+
+    @db = Mongo::Connection.new.db("social_site")
+    @fs = GridFileSystem.new(@db)
+
+Now suppose we want to save the file 'me.jpg.' This is easily done using a filesystem-like API:
+
+
+    image = File.open("me.jpg")
+    @fs.open("me.jpg", "w") do |f|
+      f.write image
+    end 
+
+
+We can then retrieve the file by filename:
+
+
+    image = @fs.open("me.jpg", "r") {|f| f.read }
+
+
+No problems there. But what if we need to replace the file? That too is straightforward:
+
+
+    image = File.open("me-dancing.jpg")
+    @fs.open("me.jpg", "w") do |f|
+      f.write image
+    end 
+
+
+But a couple things need to be kept in mind. First is that the original 'me.jpg' will be available until the new 'me.jpg' saves. From then on, calls to the #open method will always return the most recently saved version of a file. But, and this the second point, old versions of the file won't be deleted. So if you're going to be rewriting files often, you could end up with a lot of old versions piling up. One solution to this is to use the :delete_old options when writing a file:
+
+
+    image = File.open("me-dancing.jpg")
+    @fs.open("me.jpg", "w", :delete_old => true) do |f|
+      f.write image
+    end 
+
+
+This will delete all but the latest version of the file.
+
+
+#### Deleting files
+
+When you delete a file by name, you delete all versions of that file:
+
+
+    @fs.delete("me.jpg")
+
+
+#### Metadata and safe mode
+
+All of the options for storing metadata and saving in safe mode are available for the GridFileSystem class:
+
+
+    image = File.open("me.jpg")
+    @fs.open('my-avatar.jpg', w,  
+               :content_type => "application/jpg", 
+               :metadata     => {'description' => "taken on 3/1/2010 after a game of ultimate"},
+               :_id          => 'a-unique-id-to-use-instead-of-the-automatically-generated-one',
+               :safe         => true) { |f| f.write image }
+
+
+### Advanced Users
+
+Astute code readers will notice that the Grid and GridFileSystem classes are merely thin wrappers around an underlying [GridIO class](http://api.mongodb.org/ruby/current/Mongo/GridIO.html). This means that it's easy to customize the GridFS implementation presented here; just use GridIO for all the low-level work, and build the API you need in an external manager class similar to Grid or GridFileSystem.
+

data/docs/HISTORY.md

@@ -0,0 +1,263 @@
+# MongoDB Ruby Driver History
+
+### 1.3.1
+2011-5-10
+
+* Fix GridIO#gets infinite loop error (Ryan McGeary)
+* Fix BSON::OrderedHash#reject! leaving keys with null values (rpt. by Ben Poweski)
+* Minor semantic fix for OrderedHash#reject!
+* Fix Mongo::DB to allow symbols in method traversing collection names (rpt. by Chris Griego)
+* Support new server regex option "s" (dotall). This is folded in with \m in Ruby.
+* Fix so that Cursor#close hits the right node when :read_secondary is enabled.
+* Support maxScan, showDiskLoc, and returnKey cursor options.
+* Make DB#validate_collection compatible with server v1.9.1.
+* Fix so that GridIO#gets returns local md5 with md5 matches server md5 (Steve Tantra).
+* Fix bug in BSON::OrderedHash that prevents YAML.load (Ian Warshak).
+* Fix example from /examples.
+* Ensure that we do not modify hash arguments by calling Hash#dup when appropriate.
+* Ensure that JRuby deserializer preserves binary subtypes properly.
+* Fix for streaming an empty file into GridFS (Daniël van de Burgt).
+* Minor doc fixes.
+
+### 1.3.0
+2011-4-04
+
+* Add option to set timeouts on socket read calls using the
+  Mongo::Connection :op_timeout option.
+* Add StringIO methods to GridIO objects
+* Support for BSON timestamp type with BSON::Timestamp
+* Change the BSON binary subtype from 2 to 0
+* Remove private method Connection#reset_conection
+  and deprecate public method ReplSetConnection#reset_connection
+* ByteBuffer#== and OrderedHash#dup (Hongli Lai)
+* Better check for UTF8 validity in Ruby 1.9
+* Added previously removed Connection#host and Connection#port
+* Added transformers to allow Mongo::Cursor to allow instantiated objects (John Nunemaker)
+* Automated reconnection on fork
+* Added Cursor#next alias for Cursor#next_document
+* Audit tests after enabling warnings (Wojciech Piekutowski)
+* Various bug fixes thanks to Datanoise, Hongli Lai, and Mauro Pompilio
+
+### 1.2.4
+2011-2-23
+
+* Fix the exception message shown when there's an IOError (Mauro Pompilio)
+* Another update to map-reduce docs for v1.8. Note that if you use the new
+  output option {:out => {:inline => true}}, then you must also specify
+  :raw => true.
+
+### 1.2.3
+2011-2-22
+
+* Update docs for map-reduce command
+* Minor doc fix
+
+### 1.2.2
+2011-2-15
+
+* Improved replica set failover for edge case.
+* Fix for REE on OSX (Hongli Lai)
+
+### 1.2.1
+2011-1-18
+
+* Enable authentication with connection pooling.
+* Allow custom logging with Connection#instrument (CodeMonkeySteve)
+* Minor fixes and doc improvements.
+
+### 1.2.0
+2011-1-18
+
+* Some minor improvements. See commit history.
+
+### 1.2.rc0
+2011-1-5
+
+Lots of cleanup and minor bug fixes.
+* Issues resolved: http://jira.mongodb.org/browse/RUBY/fixforversion/10222
+* Updated Java BSON to Java driver 2.4.
+* Platform gem for JRuby bson.
+
+### 1.1.5
+2010-12-15
+
+* ReplSetConnection class. This must be used for replica set connections from
+  now on. You can still use Connection.multi, but that method has been deprecated.
+* Automated replica set tests. rake test:rs
+* Check that request and response ids match.
+* Several bug fixes. See the commit history for details.
+
+### 1.1.4
+2010-11-30
+
+* Important connection failure fix.
+* ObjectId#to_s optimization (David Cuadrado).
+
+### 1.1.3
+2010-11-29
+
+* Distributed reads for replica set secondaries. See /docs/examples/replica_set.rb and
+  http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html for details.
+* Note: when connecting to a replica set, you must use Connection#multi.
+* Cursor#count takes optional skip and limit
+* Collection#ensure_index for caching index creation calls
+* Collection#update and Collection#remove now return error object when using safe mode
+* Important fix for int/long serialization on bug introduced in 1.0.9
+* Numerous tweaks and bug fixes.
+
+### 1.1.2
+2010-11-4
+
+* Two critical fixes to automated failover and replica sets.
+* Bug passing :timeout to Cursor.
+* Permit safe mode specification on Connection, Collection, and DB levels.
+* Specify replica set name on connect to verify connection to the right set.
+* Misc. reorganization of project and docs.
+
+### 1.1.1
+2010-10-14
+
+* Several critical JRuby bug fixes
+* Fixes for JRuby in 1.9 mode
+* Check keys and move id only when necessary for JRuby encoder
+
+## 1.1
+2010-10-4
+
+* Official JRuby support via Java extensons for BSON (beta)
+* Connection#lock! and Connection#unlock! for easy fsync lock
+* Note: BSON::Code is no longer a subclass of String.
+
+### 1.0.9
+2010-9-20
+
+* Significant performance improvements (with a lot of help from Hongli Lai)
+
+### 1.0.8
+2010-8-27
+
+* Cursor#rewind! and more consistent Cursor Enumberable behavior
+* Deprecated ObjectID for ObjectId
+* Numerous minor bug fixes.
+
+### 1.0.7
+2010-8-4
+
+* A few minor test/doc fixes.
+* Better tests for replica sets and replication acknowledgment.
+* Deprecated DB#error and DB#last_status
+
+### 1.0.6
+2010-7-26
+
+* Replica set support.
+* Collection#map_reduce bug fix.
+
+### 1.0.5 
+2010-7-13
+
+* Fix for bug introduced in 1.0.4.
+
+### 1.0.4
+2010-7-13
+
+* Removed deprecated
+  * Cursor admin option
+  * DB#query
+  * DB#create_index (use Collection#create_index)
+  * DB#command only takes hash options now
+* j2bson executable (neomantra)
+* Fixed bson_ext compilation on Solaris (slyphon)
+* System JS helpers (neovintage)
+* Use one mutex per thread on pooled connections (cremes)
+* Check for CursorNotFound response flag
+* MapReduce can return raw command output using :raw
+* BSON::OrderedHash equality with other Ruby hashes (Ryan Angilly)
+* Fix for broken Socket.send with large payloads (Frédéric De Jaeger)
+* Lots of minor improvements. See commmits.
+
+### 1.0.3
+2010-6-15
+
+* Optimiztion for BSON::OrderedHash
+* Some important fixes.
+
+### 1.0.2
+2010-6-5
+
+This is a minor release for fixing an incompatibility with MongoDB v1.5.2
+
+* Fix for boolean response on commands for core server v1.5.2
+* BSON.read_bson_document and b2json executable (neomantra)
+* BSON::ObjectID() shortcut for BSON::ObjectID.from_string (tmm1)
+* Various bug fixes.
+
+### 1.0.1
+2010-5-7
+
+* set Encoding.default_internal
+* DEPRECATE JavaScript string on Collection#find. You now must specify $where explicitly.
+* Added Grid#exist? and GridFileSystem#exist?
+* Support for replication acknowledgment
+* Support for $slice
+* Namespaced OrderedHash under BSON (sleverbor)
+
+## 1.0
+2010-4-29
+Note: if upgrading from versions prior to 0.20, be sure to upgrade
+to 0.20 before upgrading to 1.0.
+
+* Inspected ObjectID is represented in MongoDB extended json format.
+* Support for tailable cursors.
+* Configurable query response batch size (thx. to Aman Gupta)
+
+* bson_ext installs on early release of Ruby 1.8.5 (dfitzgibbon)
+* Deprecated DB#create_index. Use Collection#create_index index.
+* Removed deprecated Grid#put syntax; no longer requires a filename.
+
+### 0.20.1
+2010-4-7
+
+* Added bson gem dependency.
+
+### 0.20
+2010-4-7
+
+If upgrading from a previous version of the Ruby driver, please read these notes carefully,
+along with the 0.20_UPGRADE doc.
+
+* Support for new commands:
+  * Collection#find_and_modify
+  * Collection#stats
+  * DB#stats
+* Query :fields options allows for values of 0 to exclude fields (houdini, railsjedi).
+* GridFS
+  * Option to delete old versions of GridFileSystem entries.
+  * Filename is now optional for Grid#put.
+  * Option to write arbitrary attributes to a file: @grid.put(@data, :favorite_phrase => "blimey!")
+  * Indexes created on the chunks collection are now unique. If you have an existing chunks collection,
+    you may want to remove 
+* Removed the following deprecated items:
+  * GridStore class
+  * RegexpOfHolding class
+  * Paired connections must now be initialized with Connection.paired
+
+* BSON-related code extracted into two separate gems: bson and bson_ext (thx to Chuck Remes).
+  * mongo_ext no longer exists.
+  * BSON::Binary constructor can now take a string, which will be packed into an array.
+  * Exception class adjustments:
+    * Mongo::InvalidObjectID moved to BSON::InvalidObjectID
+    * Mongo::InvalidDocument moved to BSON::InvalidDocument
+    * Mongo::InvalidStringEncoding moved to BSON::InvalidStringEncoding
+    * Mongo::InvalidName replaced by Mongo::InvalidNSName and BSON::InvalidKeyName
+  * BSON types are now namespaced under the BSON module. These types include:
+    * Binary
+    * ObjectID
+    * Code
+    * DBRef
+    * MinKey and MaxKey
+  * Extensions compile on Rubinius (Chuck Remes).
+
+## Prior to 0.20
+
+See git revisions.

data/docs/RELEASES.md

@@ -0,0 +1,33 @@
+# MongoDB Ruby Driver Release Plan
+
+This is a description of a formalized release plan that will take effect
+with version 1.3.0.
+
+## Semantic versioning
+
+The most significant difference is that releases will now adhere to the conventions of
+[semantic versioning](http://semver.org). In particular, we will strictly abide by the
+following release rules:
+
+1. Patch versions of the driver (Z in x.y.Z) will be released only when backward-compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
+
+2. Minor versions (Y in x.Y.z) will be released if new, backward-compatible functionality is introduced to the public API.
+
+3. Major versions (X in X.y.z) will be incremented if any backward-incompatibl changes are introduced to the public API.
+
+This policy will clearly indicate to users when an upgrade may affect their code. As a side effect, version numbers will climb more quickly than before.
+
+
+## Release checklist
+
+Before each relese to Rubygems.org, the following steps will be taken:
+
+1. All driver tests will be run on Linux, OS X, and Windows via continuous integration system.
+
+2. HISTORY file will document all significant commits.
+
+3. Version number will be incremented per the semantic version spec described above.
+
+4. Appropriate branches and tags will be created in Git repository, as necessary.
+
+5. Docs will be updated to the latest version of the driver and posted [online](http://api.mongodb.org/ruby/current/index.html).