amon 0.3.0

data/README.md

@@ -0,0 +1,76 @@
+Ruby Client for the AMEE AMON API
+=================================
+
+This is a Ruby client library for the [AMEE](http://www.amee.com/) <abbr title="AMEE Monitoring Object Notation">AMON</abbr> <abbr title="Application Programming Interface">API</abbr>. _More details and links to be inserted once information about the API is publicly available_.
+
+## Installation ##
+
+### Dependencies ###
+
+Currently, the library depends on:
+
+* [json](http://flori.github.com/json/) 1.4.X
+* [rest-client](http://github.com/archiloque/rest-client) 1.6.X
+
+These will be automatically installed if installing as a gem.
+
+### Standard installation: as a rubygem ###
+
+The library is not currently available via any public gem servers. However, it can be installed as a gem using the following steps:
+
+1. Grab the code: `git clone git@github.com:AMEE/amon.client.ruby.git`
+2. Build the gem: `gem build amon.gemspec`
+3. Install the gem: `sudo gem install amon-0.1.0.gem`
+
+### Alternative: manual installation ###
+
+You can manually install the code somewhere, and then ensure that the `lib/` directory is listed in your `LOAD_PATH`.
+
+### Alternative: vendoring in a Rails app ###
+
+If you are using the library inside a Rails (2.3) app, clone the code into `vendor/gems/amon-0.1.0`. Then list it as a gem dependency in `config/environment.rb` and Rails will automatically find and load it.
+
+If using Rails 3, you could do a similar thing using Bundler.
+
+## Loading the library in your code ##
+
+Once installed, the library can be loaded using `require "amon"`.
+
+## Configuration ##
+
+Interaction with the API is achieved through {AMON::Session Session} objects. For convenience, you can configure some 'default session options' by setting the values in the {AMON.default_session_options} hash. You can then create a session from these options at any time by calling {AMON.create_default_session}.
+
+See the {AMON::Session} page for a full explanation of the options available.
+
+### Example default session configuration ###
+
+    AMON.default_session_options[:base_uri] = "http://amon.amee.com/1"
+    AMON.default_session_options[:user] = "fred"
+    AMON.default_session_options[:password] = "s3cr3t"
+
+## Usage ##
+
+Methods which can be called on a {AMON::Session Session} can be called directly on the {AMON} module, which will cause a {AMON.create_default_session default session} to be created and used.
+
+### Simple usage example ###
+
+This example gets some measurements from an electricity meter over a 1 month period.
+
+    start_date = Time.local(2010, 3)
+    end_date   = Time.local(2010, 4)
+    
+    property = AMON.entity("da3906c0-7c6b-012d-a6d5-001c23973687")
+    concentrator = property.meters.first
+    electricity_reading = concentrator.readings_by_type["electricalInput"]
+    electricity_reading.measurements(start_date, end_date) # => Array of measurements
+
+## Development ##
+
+Tests can be run with RSpec: `spec spec/`.
+
+The documentation is generated with YARD: `rake yard`.
+
+## TODO List ##
+
+* Error handling
+* Rename Document and DocumentPart to Resource and ResourcePart

data/init.rb

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

data/lib/amon/default_session.rb

@@ -0,0 +1,45 @@
+require 'forwardable'
+
+# The AMON module responds to the same method names as an {AMON::Session}. When called,
+# these methods use a 'default' session returned by {create_default_session}. So the following
+# method calls are all equivalent:
+# 
+#     AMON::Session.new(AMON.default_session_options).entity("77e50660-93e7-012d-b57d-001c23973687")
+#     AMON.create_default_session.entity("77e50660-93e7-012d-b57d-001c23973687")
+#     AMON.entity("77e50660-93e7-012d-b57d-001c23973687")
+# 
+# Note that using a default session implicitly (as in the final line above) will cause a new
+# session to be created each time the method is called. This means caching will not be used.
+# 
+# If you are likely to be requesting the same resources in short succession, it is advisable to
+# hold on to a session object yourself. For example:
+# 
+#     @session = AMON.create_default_session
+#     @session.entity("77e50660-93e7-012d-b57d-001c23973687") # => <AMON::Entity> (from HTTP)
+#     @session.entity("77e50660-93e7-012d-b57d-001c23973687") # => <AMON::Entity> (from cache)
+module AMON
+  class << self
+    # A hash of options which are used by {create_default_session}. The values of this hash
+    # should be configured by users as appropriate.
+    # @return [Hash] an options hash, initially empty
+    def default_session_options
+      @default_session_options ||= {}
+    end
+    
+    # Assigns a new options hash as the {default_session_options}.
+    # @param [Hash] options the options hash
+    # @return [Hash] the options hash
+    def default_session_options=(options)
+      @default_session_options = options
+    end
+    
+    # Creates a new session using the {default_session_options}.
+    # @return [Session]
+    def create_default_session
+      Session.new(default_session_options)
+    end
+    
+    extend Forwardable
+    def_delegators :create_default_session, :entity, :meter, :metering_point, :measurements
+  end
+end

data/lib/amon/document.rb

@@ -0,0 +1,30 @@
+module AMON
+  # A top-level object representing an AMON resource
+  # @abstract
+  class Document
+    include JSONHelper
+    
+    # @return [Session] The session associated with this document
+    attr_reader :session
+    
+    # @param [Session] session The session
+    # @param [Hash] json The JSON data as a Hash
+    def initialize(session, json)
+      @session, @json = session, json
+    end
+    
+    # This should be implemented in subclasses, returning the UUID for the document
+    # @abstract
+    # @private
+    def id
+      raise NotImplementedError
+    end
+    
+    # Two documents are equal if they have the same class and their id fields are equal
+    # @param [Document] other
+    # @return [Boolean]
+    def ==(other)
+      self.class == other.class && id == other.id
+    end
+  end
+end

data/lib/amon/document_part.rb

@@ -0,0 +1,18 @@
+module AMON
+  # An object representing part of an AMON {Document}. For example, a {Reading} is part of a
+  # {Meter}, and cannot exist outside of it.
+  # 
+  # @abstract
+  class DocumentPart
+    include JSONHelper
+    
+    # @return [Document] The parent document of which this object is a part
+    attr_reader :parent
+    
+    # @param [Document] parent The parent document
+    # @param [Hash] json The JSON data as a Hash
+    def initialize(parent, json)
+      @parent, @json = parent, json
+    end
+  end
+end

data/lib/amon/entity.rb

@@ -0,0 +1,24 @@
+module AMON
+  # An AMON entity, such as a house, business park, or building floor
+  class Entity < Document
+    # @return [String] The id for this entity
+    field :id,                 :name => 'entityId'
+    
+    # @return [Array<String>] The ids of all the meters associated with this entity
+    field :meter_ids,          :name => 'meterIds',                  :default => []
+    
+    # @return [Array<String>] The qualified ids of all the metering points associated with this entity
+    # @todo Rename to qualified_metering_point_ids
+    field :metering_point_ids, :name => 'qualifiedMeteringPointIds', :default => []
+    
+    # @return [Array<Meter>] The meters associated with this entity
+    def meters
+      @meters ||= meter_ids.map { |id| session.meter(id) }
+    end
+    
+    # @return [Array<MeteringPoint>] The metering points associated with this entity
+    def metering_points
+      @metering_points ||= metering_point_ids.map { |id| session.metering_point(id) }
+    end
+  end
+end

data/lib/amon/json_helper.rb

@@ -0,0 +1,36 @@
+module AMON
+  module JSONHelper
+    # @return [Hash] The raw JSON data for this object, represented as a Hash
+    attr_reader :json
+    
+    private
+    
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+    
+    # @private
+    module ClassMethods
+      def field(name, options = {})
+        class_eval do
+          define_method(name) do
+            original_value = json[(options[:name] || name).to_s]
+            
+            if original_value.nil?
+              options[:default]
+            else
+              case options[:as].to_s
+                when 'Time'
+                  Time.parse(original_value)
+                else
+                  original_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/amon/measurement.rb

@@ -0,0 +1,55 @@
+module AMON
+  # A measurement corresponding to a {Reading} of a {Meter}
+  class Measurement < DocumentPart
+    # @return [String] The measurement's name
+    field :name
+    
+    # @return [Numeric] The measurement's value
+    field :value
+    
+    # @return [Time] The measurement's timestamp, if provided
+    field :timestamp,  :as => Time
+    
+    # @return [Time] The measurement's start date, if provided
+    field :start_date, :name => 'startDate', :as => Time
+    
+    # @return [Time] The measurement's end date, if provided
+    field :end_date,   :name => 'endDate',   :as => Time
+    
+    # @attr_reader [Meter] meter The meter which took this measurement
+    alias_method :meter, :parent
+    
+    # A measurement is instantaneous if it is given with a single timestamp. If, on the other hand,
+    # start and end dates are provided, it is durational.
+    # @return [Boolean]
+    # @see Measurement#durational?
+    def instantaneous?
+      !timestamp.nil?
+    end
+    
+    # The opposite of {Measurement#instantaneous? instantaneous?}
+    # @return [Boolean]
+    # @see Measurement#instantaneous?
+    def durational?
+      !instantaneous?
+    end
+    
+    # The {Meter meter} {Reading reading} associated with this measurement.
+    # @return [Reading]
+    def reading
+      meter.readings_by_type[name]
+    end
+    
+    # A single timestamp in the 'middle' of this measurement. If the measurement is instantaneous,
+    # then the mid timestamp is identical to the {Measurement#timestamp timestamp}. However, if it
+    # is durational then the mid timestamp is the halfway point between the {Measurement#start_date}
+    # and the {Measurement#end_date}.
+    def mid_timestamp
+      if instantaneous?
+        timestamp
+      else
+        start_date + (end_date - start_date) / 2
+      end
+    end
+  end
+end

data/lib/amon/metadata.rb

@@ -0,0 +1,34 @@
+module AMON
+  # Metadata associated with a {Meter}. The metadata section of an AMON document can have an
+  # arbitrary number of fields, so this class uses `method_missing` to look them up and respond
+  # appropriately.
+  # 
+  # @todo
+  #   This doesn't yet support arbitrarily nested metadata, so you can't have JSON like so:
+  #   
+  #     "metadata": {
+  #       "foo": {
+  #         "bar": "baz"
+  #       }
+  #     }
+  #   
+  #   And then access:
+  #   
+  #     object.metadata.foo.bar # => "baz"
+  #   
+  #   However, in the meantime you could do:
+  #   
+  #     object.metadata.foo[:bar] # => "baz"
+  #   
+  #   (As the JSON is full parsed into a nested hash.)
+
+  class Metadata < DocumentPart
+    def method_missing(name, *args, &block)
+      if args.empty? && block.nil?
+        json[name.to_s]
+      else
+        raise NoMethodError, "undefined method `#{name}'"
+      end
+    end
+  end
+end

data/lib/amon/meter.rb

@@ -0,0 +1,53 @@
+module AMON
+  # An AMON meter, containing any number of {Reading readings}, and {Measurement measurements} for those readings.
+  class Meter < Document
+    # @return [String] The id of the meter
+    field :id, :name => 'meterId'
+
+    # @return <String> The description for the meter
+    def description
+      @description ||= json['description']
+    end
+
+    # @return <String> The location for the meter
+    def location_name
+      @location_name ||= json['location']['name']
+    end
+    
+    # @return [Metadata] The metadata for the meter
+    def metadata
+      @metadata ||= Metadata.new(self, json['metadata'])
+    end
+    
+    # @return [Array<Reading>] The readings for the meter
+    def readings
+      @readings ||= json['readings'].map { |reading| Reading.new(self, reading) }
+    end
+    
+    # @return [Hash<String => Reading>] A hash allowing {Meter#readings} to be retrieved by their
+    # {Reading#type}
+    def readings_by_type
+      readings.inject({}) do |readings_by_type, reading|
+        readings_by_type[reading.type] = reading
+        readings_by_type
+      end
+    end
+    
+    # @return [Array<Measurement>] Measurements for this meter
+    # @see Session#measurements
+    def measurements(start_date, end_date, raw = false)
+      session.measurements(id, start_date, end_date, raw)
+    end
+    
+    # @return [Hash<String => Measurement>] A hash allowing {Meter#measurements} to be retrieved
+    # by their {Measurement#name}
+    # @see Meter#measurements
+    def measurements_by_name(start_date, end_date, raw = false)
+      measurements(start_date, end_date, raw).inject({}) do |measurements_by_name, measurement|
+        measurements_by_name[measurement.name] ||= []
+        measurements_by_name[measurement.name] << measurement
+        measurements_by_name
+      end
+    end
+  end
+end

data/lib/amon/metering_point.rb

@@ -0,0 +1,8 @@
+module AMON
+  # An AMON metering point
+  # @todo Implement this class
+  class MeteringPoint < Document
+    # @return [String] The id for this metering point
+    field :id, :name => 'meteringPointId'
+  end
+end

data/lib/amon/reading.rb

@@ -0,0 +1,59 @@
+module AMON
+  # AMON readings are 'categories' of {Measurement measurements} which are taken by {Meter meters}.
+  # For example, one reading may be 'electricalInput' with the unit 'kWh'.
+  class Reading < DocumentPart
+    # @return [String] The type of reading, which is unique within the parent {Meter meter}
+    field :type
+    
+    # @return [String] An arbitrary name for the reading
+    field :name
+    
+    # @return [String] The units this reading records {Measurement measurements} in
+    field :unit
+    
+    # @return [Numeric] The resolution of the reading
+    field :resolution
+    
+    # @return [Numeric] The accuracy of the reading
+    field :accuracy
+    
+    # @return ["instant", "duration"] Whether this reading records measurement values taken at a
+    # specific point in time ('instant'), or taken as an average over a period of time ('duration')
+    field :period, :default => "instant"
+    
+    # @attr_reader [Meter] meter The meter which took this measurement
+    alias_method :meter, :parent
+    
+    # @return [Array<Measurement>] Measurements for this reading
+    # @see Meter#measurements
+    def measurements(start_date, end_date, raw = false)
+      meter.measurements_by_name(start_date, end_date, raw)[type] || []
+    end
+    
+    # @return [true] if the {#period} is 'instant'
+    # @return [false] if the {#period} is 'duration'
+    def instantaneous?
+      period == "instant"
+    end
+    
+    # @return [Boolean] The opposite of {#instantaneous?}
+    def durational?
+      !instantaneous?
+    end
+    
+    # One reading is equal to another if the meters are equal and they are the same type
+    # @return [Boolean]
+    # @param [Reading] other The other reading to compare with.
+    def ==(other)
+      meter == other.meter && type == other.type
+    end
+    
+    # A unique id for the reading, composed of the {Meter meter} id, and the {#type}. So an
+    # '<code>electricalInput</code>' reading for a meter with id '<code>b7ddac00-9415-012d-b57e-001c23973687</code>' would
+    # have the id '<code>b7ddac00-9415-012d-b57e-001c23973687-electricalInput</code>'.
+    # @return [String] the id
+    def id
+      "#{meter.id}-#{type}"
+    end
+  end
+end

data/lib/amon/session.rb

@@ -0,0 +1,130 @@
+require 'uri'
+
+module AMON
+  # Session objects take care of making the actual HTTP requests to the AMON API
+  # 
+  # ## Caching ##
+  # 
+  # Sessions support caching which is enabled by default, but can be optionally turned off. When 
+  # caching is enabled, the same request will not be performed twice in a session. Be aware that
+  # this has some important implications:
+  # 
+  # * If a long running process uses the same session, the cache may become stale as the backend
+  #   data changes, but new API requests are not made.
+  # * There is no mechanism for automatically expiring the cache; this is left up to users of the
+  #   library.
+  # * The cache stores the AMON objects, rather than the raw response data. In this sense it 
+  #   functions as a sort of identity map - getting the same entity twice will return exactly the
+  #   same object twice, rather than two different objects representing the same data.
+  # 
+  # Often the most natural way to 'expire the cache' is to discard the session and use a new one
+  # at regular intervals. Alternatively, you can use {Session#clear_cache} and keep the same 
+  # session.
+  class Session
+    # @return [Hash] The hash of configuration options to be used when making requests
+    attr_reader :options
+    
+    # The default options for a session
+    DEFAULT_OPTIONS = {
+      :base_uri => nil,
+      :user     => nil,
+      :password => nil,
+      :cache    => true
+    }.freeze
+    
+    # @param [Hash] options the options for the session
+    # @option options [String] :base_uri The base URI for the AMON API, e.g. "http://amon.amee.com/1"
+    # (note that this includes the API version, as this library only knows about version 1 of the API)
+    # @option options [String] :user The HTTP user for authentication
+    # @option options [String] :password The HTTP password for authentication
+    # @option options [Boolean] :cache (true) Whether to perform caching or not. See above for details.
+    def initialize(options = {})
+      @options = DEFAULT_OPTIONS.merge(options)
+      @options.freeze
+    end
+    
+    # Retrieves an entity from the API
+    # @param [String] entity_id the ID of the entity to be requested
+    # @return [Entity]
+    def entity(entity_id)
+      cache(:entities, entity_id) do
+        json = get("/entities/#{URI.escape(entity_id)}")['entity']
+        Entity.new(self, json)
+      end
+    end
+    
+    # Retrieves a meter from the API
+    # @param [String] meter_id the ID of the meter to be requested
+    # @return [Meter]
+    def meter(meter_id)
+      cache(:meters, meter_id) do
+        json = get("/meters/#{URI.escape(meter_id)}")['meter']
+        Meter.new(self, json)
+      end
+    end
+    
+    # Retrieves a metering point from the API
+    # @param [String] metering_point_id the ID of the metering point to be requested
+    # @return [MeteringPoint]
+    def metering_point(metering_point_id)
+      cache(:metering_points, :metering_point_id) do
+        json = get("/metering-points/#{URI.escape(metering_point_id)}")['metering_point']
+        MeteringPoint.new(self, json)
+      end
+    end
+    
+    # Retrieves measurements from the API
+    # @param [String] meter_id The ID of the meter to get the measurements from
+    # @param [Time] start_date The starting point for the measurements
+    # @param [Time] end_date The ending point for the measurements
+    # @param [Boolean] raw Whether to return raw measurements as submitted by the hardware (may 
+    # contain a lot of data), or appropriate aggregations over the time period
+    def measurements(meter_id, start_date, end_date, raw = false)
+      cache(:measurements, [meter_id, start_date, end_date, raw]) do
+        meter = meter(meter_id)
+        measurements = get(
+          "/meters/#{meter.id}/measurements?" +
+            "raw="       + raw.to_s + "&" +
+            "startDate=" + start_date.utc.xmlschema + "&" +
+            "endDate="   + end_date.utc.xmlschema
+        )['measurements']
+        measurements.map { |measurement| Measurement.new(meter, measurement) }
+      end
+    end
+    
+    # Completely clears the cache
+    def clear_cache
+      @cache = nil
+    end
+    
+    private
+    
+      def cache(group, id, &block)
+        if options[:cache]
+          @cache            ||= {}
+          @cache[group]     ||= {}
+          @cache[group][id] ||= block.call
+        else
+          block.call
+        end
+      end
+    
+      def get(url, params = {})
+        JSON.parse(client[url].get(:params => params))
+      end
+      
+      def client
+        raise ArgumentError, "Can't make a request without :base_uri option" unless options[:base_uri]
+        
+        @client ||= RestClient::Resource.new(
+          options[:base_uri], 
+          :user     => options[:user],
+          :password => options[:password],
+          :headers  => {
+            :content_type => 'application/json',
+            :accept       => 'application/json'
+          }
+        )
+      end
+  end
+end

data/lib/amon/version.rb

@@ -0,0 +1,10 @@
+module AMON
+  # Provides details about the version of the AMON library in use.
+  module Version
+    MAJOR = 0
+    MINOR = 3
+    TINY  = 0
+    
+    STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
+  end
+end

data/lib/amon.rb

@@ -0,0 +1,18 @@
+require 'json'
+require 'rest-client'
+
+module AMON
+  autoload :JSONHelper,    'amon/json_helper'
+  autoload :Document,      'amon/document'
+  autoload :DocumentPart,  'amon/document_part'
+  autoload :Entity,        'amon/entity'
+  autoload :Meter,         'amon/meter'
+  autoload :MeteringPoint, 'amon/metering_point'
+  autoload :Metadata,      'amon/metadata'
+  autoload :Reading,       'amon/reading'
+  autoload :Measurement,   'amon/measurement'
+  autoload :Version,       'amon/version'
+  autoload :Session,       'amon/session'
+  
+  require 'amon/default_session'
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'amon'

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification 
+name: amon
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- AMEE
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-25 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 4
+        - 0
+        version: 1.4.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 6
+        - 0
+        version: 1.6.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id005
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/amon/default_session.rb
+- lib/amon/document.rb
+- lib/amon/document_part.rb
+- lib/amon/entity.rb
+- lib/amon/json_helper.rb
+- lib/amon/measurement.rb
+- lib/amon/metadata.rb
+- lib/amon/meter.rb
+- lib/amon/metering_point.rb
+- lib/amon/reading.rb
+- lib/amon/session.rb
+- lib/amon/version.rb
+- lib/amon.rb
+- README.md
+- init.rb
+- rails/init.rb
+homepage: http://amee.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Ruby client for the AMEE AMON API
+test_files: []
+
+has_rdoc: