acfs 0.42.0 → 0.43.0

data/lib/acfs/resource/persistence.rb

@@ -0,0 +1,257 @@
+class Acfs::Resource
+  #
+  # Allow to track the persistence state of a model.
+  #
+  module Persistence
+    extend ActiveSupport::Concern
+
+    # @api public
+    #
+    # Check if the model is persisted. A model is persisted if
+    # it is saved after being created
+    #
+    # @example Newly created resource:
+    #   user = User.new name: "John"
+    #   user.persisted? # => false
+    #   user.save
+    #   user.persisted? # => true
+    #
+    # @example Modified resource:
+    #   user2 = User.find 5
+    #   user2.persisted? # => true
+    #   user2.name = 'Amy'
+    #   user2.persisted? # => true
+    #   user2.save
+    #   user2.persisted? # => true
+    #
+    # @return [Boolean] True if resource has been saved
+    #
+    def persisted?
+      !new?
+    end
+
+    # @api public
+    #
+    # Return true if model is a new record and was not saved yet.
+    #
+    # @return [Boolean] True if resource is newly created,
+    #   false otherwise.
+    #
+    def new?
+      !loaded?
+    end
+    alias_method :new_record?, :new?
+
+    # @api public
+    #
+    # Saves the resource.
+    #
+    # It will PUT to the service to update the resource or send
+    # a POST to create a new one if the resource is new.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @return [Boolean] True if save operation was successful,
+    #   false otherwise.
+    # @see #save! See {#save!} for available options.
+    #
+    def save(*args)
+      save!(*args)
+      true
+    rescue Acfs::Error
+      false
+    end
+
+    # @api public
+    #
+    # Saves the resource. Raises an error if something happens.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param opts [Hash] Hash with additional options.
+    # @option opts [Hash] :data Data to send to remote service.
+    #   Default will be resource attributes.
+    #
+    # @raise [Acfs::InvalidResource]
+    #   If remote services respond with 422 response. Will fill
+    #   errors with data from response
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @see #save
+    #
+    def save!(opts = {})
+      opts[:data] = attributes unless opts[:data]
+
+      operation((new? ? :create : :update), opts) do |data|
+        update_with data
+      end
+    rescue ::Acfs::InvalidResource => err
+      self.remote_errors = err.errors
+      raise err
+    end
+
+    # @api public
+    #
+    # Update attributes with given data and save resource.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param attrs [Hash] Hash with attributes to write.
+    # @param opts [Hash] Options passed to `save`.
+    #
+    # @return [Boolean]
+    #   True if save operation was successful, false otherwise.
+    #
+    # @see #save
+    # @see #attributes=
+    # @see #update_attributes!
+    #
+    def update_attributes(attrs, opts = {})
+      check_loaded! opts
+
+      self.attributes = attrs
+      save opts
+    end
+
+    # @api public
+    #
+    # Update attributes with given data and save resource.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param [Hash] attrs Hash with attributes to write.
+    # @param [Hash] opts Options passed to `save!`.
+    #
+    # @raise [Acfs::InvalidResource]
+    #   If remote services respond with 422 response. Will fill
+    #   errors with data from response
+    #
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @see #save!
+    # @see #attributes=
+    # @see #update_attributes
+    #
+    def update_attributes!(attrs, opts = {})
+      check_loaded! opts
+
+      self.attributes = attrs
+      save! opts
+    end
+
+    # @api public
+    #
+    # Destroy resource by sending a DELETE request.
+    #
+    # Deleting a resource is a synchronous operation.
+    #
+    # @return [Boolean]
+    # @see #delete!
+    #
+    def delete(opts = {})
+      delete! opts
+      true
+    rescue Acfs::Error
+      false
+    end
+
+    # @api public
+    #
+    # Destroy resource by sending a DELETE request.
+    # Will raise an error in case something goes wrong.
+    #
+    # Deleting a resource is a synchronous operation.
+
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @return [undefined]
+    # @see #delete
+    #
+    def delete!(opts = {})
+      opts[:params] ||= {}
+      opts[:params] = attributes_for_url(:delete).merge opts[:params]
+
+      operation :delete, opts do |data|
+        update_with data
+        freeze
+      end
+    end
+
+    private
+
+    def attributes_for_url(action)
+      arguments_for_url = self.class.location(action: action).arguments
+      attributes.slice(*arguments_for_url)
+    end
+
+    module ClassMethods
+      # @api public
+      #
+      # Create a new resource sending given data. If resource cannot be
+      # created an error will be thrown.
+      #
+      # Saving a resource is a synchronous operation.
+      #
+      # @param data [Hash{Symbol, String => Object}]
+      #   Data to send in create request.
+      #
+      # @return [self] Newly resource object.
+      #
+      # @raise [Acfs::InvalidResource]
+      #   If remote services respond with 422 response. Will fill
+      #   errors with data from response
+      #
+      # @raise [Acfs::ErroneousResponse]
+      #   If remote service respond with not successful response.
+      #
+      # @see Acfs::Model::Persistence#save! Available options. `:data`
+      #   will be overridden with provided data hash.
+      # @see #create
+      #
+      def create!(data, _opts = {})
+        new(data).tap(&:save!)
+      end
+
+      # @api public
+      #
+      # Create a new resource sending given data. If resource cannot be
+      # create model will be returned and error hash contains response
+      # errors if available.
+      #
+      # Saving a resource is a synchronous operation.
+      #
+      # @param data [Hash{Symbol, String => Object}]
+      #   Data to send in create request.
+      #
+      # @return [self] Newly resource object.
+      #
+      # @raise [Acfs::ErroneousResponse]
+      #   If remote service respond with not successful response.
+      #
+      # @see Acfs::Model::Persistence#save! Available options. `:data`
+      #   will be overridden with provided data hash.
+      # @see #create!
+      #
+      def create(data, _opts = {})
+        model = new data
+        model.save
+        model
+      end
+    end
+
+    private
+
+    def update_with(data)
+      self.attributes = data
+      loaded!
+    end
+
+    def check_loaded!(opts = {})
+      return if loaded? || opts[:force]
+      raise ::Acfs::ResourceNotLoaded.new resource: self
+    end
+  end
+end

data/lib/acfs/{model → resource}/query_methods.rb

@@ -1,10 +1,8 @@
-module Acfs::Model
-
+class Acfs::Resource
   # Methods providing the query interface for finding resouces.
   #
   # @example
-  #   class MyUser
-  #     include Acfs::Model
+  #   class MyUser < Acfs::Resource
   #   end
   #
   #   MyUser.find(5)               # Find single resource
@@ -16,8 +14,8 @@ module Acfs::Model
   module QueryMethods
     extend ActiveSupport::Concern
 
+    #
     module ClassMethods
-
       # @api public
       #
       # @overload find(id, opts = {})
@@ -26,59 +24,64 @@ module Acfs::Model
       #   @example
       #     user = User.find(5) # Will query `http://base.url/users/5`
       #
-      #   @param [ Fixnum  ] id Resource IDs to fetch from remote service.
-      #   @param [ Hash ] opts Additional options.
-      #   @option opts [ Hash ] :params Additional parameters added to request. `:id` will be overridden
-      #     with given ID.
+      #   @param id [Fixnum] Resource IDs to fetch from remote service.
+      #   @param params [Hash] Additional options.
+      #   @option opts [Hash] :params Additional parameters added to
+      #     request. `:id` will be overridden with given ID.
       #
-      #   @yield [ resource ] Callback block to be executed after resource was fetched successfully.
-      #   @yieldparam resource [ self ] Fetched resources.
+      #   @yield [resource] Callback block to be executed after resource
+      #     was fetched successfully.
+      #   @yieldparam resource [self] Fetched resources.
       #
-      #   @return [ self ] Resource object if only one ID was given.
+      #   @return [self] Resource object if only one ID was given.
       #
-      # @overload find(*ids, opts = {})
+      # @overload find(ids, opts = {})
       #   Load collection of specified resources by given IDs.
       #
       #   @example
-      #     User.find(1, 2, 5) # Will return collection and will request
-      #                        # `http://base.url/users/1`, `http://base.url/users/2`
-      #                        # and `http://base.url/users/5` parallel
-      #
-      #   @param [ Fixnum, ... ] ids One or more resource IDs to fetch from remote service.
-      #   @param [ Hash ] opts Additional options.
-      #   @option opts [ Hash ] :params Additional parameters added to request. `:id` will be overridden
-      #     with individual resource ID.
-      #
-      #   @yield [ collection ] Callback block to be executed after collection was fetched successfully.
-      #   @yieldparam resource [ Collection ] Collection with fetched resources.
-      #
-      #   @return [ Collection ] Collection of requested resources if multiple IDs were given.
-      #
-      def find(*attrs, &block)
-        opts  = attrs.extract_options!
-
-        attrs.size > 1 ? find_multiple(attrs, opts, &block) : find_single(attrs[0], opts, &block)
+      #     User.find([1, 2, 5]) # Will return collection and will request
+      #                          # `http://base.url/users/1`,
+      #                          # `http://base.url/users/2`
+      #                          # and `http://base.url/users/5` parallel
+      #
+      #   @param ids [Array<Integer>] List of resource IDs.
+      #   @param opts [Hash] Additional options.
+      #   @option opts [Hash] :params Additional parameters added to
+      #     request. `:id` will be overridden with individual resource ID.
+      #
+      #   @yield [collection] Callback block to be executed after collection
+      #     was fetched successfully.
+      #   @yieldparam resource [Collection] Collection with fetched resources.
+      #
+      #   @return [Collection] Collection of requested resources.
+      #
+      def find(id_or_ids, opts = {}, &block)
+        if id_or_ids.respond_to? :each
+          find_multiple id_or_ids, opts, &block
+        else
+          find_single id_or_ids, opts, &block
+        end
       end
 
       # @api public
       #
       # Try to load all resources.
       #
-      # @param [ Hash  ] params Request parameters that will be send to remote service.
+      # @param params [Hash] Request parameters that will be send to
+      #   remote service.
       #
-      # @yield [ collection ] Callback block to be executed when resource collection was loaded successfully.
-      # @yieldparam collection [ Collection ] Collection of fetched resources.
+      # @yield [collection] Callback block to be executed when resource
+      #   collection was loaded successfully.
+      # @yieldparam collection [Collection] Collection of fetched resources.
       #
-      # @return [ Collection ] Collection of requested resources.
+      # @return [Collection] Collection of requested resources.
       #
       def all(params = {}, opts = {}, &block)
         collection = ::Acfs::Collection.new self
         collection.__callbacks__ << block if block
 
         operation :list, opts.merge(params: params) do |data, response|
-          data.each do |obj|
-            collection << create_resource(obj)
-          end
+          data.each {|obj| collection << create_resource(obj) }
           collection.process_response response
           collection.loaded!
           collection.__invoke__
@@ -86,49 +89,57 @@ module Acfs::Model
 
         collection
       end
-      alias :where :all
+      alias_method :where, :all
 
       # @api public
       #
       # Try to load first resource. Return nil if no object can be loaded.
       #
-      # @param [ Hash  ] params Request parameters that will be send to remote service.
+      # @param params [Hash] Request parameters that will be send
+      #   to remote service.
       #
-      # @yield [ resource ] Callback block to be executed after resource was fetched (even if nil).
-      # @yieldparam resource [ self ] Fetched resource, nil if empty list is returned
+      # @yield [resource] Callback block to be executed after
+      #   resource was fetched (even if nil).
+      # @yieldparam resource [self] Fetched resource, nil
+      #   if empty list is returned
       #
-      # @return [ self ] Resource object, nil if empty list is returned
+      # @return [self] Resource object, nil if empty list is returned
       #
       def find_by(params, &block)
-        model = Acfs::Util::ResourceDelegator.new self.new
-        model.__callbacks__ << block unless block.nil?
-
-        operation :list, params: params do |data|
-          if data.empty?
-            model.__setobj__ nil
-          else
-            model.__setobj__ create_resource data.first, origin: model.__getobj__
+        Acfs::Util::ResourceDelegator.new(new).tap do |m|
+          m.__callbacks__ << block unless block.nil?
+          operation :list, params: params do |data|
+            if data.empty?
+              m.__setobj__ nil
+            else
+              m.__setobj__ create_resource(data.first, origin: m.__getobj__)
+            end
+            m.__invoke__
           end
-          model.__invoke__
         end
-
-        model
       end
 
       # @api public
       #
-      # Try to load first resource. Raise Acfs::ResourceNotFound exception if no object can be loaded.
+      # Try to load first resource. Raise Acfs::ResourceNotFound
+      # exception if no object can be loaded.
       #
-      # @param [ Hash  ] params Request parameters that will be send to remote service.
+      # @param params [Hash] Request parameters that will be send
+      #   to remote service.
       #
-      # @yield [ resource ] Callback block to be executed after resource was fetched successfully.
-      # @yieldparam resource [ self ] Fetched resource, nil if empty list is returned
+      # @yield [resource] Callback block to be executed after
+      #   resource was fetched successfully.
+      # @yieldparam resource [self] Fetched resource, nil
+      #   if empty list is returned
       #
-      # @return [ self ] Resource object, nil if empty list is returned
+      # @return [self] Resource object, nil if empty list is returned
       #
       def find_by!(params, &block)
         find_by params do |m|
-          raise Acfs::ResourceNotFound.new message: "Recieved erronious response: no `#{self.name}` with params #{params.to_s} found" if m.nil?
+          if m.nil?
+            raise Acfs::ResourceNotFound.new message: 'Recieved erronious ' \
+              "response: no `#{name}` with params #{params} found"
+          end
           block.call m unless block.nil?
         end
       end
@@ -158,7 +169,7 @@ module Acfs::Model
       def each_page(opts = {})
         cb = proc do |collection|
           yield collection
-          collection.next_page(&cb) rescue ArgumentError
+          collection.next_page(&cb)
         end
         where opts, &cb
       end
@@ -185,16 +196,17 @@ module Acfs::Model
       #
       def each_item(opts = {}, &block)
         each_page(opts) do |collection|
-          collection.each &block
+          collection.each(&block)
         end
       end
 
       private
+
       def find_single(id, opts, &block)
-        model = Acfs::Util::ResourceDelegator.new self.new
+        model = Acfs::Util::ResourceDelegator.new new
 
         opts[:params] ||= {}
-        opts[:params].merge!({ id: id }) unless id.nil?
+        opts[:params].merge! id: id unless id.nil?
 
         model.__callbacks__ << block unless block.nil?
 
@@ -235,12 +247,15 @@ module Acfs::Model
       def resource_class_lookup(type)
         return self if type.nil?
         klass = type.camelize.constantize
-        raise Acfs::ResourceTypeError.new type_name: type, base_class: self unless klass <= self
+
+        unless klass <= self
+          raise Acfs::ResourceTypeError.new type_name: type, base_class: self
+        end
+
         klass
       rescue NameError, NoMethodError
         raise Acfs::ResourceTypeError.new type_name: type, base_class: self
       end
-
     end
   end
 end