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

#[], #[]=, #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')

Parameters:

  • hash_or_collection (Hash | String) —

    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.

  • id (Object) (defaults to: nil) —

    The object id, when using the legacy API.

  • database (String) (defaults to: nil) —

    The database name, when using the legacy API.

Raises:



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:

  • (Hash) —

    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:

  • (String) —

    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:

  • (String) —

    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:



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:

  • buffer (BSON::ByteBuffer) (defaults to: ByteBuffer.new) —

    The encoded BSON buffer to append to.

Returns:



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

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