rod-rest 0.0.1.1 → 0.5.0

data/.gitignore

@@ -1 +1,2 @@
 .bundle
+pkg

data/Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    rod-rest (0.0.1)
+    rod-rest (0.0.1.1)
       faraday
       rod
       sinatra

data/Readme.md

@@ -1,3 +1,113 @@
 # rod-rest
 
 REST API for [Ruby Object Database](https://github.com/apohllo/rod)
+
+
+## Server
+
+Starting the server is as simple as:
+
+```ruby
+SomeDatabase.instance.open_database("path/to/rod/database")
+Rod::Rest::API.start_with_database(SomeDatabase.instance)
+```
+
+It starts Sinatra application listening by default on port 4567.
+
+## Client
+
+The client requires a `http_client` to be passed to the constructor. We
+recommend Faraday, e.g.
+
+```ruby
+faraday = Faraday.new(url: "http://localhost:4567")
+client = Rod::Rest::Client.new(http_client: faraday)
+```
+
+The client automatically fetches metadata, so there is no need to set it up.
+Assuming you have the following Rod classes defined on the server side:
+
+```ruby
+class Person < Rod::Model
+  field :name, :string, index: :hash
+  field :surname, :string, index: :hash
+end
+
+class Car < Rod::Model
+  field :brand, :string, index: :hash
+  has_one :owner, class_name: "Person"
+  has_many :drivers, class_name: "Person"
+end
+```
+
+
+The client provides the following calls:
+
+```ruby
+# return people count
+client.people_count()
+
+# find person by ROD id
+client.find_person(1)
+
+# find several people by their ROD ids
+client.find_people(1,2,3)
+# or
+client.find_people(1..3)
+
+# find people by name
+client.find_people_by_name("Albert")
+
+# find people by surname
+client.find_people_by_surname("Einstein")
+
+# return cars count
+client.cars_count()
+
+# find cars by brand
+car = client.find_cars_by_brand("Mercedes").first
+car.owner                                   # returns proxy to singular association
+car.drivers                                 # returns collection proxy
+car.drivers.each do |driver|
+  puts driver.name
+end
+
+puts car.drivers.first.name
+
+car.drivers[1..2].each do |driver|          # negative indices are not yet supported
+  puts driver.surname
+end
+```
+  
+There are also some more low-level API calls supported, by usually when you get the
+first object of some larger graph, there is no need to use them.
+
+
+## License
+
+(The MIT/X11 License)
+
+Copyright (c) 2014 Aleksander Pohl
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Feedback
+
+* mailto:apohllo@o2.pl

data/changelog.txt

@@ -0,0 +1,11 @@
+0.5.0
+#inspect & #to_s for major classes
+ProxyCache
+Improved readme
+Caching in CollectionProxy
+Support for index ranges and collections
+Support for id ranges and collections
+0.0.1.1
+Fix Ruby restriction in gemspec
+0.0.1
+Working version of the API

data/lib/rod/rest.rb

@@ -12,3 +12,4 @@ require 'rod/rest/metadata'
 require 'rod/rest/property_metadata'
 require 'rod/rest/resource_metadata'
 require 'rod/rest/proxy_factory'
+require 'rod/rest/proxy_cache'

data/lib/rod/rest/api.rb

@@ -15,59 +15,13 @@ module Rod
         def build_api_for(resource,options={})
           serializer = options[:serializer] || JsonSerializer.new
           resource_name = options[:resource_name] || plural_resource_name(resource)
-          get "/#{resource_name}" do
-            if params.empty?
-              serializer.serialize({count: resource.count})
-            elsif params.size == 1
-              name, value = params.first
-              if resource.respond_to?("find_all_by_#{name}")
-                serializer.serialize(resource.send("find_all_by_#{name}",value))
-              else
-                status 404
-                serializer.serialize(nil)
-              end
-            else
-              status 404
-              serializer.serialize(nil)
-            end
-          end
 
-          get "/#{resource_name}/:id" do
-            object = resource.find_by_rod_id(params[:id].to_i)
-            if object
-              serializer.serialize(object)
-            else
-              status 404
-              serializer.serialize(nil)
-            end
-          end
+          define_index(resource,resource_name,serializer)
+          define_show(resource,resource_name,serializer)
 
           resource.plural_associations.each do |property|
-            get "/#{resource_name}/:id/#{property.name}" do
-              object = resource.find_by_rod_id(params[:id].to_i)
-              if object
-                serializer.serialize({count: object.send("#{property.name}_count") })
-              else
-                status 404
-                serializer.serialize(nil)
-              end
-            end
-
-            get "/#{resource_name}/:id/#{property.name}/:index" do
-              object = resource.find_by_rod_id(params[:id].to_i)
-              if object
-                related_object = object.send(property.name)[params[:index].to_i]
-                if related_object
-                  serializer.serialize(related_object)
-                else
-                  status 404
-                  serializer.serialize(nil)
-                end
-              else
-                status 404
-                serializer.serialize(nil)
-              end
-            end
+            define_association_index(resource,resource_name,property,serializer)
+            define_association_show(resource,resource_name,property,serializer)
           end
         end
 
@@ -94,6 +48,150 @@ module Rod
           end
           run!(web_options)
         end
+
+        protected
+        # GET /cars
+        # GET /cars?name=Mercedes
+        def define_index(resource,resource_name,serializer)
+          get index_path(resource_name) do
+            case params.size
+            when 0
+              respond_with_count(resource,serializer)
+            when 1
+              index_name, searched_value = params.first
+              respond_with_indexed_resource(resource,index_name,searched_value,serializer)
+            else
+              respond_with_nil(serializer)
+            end
+          end
+        end
+
+        # GET /cars/1
+        # GET /cars/1..3
+        # GET /cars/1,2,3
+        def define_show(resource,resource_name,serializer)
+          get show_path(resource_name) do
+            respond_with_resource(params[:id],resource,serializer)
+          end
+        end
+
+        # GET /cars/1/drivers
+        def define_association_index(resource,resource_name,property,serializer)
+          get association_index_path(resource_name,property.name) do
+            respond_with_related_count(resource,property.name,params[:id].to_i,serializer)
+          end
+        end
+
+        # GET /cars/1/drivers/0
+        # GET /cars/1/drivers/0..2
+        # GET /cars/1/drivers/0,1,2
+        def define_association_show(resource,resource_name,property,serializer)
+          get association_show_path(resource_name,property.name) do
+            respond_with_related_resource(params[:id].to_i,params[:index],resource,property,serializer)
+          end
+        end
+
+        def index_path(resource_name)
+          "/#{resource_name}"
+        end
+
+        def show_path(resource_name)
+          "/#{resource_name}/:id"
+        end
+
+        def association_index_path(resource_name,property_name)
+          "/#{resource_name}/:id/#{property_name}"
+        end
+
+        def association_show_path(resource_name,property_name)
+          "/#{resource_name}/:id/#{property_name}/:index"
+        end
+      end
+
+      protected
+      def respond_with_resource(id_param,resource,serializer)
+        id_or_range = extract_elements(id_param)
+        result =
+          if Integer === id_or_range
+            fetch_one(id_or_range,resource)
+          else
+            fetch_collection(id_or_range,resource)
+          end
+        serializer.serialize(result)
+      end
+
+      def respond_with_related_resource(id,index_param,resource,property,serializer)
+        object = resource.find_by_rod_id(id)
+        if object
+          index_or_range = extract_elements(index_param)
+          result =
+            if Integer === index_or_range
+              fetch_one_related(index_or_range,object,property)
+            else
+              fetch_related_collection(index_or_range,object,property)
+            end
+          serializer.serialize(result)
+        else
+          respond_with_nil(serializer)
+        end
+      end
+
+      def respond_with_count(resource,serializer)
+        serializer.serialize({count: resource.count})
+      end
+
+      def respond_with_related_count(resource,property_name,id,serializer)
+        object = resource.find_by_rod_id(id)
+        if object
+          serializer.serialize({count: object.send("#{property_name}_count") })
+        else
+          respond_with_nil(serializer)
+        end
+      end
+
+      def respond_with_indexed_resource(resource,index_name,searched_value,serializer)
+        if resource.respond_to?("find_all_by_#{index_name}")
+          serializer.serialize(resource.send("find_all_by_#{index_name}",searched_value))
+        else
+          respond_with_nil(serializer)
+        end
+      end
+
+      def fetch_collection(ids,resource)
+        ids.map{|id| resource.find_by_rod_id(id) }.compact
+      end
+
+      def fetch_one(id,resource)
+        resource.find_by_rod_id(id) || report_not_found
+      end
+
+      def fetch_related_collection(indices,object,property)
+        indices.map{|index| object.send(property.name)[index] }.compact
+      end
+
+      def fetch_one_related(index,object,property)
+        object.send(property.name)[index] || report_not_found
+      end
+
+      def extract_elements(id)
+        case id
+        when /^(\d+)\.\.(\d+)/
+          ($~[1].to_i..$~[2].to_i)
+        when /,/
+          id.split(",").map(&:to_i)
+        else
+          id.to_i
+        end
+      end
+
+      def report_not_found
+        status 404
+        nil
+      end
+
+      def respond_with_nil(serializer)
+        report_not_found
+        serializer.serialize(nil)
       end
     end
   end

data/lib/rod/rest/client.rb

@@ -18,11 +18,18 @@ module Rod
       #   be provided).
       # * metadata_factory - factory used to build the metadata (used only if
       #   metadata was not provided).
+      # * proxy_cache - used to cache proxied objects. By default it is
+      #   ProxyCache. Might be disabled by passing +nil+.
       def initialize(options={})
         @web_client = options.fetch(:http_client)
         @parser = options[:parser] || JSON
         @proxy_factory_class = options[:factory] || ProxyFactory
         @url_encoder = options[:url_encoder] || CGI
+        if options.has_key?(:proxy_cache)
+          @proxy_cache = options[:proxy_cache]
+        else
+          @proxy_cache = ProxyCache.new
+        end
 
         @metadata = options[:metadata]
         if @metadata
@@ -46,7 +53,7 @@ module Rod
       def fetch_object(object_stub)
         check_stub(object_stub)
         check_method(object_stub)
-        __send__(primary_finder_method_name(object_stub[:type]),object_stub[:rod_id])
+        __send__(primary_finder_method(object_stub[:type]),object_stub[:rod_id])
       end
 
       # Fetch object related via the association to the +subject+.
@@ -54,10 +61,19 @@ module Rod
       # the +index+-th element in the collection.
       def fetch_related_object(subject,association_name,index)
         check_subject_and_association(subject,association_name)
-        __send__(association_method_name(subject.type,association_name),subject.rod_id,index)
+        __send__(association_method(subject.type,association_name),subject.rod_id,index)
+      end
+
+      # Fetch objects related via the association to the +subject+.
+      # The association name is +association_name+ and the objects are the
+      # objects indicated by the idices. This might be a range or a comma
+      # separated list of indices.
+      def fetch_related_objects(subject,association_name,*indices)
+        check_subject_and_association(subject,association_name)
+        __send__(plural_association_method(subject.type,association_name),subject.rod_id,*indices)
       end
 
-      # Overrided in order to fetch the metadata when it was not provided in the
+      # Overrided in order to fetch the metadata if it was not provided in the
       # constructor.
       def method_missing(*args)
         unless @metadata.nil?
@@ -68,6 +84,16 @@ module Rod
         self.send(*args)
       end
 
+      # Detailed description of the client.
+      def inspect
+        "Rod::Rest::Client<port: #{@web_client.port}, host: #{@web_client.host}>"
+      end
+
+      # Short description of the client.
+      def to_s
+        "ROD REST API client"
+      end
+
       private
       def fetch_metadata
         response = @web_client.get(metadata_path())
@@ -81,17 +107,17 @@ module Rod
         define_counters(metadata)
         define_finders(metadata)
         define_relations(metadata)
-        @factory = @proxy_factory_class.new(metadata.resources,self)
+        @factory = @proxy_factory_class.new(metadata.resources,self,cache: @proxy_cache)
       end
 
       def define_counters(metadata)
         metadata.resources.each do |resource|
-          self.define_singleton_method("#{plural_resource_name(resource)}_count") do
-            get_parsed_response(resource_path(resource))[:count]
+          self.define_singleton_method(count_method(resource)) do
+            return_count(count_path(resource))
           end
           resource.plural_associations.each do |association|
-            self.define_singleton_method(association_count_method_name(resource,association.name)) do |id|
-              get_parsed_response(association_count_path(resource,id,association.name))[:count]
+            self.define_singleton_method(association_count_method(resource,association.name)) do |id|
+              return_count(association_count_path(resource,id,association.name))
             end
           end
         end
@@ -99,12 +125,15 @@ module Rod
 
       def define_finders(metadata)
         metadata.resources.each do |resource|
-          self.define_singleton_method(primary_finder_method_name(resource)) do |id|
-            @factory.build(get_parsed_response(primary_resource_finder_path(resource,id)))
+          self.define_singleton_method(primary_finder_method(resource)) do |id|
+            return_single(primary_resource_finder_path(resource,id))
+          end
+          self.define_singleton_method(plural_finder_method(resource)) do |*id|
+            return_collection(plural_resource_finder_path(resource,id))
           end
           resource.indexed_properties.each do |property|
-            self.define_singleton_method(finder_method_name(resource,property.name)) do |value|
-              get_parsed_response(resource_finder_path(resource,property.name,value)).map{|hash| @factory.build(hash) }
+            self.define_singleton_method(finder_method(resource,property.name)) do |value|
+              return_collection(resource_finder_path(resource,property.name,value))
             end
           end
         end
@@ -113,13 +142,28 @@ module Rod
       def define_relations(metadata)
         metadata.resources.each do |resource|
           resource.plural_associations.each do |association|
-            self.define_singleton_method(association_method_name(resource,association.name)) do |id,index|
-              @factory.build(get_parsed_response(association_path(resource,association.name,id,index)))
+            self.define_singleton_method(association_method(resource,association.name)) do |id,index|
+              return_single(association_path(resource,association.name,id,index))
+            end
+            self.define_singleton_method(plural_association_method(resource,association.name)) do |id,*indices|
+              return_collection(plural_association_path(resource,association.name,id,*indices))
             end
           end
         end
       end
 
+      def return_count(path)
+        get_parsed_response(path)[:count]
+      end
+
+      def return_single(path)
+        @factory.build(get_parsed_response(path))
+      end
+
+      def return_collection(path)
+        get_parsed_response(path).map{|hash| @factory.build(hash) }
+      end
+
       def get_parsed_response(path)
         result = @web_client.get(path)
         check_status(result,path)
@@ -144,18 +188,18 @@ module Rod
       end
 
       def check_method(object_stub)
-        unless self.respond_to?(primary_finder_method_name(object_stub[:type]))
-          raise APIError.new(invalid_method_error(primary_finder_method_name(object_stub[:type])))
+        unless self.respond_to?(primary_finder_method(object_stub[:type]))
+          raise APIError.new(invalid_method_error(primary_finder_method(object_stub[:type])))
         end
       end
 
       def check_subject_and_association(subject,association_name)
-        unless self.respond_to?(association_method_name(subject.type,association_name))
-          raise APIError.new(invalid_method_error(association_method_name(subject.type,association_name)))
+        unless self.respond_to?(association_method(subject.type,association_name))
+          raise APIError.new(invalid_method_error(association_method(subject.type,association_name)))
         end
       end
 
-      def resource_path(resource)
+      def count_path(resource)
         "/#{plural_resource_name(resource)}"
       end
 
@@ -163,6 +207,10 @@ module Rod
         "/#{plural_resource_name(resource)}/#{id}"
       end
 
+      def plural_resource_finder_path(resource,*ids)
+        "/#{plural_resource_name(resource)}/#{convert_path_elements(*ids)}"
+      end
+
       def resource_finder_path(resource,property_name,value)
         "/#{plural_resource_name(resource)}#{finder_query(property_name,value)}"
       end
@@ -175,26 +223,50 @@ module Rod
         "/#{plural_resource_name(resource)}/#{id}/#{association_name}/#{index}"
       end
 
+      def plural_association_path(resource,association_name,id,*indices)
+        "/#{plural_resource_name(resource)}/#{id}/#{association_name}/#{convert_path_elements(*indices)}"
+      end
+
       def metadata_path
         "/metadata"
       end
 
-      def primary_finder_method_name(resource)
+      def convert_path_elements(*elements)
+        if elements.size == 1 && Range === elements.first
+          elements.first.to_s
+        else
+          elements.join(",")
+        end
+      end
+
+      def count_method(resource)
+        "#{plural_resource_name(resource)}_count"
+      end
+
+      def primary_finder_method(resource)
         "find_#{singular_resource_name(resource)}"
       end
 
-      def finder_method_name(resource,property_name)
+      def plural_finder_method(resource)
+        "find_#{plural_resource_name(resource)}"
+      end
+
+      def finder_method(resource,property_name)
         "find_#{plural_resource_name(resource)}_by_#{property_name}"
       end
 
-      def association_count_method_name(resource,association_name)
+      def association_count_method(resource,association_name)
         "#{singular_resource_name(resource)}_#{association_name}_count"
       end
 
-      def association_method_name(resource,association_name)
+      def association_method(resource,association_name)
         "#{singular_resource_name(resource)}_#{association_name.to_s.singularize}"
       end
 
+      def plural_association_method(resource,association_name)
+        "#{singular_resource_name(resource)}_#{association_name.to_s}"
+      end
+
       def finder_query(property_name,value)
         "?#{@url_encoder.escape(property_name)}=#{@url_encoder.escape(value)}"
       end