class Eco::API::Session::Batch::Status

The `Batch::Status` class aims to offer support to keep memory on:

1. what has happened during the execution of a `Session::Batch` (i.e. errors)
2. be able to build a summary of what happened
3. gather the people that was returned as a result of the `batch` (for `get` batch type)

@attr_reader source_queue [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]

The queue as it was originally made (it could contain duplicates)

@attr_reader queue [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]

`source_queue` with no repeated elements (**note**: observe that the elimination of duplicates could fail)

@attr_reader mode [Symbol] the `mode` that the `batch` was run with @attr_reader root [Eco::API::Session::Job] the `job` that launched the `batch`

Attributes

modes[R]
method[R]
mode[R]
queue[R]
root[R]
source_queue[R]

Public Class Methods

new(e, queue:, method:, mode: :exact) click to toggle source

@param e [Eco::API::Common::Session::Environment] requires a session environment, as any child of `Eco::API::Common::Session::BaseSession` @param queue [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>] the `source_queue` @param method [Symbol] the type of `batch operation` @param mode [Symbol] the mode of `batch operation`. It can be `:search` or `:exact`

# File lib/eco/api/session/batch/status.rb, line 34
def initialize(e, queue:, method:, mode: :exact)
  super(e)
  fatal("In batch operations you must batch an Enumerable. Received: #{queue}")  unless queue && queue.is_a?(Enumerable)

  self.mode     = mode
  @method       = method
  @source_queue = queue

  que = queue.to_a
  que = queue if queue.respond_to?(:uniq)
  if que.length != que.uniq.length
    logger.warn("Please, review your entries-to-query builder, you have repeated entries")
    queue = que.uniq
  end

  @queue  = queue
  @hash   = @queue.each_with_index.map do |entry, i|
    [entry, i]
  end.to_h
  @responses    = []
  @person_match = []
  @people_match = Array.new(@queue.length, [])
end
valid_mode?(value) click to toggle source
# File lib/eco/api/session/batch/status.rb, line 25
def valid_mode?(value)
  modes.include?(value)
end

Public Instance Methods

[](key) click to toggle source

Get the assciated `reponse` of an input entry object `key` @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] these are the **index options**:

1. `Integer`: index/position of the entry in the final `queue`
2. `Hash`: entry queries can be raw `Hash` objects
3. `Person` object: the most common case is to use the person wrapper classes of the `Ecoportal::API` namespace.

@return [Ecoportal::API::Common::BatchResponse]

# File lib/eco/api/session/batch/status.rb, line 87
def [](key)
  @responses[to_index(key)]
end
[]=(key, response) click to toggle source

Associates an input entry object `key` to its `response` @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @see Eco::API::Session::Batch::Status#[] for `key` options @param response key [Ecoportal::API::Common::BatchResponse]

# File lib/eco/api/session/batch/status.rb, line 95
def []=(key, response)
  @responses[to_index(key)] = response
end
errors() click to toggle source

@return [Eco::API::Session::Batch::Errors] errors object helper

# File lib/eco/api/session/batch/status.rb, line 71
def errors
  @errors ||= Eco::API::Session::Batch::Errors.new(status: self)
end
errors?() click to toggle source

@see Eco::API::Session::Batch::Errors#any? @return [Boolean] `true` if there were Server errors, `false` otherwise

# File lib/eco/api/session/batch/status.rb, line 77
def errors?
  errors.any?
end
mode=(value) click to toggle source
# File lib/eco/api/session/batch/status.rb, line 65
def mode=(value)
  fatal("Invalid :mode '#{value}. You must specify mode: as one of #{self.class.modes} ") unless self.class.valid_mode?(value)
  @mode = value
end
people() click to toggle source

When the batch method has been `get`, it gathers into an `Array` the people found. @note here is where the used `mode` gets relevance:

- while `:exact` mode will keep the order of found people as per order of final `queue`
- `:search` mode will just gather the results (order won't match)

@raise [Exception] when the `method` of the batch operation was other than `get` @return [Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>] all the people that has been found.

# File lib/eco/api/session/batch/status.rb, line 173
def people
  fatal "This batch wasn't a 'get'. Can't obtain people without 'get' method" unless method == :get
  if mode == :exact
    out = Array(queue.length)
    @responses.each_with_index do |response, i|
      out[i] = response.result if response.success?
    end
  elsif mode == :search
    out = []
    queue.each_with_index.map do |entry, i|
      pers   = person(entry)
      pers ||= person_match(entry)
      ppl    = pers ? [pers] : people_match(entry)
      out += ppl
    end
  end
  out
end
people_match(key) click to toggle source
# File lib/eco/api/session/batch/status.rb, line 159
def people_match(key)
  @people_match[to_index(key)]
end
person(key) click to toggle source

The person we got from the Server wrapped to the `Person` object for the input entry object `key` @note it only makes sense when the used batch method was `get` @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @see Eco::API::Session::Batch::Status#[] for `key` options @return [Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]

# File lib/eco/api/session/batch/status.rb, line 139
def person(key)
  return self[key].result if success?(key)
  nil
end
person_match(key) click to toggle source

The person we got from the Server wrapped to the `Person` object for the input entry object `key` @note

- it only makes sense when the _batch method_ used was `get` with `q`
- **found using a search criteria** (`mode` == `:search`), as opposite to find the person directly by `external_id`

@param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @see Eco::API::Session::Batch::Status#[] for `key` options @return [Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]

# File lib/eco/api/session/batch/status.rb, line 151
def person_match(key)
  @person_match[to_index(key)]
end
received?(key) click to toggle source

Has the entry `key` been queried to the server? @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @return [Boolean] `true` if input entry `key` has an associated `Ecoportal::API::Common::BatchResponse`

# File lib/eco/api/session/batch/status.rb, line 102
def received?(key)
  !!self[key]
end
root=(object) click to toggle source

Nativelly to this gem, a batch against the server is lauched by an Eco::API::Session::Job. When the batch returns the `BatchStatus`, the `Job` assigns itself as `root` of it. @param object [Eco::API::Session::Job]

# File lib/eco/api/session/batch/status.rb, line 61
def root=(object)
  @root = object
end
set_people_match(key, people) click to toggle source
# File lib/eco/api/session/batch/status.rb, line 163
def set_people_match(key, people)
  @people_match[to_index(key)] = people
end
set_person_match(key, person) click to toggle source
# File lib/eco/api/session/batch/status.rb, line 155
def set_person_match(key, person)
  @person_match[to_index(key)] = person
end
success?(key) click to toggle source

Has the entry `key` 's query to the server been successful @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @return [Boolean] `true` if input entry `key` has not had a server Error during the query

# File lib/eco/api/session/batch/status.rb, line 109
def success?(key)
  self[key]&.success?
end
to_index(key) click to toggle source

Helper to transform any `key` to an `Integer` index @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] @return [Integer] the index that `key` has in the final `queue`

# File lib/eco/api/session/batch/status.rb, line 116
def to_index(key)
  key.is_a?(Integer) ? valid_index(index: key) : valid_index(entry: key)
end
valid_index(index: nil, entry: nil) click to toggle source

Index validator to make this object reliable @return [Integer] the actual `index`

# File lib/eco/api/session/batch/status.rb, line 122
def valid_index(index: nil, entry: nil)
  index ||= @hash[entry]
  unless index && index < @queue.length
    msg  = "You must provide either the index on the final 'queue' or the original entry object of the batch. "
    msg += "Given, index=#{index.class}, entry:#{entry.class}"
    fatal msg
  end
  index
end