restfully 0.2.3 → 0.3.0

data/LICENSE

@@ -1,4 +1,5 @@
 Copyright (c) 2009 Cyril Rohr
+Copyright (c) 2009 INRIA Rennes - Bretagne Atlantique
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -9,7 +9,8 @@ Alpha work.
 
 == Usage
 === Command line
-  $ resfully base_uri [root_path] [-u username] [-p password]
+  $ export RUBYOPT="-rubygems"
+  $ restfully base_uri [root_path] [-u username] [-p password]
   
 e.g., for the Grid5000 API:
   $ restfully https://api.grid5000.fr/sid /grid5000 -u username -p password
@@ -17,37 +18,74 @@ e.g., for the Grid5000 API:
 If the connection was successful, you should get a prompt. Call the +root+ function to see what are the available resources. <tt>@property</tt> means that you can call the +property+ method on the object. Other properties are available via the <tt>[]</tt> function.
 e.g.:
   irb(main):005:0> root
-  => #<Restfully::Resource:0x90bdd4
-       ------------ META ------------
-       @uri: "/grid5000"
-       @uid: "grid5000"
-       @type: "grid"
-       @environments: Restfully::Collection
-       @sites: Restfully::Collection
-       @version: Restfully::Resource
-       @versions: Restfully::Collection
-       ------------ PROPERTIES ------------
-       "version" => "ee1f8111c8835496a9e4a6f7c9491c0238ee9827">
+  => #<Restfully::Resource:0x8848de
+      	------------ META ------------
+      	@uri: #<URI::Generic:0x11091a8 URL:/grid5000>
+      	@uid: "grid5000"
+      	@type: "grid"
+      	@environments: Restfully::Collection
+      	@sites: Restfully::Collection
+      	@version: Restfully::Resource
+      	@versions: Restfully::Collection
+      	------------ PROPERTIES ------------
+      	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
     
    irb(main):006:0> root.uri
-   => "/grid5000"
+   => #<URI::Generic:0x11091a8 URL:/grid5000>
    
    irb(main):007:0> root.sites
-   => #<Restfully::Collection:0x8faaf2
-        ------------ META ------------
-        @uri: "/grid5000/sites"
-        ------------ PROPERTIES ------------
-        "lille" => Restfully::Resource
-        "grenoble" => Restfully::Resource
-        "toulouse" => Restfully::Resource
-        "sophia" => Restfully::Resource
-        "rennes" => Restfully::Resource
-        "lyon" => Restfully::Resource
-        "nancy" => Restfully::Resource
-        "bordeaux" => Restfully::Resource
-        "orsay" => Restfully::Resource>
-   irb(main):008:0> root['version']
-   => "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
+   => #<Restfully::Collection:0x881f6c
+       	------------ META ------------
+       	@uri: "/grid5000/sites"
+       	@offset: 0
+       	@total: 9
+       	@version: Restfully::Resource
+       	@versions: Restfully::Collection
+       	------------ PROPERTIES ------------
+       	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8"
+       	------------ ITEMS ------------
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource
+       	Restfully::Resource>
+   
+   irb(main):008:0> root.sites.by_uid('rennes').clusters.by_uid('paradent').nodes.by_uid('paradent-1').metrics.by_uid('mem_free', 'cpu_idle', 'bytes_in')
+   => [#<Restfully::Resource:0x4259a
+       	------------ META ------------
+       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/mem_free"
+       	@uid: "mem_free"
+       	@type: "metric"
+       	@parent: Restfully::Resource
+       	@timeseries: Restfully::Resource
+       	------------ PROPERTIES ------------
+       	"last_update" => -901639018
+       	"step" => 15
+       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0x12444
+       	------------ META ------------
+       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/cpu_idle"
+       	@uid: "cpu_idle"
+       	@type: "metric"
+       	@parent: Restfully::Resource
+       	@timeseries: Restfully::Resource
+       	------------ PROPERTIES ------------
+       	"last_update" => -901639018
+       	"step" => 15
+       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0xe4c870
+       	------------ META ------------
+       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/bytes_in"
+       	@uid: "bytes_in"
+       	@type: "metric"
+       	@parent: Restfully::Resource
+       	@timeseries: Restfully::Resource
+       	------------ PROPERTIES ------------
+       	"last_update" => -901639018
+       	"step" => 15
+       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>]
    
    irb(main):009:0> root.version
    => #<Restfully::Resource:0x8facf0
@@ -90,4 +128,4 @@ See the +examples+ directory for examples.
 
 == Copyright
 
-Copyright (c) 2009 Cyril Rohr. See LICENSE for details.
+Copyright (c) 2009 Cyril Rohr, INRIA Rennes - Bretagne Atlantique. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.2.3
+0.3.0

data/bin/restfully

@@ -9,26 +9,31 @@ require 'logger'
 require 'pp'
 require 'yaml'
 
-@options = {}
+
+logger = Logger.new(STDOUT)
+logger.level = Logger::WARN
+@options = {:logger => logger}
 option_parser = OptionParser.new do |opts|
   opts.banner = "Usage: restfully base_uri [root_path] [options]"
 
   opts.on("-u=", "--username=", "Sets the username") do |u|
-    @options['username'] = u
+    @options[:username] = u
   end
   opts.on("-p=", "--password=", "Sets the user password") do |p|
-    @options['password'] = p
+    @options[:password] = p
   end
   opts.on("-c=", "--config=", "Sets the various options based on a custom YAML configuration file") do |v|
-    @options['configuration_file'] = v
-  end
-  opts.on("-v", "--verbose", "Run verbosely") do |v|
-    @options['verbose'] = v
+    @options[:configuration_file] = v
   end
   opts.on("--log=", "Outputs log messages to the given file. Defaults to stdout") do |v|
-    @options['log'] = v
+    original_logger_level = logger.level
+    logger = Logger.new(File.expand_path(v))
+    logger.level = original_logger_level
+    @options[:logger] = logger
+  end
+  opts.on("-v", "--verbose", "Run verbosely") do |v|
+    @options[:logger].level = Logger::DEBUG
   end
-  
   opts.on_tail("-h", "--help", "Show this message") do
     puts opts
     exit
@@ -38,44 +43,61 @@ end
 
 option_parser.parse!
 
-@base_uri = ARGV.shift
-@root_path = ARGV.shift || "/"
+@options[:base_uri] = ARGV.shift
+@options[:root_path] = ARGV.shift || "/"
 
-if (config_filename = @options.delete('configuration_file')) && File.exists?(File.expand_path(config_filename))
-  config = YAML.load_file(File.expand_path(config_filename))
-  @base_uri = config.delete('base_uri') || @base_uri
-  @root_path = config.delete('root_path') || @root_path
-  @options.merge!(config)
+def session
+  @session ||= Restfully::Session.new(@options)
 end
 
-unless @base_uri
-  $stderr.puts option_parser.help
-  exit(-1)
-else
-  if (log_file=@options.delete('log'))
-    @logger = Logger.new(File.expand_path(log_file))
-  else
-    @logger = Logger.new(STDOUT)
-  end
-  if @options.delete('verbose')
-    @logger.level = Logger::DEBUG
-  else
-    @logger.level = Logger::WARN
-  end
-
-  def session
-    @session ||= Restfully::Session.new(@base_uri, @options.merge('root_path' => @root_path, 'logger' => @logger))
-  end
-  def root 
-    @root ||= Restfully::Resource.new(session.root_path, session).load
-  end
-  
-  root # preloads
-  
-  require 'irb'
-  require 'irb/completion'
-  
-  ARGV.clear
-  IRB.start
-  exit!
+def root 
+  @root ||= session.root.load
+rescue Restfully::HTTP::Error => e
+  puts "#{e.class.name}: #{e.message}"
 end
+
+require 'irb'
+require 'irb/completion'
+ARGV.clear
+IRB.start
+exit!  
+
+
+# if (config_filename = @options.delete('configuration_file')) && File.exists?(File.expand_path(config_filename))
+#   config = YAML.load_file(File.expand_path(config_filename))
+#   @base_uri = config.delete('base_uri') || @base_uri
+#   @root_path = config.delete('root_path') || @root_path
+#   @options.merge!(config)
+# end
+# 
+# unless @base_uri
+#   $stderr.puts option_parser.help
+#   exit(-1)
+# else
+#   if (log_file=@options.delete('log'))
+#     @logger = Logger.new(File.expand_path(log_file))
+#   else
+#     @logger = Logger.new(STDOUT)
+#   end
+#   if @options.delete('verbose')
+#     @logger.level = Logger::DEBUG
+#   else
+#     @logger.level = Logger::WARN
+#   end
+# 
+#   def session
+#     @session ||= Restfully::Session.new(@base_uri, @options.merge('root_path' => @root_path, 'logger' => @logger))
+#   end
+#   def root 
+#     @root ||= Restfully::Resource.new(session.root_path, session).load
+#   end
+#   
+#   root # preloads
+#   
+#   require 'irb'
+#   require 'irb/completion'
+#   
+#   ARGV.clear
+#   IRB.start
+#   exit!
+# end

data/examples/grid5000.rb

@@ -10,19 +10,19 @@ logger.level = Logger::INFO
 # Restfully.adapter = Restfully::HTTP::RestClientAdapter
 # Restfully.adapter = Patron::Session
 RestClient.log = 'stdout'
-Restfully::Session.new('https://localhost:3443/sid', 'root_path' => '/grid5000', 'logger' => logger) do |grid, session|
+Restfully::Session.new(:base_uri => 'http://api.local/sid', :root_path => '/grid5000', :logger => logger) do |grid, session|
   grid_stats = {'hardware' => {}, 'system' => {}}
-  grid.sites.each do |site_uid, site|
-    site_stats = site.status.inject({'hardware' => {}, 'system' => {}}) {|accu, (node_uid, node_status)|
+  grid.sites.each do |site|
+    site_stats = site.status.inject({'hardware' => {}, 'system' => {}}) {|accu, node_status|
       accu['hardware'][node_status['hardware_state']] = (accu['hardware'][node_status['hardware_state']] || 0) + 1
       accu['system'][node_status['system_state']] = (accu['system'][node_status['system_state']] || 0) + 1
       accu
-    }
+    } rescue {'hardware' => {}, 'system' => {}}
     grid_stats['hardware'].merge!(site_stats['hardware']) { |key,oldval,newval| oldval+newval }
     grid_stats['system'].merge!(site_stats['system']) { |key,oldval,newval| oldval+newval }
-    p [site_uid, site_stats]
+    p [site.uid, site_stats]
   end
   p [:total, grid_stats]
   puts "Getting status of a few nodes in rennes:"
-  pp grid.sites['rennes'].status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
+  pp grid.sites.by_uid('rennes').status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
 end

data/lib/restfully.rb

@@ -11,7 +11,8 @@ require 'restfully/resource'
 require 'restfully/collection'
 
 
-module Restfully  
+module Restfully
+  VERSION = "0.3.0"
   class << self
     attr_accessor :adapter
   end

data/lib/restfully/collection.rb

@@ -1,41 +1,87 @@
 require 'delegate'
 
 module Restfully
-  class Collection < DelegateClass(Hash)
+  # Resource and Collection classes should clearly include a common module to deal with links, attributes, associations and loading
+  class Collection < DelegateClass(Array)
     
-    attr_reader :state, :raw, :uri, :session, :title
+    attr_reader :state, :raw, :uri, :session, :title, :offset, :total
     
     def initialize(uri, session, options = {})
       options = options.symbolize_keys
       @uri = uri
       @title = options[:title]
       @session = session
-      @raw = options[:raw]
       @state = :unloaded
-      @items = {}
+      @items = []
+      @indexes = {}
+      @associations = {}
+      @attributes = {}
       super(@items)
     end
     
     def loaded?;    @state == :loaded;    end
     
+    def method_missing(method, *args)
+      load
+      if association = @associations[method.to_s]
+        session.logger.debug "Loading association #{method}, args=#{args.inspect}"
+        association.load(*args)
+      elsif method.to_s =~ /^by_(.+)$/
+        key = $1
+        @indexes[method.to_s] ||= @items.inject({}) { |accu, item| 
+          accu[item.has_key?(key) ? item[key] : item.send(key.to_sym)] = item
+          accu
+        }
+        if args.empty?
+          @indexes[method.to_s]
+        elsif args.length == 1
+          @indexes[method.to_s][args.first]
+        else
+          @indexes[method.to_s].values_at(*args)
+        end
+      else
+        super(method, *args)
+      end
+    end
+    
     def load(options = {})
       options = options.symbolize_keys
       force_reload = !!options.delete(:reload) || options.has_key?(:query)
-      if loaded? && !force_reload
+      if loaded? && !force_reload && options[:raw].nil?
         self
-      else  
+      else
+        @raw = options[:raw]
+        @associations.clear
+        @attributes.clear
         @items.clear
         if raw.nil? || force_reload
           response = session.get(uri, options)
           @raw = response.body
         end
         raw.each do |key, value|
-          next if key == 'links'
-          self_link = (value['links'] || []).map{|link| Link.new(link)}.detect{|link| link.self?}
-          if self_link && self_link.valid?
-            @items.store(key, Resource.new(self_link.href, session, :raw => value).load)
+          case key
+          when "total", "offset"
+            instance_variable_set("@#{key}".to_sym, value)
+          when "links"
+            value.each{|link| define_link(Link.new(link))}
+          when "items"
+            value.each do |item|
+              self_link = (item['links'] || []).map{|link| Link.new(link)}.detect{|link| link.self?}
+              if self_link && self_link.valid?
+                @items << Resource.new(self_link.href, session).load(:raw => item)
+              else
+                session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
+              end
+            end
           else
-            session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
+            case value
+            when Hash
+              @attributes.store(key, SpecialHash.new.replace(value)) unless @associations.has_key?(key)
+            when Array
+              @attributes.store(key, SpecialArray.new(value))
+            else
+              @attributes.store(key, value)
+            end
           end
         end       
         @state = :loaded
@@ -43,21 +89,58 @@ module Restfully
       end
     end
     
+    def respond_to?(method, *args)
+      @associations.has_key?(method.to_s) || super(method, *args)
+    end
+    
     def inspect(options = {:space => "\t"})
       output = "#<#{self.class}:0x#{self.object_id.to_s(16)}"
       if loaded?
         output += "\n#{options[:space]}------------ META ------------"
         output += "\n#{options[:space]}@uri: #{uri.inspect}"
-        unless @items.empty?        
+        output += "\n#{options[:space]}@offset: #{offset.inspect}"
+        output += "\n#{options[:space]}@total: #{total.inspect}"
+        @associations.each do |title, assoc|
+          output += "\n#{options[:space]}@#{title}: #{assoc.class.name}"
+        end
+        unless @attributes.empty?
           output += "\n#{options[:space]}------------ PROPERTIES ------------"
-          @items.each do |key, value|
-            output += "\n#{options[:space]}#{key.inspect} => #{value.class.name}"
+          @attributes.each do |key, value|
+            output += "\n#{options[:space]}#{key.inspect} => #{value.inspect}"
+          end
+        end
+        unless @items.empty?        
+          output += "\n#{options[:space]}------------ ITEMS ------------"
+          @items.each do |value|
+            output += "\n#{options[:space]}#{value.class.name}"
           end
         end
       end
       output += ">"
     end
     
-    
+    protected
+    def define_link(link)
+      if link.valid?
+        case link.rel
+        when 'parent'
+          @associations['parent'] = Resource.new(link.href, session)
+        when 'collection'
+          raw_included = link.resolved? ? raw[link.title] : nil
+          @associations[link.title] = Collection.new(link.href, session, 
+            :raw => raw_included,
+            :title => link.title)
+        when 'member'
+          raw_included = link.resolved? ? raw[link.title] : nil
+          @associations[link.title] = Resource.new(link.href, session, 
+            :title => link.title,
+            :raw => raw_included)
+        when 'self'
+          # we do nothing
+        end
+      else 
+        session.logger.warn link.errors.join("\n")
+      end
+    end
   end
 end