Class: Familia::Horreum

Inherits:
Object
  • Object
show all
Includes:
Base, Commands, Serialization, Settings, Utils
Defined in:
lib/familia/horreum.rb,
lib/familia/horreum/utils.rb,
lib/familia/horreum/commands.rb,
lib/familia/horreum/settings.rb,
lib/familia/horreum/class_methods.rb,
lib/familia/horreum/serialization.rb,
lib/familia/horreum/relations_management.rb

Overview

Familia::Horreum

Defined Under Namespace

Modules: ClassMethods, Commands, RelationsManagement, Serialization, Settings, Utils

Instance Attribute Summary

Attributes included from Serialization

#redis

Attributes included from Settings

#dump_method, #load_method, #suffix

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Serialization

#apply_fields, #commit_fields, #destroy!, #refresh, #refresh!, #save, #to_a, #to_h, #to_redis, #transaction

Methods included from Settings

#db, #db=, #opts, #redisdetails

Methods included from Commands

#decr, #decrby, #exists?, #expire, #hdel!, #hget, #hgetall, #hkeys, #hlen, #hmset, #hset, #hstrlen, #hvals, #incr, #incrby, #incrbyfloat, #key?, #realttl, #redistype, #rename

Methods included from Utils

#join, #rediskey, #redisuri

Methods included from Base

add_feature, #generate_id, #update_expiration, #uuid

Constructor Details

#initialize(*args, **kwargs) ⇒ Horreum

Instance initialization This method sets up the object’s state, including Redis-related data



72
73
74
75
76
77
78
79
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
 
# File 'lib/familia/horreum.rb', line 72

def initialize(*args, **kwargs)
  Familia.ld "[Horreum] Initializing #{self.class}"
  initialize_relatives

  # If there are positional arguments, they should be the field
  # values in the order they were defined in the implementing class.
  #
  # Handle keyword arguments
  # Fields is a known quantity, so we iterate over it rather than kwargs
  # to ensure that we only set fields that are defined in the class. And
  # to avoid runaways.
  if args.any?
    initialize_with_positional_args(*args)
  elsif kwargs.any?
    initialize_with_keyword_args(**kwargs)
  else
    Familia.ld "[Horreum] #{self.class} initialized with no arguments"
    # If there are no arguments, we need to set the default values
    # for the fields. This is done in the order they were defined.
    # self.class.fields.each do |field|
    #  default = self.class.defaults[field]
    #  send(:"#{field}=", default) if default
    # end
  end

  # Automatically add a 'key' field if it's not already defined
  # This ensures that every object has a unique identifier
  unless self.class.fields.include?(:key)
    # Define the 'key' field for this class
    # This approach allows flexibility in how identifiers are generated
    # while ensuring each object has a consistent way to be referenced
    self.class.field :key # , default: -> { identifier }
  end

  # Implementing classes can define an init method to do any
  # additional initialization. Notice that this is called
  # after the fields are set.
  init if respond_to?(:init)
end

Class Method Details

.inherited(member) ⇒ Object

Extends ClassMethods to subclasses and tracks Familia members



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/familia/horreum.rb', line 58

def inherited(member)
  Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
  member.extend(ClassMethods)
  member.extend(Features)

  # Tracks all the classes/modules that include Familia. It's
  # 10pm, do you know where you Familia members are?
  Familia.members << member
  super
end

Instance Method Details

#identifier ⇒ Object

Determines the unique identifier for the instance This method is used to generate Redis keys for the object

Raises:



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/familia/horreum.rb', line 217

def identifier
  definition = self.class.identifier # e.g.
  # When definition is a symbol or string, assume it's an instance method
  # to call on the object to get the unique identifier. When it's a callable
  # object, call it with the object as the argument. When it's an array,
  # call each method in turn and join the results. When it's nil, raise
  # an error
  unique_id = case definition
              when Symbol, String
                send(definition)
              when Proc
                definition.call(self)
              when Array
                Familia.join(definition.map { |method| send(method) })
              else
                raise Problem, "Invalid identifier definition: #{definition.inspect}"
              end

  # If the unique_id is nil, raise an error
  raise Problem, "Identifier is nil for #{self.class}" if unique_id.nil?
  raise Problem, 'Identifier is empty' if unique_id.empty?

  unique_id
end

#initialize_relatives ⇒ Object

Sets up related Redis objects for the instance This method is crucial for establishing Redis-based relationships

This needs to be called in the initialize method.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/familia/horreum.rb', line 117

def initialize_relatives
  # Generate instances of each RedisType. These need to be
  # unique for each instance of this class so they can piggyback
  # on the specifc index of this instance.
  #
  # i.e.
  #     familia_object.rediskey              == v1:bone:INDEXVALUE:object
  #     familia_object.redis_type.rediskey == v1:bone:INDEXVALUE:name
  #
  # See RedisType.install_redis_type
  self.class.redis_types.each_pair do |name, redis_type_definition|
    klass = redis_type_definition.klass
    opts = redis_type_definition.opts
    Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"

    # As a subclass of Familia::Horreum, we add ourselves as the parent
    # automatically. This is what determines the rediskey for RedisType
    # instance and which redis connection.
    #
    #   e.g. If the parent's rediskey is `customer:customer_id:object`
    #     then the rediskey for this RedisType instance will be
    #     `customer:customer_id:name`.
    #
    opts[:parent] = self # unless opts.key(:parent)

    # Instantiate the RedisType object and below we store it in
    # an instance variable.
    redis_type = klass.new name, opts

    # Freezes the redis_type, making it immutable.
    # This ensures the object's state remains consistent and prevents any modifications,
    # safeguarding its integrity and making it thread-safe.
    # Any attempts to change the object after this will raise a FrozenError.
    redis_type.freeze

    # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
    instance_variable_set :"@#{name}", redis_type
  end
end

#optimistic_refresh(**fields) ⇒ Array

A thin wrapper around the private initialize method that accepts a field hash and refreshes the existing object.

This method is part of horreum.rb rather than serialization.rb because it operates solely on the provided values and doesn’t query Redis or other external sources. That’s why it’s called “optimistic” refresh: it assumes the provided values are correct and updates the object accordingly.

Parameters:

  • fields (Hash) —

    A hash of field names and their new values to update the object with.

Returns:

  • (Array) —

    The list of field names that were updated.

See Also:



210
211
212
213
 
# File 'lib/familia/horreum.rb', line 210

def optimistic_refresh(**fields)
  Familia.ld "[optimistic_refresh] #{self.class} #{rediskey} #{fields.keys}"
  initialize_with_keyword_args(**fields)
end