Module: Collins::State::Mixin::ClassMethods

Defined in:
lib/collins/state/mixin_class_methods.rb

Overview

Static (Class) methods to be added to classes that mixin this module. These methods provide functionality for registering new actions and events, along with access to the managed state. This is accomplished via class instance variables which allow each class that include the Collins::State::Mixin its own managed state and variables.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#actions ⇒ Hash<Symbol, Collins::SimpleCallback> (readonly)

Returns Registered actions for the managed state.

Returns:

  • (Hash<Symbol, Collins::SimpleCallback>) —

    Registered actions for the managed state



12
13
14
 
# File 'lib/collins/state/mixin_class_methods.rb', line 12

def actions
  @actions
end

#events ⇒ Hash<Symbol, Collins::SimpleCallback> (readonly)

Returns Registered events for the managed state.

Returns:

  • (Hash<Symbol, Collins::SimpleCallback>) —

    Registered events for the managed state



15
16
17
 
# File 'lib/collins/state/mixin_class_methods.rb', line 15

def events
  @events
end

Instance Method Details

#action(name, options = {}) {|block| ... } ⇒ Collins::SimpleCallback

Register a named action for use as a transition execution target

Actions are called when specified by a ‘:before_transition` or `:on_transition` option to an event. Options are not currently used.

Parameters:

  • name (Symbol) —

    Action name

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

    Action options

Yield Parameters:

  • block (Collins::Asset) —

    Given an asset, perform the specified action

Yield Returns:

  • (Boolean, Object) —

    indicates success or failure of operation. Only ‘false` (or an exception) indicate failure. Other return values are fine.

Returns:

  • (Collins::SimpleCallback) —

    the callback created for the action



67
68
69
70
71
72
 
# File 'lib/collins/state/mixin_class_methods.rb', line 67

def action name, options = {}, &block
  name_sym = name.to_sym
  new_action = ::Collins::SimpleCallback.new(name_sym, options, block)
  @actions[name_sym] = new_action
  new_action
end

#after(duration, time_unit = :seconds) ⇒ Fixnum

Convert a ‘Fixnum` into seconds based on the specified `time_unit`

Parameters:

  • duration (Fixnum) —

    Time value

  • time_unit (Symbol) (defaults to: :seconds) —

    Unit of time, one of ‘:hour`, `:hours`, `:minute`, `:minutes`.

Returns:

  • (Fixnum) —

    Value in seconds



114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/collins/state/mixin_class_methods.rb', line 114

def after duration, time_unit = :seconds
  multiplier = case time_unit
               when :days, :day
                 24*60*60
               when :hours, :hour
                 60*60
               when :minutes, :minute
                 60
               else
                 1
               end
  multiplier * duration.to_i
end

#event(name, options = {}) ⇒ Collins::SimpleCallback

Note:

A transition will not occur unless the :before_transition is successful (does not return false or throw an exception)

Register a named event associated with the managed state

Events are typically called as method invocations on the class, or as the result of a state being expired and a transition being specified.

The example (and events in general) can be read as: Execute ‘:before_transition` before successfully transitioning to this event. Once transitioned, after `:expires` is reached the `:on_transition` action should be called, followed by the event associated with the specified `:transition`.

Examples:

event :stuff, :desc => 'I do things', :before_transition => :try_action, :expires => after(5, :minutes),
              :transition => :after_stuff_event, :on_transition => :stuff_action

Parameters:

  • name (Symbol) —

    Event name

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

    Event options

Options Hash (options):

  • :before_transition (Symbol) —

    An action to execute successfully before transitioning to this state

  • :desc (String) —

    A description of the event, required

  • :expires (#to_i) —

    Do not consider ‘:on_transition` or `:transition` until after this amount of time

  • :on_transition (Symbol) —

    Once the expiration time has passed execute this action

  • :transition (Symbol) —

    The event to call after its appropriate for transition (due to timeout and successful ‘:before` calls)

Returns:

  • (Collins::SimpleCallback) —

    the callback created for the action

Raises:

  • (KeyError) —

    if the options hash is missing a ‘:desc` key



99
100
101
102
103
104
105
106
107
 
# File 'lib/collins/state/mixin_class_methods.rb', line 99

def event name, options = {}
  name_sym = name.to_sym
  ::Collins::Option(options[:desc]).or_else {
    raise KeyError.new("Event #{name} is missing :desc key")
  }
  new_event = ::Collins::SimpleCallback.new(name_sym, options)
  @events[name_sym] = new_event
  new_event
end

#manage_state(name, options = {}) {|block| ... } ⇒ Object

Note:

Only one managed state per class is allowed.

Register a managed state for this class

Examples:

manage_state :a_process, :initial => :start do |client|
  action :log_it do |asset|
    client.log! asset, "Did some logging"
  end
  event :start, :desc => 'Initial state', :expires => after(30, :minutes), :on_transition => :log_it, :transition => :done
  event :done, :desc => 'Done'
end

Parameters:

  • name (Symbol) —

    The name of the managed state, e.g. ‘:some_process`

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

    Managed state options

Options Hash (options):

  • :initial (Symbol) —

    First event to fire if the state is being initialized

Yield Parameters:

  • block (Collins::Client) —

    Managed state description, registering events and actions



33
34
35
36
37
 
# File 'lib/collins/state/mixin_class_methods.rb', line 33

def manage_state name, options = {}, &block
  @actions = {}
  @events = {}
  @managed_state = ::Collins::SimpleCallback.new(name, options, block)
end

#managed_state(client) ⇒ Object

Get and execute the managed state associated with this class

Parameters:

  • client (Collins::Client) —

    Collins client instance

See Also:

  • Collins::State::Mixin::ClassMethods.{{#manage_state}


53
54
55
 
# File 'lib/collins/state/mixin_class_methods.rb', line 53

def managed_state client
  @managed_state.call(client)
end

#managed_state_name ⇒ String

Returns Name of managed state associated with this class.

Returns:

  • (String) —

    Name of managed state associated with this class



40
41
42
 
# File 'lib/collins/state/mixin_class_methods.rb', line 40

def managed_state_name
  @managed_state.name
end

#managed_state_options ⇒ Hash

Returns Options associated with this managed state.

Returns:

  • (Hash) —

    Options associated with this managed state



45
46
47
 
# File 'lib/collins/state/mixin_class_methods.rb', line 45

def managed_state_options
  @managed_state.options
end