Class: Mongo::ObjectID

Inherits:
Object show all
Defined in:
lib/mongo/types/objectid.rb

Overview

ObjectID class for documents in MongoDB.

Constant Summary collapse

BYTE_ORDER =

This is the legacy byte ordering for Babble. Versions of the Ruby driver prior to 0.14 used this byte ordering when converting ObjectID instances to and from strings. If you have string representations of ObjectIDs using the legacy byte ordering make sure to use the to_s_legacy and from_string_legacy methods, or convert your strings with ObjectID#legacy_string_convert

[7, 6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8]
@@lock = 
Mutex.new
@@index = 
0

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data = nil) ⇒ ObjectID

Create a new object id. If no parameter is given, an id corresponding to the ObjectID BSON data type will be created. This is a 12-byte value consisting of a 4-byte timestamp, a 3-byte machine id, a 2-byte process id, and a 3-byte counter.

Parameters:

  • data (Array) (defaults to: nil) —

    should be an array of bytes. If you want to generate a standard MongoDB object id, leave this argument blank.



43
44
45
 
# File 'lib/mongo/types/objectid.rb', line 43

def initialize(data=nil)
  @data = data || generate
end

Class Method Details

.create_pk(doc) ⇒ Mongo::ObjectID, Object

Adds a primary key to the given document if needed.

Parameters:

  • doc (Hash) —

    a document requiring an _id.

Returns:



76
77
78
 
# File 'lib/mongo/types/objectid.rb', line 76

def self.create_pk(doc)
  doc.has_key?(:_id) || doc.has_key?('_id') ? doc : doc.merge!(:_id => self.new)
end

.from_string(str) ⇒ Mongo::ObjectID

Given a string representation of an ObjectID, return a new ObjectID with that value.

Parameters:

  • str (String)

Returns:

Raises:



109
110
111
112
113
114
115
116
 
# File 'lib/mongo/types/objectid.rb', line 109

def self.from_string(str)
  raise InvalidObjectID, "illegal ObjectID format" unless legal?(str)
  data = []
  12.times do |i|
    data[i] = str[i * 2, 2].to_i(16)
  end
  self.new(data)
end

.from_string_legacy(str) ⇒ Object

Deprecated.

Create a new ObjectID given a string representation of an ObjectID using the legacy byte ordering. This method may eventually be removed. If you are not sure that you need this method you should be using the regular from_string.

Raises:



123
124
125
126
127
128
129
130
131
 
# File 'lib/mongo/types/objectid.rb', line 123

def self.from_string_legacy(str)
  warn "Support for legacy object ids has been DEPRECATED."
  raise InvalidObjectID, "illegal ObjectID format" unless legal?(str)
  data = []
  BYTE_ORDER.each_with_index { |string_position, data_index|
    data[data_index] = str[string_position * 2, 2].to_i(16)
  }
  self.new(data)
end

.from_time(time) ⇒ Mongo::ObjectID

Create an object id from the given time. This is useful for doing range queries; it works because MongoDB’s object ids begin with a timestamp.

Examples:

Return all document created before Jan 1, 2010.

time = Time.utc(2010, 1, 1)
time_id = ObjectID.from_time(time)
collection.find({'_id' => {'$lt' => time_id}})

Parameters:

  • time (Time) —

    a utc time to encode as an object id.

Returns:



66
67
68
 
# File 'lib/mongo/types/objectid.rb', line 66

def self.from_time(time)
  self.new([time.to_i,0,0].pack("NNN").unpack("C12"))
end

.legacy_string_convert(str) ⇒ Object

Deprecated.

Convert a string representation of an ObjectID using the legacy byte ordering to the proper byte ordering. This method may eventually be removed. If you are not sure that you need this method it is probably unnecessary.



171
172
173
174
175
176
177
178
 
# File 'lib/mongo/types/objectid.rb', line 171

def self.legacy_string_convert(str)
  warn "Support for legacy object ids has been DEPRECATED."
  legacy = ' ' * 24
  BYTE_ORDER.each_with_index do |legacy_pos, pos|
    legacy[legacy_pos * 2, 2] = str[pos * 2, 2]
  end
  legacy
end

.legal?(str) ⇒ Boolean

Returns:

  • (Boolean) 


47
48
49
50
51
52
 
# File 'lib/mongo/types/objectid.rb', line 47

def self.legal?(str)
  len = BYTE_ORDER.length * 2
  str =~ /([0-9a-f]+)/i
  match = $1
  str && str.length == len && match == str
end

Instance Method Details

#eql?(object_id) ⇒ Boolean Also known as: ==

Check equality of this object id with another.

Parameters:

Returns:

  • (Boolean) 


83
84
85
 
# File 'lib/mongo/types/objectid.rb', line 83

def eql?(object_id)
  @data == object_id.instance_variable_get("@data")
end

#generation_time ⇒ Time

Return the UTC time at which this ObjectID was generated. This may be used in lieu of a created_at timestamp since this information is always encoded in the object id.

Returns:

  • (Time) —

    the time at which this object was created.



185
186
187
 
# File 'lib/mongo/types/objectid.rb', line 185

def generation_time
  Time.at(@data.pack("C4").unpack("N")[0]).utc
end

#hash ⇒ Integer

Get a unique hashcode for this object. This is required since we’ve defined an #eql? method.

Returns:

  • (Integer) 


92
93
94
 
# File 'lib/mongo/types/objectid.rb', line 92

def hash
  @data.hash
end

#to_a ⇒ Array

Get an array representation of the object id.

Returns:

  • (Array) 


99
100
101
 
# File 'lib/mongo/types/objectid.rb', line 99

def to_a
  @data.dup
end

#to_json(escaped = false) ⇒ String

Convert to MongoDB extended JSON format. Since JSON includes type information, but lacks an ObjectID type, this JSON format encodes the type using an $id key.

Returns:

  • (String) —

    the object id represented as MongoDB extended JSON.



149
150
151
 
# File 'lib/mongo/types/objectid.rb', line 149

def to_json(escaped=false)
  "{\"$oid\": \"#{to_s}\"}"
end

#to_s ⇒ String Also known as: inspect

Get a string representation of this object id.

Returns:

  • (String) 


136
137
138
139
140
141
142
 
# File 'lib/mongo/types/objectid.rb', line 136

def to_s
  str = ' ' * 24
  12.times do |i|
    str[i * 2, 2] = '%02x' % @data[i]
  end
  str
end

#to_s_legacy ⇒ Object

Deprecated.

Get a string representation of this ObjectID using the legacy byte ordering. This method may eventually be removed. If you are not sure that you need this method you should be using the regular to_s.



157
158
159
160
161
162
163
164
 
# File 'lib/mongo/types/objectid.rb', line 157

def to_s_legacy
  warn "Support for legacy object ids has been DEPRECATED."
  str = ' ' * 24
  BYTE_ORDER.each_with_index { |string_position, data_index|
    str[string_position * 2, 2] = '%02x' % @data[data_index]
  }
  str
end