Class: Mongoid::PersistenceContext

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Inherits:	Object
Defined in:	lib/mongoid/persistence_context.rb

Overview

Object encapsulating logic for setting/getting a collection and database name and a client with particular options to use when persisting models.

Constant Summary

EXTRA_OPTIONS =

Extra options in addition to driver client options that determine the persistence context.
Returns:
- (Array<Symbol>) —
  
  The list of extra options besides client options that determine the persistence context.
# File 'lib/mongoid/persistence_context.rb', line 27
```
[ :client,
  :collection,
  :collection_options
].freeze
```
PERSISTENCE_CONTEXT_KEY = Internal use only

Key to store persistence contexts in the thread local storage.

# File 'lib/mongoid/persistence_context.rb', line 286
```
:"[mongoid]:persistence_context"
```
VALID_OPTIONS =

The full list of valid persistence context options.
Returns:
- (Array<Symbol>) —
  
  The full list of options defining the persistence context.
# File 'lib/mongoid/persistence_context.rb', line 36
```
( Mongo::Client::VALID_OPTIONS + EXTRA_OPTIONS ).freeze
```

Class Method Summary

.clear(object, cluster = nil, original_context = nil)

Clear the persistence context for a particular class or model instance.
.get(object) ⇒ Mongoid::PersistenceContext

Get the persistence context for a particular class or model instance.
.new(object, opts = {}) ⇒ PersistenceContext constructor

Initialize the persistence context object.
.set(object, options_or_context) ⇒ Mongoid::PersistenceContext

::Set the persistence context for a particular class or model instance.
.context_store private
.get_context(object) ⇒ Mongoid::PersistenceContext | nil private Internal use only Internal use only

Get the persistence context for a given object from the thread local.
.store_context(object, context) private Internal use only Internal use only

Store persistence context for a given object in the thread local.

Instance Attribute Summary

#options ⇒ Hash readonly

The options defining this persistence context.
#reusable_client? ⇒ true | false readonly Internal use only Internal use only

Whether the client of the context can be reused later, and therefore should not be closed.

Instance Method Summary

#==(other) ⇒ true | false

Determine if this persistence context is equal to another.
#client ⇒ Mongo::Client

Get the client for this persistence context.
#client_name ⇒ Symbol

Get the client name for this persistence context.
#collection(parent = nil) ⇒ Mongo::Collection

Get the collection for this persistence context.
#collection_name ⇒ String

Get the collection name for this persistence context.
#database_name ⇒ String

Get the database name for this persistence context.
#for_child(document) ⇒ PersistenceContext Internal use only Internal use only

Returns a new persistence context that is consistent with the given child document, inheriting most appropriate settings.
#requested_storage_options ⇒ Hash | nil Internal use only Internal use only

The subset of provided options that may be used as storage options.
#__evaluate__(name) private
#client_options private
#database_name_option private
#set_options!(opts) private

Constructor Details

.new(object, opts = {}) ⇒ `PersistenceContext`

Initialize the persistence context object.

Examples:

Create a new persistence context.

PersistenceContext.new(model, collection: 'other')

Parameters:

object (Object) —

The class or model instance for which a persistence context should be created.
opts (Hash) (defaults to: {}) —

The persistence context options.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 46


def initialize(object, opts = {})
  @object = object
  set_options!(opts)
end

Class Method Details

.clear(object, cluster = nil, original_context = nil)

Clear the persistence context for a particular class or model instance.

Examples:

Clear the persistence context for a class or model instance.

PersistenceContext.clear(model)

Parameters:

object (Class | Object) —

The class or model instance.
cluster (Mongo::Cluster) (defaults to: nil) —

The original cluster before this context was used.
original_context (PersistenceContext) (defaults to: nil) —

The original persistence context that was set before this context was used.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 271


def clear(object, cluster = nil, original_context = nil)
  if context = get(object)
    unless cluster.nil? || context.cluster.equal?(cluster)
      context.client.close unless context.reusable_client?
    end
  end
ensure
  store_context(object, original_context)
end

.context_store (private)

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 288


def context_store
  Threaded.get(PERSISTENCE_CONTEXT_KEY) { {} }
end

.get(object) ⇒ `PersistenceContext`

Get the persistence context for a particular class or model instance.

Examples:

Get the persistence context for a class or model instance.

PersistenceContext.get(model)

Parameters:

object (Object) —

The class or model instance.

Returns:

(PersistenceContext) —

The persistence context for the object.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 258


def get(object)
  get_context(object)
end

.get_context(object) ⇒ `PersistenceContext` | `nil` (private)

This method is for internal use only.

Get the persistence context for a given object from the thread local

storage.

Parameters:

object (Object) —

Object to get the persistance context for.

Returns:

(PersistenceContext | nil) —

The persistence context for the object if previously stored, otherwise nil.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 301


def get_context(object)
  context_store[object.object_id]
end

.set(object, options_or_context) ⇒ `PersistenceContext`

::Set the persistence context for a particular class or model instance.

If there already is a persistence context set, options in the existing context are combined with options given to the set call.

Examples:

::Set the persistence context for a class or model instance.

PersistenceContext.set(model)

Parameters:

object (Object) —

The class or model instance.
options_or_context (Hash | PersistenceContext) —

The persistence options or a persistence context object.

Returns:

(PersistenceContext) —

The persistence context for the object.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 235


def set(object, options_or_context)
  existing_context = get_context(object)
  existing_options = if existing_context
    existing_context.options
  else
    {}
  end
  if options_or_context.is_a?(PersistenceContext)
    options_or_context = options_or_context.options
  end
  new_options = existing_options.merge(options_or_context)
  context = PersistenceContext.new(object, new_options)
  store_context(object, context)
end

.store_context(object, context) (private)

This method is for internal use only.

Store persistence context for a given object in the thread local

storage.

Parameters:

object (Object) —

Object to store the persistance context for.
context (PersistenceContext) —

Context to store

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 312


def store_context(object, context)
  if context.nil?
    context_store.delete(object.object_id)
  else
    context_store[object.object_id] = context
  end
end

Instance Attribute Details

#options ⇒ Hash (readonly)

The options defining this persistence context.

Returns:

(Hash) —

The persistence context options.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 20


attr_reader :options

#reusable_client? ⇒ `true` | `false` (readonly)

This method is for internal use only.

Whether the client of the context can be reused later, and therefore should not be closed.

If the persistence context is requested with :client option only, it means that the context should use a client configured in mongoid.yml. Such clients should not be closed when the context is cleared since they will be reused later.

Returns:

(true | false) —

True if client can be reused, otherwise false.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 170


def reusable_client?
  @options.keys == [:client]
end

Instance Method Details

#==(other) ⇒ `true` | `false`

Determine if this persistence context is equal to another.

Examples:

Compare two persistence contexts.

context == other_context

Parameters:

other (Object) —

The object to be compared with this one.

Returns:

(true | false) —

Whether the two persistence contexts are equal.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 154


def ==(other)
  return false unless other.is_a?(PersistenceContext)
  options == other.options
end

#evaluate(name) (private)

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 197


def __evaluate__(name)
  return nil unless name
  name.respond_to?(:call) ? name.call.to_sym : name.to_sym
end

#client ⇒ `Mongo::Client`

Get the client for this persistence context.

Examples:

Get the client for this persistence context.

context.client

Returns:

(Mongo::Client) —

The client for this persistence context.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 117


def client
  @client ||= begin
    client = Clients.with_name(client_name)
    options = client_options

    if database_name_option
      client = client.use(database_name)
      options = options.except(:database, 'database')
    end

    client = client.with(options) unless options.empty?

    client
  end
end

#client_name ⇒ Symbol

Get the client name for this persistence context.

Examples:

Get the client name for this persistence context.

context.client_name

Returns:

(Symbol) —

The client name for this persistence context.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 140


def client_name
  @client_name ||= __evaluate__(options[:client]) ||
                     Threaded.client_override ||
                     __evaluate__(storage_options[:client])
end

#client_options (private)

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 202


def client_options
  @client_options ||= begin
    opts = options.select do |k, v|
                          Mongo::Client::VALID_OPTIONS.include?(k.to_sym)
                        end
    if opts[:read].is_a?(Symbol)
      opts[:read] = {mode: opts[:read]}
    end
    opts
  end
end

#collection(parent = nil) ⇒ `Mongo::Collection`

Get the collection for this persistence context.

Examples:

Get the collection for this persistence context.

context.collection

Parameters:

parent (Object) (defaults to: nil) —

The parent object whose collection name is used instead of this persistence context’s collection name.

Returns:

(Mongo::Collection) —

The collection for this persistence context.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 81


def collection(parent = nil)
  parent ?
    parent.collection.with(client_options.except(:database, "database")) :
    client[collection_name.to_sym]
end

#collection_name ⇒ String

Get the collection name for this persistence context.

Examples:

Get the collection name for this persistence context.

context.collection_name

Returns:

(String) —

The collection name for this persistence context.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 94


def collection_name
  @collection_name ||= (__evaluate__(options[:collection] ||
                         storage_options[:collection]))
end

#database_name ⇒ String

Get the database name for this persistence context.

Examples:

Get the database name for this persistence context.

context.database_name

Returns:

(String) —

The database name for this persistence context.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 106


def database_name
  __evaluate__(database_name_option) || client.database.name
end

#database_name_option (private)

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 214


def database_name_option
  @database_name_option ||= options[:database] ||
                              Threaded.database_override ||
                              storage_options[:database]
end

#for_child(document) ⇒ `PersistenceContext`

This method is for internal use only.

Returns a new persistence context that is consistent with the given child document, inheriting most appropriate settings.

Parameters:

document (Mongoid::Document | Class) —

the child document

Returns:

(PersistenceContext) —

the new persistence context

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 59


def for_child(document)
  if document.is_a?(Class)
    return self if document == (@object.is_a?(Class) ? @object : @object.class)
  elsif document.is_a?(Mongoid::Document)
    return self if document.class == (@object.is_a?(Class) ? @object : @object.class)
  else
    raise ArgumentError, 'must specify a class or a document instance'
  end

  PersistenceContext.new(document, options.merge(document.storage_options))
end

#requested_storage_options ⇒ Hash | `nil`

This method is for internal use only.

The subset of provided options that may be used as storage options.

Returns:

(Hash | nil) —

the requested storage options, or nil if none were specified.

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 181


def requested_storage_options
  slice = @options.slice(*Mongoid::Clients::Validators::Storage::VALID_OPTIONS)
  slice.any? ? slice : nil
end

#set_options!(opts) (private)

[ GitHub ]

# File 'lib/mongoid/persistence_context.rb', line 188


def set_options!(opts)
  @options ||= opts.each.reduce({}) do |_options, (key, value)|
                 unless VALID_OPTIONS.include?(key.to_sym)
                   raise Errors::InvalidPersistenceOption.new(key.to_sym, VALID_OPTIONS)
                 end
                 value ? _options.merge!(key => value) : _options
               end
end

Class: Mongoid::PersistenceContext

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(object, opts = {}) ⇒ PersistenceContext

Class Method Details

.clear(object, cluster = nil, original_context = nil)

.context_store (private)

.get(object) ⇒ PersistenceContext

.get_context(object) ⇒ PersistenceContext | nil (private)

.set(object, options_or_context) ⇒ PersistenceContext

.store_context(object, context) (private)

Instance Attribute Details

#options ⇒ Hash (readonly)

#reusable_client? ⇒ true | false (readonly)

Instance Method Details

#==(other) ⇒ true | false

#__evaluate__(name) (private)

#client ⇒ Mongo::Client

#client_name ⇒ Symbol

#client_options (private)

#collection(parent = nil) ⇒ Mongo::Collection

#collection_name ⇒ String

#database_name ⇒ String

#database_name_option (private)

#for_child(document) ⇒ PersistenceContext

#requested_storage_options ⇒ Hash | nil

#set_options!(opts) (private)

.new(object, opts = {}) ⇒ `PersistenceContext`

.get(object) ⇒ `PersistenceContext`

.get_context(object) ⇒ `PersistenceContext` | `nil` (private)

.set(object, options_or_context) ⇒ `PersistenceContext`

#reusable_client? ⇒ `true` | `false` (readonly)

#==(other) ⇒ `true` | `false`

#evaluate(name) (private)

#client ⇒ `Mongo::Client`

#collection(parent = nil) ⇒ `Mongo::Collection`

#for_child(document) ⇒ `PersistenceContext`

#requested_storage_options ⇒ Hash | `nil`