Merge branch 'master' into provide_fields_to_operation

Conflicts:
	lib/jsonapi/operation.rb

Author: senid231

.travis.yml

@@ -3,15 +3,14 @@ sudo: false
 env:
   - "RAILS_VERSION=4.1.0"
   - "RAILS_VERSION=4.2.6"
-  - "RAILS_VERSION=5.0.0.beta3"
+  - "RAILS_VERSION=5.0.0.rc1"
 rvm:
-  - 2.0
   - 2.1
   - 2.2.4
   - 2.3.0
 matrix:
   exclude:
     - rvm: 2.0
-      env: "RAILS_VERSION=5.0.0.beta3"
+      env: "RAILS_VERSION=5.0.0.rc1"
     - rvm: 2.1
-      env: "RAILS_VERSION=5.0.0.beta3"
+      env: "RAILS_VERSION=5.0.0.rc1"

README.md

@@ -36,6 +36,7 @@ backed by ActiveRecord models or by custom objects.
     * [Error Codes] (#error-codes)
     * [Handling Exceptions] (#handling-exceptions)
     * [Action Callbacks] (#action-callbacks)
+  * [Operation Processors] (#operation-processors)
   * [Serializer] (#serializer)
     * [Serializer options] (#serializer-options)
     * [Formatting] (#formatting)
@@ -1117,68 +1118,31 @@ Callbacks can be defined for the following `JSONAPI::Resource` events:
 - `:remove_to_one_link`
 - `:replace_fields`
 
-##### `JSONAPI::OperationsProcessor` Callbacks
+##### `JSONAPI::Processor` Callbacks
 
-Callbacks can also be defined for `JSONAPI::OperationsProcessor` events:
-- `:operations`: The set of operations.
+Callbacks can also be defined for `JSONAPI::Processor` events:
 - `:operation`: Any individual operation.
-- `:find_operation`: A `find_operation`.
-- `:show_operation`: A `show_operation`.
-- `:show_relationship_operation`: A `show_relationship_operation`.
-- `:show_related_resource_operation`: A `show_related_resource_operation`.
-- `:show_related_resources_operation`: A `show_related_resources_operation`.
-- `:create_resource_operation`: A `create_resource_operation`.
-- `:remove_resource_operation`: A `remove_resource_operation`.
-- `:replace_fields_operation`: A `replace_fields_operation`.
-- `:replace_to_one_relationship_operation`: A `replace_to_one_relationship_operation`.
-- `:create_to_many_relationship_operation`: A `create_to_many_relationship_operation`.
-- `:replace_to_many_relationship_operation`: A `replace_to_many_relationship_operation`.
-- `:remove_to_many_relationship_operation`: A `remove_to_many_relationship_operation`.
-- `:remove_to_one_relationship_operation`: A `remove_to_one_relationship_operation`.
-
-The operation callbacks have access to two meta data hashes, `@operations_meta` and `@operation_meta`, two links hashes,
-`@operations_links` and `@operation_links`, the full list of `@operations`, each individual `@operation` and the
-`@result` variables.
-
-##### Custom `OperationsProcessor` Example to Return total_count in Meta
-
-Note: this can also be accomplished with the `top_level_meta_include_record_count` option, and in most cases that will
-be the better option.
-
-To return the total record count of a find operation in the meta data of a find operation you can create a custom
-OperationsProcessor. For example:
-
-```ruby
-# lib/jsonapi/counting_active_record_operations_processor.rb
-class CountingActiveRecordOperationsProcessor < ActiveRecordOperationsProcessor
-  after_find_operation do
-    @operation_meta[:total_records] = @operation.record_count
-  end
-end
-```
-
-Set the configuration option `operations_processor` to use the new `CountingActiveRecordOperationsProcessor` by
-specifying the snake cased name of the class (without the `OperationsProcessor`).
-
-```ruby
-require 'jsonapi/counting_active_record_operations_processor'
-
-JSONAPI.configure do |config|
-  config.operations_processor = :counting_active_record
-end
-```
-
-To use a specific `OperationsProcessor` in a `ResourceController`, override the `create_operations_processor` method:
-
-```ruby
-def create_operations_processor
-  CountingActiveRecordOperationsProcessor.new
-end
-```
-
-The callback code will be called after each find. It will use the same options as the find operation, without the
-pagination, to collect the record count. This is stored in the `operation_meta`, which will be returned in the top level
-meta element.
+- `:find`: A `find` operation is being processed.
+- `:show`: A `show` operation is being processed.
+- `:show_relationship`: A `show_relationship` operation is being processed.
+- `:show_related_resource`: A `show_related_resource` operation is being processed.
+- `:show_related_resources`: A `show_related_resources` operation is being processed.
+- `:create_resource`: A `create_resource` operation is being processed.
+- `:remove_resource`: A `remove_resource` operation is being processed.
+- `:replace_fields`: A `replace_fields` operation is being processed.
+- `:replace_to_one_relationship`: A `replace_to_one_relationship` operation is being processed.
+- `:create_to_many_relationship`: A `create_to_many_relationship` operation is being processed.
+- `:replace_to_many_relationship`: A `replace_to_many_relationship` operation is being processed.
+- `:remove_to_many_relationship`: A `remove_to_many_relationship` operation is being processed.
+- `:remove_to_one_relationship`: A `remove_to_one_relationship` operation is being processed.
+
+See [Operation Processors] (#operation-processors) for details on using OperationPprocessors
+
+##### `JSONAPI::OperationsProcessor` Callbacks (a removed feature)
+
+Note: The `JSONAPI::OperationsProcessor` has been removed and replaced with the `JSONAPI::OperationDispatcher`
+and `Processor` classes per resource. The callbacks have been renamed and moved to the
+`Processor`s, with the exception of the `operations` callback which is now on the controller.
 
 ### Controllers
 
@@ -1202,6 +1166,7 @@ end
 Of course you are free to extend this as needed and override action handlers or other methods.
 
 A jsonapi-controller generator is avaliable
+
 ```
 rails generate jsonapi:controller contact
 ```
@@ -1417,6 +1382,56 @@ class UsersController < JSONAPI::ResourceController
 end
 ```
 
+### Operation Processors
+
+Operation Processors are called to perform the operation(s) that make up a request. The controller (through the `OperationDispatcher`), creates an `OperatorProcessor` to handle each operation. The processor is created based on the resource name, including the namespace. If a processor does not exist for a resource (namespace matters) the default operation processor is used instead. The default processor can be changed by a configuration setting.
+
+Defining a custom `Processor` allows for custom callback handling of each operation type for each resource type. For example:
+
+```ruby
+class Api::V4::BookProcessor < JSONAPI::Processor
+  after_find do
+    unless @result.is_a?(JSONAPI::ErrorsOperationResult)
+      @result.meta[:total_records_found] = @result.record_count
+    end
+  end
+end
+```
+
+This simple example uses a callback to update the result's meta property with the total count of records (a redundant
+feature only for example purposes), if there wasn't an error in the operation.  It is also possible to override the
+`find` method as well if a different behavior is needed, for example:
+
+```ruby
+class Api::V4::BookProcessor < JSONAPI::Processor
+  def find
+    filters = params[:filters]
+    include_directives = params[:include_directives]
+    sort_criteria = params.fetch(:sort_criteria, [])
+    paginator = params[:paginator]
+
+    verified_filters = resource_klass.verify_filters(filters, context)
+    resource_records = resource_klass.find(verified_filters,
+                                           context: context,
+                                           include_directives: include_directives,
+                                           sort_criteria: sort_criteria,
+                                           paginator: paginator)
+
+    page_options = {}
+    # Overriding the default record count logic to always include it in the meta
+    #if (JSONAPI.configuration.top_level_meta_include_record_count ||
+    #  (paginator && paginator.class.requires_record_count))
+      page_options[:record_count] = resource_klass.find_count(verified_filters,
+                                                              context: context,
+                                                              include_directives: include_directives)
+    #end
+end
+```
+
+Note: The authors of this gem expect the most common uses cases to be handled using the callbacks. It is likely that the
+internal functionality of the operation processing methods will change, at least for several revisions. Effort will be
+made to call this out in release notes. You have been warned.
+
 ### Serializer
 
 The `ResourceSerializer` can be used to serialize a resource into JSON API compliant JSON. `ResourceSerializer` must be
@@ -1837,8 +1852,7 @@ JR has a few configuration options. Some have already been mentioned above. To s
 initializer and add the options you wish to set. All options have defaults, so you only need to set the options that
 are different. The default options are shown below.
 
-If using custom classes (such as the CountingActiveRecordOperationsProcessor, or a CustomPaginator),
-be sure to require them at the top of the initializer before usage.
+If using custom classes (such as a CustomPaginator), be sure to require them at the top of the initializer before usage.
 
 ```ruby
 JSONAPI.configure do |config|
@@ -1848,8 +1862,9 @@ JSONAPI.configure do |config|
   #:underscored_route, :camelized_route, :dasherized_route, or custom
   config.route_format = :dasherized_route
 
-  #:basic, :active_record, or custom
-  config.operations_processor = :active_record
+  # Default Processor, used if a resource specific one is not defined.
+  # Must be a class
+  config.default_processor_klass = JSONAPI::Processor
 
   #:integer, :uuid, :string, or custom (provide a proc)
   config.resource_key_type = :integer

lib/jsonapi-resources.rb

@@ -13,9 +13,9 @@
 require 'jsonapi/exceptions'
 require 'jsonapi/error'
 require 'jsonapi/error_codes'
-require 'jsonapi/request'
-require 'jsonapi/operations_processor'
-require 'jsonapi/active_record_operations_processor'
+require 'jsonapi/request_parser'
+require 'jsonapi/operation_dispatcher'
+require 'jsonapi/processor'
 require 'jsonapi/relationship'
 require 'jsonapi/include_directives'
 require 'jsonapi/operation_result'

lib/jsonapi/active_record_operations_processor.rb

@@ -7,9 +7,11 @@ module ActsAsResourceController
 
     def self.included(base)
       base.extend ClassMethods
+      base.include Callbacks
       base.before_action :ensure_correct_media_type, only: [:create, :update, :create_relationship, :update_relationship]
       base.before_action :ensure_valid_accept_media_type
       base.cattr_reader :server_error_callbacks
+      base.define_jsonapi_resources_callbacks :process_operations
     end
 
     def index
@@ -57,23 +59,44 @@ def get_related_resources
     end
 
     def process_request
-      @request = JSONAPI::Request.new(params, context: context,
-                                      key_formatter: key_formatter,
-                                      server_error_callbacks: (self.class.server_error_callbacks || []))
+      @request = JSONAPI::RequestParser.new(params, context: context,
+                                            key_formatter: key_formatter,
+                                            server_error_callbacks: (self.class.server_error_callbacks || []))
       unless @request.errors.empty?
         render_errors(@request.errors)
       else
-        operation_results = create_operations_processor.process(@request)
-        render_results(operation_results)
+        process_operations
+        render_results(@operation_results)
       end
 
     rescue => e
       handle_exceptions(e)
     end
 
-    # set the operations processor in the configuration or override this to use another operations processor
-    def create_operations_processor
-      JSONAPI.configuration.operations_processor.new
+    def process_operations
+      run_callbacks :process_operations do
+        @operation_results = operation_dispatcher.process(@request.operations)
+      end
+    end
+
+    def transaction
+      lambda { |&block|
+        ActiveRecord::Base.transaction do
+          block.yield
+        end
+      }
+    end
+
+    def rollback
+      lambda {
+        fail ActiveRecord::Rollback
+      }
+    end
+
+    def operation_dispatcher
+      @operation_dispatcher ||= JSONAPI::OperationDispatcher.new(transaction: transaction,
+                                                                 rollback: rollback,
+                                                                 server_error_callbacks: @request.server_error_callbacks)
     end
 
     private

lib/jsonapi/acts_as_resource_controller.rb

@@ -1,6 +1,5 @@
 require 'jsonapi/formatter'
-require 'jsonapi/operations_processor'
-require 'jsonapi/active_record_operations_processor'
+require 'jsonapi/processor'
 require 'concurrent'
 
 module JSONAPI
@@ -9,13 +8,13 @@ class Configuration
                 :resource_key_type,
                 :route_format,
                 :raise_if_parameters_not_allowed,
-                :operations_processor,
                 :allow_include,
                 :allow_sort,
                 :allow_filter,
                 :default_paginator,
                 :default_page_size,
                 :maximum_page_size,
+                :default_processor_klass,
                 :use_text_errors,
                 :top_level_links_include_pagination,
                 :top_level_meta_include_record_count,
@@ -34,9 +33,6 @@ def initialize
       #:underscored_route, :camelized_route, :dasherized_route, or custom
       self.route_format = :dasherized_route
 
-      #:basic, :active_record, or custom
-      self.operations_processor = :active_record
-
       #:integer, :uuid, :string, or custom (provide a proc)
       self.resource_key_type = :integer
 
@@ -80,6 +76,10 @@ def initialize
       self.always_include_to_one_linkage_data = false
       self.always_include_to_many_linkage_data = false
 
+      # The default Operation Processor to use if one is not defined specifically
+      # for a Resource.
+      self.default_processor_klass = JSONAPI::Processor
+
       # Formatter Caching
       # Set to false to disable caching of string operations on keys and links.
       self.cache_formatters = true
@@ -144,15 +144,14 @@ def route_formatter
       return formatter
     end
 
-    def operations_processor=(operations_processor)
-      @operations_processor_name = operations_processor
-      @operations_processor = JSONAPI::OperationsProcessor.operations_processor_for(@operations_processor_name)
-    end
-
     def exception_class_whitelisted?(e)
       @exception_class_whitelist.flatten.any? { |k| e.class.ancestors.include?(k) }
     end
 
+    def default_processor_klass=(default_processor_klass)
+      @default_processor_klass = default_processor_klass
+    end
+
     attr_writer :allow_include, :allow_sort, :allow_filter
 
     attr_writer :default_paginator