class BSON::DBRef

Represents a DBRef document in the database.

Constants

COLLECTION

The constant for the collection reference field.

@deprecated

DATABASE

The constant for the database field.

@deprecated

ID

The constant for the id field.

@deprecated

Public Class Methods

new(hash_or_collection, id = nil, database = nil) click to toggle source

Instantiate a new DBRef.

@example Create the DBRef - hash API.

BSON::DBRef.new({'$ref' => 'users', '$id' => id, '$db' => 'database'})

@example Create the DBRef - legacy API.

BSON::DBRef.new('users', id, 'database')

@param [ Hash | String ] hash_or_collection The DBRef hash, when using

the hash API. It must contain $ref and $id. When using the legacy API,
this parameter must be a String containing the collection name.

@param [ Object ] id The object id, when using the legacy API. @param [ String ] database The database name, when using the legacy API.

Calls superclass method
# File lib/bson/dbref.rb, line 77
def initialize(hash_or_collection, id = nil, database = nil)
  if hash_or_collection.is_a?(Hash)
    hash = hash_or_collection

    unless id.nil? && database.nil?
      raise ArgumentError, 'When using the hash API, DBRef constructor accepts only one argument'
    end
  else
    warn("BSON::DBRef constructor called with the legacy API - please use the hash API instead")

    if id.nil?
      raise ArgumentError, 'When using the legacy constructor API, id must be provided'
    end

    hash = {
      :$ref => hash_or_collection,
      :$id => id,
      :$db => database,
    }
  end

  hash = reorder_fields(hash)
  %w($ref $id).each do |key|
    unless hash[key]
      raise ArgumentError, "DBRef must have #{key}: #{hash}"
    end
  end

  unless hash['$ref'].is_a?(String)
    raise ArgumentError, "The value for key $ref must be a string, got: #{hash['$ref']}"
  end

  if db = hash['$db']
    unless db.is_a?(String)
      raise ArgumentError, "The value for key $db must be a string, got: #{hash['$db']}"
    end
  end

  super(hash)
end

Public Instance Methods

as_json(*args) click to toggle source

Get the DBRef as a JSON document

@example Get the DBRef as a JSON hash.

dbref.as_json

@return [ Hash ] The max key as a JSON hash.

# File lib/bson/dbref.rb, line 60
def as_json(*args)
  {}.update(self)
end
collection() click to toggle source

@return [ String ] collection The collection name.

# File lib/bson/dbref.rb, line 40
def collection
  self['$ref']
end
database() click to toggle source

@return [ String ] database The database name.

# File lib/bson/dbref.rb, line 50
def database
  self['$db']
end
id() click to toggle source

@return [ BSON::ObjectId ] id The referenced document id.

# File lib/bson/dbref.rb, line 45
def id
  self['$id']
end
to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?) click to toggle source

Converts the DBRef to raw BSON.

@example Convert the DBRef to raw BSON.

dbref.to_bson

@param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to. @param [ true, false ] validating_keys Whether keys should be validated when serializing.

@return [ BSON::ByteBuffer ] The buffer with the encoded object.

# File lib/bson/dbref.rb, line 127
def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
  as_json.to_bson(buffer, validating_keys)
end

Private Instance Methods

reorder_fields(hash) click to toggle source

Reorder the fields of the given Hash to have $ref first, $id second, and $db third. The rest of the fields in the hash can come in any order after that.

@param [ Hash ] hash The input hash. Must be a valid dbref.

@return [ Hash ] The hash with it’s fields reordered.

# File lib/bson/dbref.rb, line 140
def reorder_fields(hash)
  hash = BSON::Document.new(hash)
  reordered = {}
  reordered['$ref'] = hash.delete('$ref')
  reordered['$id'] = hash.delete('$id')
  if db = hash.delete('$db')
    reordered['$db'] = db
  end

  reordered.update(hash)
end