module Hoodoo::ActiveRecord::Dated::ClassMethods
Collection of class methods that get defined on an including class via Hoodoo::ActiveRecord::Dated::included
.
Public Instance Methods
Return an ActiveRecord::Relation containing the model instances which are effective at context.request.dated_at
. If this value is nil the current time in UTC is used.
If historic dating hasn’t been enabled via a call to dating_enabled
, then the default ‘all’ scope is returned instead.
context
-
Hoodoo::Services::Context
instance describing a call context. This is typically a value passed to one of theHoodoo::Services::Implementation
instance methods that a resource subclass implements.
Additional named parameters are:
unquoted_column_names
-
(Optional) An Array of Strings giving one or more column names to use for the query. If omitted, all model attribtues are used as columns. If the “id” column is not included in the Array, it will be added anyway as this column is mandatory. The effect is equivalent to an Array given in the
ActiveRecord
select
method.
# File lib/hoodoo/active/active_record/dated.rb, line 221 def dated( context, unquoted_column_names: nil ) date_time = context.request.dated_at || Time.now return self.dated_at( date_time, unquoted_column_names: unquoted_column_names ) end
Return an ActiveRecord::Relation scoping a query to include only model instances that are relevant/effective at the specified date_time.
If historic dating hasn’t been enabled via a call to dating_enabled
, then the default ‘all’ scope is returned instead.
date_time
-
(Optional) A Time or DateTime instance, or a String that can be converted to a DateTime instance, for which the “effective dated” scope is to be constructed.
Additional named parameters are:
unquoted_column_names
-
(Optional) An Array of Strings giving one or more column names to use for the query. If omitted, all model attribtues are used as columns. If the “id” column is not included in the Array, it will be added anyway as this column is mandatory. The effect is equivalent to an Array given in the
ActiveRecord
select
method.
# File lib/hoodoo/active/active_record/dated.rb, line 247 def dated_at( date_time = Time.now, unquoted_column_names: nil ) dating_table_name = dated_with_table_name() return all() if dating_table_name.nil? # "Model.all" -> returns anonymous scope # Rationalise and convert the date time to UTC. date_time = Hoodoo::Utilities.rationalise_datetime( date_time ).utc safe_date_time = self.connection.quoted_date( date_time ) # Create strings that specify the required attributes escaped and # joined by commas for use in a SQL query, for both main and history # tables. safe_name_string = self.quoted_column_name_string( unquoted_column_names: unquoted_column_names ) safe_history_name_string = self.quoted_column_name_string_for_history( unquoted_column_names: unquoted_column_names ) # A query that combines historical and current records which are # effective at the specified date time. nested_query = %{ ( SELECT #{ safe_name_string } FROM ( SELECT #{ safe_name_string },"updated_at" AS "effective_start",NULL AS "effective_end" FROM #{ self.table_name } UNION ALL SELECT #{ safe_history_name_string },"effective_start","effective_end" FROM #{ dating_table_name } ) AS u WHERE "effective_start" <= '#{ safe_date_time }' AND ("effective_end" > '#{ safe_date_time }' OR "effective_end" IS NULL) ) AS #{ self.table_name } } # Form a query which uses ActiveRecord to list a dated or current # record. return from( nested_query ) end
Return an ActiveRecord::Relation scoping a query that would include all historical and current model instances.
If historic dating hasn’t been enabled via a call to dating_enabled
, then the default ‘all’ scope is returned instead.
Named parameters are:
unquoted_column_names
-
(Optional) An Array of Strings giving one or more column names to use for the query. If omitted, all model attributes are used as columns. If the “id” column is not included in the Array, it will be added anyway as this column is mandatory. The effect is equivalent to an Array given in the
ActiveRecord
select
method.
# File lib/hoodoo/active/active_record/dated.rb, line 308 def dated_historical_and_current( unquoted_column_names: nil ) dating_table_name = dated_with_table_name() return all() if dating_table_name.nil? # "Model.all" -> returns anonymous scope # Create strings that specify the required attributes escaped and # joined by commas for use in a SQL query, for both main and history # tables. safe_name_string = self.quoted_column_name_string( unquoted_column_names: unquoted_column_names ) safe_history_name_string = self.quoted_column_name_string_for_history( unquoted_column_names: unquoted_column_names ) # A query that combines historical and current records. nested_query = %{ ( SELECT #{ safe_name_string } FROM #{ self.table_name } UNION ALL SELECT #{ safe_history_name_string } FROM #{ dating_table_name } ) AS #{ self.table_name } } # Form a query which uses ActiveRecord to list current and dated # records. return from( nested_query ) end
Returns the anonymous ActiveRecord::Base
instance used for this model’s history entries, or nil
if historic dating has not been enabled via a prior call to dating_enabled
.
# File lib/hoodoo/active/active_record/dated.rb, line 347 def dated_with return self.nz_co_loyalty_hoodoo_dated_with end
Get the symbolised name of the history table for model. This defaults to the name of the model’s table concatenated with _history_entries
. If the table name is :posts
, the history table would be :posts_history_entries
.
If historic dating hasn’t been enabled via a call to dating_enabled
, returns nil
.
# File lib/hoodoo/active/active_record/dated.rb, line 359 def dated_with_table_name instance = self.dated_with() instance.nil? ? nil : instance.table_name end
Activate historic dating for this model.
See the module documentation for Hoodoo::ActiveRecord::Dated
for full information on dating, table requirements, default table names and so forth.
Named parameters are:
history_table_name
-
Optional String or Symbol name of the table which stores the history entries for this model. If omitted, defaults to the value described by the documentation for
Hoodoo::ActiveRecord::Dated
.
# File lib/hoodoo/active/active_record/dated.rb, line 164 def dating_enabled( history_table_name: self.table_name + '_history_entries' ) # Define an anonymous model for the history entries. history_klass = Class.new( ::ActiveRecord::Base ) do self.primary_key = :id self.table_name = history_table_name end # Record the anonymous model class in a namespaced class attribute # for reference in the rest of the dating code via #dated_with(). self.nz_co_loyalty_hoodoo_dated_with = history_klass # Enable the monkey patch to the Finder module's '#acquire_in' class # method, if need be. if self.include?( Hoodoo::ActiveRecord::Finder ) Hoodoo::Monkey.register( target_unit: self, extension_module: Hoodoo::Monkey::Patch::ActiveRecordDatedFinderAdditions ) Hoodoo::Monkey.enable( extension_module: Hoodoo::Monkey::Patch::ActiveRecordDatedFinderAdditions ) end end
If a prior call has been made to dating_enabled
then this method returns true
, else false
.
# File lib/hoodoo/active/active_record/dated.rb, line 194 def dating_enabled? return self.dated_with().present? end
Protected Instance Methods
Returns a String of comma-separated sanitised (quoted) column names based on this model’s attribute names, or the given array of unquoted column names.
Named parameters are:
unquoted_column_names
-
Optional Array of unquoted column names to use. Must contain only Strings. If column “id” is missing, it will be added for you.
# File lib/hoodoo/active/active_record/dated.rb, line 388 def quoted_column_name_string( unquoted_column_names: nil ) unquoted_column_names ||= self.attribute_names() unquoted_column_names = unquoted_column_names + [ 'id' ] unless unquoted_column_names.include?( 'id' ) return self.quoted_column_names( unquoted_column_names ).join( ',' ) end
As ::quoted_column_name_string, but returns a String appropriate for the history table. Notably, this requires a source column of “uuid” to be mapped in as column name “id” and works on the assumption that the primary key is “id”.
Named parameters are:
unquoted_column_names
-
Optional Array of unquoted column names to use. Must contain only Strings. If column “id” is missing, it will be added for you.
# File lib/hoodoo/active/active_record/dated.rb, line 406 def quoted_column_name_string_for_history( unquoted_column_names: nil ) unquoted_column_names ||= self.attribute_names primary_key_index = unquoted_column_names.index( 'id' ) if primary_key_index.nil? unquoted_column_names = unquoted_column_names + [ 'id' ] primary_key_index = unquoted_column_names.count - 1 end quoted_column_names = self.quoted_column_names( unquoted_column_names ) quoted_primary_key_name = quoted_column_names[ primary_key_index ] history_primary_key = '"uuid" AS ' << quoted_primary_key_name quoted_column_names[ primary_key_index ] = history_primary_key return quoted_column_names.join( ',' ) end
Takes an Array of unquoted column names and returns a new Array of names quoted by the current database adapter.
unquoted_column_names
-
Optional Array of unquoted column names to use. Must contain only Strings.
# File lib/hoodoo/active/active_record/dated.rb, line 372 def quoted_column_names( unquoted_column_names ) return unquoted_column_names.map do | c | ActiveRecord::Base.connection.quote_column_name( c ) end end