state.rb 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. require_dependency 'mixin/rails_logger'
  2. require_dependency 'mixin/start_finish_logger'
  3. class Sequencer
  4. class State
  5. include ::Mixin::RailsLogger
  6. include ::Mixin::StartFinishLogger
  7. def initialize(sequence, parameters: {}, expecting: nil)
  8. @index = -1
  9. @units = sequence.units
  10. @result_index = @units.count
  11. @values = {}
  12. initialize_attributes(sequence.units)
  13. initialize_parameters(parameters)
  14. initialize_expectations(expecting || sequence.expecting)
  15. end
  16. # Stores a value for the given attribute. Value can be a regular object
  17. # or the result of a given code block.
  18. # The attribute gets validated against the .provides list of attributes.
  19. # In the case than an attribute gets provided that is not declared to
  20. # be provided an exception will be raised.
  21. #
  22. # @param [Symbol] attribute the attribute for which the value gets provided.
  23. # @param [Object] value the value that should get stored for the given attribute.
  24. # @yield [] executes the given block and takes the result as the value.
  25. # @yieldreturn [Object] the value for the given attribute.
  26. #
  27. # @example
  28. # state.provide(:sum, 3)
  29. #
  30. # @example
  31. # state.provide(:sum) do
  32. # some_value = rand(100)
  33. # some_value * 3
  34. # end
  35. #
  36. # @raise [RuntimeError] if the attribute is not provideable from the calling Unit
  37. #
  38. # @return [nil]
  39. def provide(attribute, value = nil)
  40. if provideable?(attribute)
  41. value = yield if block_given?
  42. set(attribute, value)
  43. else
  44. value = "UNEXECUTED BLOCK: #{caller(1..1).first}" if block_given?
  45. unprovideable_setter(attribute, value)
  46. end
  47. end
  48. # Returns the value of the given attribute.
  49. # The attribute gets validated against the .uses list of attributes. In the
  50. # case than an attribute gets used that is not declared to be used
  51. # an exception will be raised.
  52. #
  53. # @param [Symbol] attribute the attribute for which the value is requested.
  54. #
  55. # @example
  56. # state.use(:answer)
  57. # #=> 42
  58. #
  59. # @raise [RuntimeError] if the attribute is not useable from the calling Unit
  60. #
  61. # @return [nil]
  62. def use(attribute)
  63. if useable?(attribute)
  64. get(attribute)
  65. else
  66. unaccessable_getter(attribute)
  67. end
  68. end
  69. # Returns the value of the given attribute.
  70. # The attribute DOES NOT get validated against the .uses list of attributes.
  71. #
  72. # @param [Symbol] attribute the attribute for which the value is requested.
  73. #
  74. # @example
  75. # state.optional(:answer)
  76. # #=> 42
  77. #
  78. # @example
  79. # state.optional(:unknown)
  80. # #=> nil
  81. #
  82. # @return [Object, nil]
  83. def optional(attribute)
  84. return get(attribute) if @attributes.known?(attribute)
  85. logger.public_send(log_level[:optional]) { "Access to unknown optional attribute '#{attribute}'." }
  86. nil
  87. end
  88. # Checks if a value for the given attribute is provided.
  89. # The attribute DOES NOT get validated against the .uses list of attributes.
  90. #
  91. # @param [Symbol] attribute the attribute which should get checked.
  92. #
  93. # @example
  94. # state.provided?(:answer)
  95. # #=> true
  96. #
  97. # @example
  98. # state.provided?(:unknown)
  99. # #=> false
  100. #
  101. # @return [Boolean]
  102. def provided?(attribute)
  103. optional(attribute) != nil
  104. end
  105. # Unsets the value for the given attribute.
  106. # The attribute gets validated against the .uses list of attributes.
  107. # In the case than an attribute gets unset that is not declared
  108. # to be used an exception will be raised.
  109. #
  110. # @param [Symbol] attribute the attribute for which the value gets unset.
  111. #
  112. # @example
  113. # state.unset(:answer)
  114. #
  115. # @raise [RuntimeError] if the attribute is not useable from the calling Unit
  116. #
  117. # @return [nil]
  118. def unset(attribute)
  119. value = nil
  120. if useable?(attribute)
  121. set(attribute, value)
  122. else
  123. unprovideable_setter(attribute, value)
  124. end
  125. end
  126. # Handles state processing of the next Unit in the Sequence while executing
  127. # the given block. After the Unit is processed the state will get cleaned up
  128. # and no longer needed attribute values will get discarded.
  129. #
  130. # @yield [] executes the given block and handles the state changes before and afterwards.
  131. #
  132. # @example
  133. # state.process do
  134. # unit.process
  135. # end
  136. #
  137. # @return [nil]
  138. def process
  139. @index += 1
  140. yield
  141. cleanup
  142. end
  143. # Handles state processing of the next Unit in the Sequence while executing
  144. # the given block. After the Unit is processed the state will get cleaned up
  145. # and no longer needed attribute values will get discarded.
  146. #
  147. # @example
  148. # state.to_h
  149. # #=> {"ssl_verify"=>true, "host_url"=>"ldaps://192...", ...}
  150. #
  151. # @return [Hash{Symbol => Object}]
  152. def to_h
  153. available.map { |identifier| [identifier, @values[identifier]] }.to_h
  154. end
  155. private
  156. def available
  157. @attributes.select do |_identifier, attribute|
  158. @index.between?(attribute.from, attribute.to)
  159. end.keys
  160. end
  161. def unit(index = nil)
  162. @units[index || @index]
  163. end
  164. def provideable?(attribute)
  165. unit.provides.include?(attribute)
  166. end
  167. def useable?(attribute)
  168. unit.uses.include?(attribute)
  169. end
  170. def set(attribute, value)
  171. logger.public_send(log_level[:set]) { "Setting '#{attribute}' value (#{value.class.name}): #{value.inspect}" }
  172. @values[attribute] = value
  173. end
  174. def get(attribute)
  175. value = @values[attribute]
  176. logger.public_send(log_level[:get]) { "Getting '#{attribute}' value (#{value.class.name}): #{value.inspect}" }
  177. value
  178. end
  179. def unprovideable_setter(attribute, value)
  180. message = "Unprovideable attribute '#{attribute}' set with value (#{value.class.name}): #{value.inspect}"
  181. logger.error(message)
  182. raise message
  183. end
  184. def unaccessable_getter(attribute)
  185. message = "Unaccessable getter used for attribute '#{attribute}'"
  186. logger.error(message)
  187. raise message
  188. end
  189. def initialize_attributes(units)
  190. log_start_finish(log_level[:attribute_initialization][:start_finish], 'Attributes lifespan initialization') do
  191. @attributes = Sequencer::Units::Attributes.new(units.declarations)
  192. logger.public_send(log_level[:attribute_initialization][:attributes]) { "Attributes lifespan: #{@attributes.inspect}" }
  193. end
  194. end
  195. def initialize_parameters(parameters)
  196. logger.public_send(log_level[:parameter_initialization][:parameters]) { "Initializing Sequencer::State with initial parameters: #{parameters.inspect}" }
  197. log_start_finish(log_level[:parameter_initialization][:start_finish], 'Attribute value provisioning check and initialization') do
  198. @attributes.each do |identifier, attribute|
  199. if !attribute.will_be_used?
  200. logger.public_send(log_level[:parameter_initialization][:unused]) { "Attribute '#{identifier}' is provided by Unit(s) but never used." }
  201. next
  202. end
  203. init_param = parameters.key?(identifier)
  204. provided_attr = attribute.will_be_provided?
  205. if !init_param && !provided_attr
  206. message = "Attribute '#{identifier}' is used in Unit '#{unit(attribute.to).name}' (index: #{attribute.to}) but is not provided or given via initial parameters."
  207. logger.error(message)
  208. raise message
  209. end
  210. # skip if attribute is provided by an Unit but not
  211. # an initial parameter
  212. next if !init_param
  213. # update 'from' lifespan information for attribute
  214. # since it's provided via the initial parameter
  215. attribute.from = @index
  216. # set initial value
  217. set(identifier, parameters[identifier])
  218. end
  219. end
  220. end
  221. def initialize_expectations(expected_attributes)
  222. expected_attributes.each do |identifier|
  223. logger.public_send(log_level[:expectations_initialization]) { "Adding attribute '#{identifier}' to the list of expected result attributes." }
  224. @attributes[identifier].to = @result_index
  225. end
  226. end
  227. def cleanup
  228. log_start_finish(log_level[:cleanup][:start_finish], "State cleanup of Unit #{unit.name} (index: #{@index})") do
  229. @attributes.delete_if do |identifier, attribute|
  230. remove = !attribute.will_be_used?
  231. remove ||= attribute.to <= @index
  232. if remove && attribute.will_be_used?
  233. logger.public_send(log_level[:cleanup][:remove]) { "Removing unneeded attribute '#{identifier}': #{@values[identifier].inspect}" }
  234. end
  235. remove
  236. end
  237. end
  238. end
  239. def log_level
  240. @log_level ||= Sequencer.log_level_for(:state)
  241. end
  242. end
  243. end