A ruby gem for accessing the AMEE carbon calculator
Ruby
Latest commit 381b6e3 Jan 22, 2013 @andrewatamee andrewatamee Revert "Version bump to 4.5.0"
This reverts commit 8d2a8f6.
Permalink
Failed to load latest commit information.
bin Brought copyright years up to date. Jan 22, 2013
cassettes Make authentication loop around and retry the request properly SDK-228 Jan 19, 2012
examples Brought copyright years up to date. Jan 22, 2013
gemfiles Add appraisal config for rails 2.3, 3.0, and 3.1 Nov 17, 2011
lib Brought copyright years up to date. Jan 22, 2013
rails Brought copyright years up to date. Jan 22, 2013
spec Brought copyright years up to date. Jan 22, 2013
.gitignore Update bundler version. Jul 6, 2012
.rvmrc Add rvm gemset config Nov 17, 2011
Appraisals Add appraisal config for rails 2.3, 3.0, and 3.1 Nov 17, 2011
CHANGELOG.txt update CHANGELOG Jan 26, 2012
Gemfile Revert "Updated version of bundler allowed to be used." Jan 22, 2013
LICENSE.txt Brought copyright years up to date. Jan 22, 2013
README.txt Brought copyright years up to date. Jan 22, 2013
Rakefile Revert "Fixed bug with rdoc generation task." Jan 22, 2013
VERSION Revert "Version bump to 4.5.0" Jan 22, 2013
amee.example.yml Update documentation Jul 21, 2010
amee.gemspec
amee_test_credentials.example.yml SDK-119 Replace NET-HTTP with Typhoeus Nov 25, 2011
cacert.pem merge SSL support Jul 21, 2010
init.rb Brought copyright years up to date. Jan 22, 2013

README.txt

== AMEE-Ruby

A gem to provide a Ruby interface to AMEEconnect (http://www.amee.com)

Licensed under the BSD 3-Clause license (See LICENSE.txt for details)

Author: James Smith, James Hetherington, Andrew Hill, Andrew Berkeley

Copyright: Copyright (c) 2008-2013 AMEE UK Ltd

Homepage: http://github.com/AMEE/amee-ruby

Documentation: http://rubydoc.info/gems/amee/frames

== INSTALLATION

1) Install gem
    > sudo gem install amee

== REQUIREMENTS

If you are using Rails, note that version 4.x of this gem supports Rails 3 apps 
only. If you are using Rails 2, you should stay with version 3.x. See the 'Rails'
section below for more details.

'Nokogiri' is used for XML parsing, and requires libxml2. See
http://nokogiri.org/tutorials/installing_nokogiri.html for instructions if you
have problems installing.

== USAGE

Currently, you can read DataCategories, DataItems and DataItemValues. See 
examples/view_data_*.rb for simple usage examples. You can also get the list
of available Profiles, and create and delete them. See examples/list_profiles.rb
and examples/create_profile.rb for details. You can also load ProfileCategories,
and load, create and update ProfileItems.

The gem will use the AMEE JSON API if the JSON gem is installed on the local
system. Otherwise the XML API will be used.

== SUPPORT
                    Create    Read     Update    Delete
DataCategories         N        Y         N         N
DataItems              N        Y         N         N
DataItemValues         N        Y         N         Y
Profile List           -        Y         -         -
Profiles               Y        -         -         Y
ProfileCategories      -        Y         -         -
 - drilldown           -        Y         -         -
ProfileItems           Y        Y         Y         Y

== INTERACTIVE SHELL

You can use the 'ameesh' app to interactively explore the AMEE data area. Run
'ameesh -u USERNAME -p PASSWORD -s SERVER' to try it out. Source code for this 
tool is in bin/ameesh and lib/amee/shell.rb. Profiles are not accessible through
this interface yet.

== RAILS

This gem can also be used as a Rails plugin.

Rails 2: add the following to environment.rb:
    config.gem "amee", :version => '~> 3.1'

Rails 3: add the following to your Gemfile:
    gem "amee", '~> 4.1'

If you copy amee.example.yml from the gem source directory to amee.yml in your
app's config directory, a persistent AMEE connection will be available from 
AMEE::Rails#connection, which you can use anywhere. In your controllers, you can
also use the global_amee_connection function to access the same global connection.

    data = AMEE::Data::Category.root(global_amee_connection)

If you do not use this facility, you will have to create your own connection
objects and manage them yourself, which you can do using AMEE::Connection#new

Instead of using an amee.yml file, you can set ENV['AMEE_USERNAME'], ENV['AMEE_PASSWORD']
and ENV['AMEE_SERVER'] to achieve the same effect. This is useful for deploying
to environments like Heroku, for instance.

There is a helper for ActiveRecord models which should be linked to an AMEE profile.
By adding:

    has_amee_profile

to your model, and by adding an amee_profile:string field to the model in the
database, an AMEE profile will be automatically created and destroyed with your
model. By overriding the function amee_save in your model, you can store data in
AMEE when your model is saved.

== CACHING

The AMEE::Connection object implements an optional cache for GET requests.

This uses ActiveSupport::Cache, and supports any ActiveSupport::Cache::Store
caching method except for MemCacheStore (which doesn't provide required features).

All GET requests are cached. POST, PUT, or DELETEs will clear the cache for any
path that matches the affected URL. #expire, #expire_matching, and #expire_all
functions are available for manual cache management. Also, all AMEE objects have
and #expire-cache function to clear them and their descendants from the cache.

To enable caching, pass ':cache => :memory_store' to AMEE::Connection.new, or add
'cache: memory_store' to your amee.yml if using Rails. If you want to use the
same caching configuration as your Rails app, you can add 'cache: rails' to 
amee.yml instead. Caching is disabled by default.

== RETRY / TIMEOUT SUPPORT

The AMEE::Connection object can now automatically retry if a request fails due to 
network problems or connection failures. To enable this feature, pass ':retries => 3'
to AMEE::Connection.new, or add 'retries: 3' to your amee.yml if using Rails. You can
change the number of retry attempts, 3 is just used as an example above.

The Connection object also allows a timeout to be set for requests. By default this is
set to 60 seconds, but if you want to provide a different value (30 seconds for 
instance), pass ':timeout => 30' to AMEE::Connection.new, or 'timeout: 30' in amee.yml.