Class: Beetle::Handler

Inherits:
Object
  • Object
show all
Includes:
Logging
Defined in:
lib/beetle/handler.rb

Overview

Instances of class Handler are created by the message processing logic in class Message. There should be no need to ever create them in client code, except for testing purposes.

Most applications will define Handler subclasses and override the process, error and failure methods.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Logging

#logger

Constructor Details

#initialize(processor = nil, opts = {}) ⇒ Handler

optionally capture processor, error and failure callbacks



28
29
30
31
32
33
 
# File 'lib/beetle/handler.rb', line 28

def initialize(processor=nil, opts={}) #:notnew:
  @processor = processor
  @error_callback = opts[:errback]
  @failure_callback = opts[:failback]
  @__handler_called__ = nil
end

Instance Attribute Details

#message ⇒ Object (readonly)

the Message instance which caused the handler to be created



12
13
14
 
# File 'lib/beetle/handler.rb', line 12

def message
  @message
end

Class Method Details

.create(handler, opts = {}) ⇒ Object

:nodoc:



14
15
16
17
18
19
20
21
22
23
24
25
 
# File 'lib/beetle/handler.rb', line 14

def self.create(handler, opts={}) #:nodoc:
  if handler.is_a? Handler
    # a handler instance
    handler
  elsif handler.is_a?(Class) && handler.ancestors.include?(Handler)
    # handler class
    handler.new
  else
    # presumably something which responds to call
    new(handler, opts)
  end
end

.logger ⇒ Object

returns the configured Beetle logger



114
115
116
 
# File 'lib/beetle/handler.rb', line 114

def self.logger
  Beetle.config.logger
end

Instance Method Details

#call(message) ⇒ Object

called when a message should be processed. if the message was caused by an RPC, the return value will be sent back to the caller. calls the initialized processor proc if a processor proc was specified when creating the Handler instance. calls method process if no proc was given. make sure to call super if you override this method in a subclass.



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/beetle/handler.rb', line 40

def call(message)
  @message = message
  if @processor
    @processor.call(message)
  else
    process
  end
ensure
  @__handler_called__ = true
end

#completed ⇒ Object

called after all normal processing has been completed. flushes the loggger, if it responds to flush.



108
109
110
111
 
# File 'lib/beetle/handler.rb', line 108

def completed
  logger.debug "Beetle: message processing completed"
  logger.flush if logger.respond_to?(:flush)
end

#error(exception) ⇒ Object

called when handler execution raised an exception and no error callback was specified when the handler instance was created



96
97
98
 
# File 'lib/beetle/handler.rb', line 96

def error(exception)
  logger.error "Beetle: handler execution raised an exception: #{exception.class}(#{exception.message})"
end

#failure(result) ⇒ Object

called when message processing has finally failed (i.e., the number of allowed handler execution attempts or the number of allowed exceptions has been reached) and no failure callback was specified when this handler instance was created.



103
104
105
 
# File 'lib/beetle/handler.rb', line 103

def failure(result)
  logger.error "Beetle: handler has finally failed"
end

#post_process ⇒ Object

called after message processing finishes



62
63
 
# File 'lib/beetle/handler.rb', line 62

def post_process
end

#pre_process(message) ⇒ Object

called before message processing starts



52
53
 
# File 'lib/beetle/handler.rb', line 52

def pre_process(message)
end

#process ⇒ Object

called for message processing if no processor was specfied when the handler instance was created



57
58
59
 
# File 'lib/beetle/handler.rb', line 57

def process
  logger.info "Beetle: received message #{message.inspect}"
end

#process_exception(exception) ⇒ Object

should not be overriden in subclasses



66
67
68
69
70
71
72
73
74
 
# File 'lib/beetle/handler.rb', line 66

def process_exception(exception) #:nodoc:
  if @error_callback
    @error_callback.call(message, exception)
  else
    error(exception)
  end
rescue Exception
  Beetle::reraise_expectation_errors!
end

#process_failure(result) ⇒ Object

should not be overriden in subclasses



77
78
79
80
81
82
83
84
85
 
# File 'lib/beetle/handler.rb', line 77

def process_failure(result) #:nodoc:
  if @failure_callback
    @failure_callback.call(message, result)
  else
    failure(result)
  end
rescue Exception
  Beetle::reraise_expectation_errors!
end

#processing_completed ⇒ Object

should not be overriden in subclasses



88
89
90
91
92
 
# File 'lib/beetle/handler.rb', line 88

def processing_completed
  completed if @__handler_called__
rescue Exception
  Beetle::reraise_expectation_errors!
end