Class: BSON::DBRef

Inherits:
Document show all
Includes:
JSON
Defined in:
lib/bson/dbref.rb

Overview

Represents a DBRef document in the database.

Constant Summary collapse

COLLECTION =
Deprecated.

The constant for the collection reference field.

'$ref'.freeze
ID =
Deprecated.

The constant for the id field.

'$id'.freeze
DATABASE =
Deprecated.

The constant for the database field.

'$db'.freeze

Instance Method Summary collapse

Methods included from JSON

#to_json

Methods inherited from Document

#[], #[]=, #deep_symbolize_keys!, #delete, #dig, #except, #fetch, #has_key?, #has_value?, #merge, #merge!, #slice, #symbolize_keys!, #to_bson_normalized_value

Constructor Details

#initialize(hash_or_collection, id = nil, database = nil) ⇒ DBRef

Instantiate a new DBRef.

Examples:

Create the DBRef - hash API.

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

Create the DBRef - legacy API.

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

Raises:

  • if giving invalid arguments to the constructor.

Parameters:

  • 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.

  • (defaults to: nil)

    The object id, when using the legacy API.

  • (defaults to: nil)

    The database name, when using the legacy API.



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/bson/dbref.rb', line 80

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 Error::InvalidDBRefArgument, '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 Error::InvalidDBRefArgument, '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 Error::InvalidDBRefArgument, "DBRef must have #{key}: #{hash}"
    end
  end

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

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

  super(hash)
end

Instance Method Details

#as_json(*args) ⇒ Hash

Get the DBRef as a JSON document

Examples:

Get the DBRef as a JSON hash.

dbref.as_json

Returns:

  • The max key as a JSON hash.



60
61
62
 
# File 'lib/bson/dbref.rb', line 60

def as_json(*args)
  {}.update(self)
end

#collection ⇒ String

Returns collection The collection name.

Returns:

  • collection The collection name.



40
41
42
 
# File 'lib/bson/dbref.rb', line 40

def collection
  self['$ref']
end

#database ⇒ String

Returns database The database name.

Returns:

  • database The database name.



50
51
52
 
# File 'lib/bson/dbref.rb', line 50

def database
  self['$db']
end

#id ⇒ BSON::ObjectId

Returns id The referenced document id.

Returns:

  • id The referenced document id.



45
46
47
 
# File 'lib/bson/dbref.rb', line 45

def id
  self['$id']
end

#to_bson(buffer = ByteBuffer.new) ⇒ BSON::ByteBuffer

Converts the DBRef to raw BSON.

Examples:

Convert the DBRef to raw BSON.

dbref.to_bson

Parameters:

  • (defaults to: ByteBuffer.new)

    The encoded BSON buffer to append to.

Returns:

  • The buffer with the encoded object.



129
130
131
 
# File 'lib/bson/dbref.rb', line 129

def to_bson(buffer = ByteBuffer.new)
  as_json.to_bson(buffer)
end