ce-greenbutton 0.1.0

data/lib/ce-greenbutton/model/gb_data_description.rb

@@ -0,0 +1,41 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'ce-greenbutton/utils'
+
+# Represents common data for a UsagePoint
+#
+# Author TCSASSEMBLER
+# Version 1.0
+class GbDataDescription
+  include Utils::Hash
+
+  # Represents the custodian value in the ApplicationInformation structure.
+  attr_accessor :custodian
+
+  # Represents the access_token used to retrieve the GreenButton data.
+  attr_accessor :user_id
+
+  # Represents the commodity value of the corresponding ReadingType structure.
+  attr_accessor :commodity
+
+  # Represents the currency value of the corresponding ReadingType structure.
+  attr_accessor :currency
+
+  # Represents the "uom" value of the corresponding ReadingType structure.
+  attr_accessor :unit_of_measure
+
+  # Represents the "powerOfTenMultiplier" value of the corresponding
+  # ReadingType structure.
+  attr_accessor :power_of_ten_multiplier
+
+  # Represents the last updated date/time
+  attr_accessor :updated
+
+  # An array of GbData
+  attr_accessor :gb_data_array
+
+  # Returns the parsed elements as a hash with key equals the property name and
+  # value equals the parsed value.
+  def _parse
+    to_hash
+  end
+end

data/lib/ce-greenbutton/model/gb_data_reading.rb

@@ -0,0 +1,23 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+# Represents an IntervalReading structure.
+#
+# Author ahmed.seddiq
+# Version 1.0
+class GbDataReading
+
+  # Represents the start time (local) value from the IntervalReading ->
+  # timePeriod structure
+  attr_accessor :time_start
+
+  # Represents the duration value from the IntervalReading -> timePeriod
+  # structure
+  attr_accessor :time_duration
+
+  # Represents the value element in the IntervalReading structure
+  attr_accessor :value
+
+  # Represents the cost element in the IntervalReading structure
+  attr_accessor :cost
+
+end

data/lib/ce-greenbutton/parser.rb

@@ -0,0 +1,54 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'ce-greenbutton/elements/gb_data_feed'
+module GreenButton
+  # Public: Defines a parse method. It accepts both strings and io inputs.
+  #
+  # Author ahmed.seddiq
+  # Version: 1.0
+  module Parser
+    # Public: Parses the given input to an instance of GbDataFeed. After parsing
+    # the GbDataFeed.entries will contain a hash of defined GbEntries. The key
+    # of the hash is the "self" link identifies each entry. the "up" links are
+    # also added to the hash with an array value aggregating all sub entries.
+    #
+    #
+    # For example:
+    #
+    #   if we have a feed with one UsagePoint, one MeterReading, three IntervalBlocks
+    #   the entries hash will be some thing like
+    #   {"http://url.of.usage.point.self" => GbEntry(of type UsagePoint)}
+    #   {"http://url.of.usage.point.up" => [GbEntry(of type UsagePoint)]}
+    #   {"http://url.of.meter.reading.self" => GbEntry(of type MeterReading)}
+    #   {"http://url.of.meter.reading.up" => [GbEntry(of type MeterReading)]}
+    #   {"http://url.of.interval.block.1.self" => GbEntry(of type IntervalBlock)}
+    #   {"http://url.of.interval.block.2.self" => GbEntry(of type IntervalBlock)}
+    #   {"http://url.of.interval.block.3.self" => GbEntry(of type IntervalBlock)}
+    #   {"http://url.of.interval.block.[1|2|3].up" =>
+    #   [GbEntry(of type IntervalBlock), GbEntry(of type IntervalBlock),
+    #   GbEntry(of type IntervalBlock)]
+    #
+    def self.parse(input)
+      feed = Parser::GbDataFeed.parse(input)
+      entries = {}
+      feed.entries.each do |entry|
+        entries[entry.self] = entry
+        if entries[entry.up].nil?
+          entries[entry.up] = []
+        end
+        entries[entry.up] << entry
+        entry.link = nil
+      end
+
+      feed.entries = entries
+      feed
+    end
+
+  end
+
+
+end
+
+
+
+
+

data/lib/ce-greenbutton/ruby_extensions.rb

@@ -0,0 +1,23 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+# Extending the Integer to add the utility method of extracting bits
+class Integer
+  # Extracts bits in range from: to to:
+  #
+  # Example:
+  #   10.bits(from:1, to:2)   # 1010
+  #   # => 1
+  def bits(options)
+    from = options[:from] || 0
+    to = options[:to]
+    val = self
+    unless from.nil?
+      val = val >> from
+    end
+    unless to.nil?
+      val = val & (2 ** (to - from + 1) - 1)
+    end
+
+    val
+  end
+end

data/lib/ce-greenbutton/utils.rb

@@ -0,0 +1,136 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'ice_cube'
+require 'ce-greenbutton/ruby_extensions'
+# Mixins for common functionality.
+#
+# Author: ahmed.seddiq
+# Version: 1.0
+#
+module Utils
+  module Hash
+    # Converts instance variables of an object to a hash.
+    #
+    # obj - the object to inspect
+    #
+    # Returns a hash representing the instance variables of the given object.
+    def to_hash
+      if self.instance_variables.length > 0
+        hash = {}
+        self.instance_variables.each do |var|
+          hash[var.to_s.delete('@')] = self.instance_variable_get(var)
+        end
+        hash
+      else
+        self
+      end
+    end
+  end
+
+  module DSTRule
+    # Converts the given DST rule to a Time instance indicating the start
+    # time of applying this rule.
+    #
+    # Based on the ESPI schema, The rule string is encoded as follows:
+    #
+    # Bits  0 - 11: seconds 0 - 3599
+    # Bits 12 - 16: hours 0 - 23
+    # Bits 17 - 19: day of the week 0 = not applicable, 1 - 7 (Monday = 1)
+    # Bits:20 - 24: day of the month 0 = not applicable, 1 - 31
+    # Bits: 25 - 27: operator  (detailed below)
+    # Bits: 28 - 31: month 1 - 12
+    #
+    # Rule value of 0xFFFFFFFF means rule processing/DST correction is disabled.
+    #
+    # The operators:
+    #
+    # 0: DST starts/ends on the Day of the Month
+    # 1: DST starts/ends on the Day of the Week that is on or after the Day of the Month
+    # 2: DST starts/ends on the first occurrence of the Day of the Week in a month
+    # 3: DST starts/ends on the second occurrence of the Day of the Week in a month
+    # 4: DST starts/ends on the third occurrence of the Day of the Week in a month
+    # 5: DST starts/ends on the forth occurrence of the Day of the Week in a month
+    # 6: DST starts/ends on the fifth occurrence of the Day of the Week in a month
+    # 7: DST starts/ends on the last occurrence of the Day of the Week in a month
+    #
+    # An example: DST starts on third Friday in March at 1:45 AM.  The rule...
+    # Seconds: 2700
+    # Hours: 1
+    # Day of Week: 5
+    # Day of Month: 0
+    # Operator: 4
+    # Month: 3
+    #
+    # rule - the dst rule, it can be the dst start rule or dst end rule.
+    # Returns a Time instance representing the starting time of applying the rule
+    #
+    def to_time(rule)
+      if rule.is_a? String
+        # expected to be in hex
+        rule = rule.to_i(16)
+      end
+      if rule == 0xFFFFFFFF
+        return nil
+      end
+
+      parts = extract_parts(rule)
+
+      # start a schedule with 1 January of current year
+      current_year = DateTime.now.year
+      end_of_year = Time.new(current_year, 12, 31,23,59,59)
+      date = nil
+      case parts[:operator]
+        when 0
+          raise InvalidDstRuleError, 'day of month must be provided for operator 0' if parts[:day_of_month] == 0
+          date = Time.new(current_year, parts[:month], parts[:day_of_month])
+        when 1
+          raise InvalidDstRuleError, 'day of month must be provided for operator 1' if parts[:day_of_month] == 0
+          raise InvalidDstRuleError, 'day of week must be provided for operator 1' if parts[:day_of_week] == 0
+          # first day_of_week on or after the day of month
+          schedule = IceCube::Schedule.new(Date.new(current_year, parts[:month], parts[:day_of_month]))
+          # It may be in the next month
+          months = [parts[:month], parts[:month] + 1]
+          months = [parts[:month]] if parts[:month] == 12
+          schedule.add_recurrence_rule IceCube::Rule.yearly.until(end_of_year).month_of_year(months).day_of_week(parts[:day_of_week] % 7 => [1, 2, 3, 4, 5])
+          dates = schedule.all_occurrences
+          raise InvalidDstRuleError, "Can't find day of week on or after the given day of month" if dates.length == 0
+          date = dates[0]
+        else
+          raise InvalidDstRuleError, 'day of week must be provided for operators 2..7' if parts[:day_of_week] == 0
+          # Last occurrence of day_of_week in the month
+          order_in_month = parts[:operator] - 1
+          order_in_month = -1 if (parts[:operator] == 7)
+          schedule = IceCube::Schedule.new(Date.new(current_year, 1, 1))
+          schedule.add_recurrence_rule IceCube::Rule.yearly.until(end_of_year).month_of_year(parts[:month]).day_of_week(parts[:day_of_week] % 7 => [order_in_month])
+          dates = schedule.all_occurrences
+          raise InvalidDstRuleError, "Can't find day of week on or after the given day of month" if dates.length == 0
+          date = dates[0]
+      end
+
+      time = date.to_i
+      time += (parts[:hours] * 60 * 60) + parts[:seconds]
+      Time.at(time)
+    end
+
+    private
+    def extract_parts(rule)
+      parts = {}
+      parts[:seconds] = rule.bits(from: 0, to: 11)
+      parts[:hours] = rule.bits(from: 12, to: 16)
+      parts[:day_of_week] = rule.bits(from: 17, to: 19)
+      parts[:day_of_month] = rule.bits(from: 20, to: 24)
+      parts[:operator] = rule.bits(from: 25, to: 27)
+      parts[:month] = rule.bits(from: 28, to: 31)
+
+      # validate extracted values
+      raise InvalidDstRuleError, 'seconds should be from 0 - 3599' unless parts[:seconds] < 3600
+      raise InvalidDstRuleError, 'hours should be from 0 - 23' unless parts[:hours] < 24
+      raise InvalidDstRuleError, 'day_of_week should be from 0 - 7' unless parts[:day_of_week] < 8
+      raise InvalidDstRuleError, 'day_of_month should be from 0 - 31' unless parts[:day_of_week] < 32
+      raise InvalidDstRuleError, 'month should be from 1 - 12' unless parts[:month].between?(1, 12)
+      parts
+    end
+
+    class InvalidDstRuleError < Exception
+    end
+  end
+end

data/lib/ce-greenbutton/version.rb

@@ -0,0 +1,3 @@
+module GreenButton
+  VERSION = "0.1.0"
+end

data/lib/ce-greenbutton.rb

@@ -0,0 +1,352 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'open-uri'
+require 'date'
+require 'ce-greenbutton/parser'
+require 'ce-greenbutton/elements/gb_application_information'
+require 'ce-greenbutton/elements/gb_entry'
+
+# The main entry of the module. provides the download_data method that will
+#   download and parse GreenButton data.
+# For example:
+#   # The following will download and parse all data for subscription
+#   require 'ce-greenbutton'
+#   GreenButton.config(reg_access_token: "your access token"
+#                      application_information_url: "http://app_info_url")
+#   gb = GreenButton.download_data('your access token', 'http://greenbutton.data.url')
+#   # => [gb_data_description]
+#
+#   # The following will download and parse all data for 2013
+#   require 'date'
+#   require 'ce-greenbutton'
+#   GreenButton.config(reg_access_token: "your access token"
+#                      application_information_url: "http://app_info_url")
+#   gb = GreenButton.download_data('your access token',
+#         'http://greenbutton.data.url'), Date.new(2013,1,1), Date.new(2013,12,31))
+#   # => [gb_data_description]
+#
+#
+# Changes for v1.1 (SunShot - Clearly Energy GreenButton Ruby Gem Update)
+#   1. added new method download_data_ftp
+#   2. parsing code is refactored to parse_data private method.
+#   3. download_data method is updated to use the parse_data method.
+#   4. config method is updated to support ftp options.
+#   5. check_config method is updated to check ftp options.
+#   6. added check_arguments_ftp method.
+#
+# Author: ahmed.seddiq
+# Version: 1.1
+module GreenButton
+
+  # Constant: the known data kind names mapped to the kind value,
+  #  the values are retrieved from the GreenButton xml schema.
+  SERVICEKIND_NAMES = {
+      0 => 'electricity',
+      1 => 'gas',
+      2 => 'water',
+      3 => 'time',
+      4 => 'heat',
+      5 => 'refuse',
+      6 => 'sewerage',
+      7 => 'rates',
+      8 => 'tvLicence',
+      9 => 'internet'
+  }
+
+  # Hash used to hold registered GreenButton data interpreters.
+  # Key is the kind value of the data, the value is the interpreter module.
+  @interpreters = {}
+
+  # Public: Gets the interpreter of the given kind.
+  # kind  - the kind of the GreenButton Data
+  # Returns the registered interpreter for the given kind, or nil if none found.
+  def self.interpreter(kind)
+    @interpreters[kind]
+  end
+
+  # Public: Downloads and parses the GreenButton data for the given
+  #   subscription. It also allows to filter returned readings by date.
+  #
+  # access_token        - represents the retail customer access token.
+  # subscription_id     - represents the retail customer resourceURI.
+  # interval_start_time - represents the start date to retrieve data.
+  # interval_end_time   - represents the end date to retrieve data.
+  #
+  # Examples
+  #
+  #   # The following will download and parse all data for 2013
+  #   require 'date'
+  #   require 'ce-greenbutton'
+  #   gb = GreenButton.download_data('688b026c-665f-4994-9139-6b21b13fbeee', 5,
+  #         Date.new(2013,1,1), Date.new(2013,12,31))
+  #   # => [gb_data_description]
+  #
+  # Returns an array of gb_data_description
+  # Raises ArgumentError if any passed argument is invalid.
+  # Propagates errors from OpenURI for any connection/authentication
+  def self.download_data(access_token, subscription_id,
+      interval_start_time = nil, interval_end_time = nil)
+    check_arguments(access_token, subscription_id, interval_start_time,
+                    interval_end_time)
+
+    # Construct the resource url
+    resource_url = subscription_id
+    params = []
+    if interval_start_time
+      params << "published-min=#{interval_start_time.to_s}"
+    end
+    if interval_end_time
+      params << "published-max=#{interval_end_time.to_s}"
+    end
+    resource_url += (resource_url.index('?').nil?? '?':'&')+ params.join('&') if
+                params.length > 0
+    data = open(resource_url,
+                'Authorization' => "Bearer #{access_token}")
+    parse_data(access_token, data) #Return
+  end
+
+  # Public: Downloads and parses the GreenButton data, hosted in a FTP server.
+  # The FTP host, user, password and path is configured through the config
+  # method.
+  # The File name is constructed as follows:
+  #  D_{utility_name}_{application_id}_{YYYYMMDDHHMMSS}.XML.
+  #
+  # application_id  - represents the GreenButton 3rd party application id.
+  # time            - used to construct file name. (optional, defaults
+  #                   to current time)
+  # utility_name    - represents the utility name, used to construct the
+  #                   XML file name.
+  #
+  # Returns an array of gb_data_description
+  # Raises ArgumentError if any passed argument is invalid.
+  # Propagates errors from OpenURI for any connection/authentication
+  def self.download_data_ftp(application_id, time=Time.now, utility_name)
+    check_arguments_ftp(application_id, time, utility_name)
+
+    # construct the ftp url
+    ftp_url = "ftp://#{@ftp_user}:#{@ftp_password}@#{@ftp_host}/#{@ftp_path}/" +
+      "D_#{utility_name}_#{application_id}_#{time.strftime('%Y%m%d%H%M%S')}.XML"
+
+    parse_data(@ftp_user, open(ftp_url))
+  end
+
+  # Parses the given greenbutton data to the corresponding ruby objects.
+  #
+  # user_id - identifies the owner of the data.
+  # data    - The source GreenButton xml data, can be string, or any stream returning
+  #         from a call to open(uri)
+  #
+  # Returns the parsed array of gb_data_description
+  private
+  def self.parse_data(user_id, data)
+    # get ApplicationInformation
+    app_info = GreenButton::Parser::GbApplicationInformation.
+        parse(open(@application_information_url,
+                   'Authorization' => "Bearer #{@reg_access_token}"))
+
+    feed = GreenButton::Parser.parse(data)
+    gb = []
+    unsupported_kinds = []
+    feed.entries.each_pair do |key, entry|
+      if entry.is_a? GreenButton::Parser::GbEntry
+        if entry.type == 'UsagePoint'
+          usage_point = entry.content.usage_point
+          if @interpreters[usage_point.kind].nil?
+            unsupported_kinds << usage_point.kind
+          else
+            gb_data_description = @interpreters[usage_point.kind]
+                                      .get_gb_data_description(entry, feed)
+            gb_data_description.custodian = app_info.data_custodian_id
+            gb_data_description.user_id = user_id
+            gb << gb_data_description
+          end
+
+        end
+      end
+    end
+    if gb.length == 0 and unsupported_kinds.length > 0
+      raise InvalidGbDataError, "Received unsupported GreenButton data #{unsupported_kinds.to_s}
+          Only Electricity (kind = 0) is supported."
+    end
+    gb
+  end
+
+
+  # Public: Registers a new Interpreter for the given data kind.
+  #
+  # kind                - represents the kind of GreenButton data.
+  # interpreter_name    - the name of the interpreter (String or Symbol)
+  #
+  # Examples
+  #
+  #   # To register an interpreter for the gas data (kind = 1)
+  #   # implement the interpreter with name
+  #   #  GreenButton::Interpreters::GasInterpreter
+  #   gb = GreenButton.register_interpreter(1, :gas)
+  #
+  # Returns nothing.
+  # Raises ArgumentError if any passed argument is invalid.
+  def self.register_interpreter(kind, interpreter_name)
+    unless kind.is_a?Integer and kind >= 0
+      raise ArgumentError, 'kind must be positive integer'
+    end
+    unless interpreter_name.is_a?Symbol or interpreter_name.is_a?String
+      raise ArgumentError, 'interpreter_name must be symbol or string'
+    end
+    require "ce-greenbutton/interpreters/#{interpreter_name}_interpreter"
+    @interpreters[kind] = GreenButton::Interpreters.const_get(
+        "#{interpreter_name.to_s.capitalize}Interpreter")
+  end
+
+
+  # Public: configures the GreenButton module. It must be called before usage.
+  #
+  # Supported properties:
+  #   reg_access_token: The registration access token, required,
+  #   application_information_url: required,
+  #   ftp-host: required for download_data_ftp,
+  #   ftp-user: required for download_data_ftp,
+  #   ftp-password: required for download_data_ftp,
+  #   ftp-path: the ftp directory path with no leading or trailing backslashes,
+  # optional for download_data_ftp, defaults to empty string.
+  #
+  # For example:
+  #   GreenButton.config(reg_access_token: 'your access token',
+  #                      application_information_url: 'http://app_info_url',
+  #                      ftp-host: 'your-ftp-host',
+  #                      ftp-user: 'ftp-user',
+  #                      ftp-password: 'ftp-password',
+  #                      ftp-path: 'path/to/ftp/directory' )
+  #
+  # Returns nothing.
+  #
+  def self.config(options = {})
+    @reg_access_token = options[:reg_access_token] || options['reg_access_token']
+    @application_information_url = options[:application_information_url] ||
+        options['application_information_url']
+    @ftp_host = options[:ftp_host] || options['ftp_host']
+    @ftp_user = options[:ftp_user] || options['ftp_user']
+    @ftp_password = options[:ftp_password] || options['ftp_password']
+    @ftp_path = options[:ftp_path] || options['ftp_path'] || ''
+  end
+
+  # try to load interpreters
+  SERVICEKIND_NAMES.each_pair do |kind, name|
+    begin
+      self.register_interpreter kind, name
+    rescue LoadError
+      # ignored
+    end
+  end
+
+  # Helper method to check arguments' validity of the download_data method.
+  #
+  # access_token        - represents the retail customer access token.
+  # subscription_id     - represents the retail customer resourceURI.
+  # interval_start_time - represents the start date to retrieve data (optional).
+  # interval_end_time   - represents the end date to retrieve data (optional).
+  #
+  # Returns nothing.
+  # Raises ConfigurationError If the GreenButton was not configured by
+  #                           GreenButton.config prior to usage.
+  # Raises ArgumentError if any passed argument is invalid.
+  private
+  def self.check_arguments(access_token, subscription_id, interval_start_time,
+      interval_end_time)
+    check_config
+
+    unless access_token.is_a? String and access_token.strip.length > 0
+      raise ArgumentError, 'access_token must be a non-empty string.'
+    end
+    unless subscription_id =~ URI::regexp
+      raise ArgumentError, 'subscription_id must be a valid url'
+    end
+    unless interval_start_time.nil? or interval_start_time.is_a? Date
+      raise ArgumentError, 'interval_start_time must be a valid Date object.'
+    end
+    unless interval_end_time.nil? or interval_end_time.is_a? Date
+      raise ArgumentError, 'interval_end_time must be a valid Date object.'
+    end
+  end
+
+  # Helper method to check arguments' validity of the download_data_ftp method.
+  #
+  # application_id  - represents the GreenButton 3rd party application id.
+  # time            - used to construct file name. (optional, defaults
+  #                   to current time)
+  # utility_name    - represents the utility name, used to construct the
+  #                   XML file name.
+  #
+  # Returns nothing.
+  # Raises ConfigurationError If the GreenButton was not configured by
+  #                           GreenButton.config prior to usage.
+  # Raises ArgumentError if any passed argument is invalid.
+  def self.check_arguments_ftp(application_id, time , utility_name)
+    # check module configuration with ftp options.
+    check_config(true)
+    unless application_id.is_a? String and application_id.strip.length > 0
+      raise ArgumentError, 'application_id must be a non-empty string.'
+    end
+
+    unless utility_name.is_a? String and utility_name.strip.length > 0
+      raise ArgumentError, 'utility_name must be a non-empty string.'
+    end
+
+    unless time.is_a? Time
+      raise ArgumentError, 'time must be a Time object.'
+    end
+  end
+
+  # Checks is the module is properly configured.
+  #
+  # ftp - whether to check ftp-related options.
+  #
+  # Raises ConfigurationError if any required configuration is missing.
+  def self.check_config(ftp=false)
+    if @application_information_url.nil?
+      raise ConfigurationError, 'application_information_url is not set, please call
+                           GreenButton.config first'
+    end
+    if @reg_access_token.nil?
+      raise ConfigurationError, 'registration access token is not set please call
+                           GreenButton.config first'
+    end
+
+    if ftp
+      if @ftp_host.nil?
+        raise ConfigurationError, 'ftp_host is not set, please call
+                           GreenButton.config first'
+      end
+      if @ftp_user.nil?
+        raise ConfigurationError, 'ftp_user is not set, please call
+                           GreenButton.config first'
+      end
+      if @ftp_password.nil?
+        raise ConfigurationError, 'ftp_password is not set, please call
+                           GreenButton.config first'
+      end
+    end
+  end
+
+  # This error will be raised if the download_data method was called before calling
+  #   the GreenButton.config
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class ConfigurationError < Exception
+
+  end
+
+  # Will be raised if a parsing or semantic error occurred during the data
+  #  parsing/interpretation
+  #
+  # For example, if the data does not contain a LocalTimeParameters structure
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class InvalidGbDataError < Exception
+
+  end
+
+
+end