123456789_123456789_123456789_123456789_123456789_

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

Class Method Summary

Instance Attribute Summary

Instance Method Summary

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 45



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 267



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


  








  

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



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 293



def get_context(object)
  Thread.current[PERSISTENCE_CONTEXT_KEY] ||= {}
  Thread.current[PERSISTENCE_CONTEXT_KEY][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 231



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 305



def store_context(object, context)
  if context.nil?
    Thread.current[PERSISTENCE_CONTEXT_KEY]&.delete(object.object_id)
  else
    Thread.current[PERSISTENCE_CONTEXT_KEY] ||= {}
    Thread.current[PERSISTENCE_CONTEXT_KEY][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 166



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 150



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


  








  

    #__evaluate__(name)   (private)
  

  [ GitHub ]


  

  


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



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 116



def client
  @client ||= begin
    client = Clients.with_name(client_name)
    if database_name_option
      client = client.use(database_name)
    end
    unless client_options.empty?
      client = client.with(client_options)
    end
    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 136



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


  








  

    #client_options   (private)
  

  [ GitHub ]


  

  


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



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 80



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 93



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 105



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


  








  

    #database_name_option   (private)
  

  [ GitHub ]


  

  


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



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:



Returns:


    
  
  • 
    (PersistenceContext)
—    
    

    the new persistence context
    

    
  
    • 





  [ GitHub ]


  

  


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



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 177



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 184



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