Class: Hexx::Service Abstract

Inherits:
Object
  • Object
show all
Includes:
Wisper::Publisher
Defined in:
lib/hexx/service.rb,
lib/hexx/service/with_callbacks.rb

Overview

This class is abstract.

The base class for service objects.

Examples:

require "hexx"
class GetItem < Hexx::Service
  allow_params :name
  def run
    publish :found, item = Item.where(name: name).first
  end
end

service = GetItem.new name: name
service.subscribe listener, prefix: :on
service.run
# => This will call the listener's method #on_found(item).

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#messagesArray<Hexx::Message> (readonly)

Note:

The attribute setter is private!

The array of service messages (instances of Message) with text and type attributes.

Examples:

The messages can be added by the #add_message private helper

class EditItem < Hexx::Service
  def run
    # ...
  else
    add_message "success", "changed"
    publish :changed, messages
  end
end

service = Test.new
service.run
service.messages
# => [#<Hexx::Message @type="info" @text="some_text" >]

Returns:


# File 'lib/hexx/service.rb', line 88

Class Method Details

.allow_params(*names) ⇒ Object (private)

Sets a list of allowed parameters for the class constructor and defines the corresponding instance attributes.

Examples:

class MyService < Hexx::Service
  allows_params :name
end

service = MyService.new name: "name", code: "code"
service.send :name   # => "name"
service.send :params # => { "name" => "name" }

Parameters:

  • names (Symbol, String, Array<Symbol, String>)

    The list of allowed parameters.


# File 'lib/hexx/service.rb', line 44

.new(params = {}) ⇒ Hexx::Service (private)

Constructs a service object with given parameters.

Examples:

require "hexx"
class GetItem < Hexx::Service
  allow_params :name
  def run
    publish :found, item = Item.where(name: name).first
  end
end

service = GetItem.new name: name
service.subscribe listener, prefix: :on
service.run
# => This will call the listener's method #on_found(item).

Parameters:

  • params (Hash) (defaults to: {})

    ({}) The parameters of the service object to be assigned to the #params attribute.

Returns:


# File 'lib/hexx/service.rb', line 307

.raises(exceptions) ⇒ Object (private)

Declares a list of specific StandardError exceptions.

Examples:

class Service < Hexx::Service
  raises :NotFound, :NotChanged

  def run
    run!
  rescue NotFound
    publish :not_found
  rescue NotChanged
    publish :not_changed
  rescue => err
    # works out any other (unspecified exceptions)
    publish :error
  else
    # works out the main scenario
    publish :success
  end
end

Service.const_defined? :NotFound   # => true
Service.const_defined? :NotChanged # => true

exception = Service::NotFound.new
exception.is_a? StandardError      # => true

Parameters:

  • exceptions (String, Symbol, Array<String, Symbol>)

    The list of specific StandardError exceptions.


# File 'lib/hexx/service.rb', line 224

.validate(method, options) ⇒ Object (private)

Adds a custom validation (calls given method).

Parameters:

  • method (Symbol, String)

    The name of the validation method.

  • options (Hash)

    The list of validation options.

See Also:


# File 'lib/hexx/service.rb', line 186

.validates(attribute, options) ⇒ Object (private)

Adds a standard validation for the attribute.

Parameters:

  • attribute (Symbol, String)

    The name of the attribute to validate.

  • options (Hash)

    The list of validation options.

See Also:


# File 'lib/hexx/service.rb', line 175

Instance Method Details

#add_message(type, text) ⇒ Object (private)

Adds the translated message to the #messages array.

Examples:

class Hello < Hexx::Service
  def run
    add_message "success", "Hello!"
    publish :hello, messages
  end
end

hello = Hello.new
hello.subscribe listener
hello.run

# The listener.hello [#<Hexx::Message @type="success", @text="Hello!" >]
# will be called.

Parameters:

  • type (String)

    The type of the message: “error”, “info”, “success”

  • text (String, Symbol)

    The text of the message. The symbol will be translated using the #t method.

  • options (Hash)

    The translation options.

Returns:


# File 'lib/hexx/service.rb', line 112

#escape { ... } ⇒ Object (private)

The method re-raises StandardError exceptions as a Hexx::ServiceInvalid.

  • rescues from a StandardError exceptions

  • adds error message to the service

  • re-raises the Hexx::ServiceInvalid exception

Examples:

class GetItem < Hexx::Service
  def run
    escape { do_something_unsafe }
  rescue => err
    publish :error, err.messages
  end
    publish :success
  end
end

Yields:

  • the block.

Returns:

  • the value returned by the block.

Raises:


# File 'lib/hexx/service.rb', line 257

#on_error(messages) ⇒ Object (private)

Raises the Hexx::ServiceInvalid exception, populated with given messages.

Examples:

class EditItem < Hexx::Service

  allow_params :id, :name
  # ...

  def find_item
    run_service GetItem, :on_item, id: id
  end

  def on_item_not_found(*, messages)
    on_error(messages) # Raises Hexx::ServiceInvalid
  end
end

Parameters:

  • messages (Array<Hexx::ServiceInvalid>)

    The list of error messages to be added to the exception.

Raises:


# File 'lib/hexx/service.rb', line 282

#paramsObject (private)

#runObject (private)

This method is abstract.

Runs the service object.


318
319
# File 'lib/hexx/service.rb', line 318

def run
end

#run_service(service_class, prefix, options = {}) ⇒ Object (private)

The helper runs another service object and subscribes self for the service object's notifications.

Examples:

class AddItem < Hexx::Service
  allow_params :id

  # Runs a service for finding an item.
  # Service notifications to be received with a prefix :on_item
  def find_item
    run_service GetItem, :on_item, id: params["id"]
  end

  private

  attr_reader :item

  # Receives GetItem's :found notification
  def on_item_found(item)
    @item = item
    publish :found, item
  end

  # Receives GetItem's :not_found notification
  def on_item_not_found(*)
    # ... do some stuff here
  end
end

Parameters:

  • service_class (Hexx::Service)

    The class for the service object to run.

  • prefix (Symbol)

    The prefix for callbacks to receive the service object's notifications.

  • options (Hash) (defaults to: {})

    ({}) The options for the service object initializer.


357
358
359
360
361
# File 'lib/hexx/service.rb', line 357

def run_service(service_class, prefix, options = {})
  service = service_class.new(options)
  service.subscribe with_callbacks, prefix: prefix
  service.run
end

#tObject (private)

#validate!Object (private)