service.rb in hexx-6.0.0

- old
+ new

@@ -1,6 +1,7 @@
 # encoding: utf-8
+require_relative "dependable"
 
 module Hexx
 
   # @abstract
   # The base class for service objects.
@@ -17,28 +18,103 @@
   #   service = GetItem.new name: name
   #   service.subscribe listener, prefix: :on
   #   service.run
   #   # => This will call the listener's method #on_found(item).
   class Service
+    extend Dependable
     include Wisper::Publisher
     include ActiveModel::Validations
-    include Parameters
 
-    # @!scope class
-    # @!method new(options = {})
-    # Constructs the service object.
+    # @api hide
+    # Returns the list of allowed parameters for service objects.
     #
+    # The parameters are added to the list by the {.allow_params} private
+    # helper method.
+    #
     # @example
-    #   service = Hexx::Service.new name: name
+    #   class Service < Hexx::Service
+    #     allow_params :name
+    #   end
     #
-    # @param [Hash] options The options to be assigned to the {#params}.
+    #   Service.params # => "name"
+    #
+    # @return [Array<String>] The list of allowed instance parameters.
+    def self.params
+      @params ||= []
+    end
+
+    # @!scope class
+    # @!method validates(attribute, options)
+    # Adds a standard validation for the attribute.
+    # @param [Symbol, String] attribute The name of the attribute to validate.
+    # @param [Hash] options The list of validation options.
+    # @see ActiveModel validations {APIdocs}[
+    #   http://apidock.com/rails/ActiveModel/Validations/ClassMethods/validates]
+
+    # @!scope class
+    # @!method validate(method, options)
+    # Adds a custom validation (calls given method).
+    # @param [Symbol, String] method The name of the validation method.
+    # @param [Hash] options The list of validation options.
+    # @see ActiveModel validations {APIdocs}[
+    #   http://apidock.com/rails/ActiveModel/Validations/ClassMethods/validate]
+
+    # @!scope class
+    # @!method new(params = {})
+    # Constructs the service object with given parameters.
+    #
+    # @example (see Hexx::Service)
+    # @param [Hash] params ({}) The parameters of the service object to be
+    #   assigned to the {#params} attribute.
     # @return [Hexx::Service] The service object.
-    def initialize(options = {})
-      super(options)
+
+    # @api hide
+    # Initializes the service object.
+    # @param  (see Hexx::Service.new)
+    # @return (see Hexx::Service.new)
+    def initialize(params = {})
+      @params = params.dup.stringify_keys.slice(*(self.class.params))
       @messages = []
     end
 
+    # @!attribute [r] params
+    # The list of service object parameters.
+    #
+    # The attribute is assigned via the {.new} method options.
+    # On initialization the parameters (keys) are stringified and whitelisted.
+    #
+    # Allowed parameters should be explicitly declared with the {.allow_params}.
+    #
+    # @example Only whitelisted params are being assigned.
+    #   class GetItem < Hexx::Service
+    #     allow_params :name
+    #   end
+    #
+    #   service = GetItem.new name: "Олег", family: "Рюрикович"
+    #   service.params # => { "name" => "Олег" }
+    # @return [Hash] the service object parameters.
+
+    # @!attribute [r] messages
+    # The array of service messages (instances of {Hexx::Service::Message})
+    # with +text+ and +type+ attributes.
+    #
+    # @example
+    #   class Test < Hexx::Service
+    #     def run
+    #       add_message "info", :ok
+    #     end
+    #   end
+    #
+    #   service = Test.new
+    #   service.run # adds message
+    #   service.messages
+    #   # => [#<Hexx::Service::Message @text="ok" @type="info" >]
+    #
+    # @return [Array<Hexx::Service::Message>] The array of messages.
+
+    attr_reader :params, :messages
+
     # @!scope class
     # @!visibility private
     # @!method allow_params(*params)
     # Whitelists {#params} and declares a parameter for corresponding keys.
     #
@@ -52,32 +128,10 @@
     #   service = GetItem.new name: "Олег", family: "Рюрикович"
     #   service.name # => "Олег"
     #
     # @param [Array<Symbol, String>] params The list of allowed keys.
 
-    # @!scope class
-    # @!method validates(attribute, options)
-    # Adds a standard validation for the attribute.
-    # @note The method is defined in the {ActiveModel::Validations} module.
-
-    # @!scope class
-    # @!method validate(method, options)
-    # Adds a custom validation (calls given method).
-    # @note The method is defined in the {ActiveModel::Validations} module.
-
-    # @!attribute params [r] The list of service object parameters.
-    #   The attribute is assigned via the {.new} method options.
-    #   The keys should be explicitly declared by the {.allow_params} helper.
-    #
-    #   @example Only whitelisted params are being assigned.
-    #     class GetItem < Hexx::Service
-    #       allow_params :name
-    #     end
-    #
-    #     service = GetItem.new name: "Олег", family: "Рюрикович"
-    #     service.params # => { "name" => "Олег" }
-
     # @!method subscribe(listener, options = {})
     # Subscribes the listener to service object's notifications.
     # The <tt>:prefix</tt> sets the prefix to be added to a notification name
     # to provide a corresponding listener method, that should be called by
     # the publisher.
@@ -88,12 +142,12 @@
     # @param [Hash] options The list of the subscription options.
     # @option options [Symbol] :prefix The prefix for the listener's callbacks.
 
     # @abstract
     # Runs the service object.
-    # @note The method does nothing and should be reloaded by a specific
-    #   service class.
+    #
+    # The method does nothing. To be reloaded by a specific service class.
     def run
     end
 
     # Makes private methods with given prefix public.
     #
@@ -117,29 +171,20 @@
     #   The decorator that allows access to the service's private methods.
     def with_callbacks(prefix: nil)
       WithCallbacks.new(self, prefix: prefix)
     end
 
-    # @!attribute [r] messages
-    # The array of service messages (instances of {Hexx::Service::Message})
-    # with +text+ and +type+ attributes.
-    #
-    # @example
-    #   class Test < Hexx::Service
-    #     def run
-    #       add_message "info", :ok
-    #     end
-    #   end
-    #
-    #   service = Test.new
-    #   service.run # adds message
-    #   service.messages
-    #   # => [#<Hexx::Service::Message @text="ok" @type="info" >]
-    #
-    # @return [Array<Hexx::Service::Message>] The array of messages.
-    attr_reader :messages
-
     private
+
+    # Sets a list of allowed parameters for the class constructor and
+    # defines the corresponding instance attributes.
+    #
+    # @example (see Hexx::Service::Parameters.params)
+    # @param [Array<Symbol, String>] keys The list of allowed parameters.
+    def self.allow_params(*keys)
+      @params = keys.map(&:to_s)
+      params.each { |name| Helpers::Parameter.add self, name }
+    end
 
     # The helper runs another service object and subscribes +self+ for the
     # service object's notifications.
     #
     # @example