active_remote 1.2.1

data/lib/active_remote/bulk.rb

@@ -0,0 +1,143 @@
+require 'active_remote/persistence'
+
+module ActiveRemote
+  module Bulk
+    def self.included(klass)
+      klass.class_eval do
+        extend ActiveRemote::Bulk::ClassMethods
+        include ActiveRemote::Persistence
+      end
+    end
+
+    ##
+    # Class methods
+    #
+    module ClassMethods
+
+      # Create multiple records at the same time. Returns a collection of active
+      # remote objects from the passed records. Records that were not created
+      # are returned with error messages indicating what went wrong.
+      #
+      # ====Examples
+      #
+      #   # A single hash
+      #   Tag.create_all({ :name => 'foo' })
+      #
+      #   # Hashes
+      #   Tag.create_all({ :name => 'foo' }, { :name => 'bar' })
+      #
+      #   # Active remote objects
+      #   Tag.create_all(Tag.new(:name => 'foo'), Tag.new(:name => 'bar'))
+      #
+      #   # Protobuf objects
+      #   Tag.create_all(Generic::Remote::Tag.new(:name => 'foo'), Generic::Remote::Tag.new(:name => 'bar'))
+      #
+      #   # Bulk protobuf object
+      #   Tag.create_all(Generic::Remote::Tags.new(:records => [ Generic::Remote::Tag.new(:name => 'foo') ])
+      #
+      def create_all(*records)
+        remote = self.new
+        remote.execute(:create_all, parse_records(records))
+        remote.serialize_records
+      end
+
+      # Delete multiple records at the same time. Returns a collection of active
+      # remote objects from the passed records. Records that were not deleted
+      # are returned with error messages indicating what went wrong.
+      #
+      # ====Examples
+      #
+      #   # A single hash
+      #   Tag.delete_all({ :guid => 'foo' })
+      #
+      #   # Hashes
+      #   Tag.delete_all({ :guid => 'foo' }, { :guid => 'bar' })
+      #
+      #   # Active remote objects
+      #   Tag.delete_all(Tag.new(:guid => 'foo'), Tag.new(:guid => 'bar'))
+      #
+      #   # Protobuf objects
+      #   Tag.delete_all(Generic::Remote::Tag.new(:guid => 'foo'), Generic::Remote::Tag.new(:guid => 'bar'))
+      #
+      #   # Bulk protobuf object
+      #   Tag.delete_all(Generic::Remote::Tags.new(:records => [ Generic::Remote::Tag.new(:guid => 'foo') ])
+      #
+      def delete_all(*records)
+        remote = self.new
+        remote.execute(:delete_all, parse_records(records))
+        remote.serialize_records
+      end
+
+      # Destroy multiple records at the same time. Returns a collection of active
+      # remote objects from the passed records. Records that were not destroyed
+      # are returned with error messages indicating what went wrong.
+      #
+      # ====Examples
+      #
+      #   # A single hash
+      #   Tag.destroy_all({ :guid => 'foo' })
+      #
+      #   # Hashes
+      #   Tag.destroy_all({ :guid => 'foo' }, { :guid => 'bar' })
+      #
+      #   # Active remote objects
+      #   Tag.destroy_all(Tag.new(:guid => 'foo'), Tag.new(:guid => 'bar'))
+      #
+      #   # Protobuf objects
+      #   Tag.destroy_all(Generic::Remote::Tag.new(:guid => 'foo'), Generic::Remote::Tag.new(:guid => 'bar'))
+      #
+      #   # Bulk protobuf object
+      #   Tag.destroy_all(Generic::Remote::Tags.new(:records => [ Generic::Remote::Tag.new(:guid => 'foo') ])
+      #
+      def destroy_all(*records)
+        remote = self.new
+        remote.execute(:destroy_all, parse_records(records))
+        remote.serialize_records
+      end
+
+      # Parse given records to get them ready to be built into a request.
+      #
+      # It handles any object that responds to +to_hash+, so protobuf messages
+      # and active remote objects will work just like hashes.
+      #
+      # Returns +{ :records => records }+.
+      #
+      def parse_records(*records)
+        records.flatten!
+        records.collect!(&:to_hash)
+
+        return records.first if records.first.has_key?(:records)
+
+        # If we made it this far, build a bulk-formatted hash.
+        return { :records => records }
+      end
+
+      # Update multiple records at the same time. Returns a collection of active
+      # remote objects from the passed records. Records that were not updated
+      # are returned with error messages indicating what went wrong.
+      #
+      # ====Examples
+      #
+      #   # A single hash
+      #   Tag.update_all({ :guid => 'foo', :name => 'baz' })
+      #
+      #   # Hashes
+      #   Tag.update_all({ :guid => 'foo', :name => 'baz' }, { :guid => 'bar', :name => 'qux' })
+      #
+      #   # Active remote objects
+      #   Tag.update_all(Tag.new(:guid => 'foo', :name => 'baz'), Tag.new(:guid => 'bar', :name => 'qux'))
+      #
+      #   # Protobuf objects
+      #   Tag.update_all(Generic::Remote::Tag.new(:guid => 'foo', :name => 'baz'), Generic::Remote::Tag.new(:guid => 'bar', :name => 'qux'))
+      #
+      #   # Bulk protobuf object
+      #   Tag.update_all(Generic::Remote::Tags.new(:records => [ Generic::Remote::Tag.new(:guid => 'foo', :name => 'baz') ])
+      #
+      def update_all(*records)
+        remote = self.new
+        remote.execute(:update_all, parse_records(records))
+        remote.serialize_records
+      end
+    end
+  end
+end

data/lib/active_remote/dirty.rb

@@ -0,0 +1,70 @@
+require 'active_model/dirty'
+
+# Overrides persistence methods, providing support for dirty tracking.
+#
+module ActiveRemote
+  module Dirty
+    def self.included(klass)
+      klass.class_eval do
+        include ActiveModel::Dirty
+      end
+    end
+
+    # Override #reload to provide dirty tracking.
+    #
+    def reload(*)
+      super.tap do
+        @previously_changed.try(:clear)
+        @changed_attributes.clear
+      end
+    end
+
+    # Override #save to store changes as previous changes then clear them.
+    #
+    def save(*)
+      if status = super
+        @previously_changed = changes
+        @changed_attributes.clear
+      end
+
+      status
+    end
+
+    # Override #save to store changes as previous changes then clear them.
+    #
+    def save!(*)
+      super.tap do
+        @previously_changed = changes
+        @changed_attributes.clear
+      end
+    end
+
+    # Override #serialize_records so that we can clear changes after
+    # initializing records returned from a search.
+    #
+    def serialize_records(*)
+      if serialized_records = super
+        serialized_records.each do |record|
+          record.previous_changes.try(:clear)
+          record.changed_attributes.try(:clear)
+        end
+      end
+    end
+
+  private
+
+    # Override ActiveAttr's attribute= method so we can provide support for
+    # ActiveModel::Dirty.
+    #
+    def attribute=(name, value)
+      __send__("#{name}_will_change!") unless value == self[name]
+      super
+    end
+
+    # Override #update to only send changed attributes.
+    #
+    def update(*)
+      super(changed)
+    end
+  end
+end

data/lib/active_remote/dsl.rb

@@ -0,0 +1,141 @@
+require 'active_support/inflector'
+
+module ActiveRemote
+  module DSL
+    def self.included(klass)
+      klass.class_eval do
+        extend ActiveRemote::DSL::ClassMethods
+        include ActiveRemote::DSL::InstanceMethods
+      end
+    end
+
+    module ClassMethods
+
+      # Whitelist enable attributes for serialization purposes.
+      #
+      # ====Examples
+      #
+      #   # To only publish the :guid and :status attributes:
+      #   class User < ActiveRemote::Base
+      #     attr_publishable :guid, :status
+      #   end
+      #
+      def attr_publishable(*attributes)
+        @publishable_attributes ||= []
+        @publishable_attributes += attributes
+      end
+
+      # Set the number of records per page when auto paging.
+      #
+      # ====Examples
+      #
+      #   class User < ActiveRemote::Base
+      #     auto_paging_size 100
+      #   end
+      #
+      def auto_paging_size(size=nil)
+        @auto_paging_size = size unless size.nil?
+        @auto_paging_size ||= 1000
+      end
+
+      # Set the namespace for the underlying RPC service class. If no namespace
+      # is given, then none will be used.
+      #
+      # ====Examples
+      #
+      #   # If the user's service class is namespaced (e.g. Acme::UserService):
+      #   class User < ActiveRemote::Base
+      #     namespace :acme
+      #   end
+      #
+      def namespace(name = false)
+        @namespace = name unless name == false
+        @namespace
+      end
+
+      # Retrieve the attributes that have been whitelisted for serialization.
+      #
+      def publishable_attributes
+        @publishable_attributes
+      end
+
+      # Set the RPC service class directly. By default, ActiveRemove determines
+      # the RPC service by constantizing the namespace and service name.
+      #
+      # ====Examples
+      #
+      #   class User < ActiveRemote::Base
+      #     service_class Acme::UserService
+      #   end
+      #
+      #   # ...is the same as:
+      #
+      #   class User < ActiveRemote::Base
+      #     namespace :acme
+      #     service_name :user_service
+      #   end
+      #
+      #   # ...is the same as:
+      #
+      #   class User < ActiveRemote::Base
+      #     namespace :acme
+      #   end
+      #
+      def service_class(klass = false)
+        @service_class = klass unless klass == false
+        @service_class ||= _determine_service_class
+      end
+
+      # Set the name of the underlying RPC service class. By default, Active
+      # Remote assumes that a User model will have a UserService (making the
+      # service name :user_service).
+      #
+      # ====Examples
+      #
+      #   class User < ActiveRemote::Base
+      #     service_name :jangly_users
+      #   end
+      #
+      def service_name(name = false)
+        @service_name = name unless name == false
+        @service_name ||= _determine_service_name
+      end
+
+    private
+
+      # Combine the namespace and service values, constantize them and return
+      # the class constant.
+      #
+      def _determine_service_class
+        class_name = [ namespace, service_name ].join("/")
+        const_name = class_name.camelize
+
+        return const_name.present? ? const_name.constantize : const_name
+      end
+
+      def _determine_service_name
+        underscored_name = self.name.underscore
+        "#{underscored_name}_service".to_sym
+      end
+    end
+
+    # Convenience methods for accessing DSL methods in instances.
+    #
+    module InstanceMethods
+
+    private
+
+      def _publishable_attributes
+        self.class.publishable_attributes
+      end
+
+      def _service_name
+        self.class.service_name
+      end
+
+      def _service_class
+        self.class.service_class
+      end
+    end
+  end
+end

data/lib/active_remote/errors.rb

@@ -0,0 +1,24 @@
+# TODO: Create more specific errors
+#
+module ActiveRemote
+
+  # = Active Remote Errors
+  #
+  # Generic Active Remote exception class.
+  class ActiveRemoteError < StandardError
+  end
+
+  # Raised by ActiveRemove::Base.save when the remote record is readonly.
+  class ReadOnlyRemoteRecord < ActiveRemoteError
+  end
+
+  # Raised by ActiveRemove::Base.find when remote record is not found when
+  # searching with the given arguments.
+  class RemoteRecordNotFound < ActiveRemoteError
+  end
+
+  # Raised by ActiveRemove::Base.save! and ActiveRemote::Base.create! methods
+  # when remote record cannot be saved because it is invalid.
+  class RemoteRecordNotSaved < ActiveRemoteError
+  end
+end

data/lib/active_remote/persistence.rb

@@ -0,0 +1,226 @@
+require 'active_remote/rpc'
+
+module ActiveRemote
+  module Persistence
+    def self.included(klass)
+      klass.class_eval do
+        extend ActiveRemote::Persistence::ClassMethods
+        include ActiveRemote::Persistence::InstanceMethods
+        include ActiveRemote::RPC
+
+        define_model_callbacks :save
+      end
+    end
+
+    ##
+    # Class methods
+    #
+    module ClassMethods
+
+      # Creates a remote record through the service.
+      #
+      # The service will run any validations and if any of them fail, will return
+      # the record error messages indicating what went wrong.
+      #
+      # The newly created record is returned if it was successfully saved or not.
+      #
+      def create(attributes)
+        remote = self.new(attributes)
+        remote.save
+        remote
+      end
+
+      # Creates a remote record through the service and if successful, returns
+      # the newly created record.
+      #
+      # The service will run any validations and if any of them fail, will raise
+      # an ActiveRemote::RemoteRecordNotSaved exception.
+      #
+      def create!(attributes)
+        remote = self.new(attributes)
+        remote.save!
+        remote
+      end
+
+      # Mark the class as readonly. Overrides instance-level readonly, making
+      # any instance of this class readonly.
+      def readonly!
+        @readonly = true
+      end
+
+      # Returns true if the class is marked as readonly; otherwise, returns false.
+      def readonly?
+        @readonly
+      end
+    end
+
+    ##
+    # Instance methods
+    #
+    module InstanceMethods
+      # Deletes the record from the service (the service determines if the
+      # record is hard or soft deleted) and freezes this instance to indicate
+      # that no changes should be made (since they can't be persisted). If the
+      # record was not deleted, it will have error messages indicating what went
+      # wrong. Returns the frozen instance.
+      #
+      def delete
+        raise ReadOnlyRemoteRecord if readonly?
+        execute(:delete, attributes.slice("guid"))
+        freeze if success?
+      end
+
+      # Deletes the record from the service (the service determines if the
+      # record is hard or soft deleted) and freezes this instance to indicate
+      # that no changes should be made (since they can't be persisted). If the
+      # record was not deleted, an exception will be raised. Returns the frozen
+      # instance.
+      #
+      def delete!
+        delete
+        raise ActiveRemoteError.new(errors.to_s) if has_errors?
+      end
+
+      # Destroys (hard deletes) the record from the service and freezes this
+      # instance to indicate that no changes should be made (since they can't
+      # be persisted). If the record was not deleted, it will have error
+      # messages indicating what went wrong. Returns the frozen instance.
+      #
+      def destroy
+        raise ReadOnlyRemoteRecord if readonly?
+        execute(:destroy, attributes.slice("guid"))
+        freeze if success?
+      end
+
+      # Destroys (hard deletes) the record from the service and freezes this
+      # instance to indicate that no changes should be made (since they can't
+      # be persisted). If the record was not deleted, an exception will be
+      # raised. Returns the frozen instance.
+      #
+      def destroy!
+        destroy
+        raise ActiveRemoteError.new(errors.to_s) if has_errors?
+      end
+
+      # Returns true if the record has errors; otherwise, returns false.
+      #
+      def has_errors?
+        return respond_to?(:errors) && errors.present?
+      end
+
+      # Returns true if the remote record hasn't been saved yet; otherwise,
+      # returns false.
+      #
+      def new_record?
+        return self[:guid].nil?
+      end
+
+      # Returns true if the remote record has been saved; otherwise, returns false.
+      #
+      def persisted?
+        return ! new_record?
+      end
+
+      # Returns true if the remote class or remote record is readonly; otherwise, returns false.
+      def readonly?
+        self.class.readonly? || @readonly
+      end
+
+      # Saves the remote record.
+      #
+      # If it is a new record, it will be created through the service, otherwise
+      # the existing record gets updated.
+      #
+      # The service will run any validations and if any of them fail, will return
+      # the record with error messages indicating what went wrong.
+      #
+      # Also runs any before/after save callbacks that are defined.
+      #
+      def save
+        run_callbacks :save do
+          create_or_update
+        end
+      end
+
+      # Saves the remote record.
+      #
+      # If it is a new record, it will be created through the service, otherwise
+      # the existing record gets updated.
+      #
+      # The service will run any validations. If any of them fail (e.g. error
+      # messages are returned), an ActiveRemote::RemoteRecordNotSaved is raised.
+      #
+      # Also runs any before/after save callbacks that are defined.
+      #
+      def save!
+        save || raise(RemoteRecordNotSaved)
+      end
+
+      # Returns true if the record doesn't have errors; otherwise, returns false.
+      #
+      def success?
+        return ! has_errors?
+      end
+
+      # Updates the attributes of the remote record from the passed-in hash and
+      # saves the remote record. If the object is invalid, it will have error
+      # messages and false will be returned.
+      #
+      def update_attributes(attributes)
+        assign_attributes(attributes)
+        save
+      end
+
+      # Updates the attributes of the remote record from the passed-in hash and
+      # saves the remote record. If the object is invalid, an
+      # ActiveRemote::RemoteRecordNotSaved is raised.
+      #
+      def update_attributes!(attributes)
+        assign_attributes(attributes)
+        save!
+      end
+
+    private
+
+      # Handles creating a remote object and serializing it's attributes and
+      # errors from the response.
+      #
+      def create
+        new_attributes = attributes.deep_dup
+        new_attributes.delete("guid")
+
+        execute(:create, new_attributes)
+
+        assign_attributes(last_response.to_hash)
+        add_errors_from_response
+
+        success?
+      end
+
+      # Deterines whether the record should be created or updated. New records
+      # are created, existing records are updated. If the record is marked as
+      # readonly, an ActiveRemote::ReadOnlyRemoteRecord is raised.
+      #
+      def create_or_update
+        raise ReadOnlyRemoteRecord if readonly?
+        new_record? ? create : update
+      end
+
+      # Handles updating a remote object and serializing it's attributes and
+      # errors from the response. Only attributes with the given attribute names
+      # (plus :guid) will be updated. Defaults to all attributes.
+      #
+      def update(attribute_names = @attributes.keys)
+        updated_attributes = attributes.slice(*attribute_names)
+        updated_attributes.merge!("guid" => self[:guid])
+
+        execute(:update, updated_attributes)
+
+        assign_attributes(last_response.to_hash)
+        add_errors_from_response
+
+        success?
+      end
+    end
+  end
+end