storage_room 0.2.1 → 0.3.0

data/History.txt

@@ -1,3 +1,9 @@
+=== Version 0.3.0
+* Complete refactoring of internals. 
+  * Added support for associations
+  * Added support for identity map
+  * Added configurable Resources
+
 === Version 0.1.1
 
 * Added rdoc

data/README.rdoc

@@ -1,6 +1,13 @@
 == StorageRoom Gem
 
-This gem provides read and write access to the StorageRoom API (http://storageroomapp.com). It has an ActiveRecord/ActiveModel like interface.
+This gem provides read and write access to the StorageRoom API (http://storageroomapp.com). 
+
+== Main Features
+
+* ActiveRecord/ActiveModel like interface.
+* Automatic creation of Entry Classes from a Collection, you don't have to configure anything
+* Supports lazy-loading of associations (e.g. post.category will fetch a category transparently if it has not yet been loaded)
+* Supports caching through an identity map, so that Resources don't have to be loaded multiple times
 
 
 == Installation
@@ -17,10 +24,9 @@ This is a walkthrough with all steps you need to setup a devise entry, including
   StorageRoom.authenticate(YOUR_ACCOUNT_ID, YOUR_APPLICATION_API_KEY)
   collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
   
-  entries = collection.entries
-  entry = entries.resources.first
+  entry = collection.entries.resources.first # collection.entries contains meta information, the resources key contains the returned objects
   
-  entry[:name] = 'Foobar'
+  entry.name = 'Foobar'
   
   if entry.save
     puts "Entry saved."

data/Rakefile

@@ -12,7 +12,7 @@ begin
     gem.authors = ["Sascha Konietzke"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "webmock"
-    
+      
     gem.add_dependency 'httparty', '>= 0.6.1'
     gem.add_dependency 'activesupport', '>= 3.0.0'
     
@@ -45,3 +45,5 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+Dir['tasks/**/*.rake'].each { |t| load t }

data/TODO

@@ -1,5 +1,10 @@
 
+
 == Version X
 
-- have collection fields
-- executable/cli
+- have a gemfile?
+- make on/many only accept objects of correct class?
+- executable/cli
+- file uploads/removals
+  - get files via api
+- look at arguments with identity map  

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/examples/authentication.rb

@@ -1,6 +1,8 @@
 require File.dirname(__FILE__) + '/../lib/storage_room'
 
-ACCOUNT_ID = '4cef9a8c425071fa6900002f' # your account id
-APPLICATION_API_KEY = 'c499kx9L6aBfvJlvSKbF' # your application's API key with read/write access
+ACCOUNT_ID = '4dda7761b65245fde1000051' # your account id
+APPLICATION_API_KEY = 'kCWTmS1wxYnxzJyteuIn' # your application's API key with read/write access
 
-StorageRoom.authenticate(ACCOUNT_ID, APPLICATION_API_KEY)
+StorageRoom.authenticate(ACCOUNT_ID, APPLICATION_API_KEY)
+
+StorageRoom.server = "api.lvh.me:3000"

data/examples/create_entry.rb

@@ -2,13 +2,16 @@
 
 require File.dirname(__FILE__) + '/authentication'
 
+
 # fetch the collection first
-collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
+guidebook_collection = StorageRoom::Collection.find('4dda7761b65245fde100005d')
+category_collection  = StorageRoom::Collection.find('4dda7761b65245fde100001a')
 
-entry2 = collection.entry_class.new(:title => 'Bar', :price => 2.23)
+category = category_collection.entries.resources.first # find the first category
+guidebook = guidebook_collection.entry_class.new(:title => 'Bar', :price => 2.23, :category => category)
 
-if entry2.save
-  puts "Entry saved"
+if guidebook.save # save the guidebook with the associated category
+  puts "Guidebook Entry saved (#{guidebook[:@url]})"
 else
-  puts "Entry could not be saved: #{entry2.errors.join(', ')}"
+  puts "Guidebook could not be saved: #{entry2.errors.join(', ')}"
 end

data/examples/destroy_entry.rb

@@ -2,10 +2,10 @@
 
 require File.dirname(__FILE__) + '/authentication'
 
-collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
+collection = StorageRoom::Collection.find('4dda7761b65245fde100005d')
 
 entry = collection.entries.resources.first
 
 entry.destroy
 
-puts "Destroyed #{entry[:title]}"
+puts "Destroyed #{entry.title}"

data/examples/get_collections.rb

@@ -6,6 +6,6 @@ collections = StorageRoom::Collection.all
 
 puts "Collections:"
 
-collections.resources.each do |collection|
-  puts "- #{collection[:name]}"
+collections.resources.each do |collection| # The array returned by Collection.all contains all the items in the resources key
+  puts "- #{collection.name}"
 end

data/examples/import_csv.rb

@@ -8,14 +8,14 @@ lines = CSV.read(File.dirname(__FILE__) + '/guidebooks.csv') # Exported an Excel
 
 lines.slice!(0) # remove header line
 
-collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
-klass = collection.entry_class
+collection = StorageRoom::Collection.find('4dda7761b65245fde100005d')
+Guidebook = collection.entry_class
 
 lines.each do |row|
-  guidebook = klass.new(:title => row[0], :price => row[1].to_f)
+  guidebook = Guidebook.new(:title => row[0], :price => row[1].to_f)
 
   if guidebook.save
-    puts "Guidebook saved: #{guidebook[:title]}, #{guidebook[:price]}"
+    puts "Guidebook saved: #{guidebook.title}, #{guidebook.price}"
   else
     puts "Guidebook could not be saved: #{guidebook.errors.join(', ')}"
   end

data/examples/search_entries.rb

@@ -2,12 +2,12 @@
 
 require File.dirname(__FILE__) + '/authentication'
 
-collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
+collection = StorageRoom::Collection.find('4dda7761b65245fde100005d')
 
 entries = collection.entry_class.search(:title => 'Hitchhikers Guide to the Galaxy')
 
 puts "Entries with title 'Hitchhikers Guide to the Galaxy':"
 
 entries.resources.each do |entry|
-  puts "- #{entry[:title]} : #{entry.url}"
+  puts "- #{entry.title} : #{entry[:@url]}"
 end

data/examples/update_entry.rb

@@ -2,11 +2,11 @@
 
 require File.dirname(__FILE__) + '/authentication'
 
-collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
+collection = StorageRoom::Collection.find('4dda7761b65245fde100005d')
 
 entry = collection.entries.resources.first
 
-entry[:title] = 'Foobar'
+entry.title = 'Foobar'
 
 if entry.save
   puts "Entry saved"

data/lib/console.rb

@@ -0,0 +1,12 @@
+require 'storage_room'
+
+StorageRoom.debug = true
+
+# Optionally have an init file in your home directory
+file = File.expand_path('~/.storage_room_gem.rb')
+
+begin
+  require file
+rescue LoadError
+  StorageRoom.log("Could not load init file: #{file}")
+end

data/lib/storage_room.rb

@@ -5,38 +5,62 @@ begin; require 'rubygems'; rescue LoadError; end
 
 require 'httparty'
 require 'active_support/all' 
+require 'storage_room/extensions/const_defined'
 
+require 'storage_room/plugins'
 
-module StorageRoom
-  class AbstractMethod < RuntimeError; end
-  class RequestFailed < RuntimeError; end
+module StorageRoom  
+  class AbstractMethod      < RuntimeError; end
+  class RequestFailed       < RuntimeError; end
+  class ResourceNotLoaded   < RuntimeError; end
+  class ClassNotFound       < RuntimeError; end
   
-  autoload :Attributes,     'storage_room/attributes'
+  autoload :Plugins,                  'storage_room/plugins'
+  autoload :Accessors,                'storage_room/accessors'
+  autoload :Proxy,                    'storage_room/proxy'
+  autoload :IdentityMap,              'storage_room/identity_map'
   
-  autoload :Base,           'storage_room/base'
-  autoload :Model,          'storage_room/model'
-  autoload :Array,          'storage_room/array'
-  autoload :Field,          'storage_room/field'
-  autoload :Embedded,       'storage_room/embedded'
+  autoload :Resource,                 'storage_room/resource'
+  autoload :Model,                    'storage_room/model'
+  autoload :Array,                    'storage_room/array'
+
+  autoload :Embedded,                 'storage_room/embedded'
+  
+  autoload :Collection,               'storage_room/models/collection'
+  autoload :Entry,                    'storage_room/models/entry'
+
+  autoload :Field,                    'storage_room/embeddeds/field'  
+  
+  autoload :AtomicField,              'storage_room/embeddeds/fields/atomic_field'  
+  autoload :StringField,              'storage_room/embeddeds/fields/atomic/string_field'  
+  autoload :TimeField,                'storage_room/embeddeds/fields/atomic/time_field'  
+  autoload :IntegerField,             'storage_room/embeddeds/fields/atomic/integer_field'  
+  autoload :FloatField,               'storage_room/embeddeds/fields/atomic/float_field'  
+  autoload :DateField,                'storage_room/embeddeds/fields/atomic/date_field'  
+  autoload :BooleanField,             'storage_room/embeddeds/fields/atomic/boolean_field'  
   
-  autoload :Collection,     'storage_room/models/collection'
-  autoload :Entry,       'storage_room/models/entry'
+  autoload :CompoundField,            'storage_room/embeddeds/fields/compound_field'  
+  autoload :AttachmentField,          'storage_room/embeddeds/fields/compound/attachment_field'
+  autoload :FileField,                'storage_room/embeddeds/fields/compound/file_field'
+  autoload :ImageField,               'storage_room/embeddeds/fields/compound/image_field'
+  autoload :LocationField,            'storage_room/embeddeds/fields/compound/location_field'
   
-  autoload :File,           'storage_room/embeddeds/file'
-  autoload :Location,       'storage_room/embeddeds/location'
+  autoload :AssociationField,         'storage_room/embeddeds/fields/association_field'  
+  autoload :OneAssociationField,      'storage_room/embeddeds/fields/associations/one_association_field'  
+  autoload :ManyAssociationField,     'storage_room/embeddeds/fields/associations/many_association_field'  
+  
+  autoload :File,                     'storage_room/embeddeds/file'
+  autoload :Image,                    'storage_room/embeddeds/image'
+  autoload :Location,                 'storage_room/embeddeds/location'
 
 
   class << self
-    attr_reader :api_key
-    attr_reader :user_agent
-    attr_reader :account_id
-    attr_reader :ssl
-    attr_reader :proxy_server
-    attr_reader :proxy_port
+    attr_reader :api_key, :user_agent, :account_id, :ssl, :proxy_server, :proxy_port
+    attr_accessor :debug
     
     # Authenticate once before making any requests with your account id and the application's api key
     def authenticate(account_id, api_key)
-      Base.basic_auth(api_key, 'X')
+      Resource.basic_auth(api_key, 'X')
       @api_key = api_key
       @account_id = account_id
       update_uri
@@ -44,7 +68,7 @@ module StorageRoom
     
     # Change the user agent that is sent with all requests
     def user_agent=(agent)
-      Base.headers.merge!('User-Agent' => agent)
+      Resource.headers.merge!('User-Agent' => agent)
       @user_agent = agent
     end
     
@@ -58,6 +82,20 @@ module StorageRoom
       @server || 'api.storageroomapp.com'
     end
     
+    # Hash of all mappings from an Entry's @type to a local Ruby class, if a mapping doesn't exist a class name will be created automatically
+    def entry_class_mappings
+      @entry_class_mappings ||= {}
+    end
+    
+    # Add a new mapping
+    def add_entry_class_mapping(name, class_name)
+      self.entry_class_mappings[name] = class_name.to_s
+    end
+    
+    def entry_class_for_name(name) #:nodoc:
+      self.entry_class_mappings[name] || name.gsub(/\s+/, "").classify
+    end
+    
     # Requests are made with SSL
     def ssl=(ssl)
       @ssl = ssl
@@ -68,32 +106,33 @@ module StorageRoom
     def http_proxy(server, port)
       @proxy_server = server
       @proxy_port = port
-      Base.http_proxy(server, port)
+      Resource.http_proxy(server, port)
     end
     
     # Return a Ruby class for a StorageRoom type
-    def class_for_name(name) 
-      is_ruby_19 = method(:const_defined?).arity == 1 # ruby 1.9 check
-      
-      if is_ruby_19 ? StorageRoom.const_defined?(name)  : StorageRoom.const_defined?(name, false)
+    def class_for_name(name)     
+      name_with_mapping = entry_class_for_name(name)
+        
+      if StorageRoom.is_constant_defined?(name)
         "StorageRoom::#{name}".constantize
-      elsif is_ruby_19 ? Object.const_defined?(name) : Object.const_defined?(name, false)
-        name.constantize
+      elsif Object.is_constant_defined?(name_with_mapping)
+        name_with_mapping.constantize
       else
-        klass = Class.new(Entry) 
-        Object.const_set(name, klass)
-        
-        klass
+        raise ClassNotFound.new("Unknown class: #{name}")
       end
     end
     
+    def log(msg) #:nodoc:
+      puts("[DEBUG] #{msg}") if debug
+    end
+    
     private
     
       def update_uri
         protocol = self.ssl == true ? 'https' : 'http'
       
-        Base.base_uri "#{protocol}://#{self.server}/accounts/#{self.account_id}"
+        url = Resource.base_uri("#{protocol}://#{self.server}/accounts/#{self.account_id}")
       end
     
   end
-end
+end

data/lib/storage_room/accessors.rb

@@ -0,0 +1,190 @@
+module StorageRoom
+  
+  # Module that contains attributes methods shared between StorageRoom::Resource and StorageRoom::Embedded
+  module Accessors
+    extend ActiveSupport::Concern
+         
+    included do
+      self.class_inheritable_accessor :attribute_options
+      self.attribute_options ||= {}
+    end
+    
+    module InstanceMethods
+      # Optionally pass attributes to set up the object
+      def initialize(hash={})     
+        self.attributes = hash
+      end
+            
+      # Shortcut to get an attribute. 
+      def [](name)
+        self.response_data[name]
+      end
+        
+      # Takes a response data hash, saves it in the record and initializes the class from the response data
+      def set_from_response_data(hash)
+        self.response_data = hash
+        self.initialize_from_response_data
+        self
+      end
+        
+      # Return all of the objects attributes
+      def response_data
+        @_response_data ||= Hash.new.with_indifferent_access
+      end
+    
+      # Set the objects attributes with a hash. Only attributes passed in the hash are changed, existing ones are not overridden.
+      def response_data=(hash = {})
+        response_data.merge!(hash)
+      end
+      
+      # The attributes as they were defined with key, one, many
+      def attributes
+        @_attributes ||= Hash.new.with_indifferent_access
+      end
+    
+      def attributes=(args = {})
+        attributes.merge!(args)
+      end
+      
+      def as_json(args = {}) # :nodoc:
+        to_hash(args)
+      end
+      
+      # ActiveSupport seemed to cause problems when just using as_json, so using to_hash
+      def to_hash(args = {}) # :nodoc:
+        args ||= {}
+        hash = {}
+
+        self.attributes.each do |name, value|
+          hash[name] = if value.is_a?(::Array)
+            value.map{|x| x.respond_to?(:to_hash) ? x.to_hash(:nested => true) : x }
+          elsif value.respond_to?(:to_hash)
+            value.to_hash(:nested => true)
+          elsif value.respond_to?(:as_json)
+            value.as_json(:nested => true)
+          else
+            value
+          end
+        end
+        
+        hash
+      end
+          
+      def inspect # :nodoc:
+        body = attributes.map{|k, v| "#{k}: #{attribute_for_inspect(v)}"}.join(', ')
+        "#<#{self.class} #{body}>"        
+      end
+                
+      # Reset an object to its initial state with all attributes unset
+      def reset!
+        @_response_data = Hash.new.with_indifferent_access
+        @_attributes = Hash.new.with_indifferent_access
+        true
+      end
+    
+      # Has a Resource been loaded from the API
+      def loaded?
+        self.response_data.present?
+      end
+      
+      def proxy? # :nodoc:
+        false
+      end
+      
+      protected
+        # Iterate over the response data and initialize the attributes
+        def initialize_from_response_data # :nodoc:
+          self.class.attribute_options.each do |name, options|
+            value = if options[:type] == :key
+              self[name].blank? ? options[:default] : self[name]
+            elsif options[:type] == :one
+              hash = self[name.to_s]
+              hash && hash['@type'] ? self.class.new_from_response_data(hash) : nil
+            elsif options[:type] == :many
+              response_data[name] && response_data[name].map{|hash| self.class.new_from_response_data(hash)} || []
+            else
+              raise "Invalid type: #{options[:type]}"
+            end
+
+            send("#{name}=", value)
+          end
+        end
+        
+        def ensure_loaded # :nodoc:
+          if loaded?
+            yield if block_given?
+          else
+            raise StorageRoom::ResourceNotLoaded
+          end
+        end
+        
+        def attribute_for_inspect(value) # :nodoc:
+          if value.is_a?(String) && value.length > 50
+            "#{value[0..50]}...".inspect
+          elsif value.is_a?(Date) || value.is_a?(Time)
+            %("#{value.iso8601}")
+          else
+            value.inspect
+          end
+        end
+    end
+    
+    module ClassMethods 
+      # Load an object with the specified URL from the API
+      def load(url, parameters = {})
+        return nil if url.blank?
+        
+        StorageRoom.log("Loading #{url}")
+        httparty = get(url, parameters)
+      
+        handle_critical_response_errors(httparty)
+        new_from_response_data(httparty.parsed_response.first[1])
+      end
+      
+      # Creates a new object of the correct class and initializes it from the response data
+      def new_from_response_data(response_data)
+        object = StorageRoom.class_for_name(response_data['@type']).new.set_from_response_data(response_data)
+        
+        if object.is_a?(Entry) && !object.loaded? && !object.proxy?
+          StorageRoom.log("Return  #{response_data['url']} proxied")
+          Proxy.new(object)
+        else
+          object
+        end
+      end
+      
+      # Defines a basic key for a Resource
+      def key(name, options = {})
+        options.merge!(:type => :key, :default => nil)
+        define_attribute_methods(name, options)
+      end
+      
+      # Defines a to-one association for a Resource (embedded or association)
+      def one(name, options = {})
+        options.merge!(:type => :one, :default => nil)
+        define_attribute_methods(name, options)
+      end
+
+      # Defines a to-many association for a Resource (embedded or association)      
+      def many(name, options = {})
+        options.merge!(:type => :many, :default => [])
+        define_attribute_methods(name, options)
+      end
+      
+      # Creates getter and setter for an attribute
+      def define_attribute_methods(name, options) # :nodoc:       
+        define_method name do
+          attributes[name] || options[:default]
+        end
+        
+        define_method "#{name}=" do |object|
+          attributes[name] = object
+        end
+        
+        self.attribute_options[name] = options
+      end
+    end
+    
+  end
+  
+end