amee-data-persistence 1.0.0

data/generators/persistence/templates/config/persistence.yml.erb

@@ -0,0 +1 @@
+method: <%= method %>

data/generators/persistence/templates/db/migrate/001_create_persistence_tables.rb

@@ -0,0 +1,29 @@
+class CreatePersistenceTables < ActiveRecord::Migration
+  def self.up
+    create_table :calculations do |t|
+      t.string  "profile_uid"
+      t.string  "profile_item_uid"
+      t.string  "calculation_type"
+
+      t.timestamps
+    end
+
+    create_table :terms do |t|
+      t.integer  "calculation_id"
+      t.string  "label"
+      t.string  "value"
+
+      t.timestamps
+    end
+
+    add_index :calculations, :calculation_type
+    add_index :calculations, :profile_item_uid
+    add_index :terms, [:calculation_id, :label], :name => "calc_id_label_index"
+    add_index :terms, [:label, :value, :calculation_id], :name => "label_name_calc_id_index"
+  end
+
+  def self.down
+    drop_table :calculations
+    drop_table :terms
+  end
+end

data/generators/persistence/templates/db/migrate/002_add_unit_columns.rb

@@ -0,0 +1,15 @@
+class AddUnitColumns < ActiveRecord::Migration
+  def self.up
+
+    add_column :terms, :unit, :string
+    add_column :terms, :per_unit, :string
+
+  end
+
+  def self.down
+
+    remove_column :terms, :unit, :string
+    remove_column :terms, :per_unit
+
+  end
+end

data/generators/persistence/templates/db/migrate/003_add_value_types.rb

@@ -0,0 +1,9 @@
+class AddValueTypes < ActiveRecord::Migration
+  def self.up
+    add_column :terms, :value_type, :string
+  end
+
+  def self.down
+    remove_column :terms, :value_type
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/lib/amee-data-persistence.rb

@@ -0,0 +1,12 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+require 'rubygems'
+gem 'activerecord', "~> 2.3.9"
+require 'active_record'
+require 'quantify'
+
+require 'amee/data_abstraction/calculation_collection'
+require 'amee/db/calculation'
+require 'amee/db/term'
+require 'amee/db/config'

data/lib/amee/data_abstraction/calculation_collection.rb

@@ -0,0 +1,22 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::CalculationCollection
+
+module AMEE
+  module DataAbstraction
+
+    # Class for containing a collection of instances of the class
+    # <i>OngoingCalculation</i>. This class is used to return mutliple
+    # ongoing calculation objects using the <i>OngoingCalculation.find</i>
+    # class method.
+    #
+    # This class is extended by the amee-reporting gem to provide analytical
+    # methods which can be applied across collections of caluclations (e.g.
+    # averages and summations of terms, sorting, etc.)
+    #
+    class CalculationCollection < Array
+
+    end
+  end
+end

data/lib/amee/data_abstraction/persistence_support.rb

@@ -0,0 +1,274 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Module AMEE::DataAbstraction::PersistenceSupport
+
+module AMEE
+  module DataAbstraction
+
+    # This module provides a number of class and instance methods which are
+    # added to the <i>AMEE::DataAbstraction::OngoingCalculation</i> class if
+    # the amee-data-persistence gem is required. These methods provide an
+    # interface between the <i>AMEE::DataAbstraction::OngoingCalculation</i>
+    # class (and its instances) and the the <i>AMEE::Db::Calculation</i> class
+    # which provides database persistence for calculations.
+    #
+    module PersistenceSupport
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Represents the instance of <i>AMEE::Db::Calculation</i> which is
+      # associated with <tt>self</tt>.
+      #
+      attr_accessor :db_calculation
+
+      # Represents the primary key of the associated database record (instance of
+      # <i>AMEE::Db::Calculation</i>) if a database record for <tt>self</tt> is
+      # defined.
+      #
+      def id
+        db_calculation.nil? ? nil : db_calculation.id
+      end
+
+      # Same as <i>save</i> but raises an exception on error
+      def save!
+        validate!
+        record = db_calculation || get_db_calculation
+        record.update_calculation!(to_hash)
+      end
+
+      # Saves a representation of <tt>self<tt> to the database. Returns
+      # <tt>true</tt> if successful, otherwise <tt>false</tt>.
+      #
+      def save
+        save!
+        true
+      rescue ActiveRecord::RecordNotSaved
+        false
+      end
+
+      # Deletes the database record for <tt>self</tt> and any associated profile
+      # item value in the AMEE platform.
+      #
+      def delete
+        record = db_calculation || get_db_calculation
+        AMEE::Db::Calculation.delete record.id
+        self.db_calculation = nil
+        delete_profile_item
+      end
+
+      # As <i>calculate_and_save</i> but raises an exception on error
+      def calculate_and_save!
+        calculate!
+        save!
+      end
+      
+      # Performs the calculation against AMEE and saves it to the database
+      def calculate_and_save
+        calculate_and_save!
+        true
+      rescue ActiveRecord::RecordNotFound, AMEE::DataAbstraction::Exceptions::DidNotCreateProfileItem
+        false
+      end
+
+      # Finds the instance of database record associated with <tt>self</tt> based
+      # on the <tt>profile_item_uid</tt> attribute of <tt>self</tt> and sets the
+      # <tt>db_calculation</tt> attribute of <tt>self</tt> to the associated
+      # instance of <i>AMEE::Db::Calculation</i>.
+      #
+      def get_db_calculation
+        self.db_calculation = AMEE::Db::Calculation.find_or_initialize_by_profile_item_uid(send :profile_item_uid)
+      end
+
+      # Returns the subset of terms associated with <tt>self</tt> which should be
+      # passed for database persistence, based on the configuration set in
+      # <i>AMEE::Db::Config#storage_method</i>.
+      #
+      def stored_terms
+        stored_terms = []
+        stored_terms += metadata if OngoingCalculation.store_metadata?
+        stored_terms += inputs if OngoingCalculation.store_inputs?
+        stored_terms += outputs if OngoingCalculation.store_outputs?
+        stored_terms
+      end
+
+      # Returns a hash representation of <tt>self</tt>. By default, only the terms
+      # which are configured for persistence (according to
+      # <i>AMEE::Db::Config#storage_method</i>) are included. All terms can be
+      # explicitly required by passing the symbol <tt>:full</tt> as an argument.
+      # E.g.
+      #
+      #   # Set storage to include everything
+      #   AMEE::Db::Config.storage_method=:everything
+      #
+      #   my_calculation.to_hash       #=> { :calculation_type => :fuel,
+      #                                      :profile_item_uid => nil,
+      #                                      :profile_uid => "A8D8R95EE7DH",
+      #                                      :type => { :value => 'coal'},
+      #                                      :location => { :value => 'facility' },
+      #                                      :mass => { :value => 250,
+      #                                                 :unit => <Quantify::Unit ... > },
+      #                                      :co2 => { :value => 60.5,
+      #                                                :unit => <Quantify::Unit ... > }}
+      #
+      #   # Set storage to include only oputputs and metadata
+      #   AMEE::Db::Config.storage_method=:outputs
+      #
+      #   my_calculation.to_hash       #=> { :calculation_type => :fuel,
+      #                                      :profile_item_uid => nil,
+      #                                      :profile_uid => "A8D8R95EE7DH",
+      #                                      :location => { :value => 'facility' },
+      #                                      :co2 => { :value => 60.5,
+      #                                                :unit => <Quantify::Unit ... > }}
+      #
+      #   # Set storage to include only metadata
+      #   AMEE::Db::Config.storage_method=:metadata
+      #
+      #   my_calculation.to_hash       #=> { :calculation_type => :fuel,
+      #                                      :profile_item_uid => nil,
+      #                                      :profile_uid => "A8D8R95EE7DH",
+      #                                      :location => { :value => 'facility' },
+      #
+      #   # Get full hash represenation regardless of storage level
+      #   my_calculation.to_hash :full #=> { :calculation_type => :fuel,
+      #                                      :profile_item_uid => nil,
+      #                                      :profile_uid => "A8D8R95EE7DH",
+      #                                      :type => { :value => 'coal'},
+      #                                      :location => { :value => 'facility' },
+      #                                      :mass => { :value => 250,
+      #                                                 :unit => <Quantify::Unit ... > },
+      #                                      :co2 => { :value => 60.5,
+      #                                                :unit => <Quantify::Unit ... > }}
+      #
+      def to_hash(representation=:stored_terms_only)
+        hash = {}
+        hash[:calculation_type] = label
+        hash[:profile_item_uid] = send :profile_item_uid
+        hash[:profile_uid] = send :profile_uid
+        (representation == :full ? terms : stored_terms ).each do |term|
+          sub_hash = {}
+          sub_hash[:value] = term.value
+          sub_hash[:unit] = term.unit if term.unit
+          sub_hash[:per_unit] = term.per_unit if term.per_unit
+          hash[term.label.to_sym] = sub_hash
+        end
+        return hash
+      end
+
+      module ClassMethods
+
+
+        # Find and initialize instance(s) of <i>OngoingCalculation</i> from the
+        # database using standard <i>ActiveRecord</i> <tt>find</tt> options.
+        # Returns <tt>nil</tt> if no records are found. If multiple records are
+        # found they are returned via an instance of the
+        # <i>CalculationCollection</i> class. E.g.,
+        #
+        #   OngoingCalculation.find(:first)
+        #
+        #                    #=> <AMEE::DataAbstraction::OngoingCalculation ... >
+        #
+        #  OngoingCalculation.find(:first,
+        #                          :conditions => {:profile_item_uid => "K588DH47SMN5"})
+        #
+        #                    #=> <AMEE::DataAbstraction::OngoingCalculation ... >
+        #
+        #   OngoingCalculation.find(:all)
+        #
+        #                    #=> <AMEE::DataAbstraction::CalculationCollection ... >
+        #
+        def find(*args)
+          unless args.last.is_a? Symbol or args.last.is_a? Integer
+            raise ActiveRecord::ActiveRecordError.new("Using :include with terms and then conditioning on terms doesn't work due to rails caching.  Use the :joins option instead.") if args.last[:include].to_s.match(/terms/) && args.last[:conditions].to_s.match(/terms/)
+            args.last[:include] = "terms" if args.last[:joins].to_s.match(/terms/)
+          end
+          result = AMEE::Db::Calculation.find(*args)
+          return nil unless result
+          if result.respond_to?(:map)
+            CalculationCollection.new(result.compact.map { |calc| initialize_from_db_record(calc) })
+          else
+            initialize_from_db_record(result)
+          end
+        end
+
+        # Find calculations of type  <tt>type</tt> in the database and initialize
+        # as instances of <i>OngoingCalculation</i>. Returns <tt>nil</tt> if no
+        # records are found. If multiple records are found they are returned via
+        # an instance of the <i>CalculationCollection</i> class.
+        #
+        # Specify that either the first or all records should be returns by passing
+        # <tt>:first</tt> or <tt>:all</tt> as the first argument. The unique label
+        # of the calcualtion type required should be passed as the second argument.
+        # Standard options associated with the <i>ActiveRecord</i> <tt>find</tt>
+        # class method can be passed as the third argument. E.g.,
+        #
+        #   OngoingCalculation.find_by_type(:first,:electricity)
+        #
+        #                    #=> <AMEE::DataAbstraction::OngoingCalculation ... >
+        #
+        #   OngoingCalculation.find_by_type(:all,:fuel)
+        #
+        #                    #=> <AMEE::DataAbstraction::CalculationCollection ... >
+        #
+        def find_by_type(ordinality,type,options={})
+          OngoingCalculation.find(ordinality, options.merge(:conditions => {:calculation_type => type.to_s}))
+        end
+
+        # Initialize and return an instance of <i>OngoingCalculation</i> based
+        # on the database record represented by <tt>record</tt>.
+        #
+        def initialize_from_db_record(record)
+          unless record.is_a? AMEE::Db::Calculation
+            raise ArgumentError.new("Argument is not of class AMEE::Db::Calculation")
+          end
+          calc = Calculations.calculations[record.type].begin_calculation
+          calc.db_calculation = record
+          # Means that validation needs to occur before calcs are saved
+    		  calc.choose_without_validation!(record.to_hash)
+          return calc
+        end
+
+        # Returns a new instance of the <i>AMEE::Db::BaseConfig</i> class
+        def storage_config
+          AMEE::Db::BaseConfig.new
+        end
+
+        # Returns the currently configured storage level for database persistence,
+        # i.e. whether all terms should be persisted versus outputs and/or
+        # metadata only.
+        #
+        def storage_method
+          storage_config.storage_method
+        end
+
+        # Returns <tt>true</tt> if all terms should be persisted within the
+        # database according to the currently configured storage level (See
+        # <i>AMEE::Db::BaseConfig</i>). Otherwise, returns <tt>false</tt>.
+        #
+        def store_inputs?
+          storage_config.store_everything?
+        end
+
+        # Returns <tt>true</tt> if output terms should be persisted within the
+        # database according to the currently configured storage level (See
+        # <i>AMEE::Db::BaseConfig</i>). Otherwise, returns <tt>false</tt>.
+        #
+        def store_outputs?
+          storage_config.store_outputs?
+        end
+
+        # Returns <tt>true</tt> if metadata terms should be persisted within the
+        # database according to the currently configured storage level (See
+        # <i>AMEE::Db::BaseConfig</i>). Otherwise, returns <tt>false</tt>.
+        #
+        def store_metadata?
+          storage_config.store_metadata?
+        end
+
+      end
+
+    end
+  end
+end

data/lib/amee/db/calculation.rb

@@ -0,0 +1,156 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::Db::Calculation
+
+module AMEE
+  module Db
+
+    # This class represents a database record for a calculation performed using
+    # the <i>AMEE:DataAbstraction::OngoingCalculation</i> class. This class stores
+    # the primary calculation level attributes such as the calculation
+    # <tt>calculation_type</tt>, <tt>profile_uid</tt> and <tt>profile_item_uid</tt>.
+    #
+    # The values and attributes of specific calculation terms are stored via the
+    # related class <i>AMEE::Db::Term</i>.
+    #
+    # This class is typically used by proxy, via the <tt>find</tt>,
+    # <tt>find_by_type</tt>, <tt>#save</tt>, <tt>#delete</tt>, and
+    # <tt>#get_db_calculation</tt> methods associated with the
+    # <i>AMEE:DataAbstraction::OngoingCalculation</i> class.
+    #
+    class Calculation < ActiveRecord::Base
+
+      has_many              :terms, :class_name => "AMEE::Db::Term", :dependent => :destroy
+      validates_presence_of :calculation_type
+      validates_format_of   :profile_item_uid, :with => /\A([A-Z0-9]{12})\z/, :allow_nil => true, :allow_blank => true
+      validates_format_of   :profile_uid, :with => /\A([A-Z0-9]{12})\z/, :allow_nil => true, :allow_blank => true
+      before_save           :validate_calculation_type
+
+      # Standardize the <tt>calculation_type</tt> attribute to <i>String</i>
+      # format. Called using before filter prior to record saving to ensure
+      # string serialization.
+      #
+      def validate_calculation_type
+        self.calculation_type = calculation_type.to_s
+      end
+
+      # Convenience method for returning the <tt>calculation_type</tt> attribute
+      # of <tt>self</tt> in canonical symbol form.
+      #
+      def type
+        calculation_type.to_sym
+      end
+
+      # Returns the subset of all instance attributes which should be editable via
+      # mass update methods and which should be included in hash representations of
+      # self, i.e. those passed in explcitly as data rather than added by
+      # <i>ActiveRecord</i> (e.g. <tt>id</tt>, <tt>created_at</tt>, etc.).
+      #
+      def primary_calculation_attributes
+        attributes.keys.reject {|attr| ['id','created_at','updated_at'].include? attr }
+      end
+
+      # Update the attributes of <tt>self</tt> and those of any related terms,
+      # according to the passed <tt>options</tt> hash. Any associated terms which
+      # are not represented in <tt>options</tt> are deleted.
+      #
+      # Term attributes provided in <tt>options</tt> should be keyed with the
+      # term label and include a sub-hash with keys represent one or more of
+      # :value, :unit and :per_unit. E.g.,
+      #
+      #   options = { :profile_item_uid => "W93UEY573U4E8",
+      #               :mass => { :value => 23 },
+      #               :distance => { :value => 1400,
+      #                              :unit => <Quantify::Unit::SI ... > }}
+      #
+      #   my_calculation.update_calculation!(options)
+      #
+      def update_calculation!(options)
+        primary_calculation_attributes.each do |attr|
+          if options.keys.include? attr.to_sym
+            update_calculation_attribute!(attr,options.delete(attr.to_sym),false)
+          end
+        end
+        save!
+        options.each_pair do |attribute,value|
+          add_or_update_term!(attribute,value)
+        end
+        delete_unspecified_terms(options)
+        reload
+      end
+
+      # Update the attribute of <tt>self</tt> represented by the label
+      # <tt>key</tt> with the value of <tt>value</tt>. By default,
+      # the <tt>#save!</tt> method is called, in turn calling the class
+      # validations.
+      #
+      # Specify that the record should not be saved by passing <tt>false</tt>
+      # as the final argument.
+      #
+      def update_calculation_attribute!(key,value,save=true)
+        # use attr_accessor (via #send) method rather than
+        # #update_attribute so that validations are performed
+        #
+        send("#{key}=", (value.nil? ? nil : value.to_s))
+        save! if save
+      end
+
+      # Add, or update an existing, associated term represented by the label
+      # <tt>label</tt> and value, unit and/or per_unit attributes defined by
+      # <tt>data</tt>. The <tt>data</tt> argument should be a hash with keys
+      # represent one or more of :value, :unit and :per_unit. E.g.,
+      #
+      #   data = {  :value => 1400,
+      #            :unit => <Quantify::Unit::SI ... > }
+      #
+      #   my_calculation.add_or_update_term!(:distance, data)
+      #
+      # This method is called as part of the <tt>#update_calculation!</tt>
+      # method
+      #
+      def add_or_update_term!(label,data)
+        term = Term.find_or_initialize_by_calculation_id_and_label(id,label.to_s)
+        term.update_attributes!(data)
+      end
+
+      # Delete all of the terms which are not explicitly referenced in the
+      # <tt>options</tt> hash.
+      #
+      # This method is called as part of the <tt>#update_calculation!</tt>
+      # method
+      #
+      def delete_unspecified_terms(options)
+        terms.each do |term|
+          Term.delete(term.id) unless options.keys.include? term.label.to_sym
+        end
+      end
+
+      # Returns a <i>Hash</i> representation of <tt>self</tt> including a only
+      # the data explicitly passed in (those added by <i>ActiveRecord</i> -
+      # <tt>created</tt>, <tt>updated</tt>, <tt>id</tt> - are ignored) as well
+      # as sub-hashes for all associated terms. E.g.,
+      #
+      #   my_calculation.to_hash       #=> { :profile_uid => "EYR758EY36WY",
+      #                                      :profile_item_uid => "W83URT48DY3W",
+      #                                      :type => { :value => 'car' },
+      #                                      :distance => { :value => 1600,
+      #                                                     :unit => <Quantify::Unit::SI> },
+      #                                      :co2 => { :value => 234.1,
+      #                                                :unit => <Quantify::Unit::NonSI> }}
+      #
+      # This method can be used to initialize instances of the class
+      # <tt>OngoingCalculation</tt> by providing the hashed options for any of 
+      # the <tt>choose...</tt> methods.
+      #
+      def to_hash
+        hash = {}
+        terms.each { |term| hash.merge!(term.to_hash) }
+        [ :profile_item_uid, :profile_uid ].each do |attr|
+          hash[attr] = self.send(attr)
+        end
+        return hash
+      end
+    end
+  end
+end