Class: AMON::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/amon/session.rb

Overview

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 #clear_cache and keep the same session.

Constant Summary collapse

DEFAULT_OPTIONS =

The default options for a session

{
  :base_uri => nil,
  :user     => nil,
  :password => nil,
  :cache    => true
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Session

(note that this includes the API version, as this library only knows about version 1 of the API)

Parameters:

  • options (Hash) (defaults to: {}) —

    the options for the session

Options Hash (options):

  • :base_uri (String) —

    The base URI for the AMON API, e.g. “amon.amee.com/1”

  • :user (String) —

    The HTTP user for authentication

  • :password (String) —

    The HTTP password for authentication

  • :cache (Boolean) — default: true —

    Whether to perform caching or not. See above for details.



43
44
45
46
 
# File 'lib/amon/session.rb', line 43

def initialize(options = {})
  @options = DEFAULT_OPTIONS.merge(options)
  @options.freeze
end

Instance Attribute Details

#options ⇒ Hash (readonly)

Returns The hash of configuration options to be used when making requests.

Returns:

  • (Hash) —

    The hash of configuration options to be used when making requests



27
28
29
 
# File 'lib/amon/session.rb', line 27

def options
  @options
end

Instance Method Details

#clear_cache ⇒ Object

Completely clears the cache



108
109
110
 
# File 'lib/amon/session.rb', line 108

def clear_cache
  @cache = nil
end

#device(entity_id, device_id) ⇒ Device

Retrieves a device from the API

Parameters:

  • device_id (String) —

    the ID of the device to be requested

Returns:



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/amon/session.rb', line 61

def device(entity_id, device_id)
  cache(:devices, device_id) do
    json = get(
      "/entities/#{ URI.escape(entity_id )}/devices/#{URI.escape(device_id)}" +
        ";earliest" +
        ";latest" +
        ";completeness"
    )['device']
    Device.new(self, json)
  end
end

#entity(entity_id) ⇒ Entity

Retrieves an entity from the API

Parameters:

  • entity_id (String) —

    the ID of the entity to be requested

Returns:



51
52
53
54
55
56
 
# File 'lib/amon/session.rb', line 51

def entity(entity_id)
  cache(:entities, entity_id) do
    json = get("/entities/#{URI.escape(entity_id)};completeness")['entity']
    Entity.new(self, json)
  end
end

#measurements(entity_id, device_id, start_date, end_date, raw = false) ⇒ Object

Retrieves measurements from the API

Parameters:

  • entity_id (String) —

    The ID of the entity

  • device_id (String) —

    The ID of the device to get measurements from

  • start_date (Time) —

    The starting point for the measurements

  • end_date (Time) —

    The ending point for the measurements

  • raw (Boolean) (defaults to: false) —

    Whether to return raw measurements as submitted by the hardware (may contain a lot of data), or appropriate aggregations over the time period



92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/amon/session.rb', line 92

def measurements(entity_id, device_id, start_date, end_date, raw = false)
  cache(:measurements, [device_id, start_date, end_date, raw]) do
    device = device(entity_id, device_id)
    measurements = get(
      "/entities/#{ URI.escape(entity_id) }/devices/#{ URI.escape(device.id) }/measurements" +
        ";aggregation" + 
        "?" +
        "raw="       + raw.to_s + "&" +
        "startDate=" + start_date.utc.xmlschema + "&" +
        "endDate="   + end_date.utc.xmlschema
    )['measurements']
    measurements.map { |measurement| Measurement.new(device, measurement) }
  end
end

#metering_point(metering_point_id) ⇒ MeteringPoint

Retrieves a metering point from the API

Parameters:

  • metering_point_id (String) —

    the ID of the metering point to be requested

Returns:



76
77
78
79
80
81
 
# File 'lib/amon/session.rb', line 76

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