Class: Eco::API::Session::Batch::Job

Inherits:
Common::Session::BaseSession show all
Includes:
Sets, Type, Language::Methods::DslAble
Defined in:
lib/eco/api/session/batch/job.rb,
lib/eco/api/session/batch/job/sets.rb,
lib/eco/api/session/batch/job/type.rb

Defined Under Namespace

Modules: Sets, Type

Constant Summary

Constants included from Sets

Sets::SETS

Constants included from Type

Type::TYPES

Instance Attribute Summary collapse

Attributes inherited from Common::Session::BaseSession

#config, #environment, #session

Attributes included from Language::AuxiliarLogger

#logger

Instance Method Summary collapse

Methods included from Language::Methods::DslAble

#evaluate, #method_missing, #respond_to_missing?

Methods inherited from Common::Session::BaseSession

#api, #api?, #fatal, #file_manager, #logger, #mailer, #mailer?, #s3uploader, #s3uploader?, #sftp, #sftp?

Methods included from Language::AuxiliarLogger

#log

Constructor Details

#initialize(ev, name:, type:, sets:, usecase: nil, accept_update_with_no_id: false) ⇒ Job

Returns a new instance of Job.

Parameters:

  • ev (Eco::API::Common::Session::Environment) —

    requires a session environment, as any child of Eco::API::Common::Session::BaseSession.

  • name (String) —

    the name of this batch job

  • type (Symbol) —

    a valid batch operation.

  • usecase (Eco::API::UseCases::UseCase, nil) (defaults to: nil) —

    when provided: usecase that generated this batch job. This is necessary to know the options used to run the usecase, which could modify the Batch::Job behviour.

  • accept_update_with_no_id (Boolean) (defaults to: false) —

    temporary contingency This parameter has been added due to a bug on server side. An external_id is still required.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/eco/api/session/batch/job.rb', line 39

def initialize(ev, name:, type:, sets:, usecase: nil, accept_update_with_no_id: false)
  msg = "A name is required to refer a job. Given: '#{name}'"
  raise msg unless name

  msg = "Type should be one of #{self.class.types}. Given: #{type}"
  raise msg unless self.class.valid_type?(type)

  msg = "Sets should be some of #{self.class.sets}. Given: #{sets}"
  raise msg unless self.class.valid_sets?(sets)

  msg = "usecase must be a Eco::API::UseCases::UseCase object. Given: #{usecase.class}"
  raise msg if usecase && !usecase.is_a?(Eco::API::UseCases::UseCase)

  super(ev)

  @name     = name
  @type     = type
  @sets     = [sets].flatten.compact
  @usecase  = usecase
  @feedback = Eco::API::Session::Batch::Feedback.new(job: self)
  @accept_update_with_no_id = accept_update_with_no_id
  reset
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Eco::Language::Methods::DslAble

Instance Attribute Details

#feedback ⇒ Eco::API::Session::Batch::Feedback (readonly)

helper class for feedback and end-user decision making

Returns:



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def feedback
  @feedback
end

#name ⇒ String (readonly)

the name of this batch job

Returns:

  • (String) —

    the current value of name



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def name
  @name
end

#sets ⇒ Array<Symbol> (readonly)

the parts of the person model this batch is supposed to affect

Returns:

  • (Array<Symbol>) —

    the current value of sets



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def sets
  @sets
end

#status ⇒ Eco::API::Session::Batch::Status (readonly)

if launched: the status of the batch

Returns:



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def status
  @status
end

#type ⇒ Symbol (readonly)

a valid batch operation

Returns:

  • (Symbol) —

    the current value of type



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def type
  @type
end

#usecase ⇒ Eco::API::UseCases::UseCase? (readonly)

when provided: usecase that generated this batch job

Returns:



16
17
18
 
# File 'lib/eco/api/session/batch/job.rb', line 16

def usecase
  @usecase
end

Instance Method Details

#add(entry, unique: true) {|person| ... } ⇒ Eco::API::Session::Batch::Job

Adds an entry(ies) to the job queue.

Parameters:

  • entry (Ecoportal::API::V1::Person, Enumerable<Person>) —

    the person(s) we want to update, carrying the changes to be done.

  • unique (Boolean) (defaults to: true) —

    specifies if repeated entries should be avoided in the queue.

Yields:

  • (person) —

    callback before launching the batch job request against the server.

Yield Parameters:

  • person (Person) —

    current person object that that should be treated by the callback before launching the batch.

Returns:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/eco/api/session/batch/job.rb', line 118

def add(entry, unique: true, &block)
  case entry
  when Enumerable
    entry.each {|el| add(el, unique: unique, &block)}
  else
    return self unless entry
    return self if unique && @queue_hash.key?(entry)

    @queue_hash[entry] = true
    @queue.push(entry)
    @callbacks[entry] = block if block_given?
  end

  self
end

#dup(name = "ad-hoc:job-from:#{self.name}", usecase: self.usecase) ⇒ Eco::API::Session::Batch::Job

Note:
  • this job will not be linked to the Batch::Jobs model of the current session
  • mostly used for error_handlers

Creates an empty Batch::Job with same behaviour as the current one

Returns:



76
77
78
79
80
81
82
83
84
 
# File 'lib/eco/api/session/batch/job.rb', line 76

def dup(name = "ad-hoc:job-from:#{self.name}", usecase: self.usecase)
  self.class.new(
    enviro,
    name:    name,
    type:    type,
    sets:    sets,
    usecase: usecase
  )
end

#ensure_requests! ⇒ Object

Note:

some times we need a summary of what actually is going to be run without invoking launch (i.e. when there's a uncompliance with the batch policy)



142
143
144
145
146
147
 
# File 'lib/eco/api/session/batch/job.rb', line 142

def ensure_requests!
  return if instance_variable_defined?(:@requests)

  pqueue    = processed_queue
  @requests = as_update(pqueue)
end

#error_handler? ⇒ Boolean

Returns true if the current batch job is a result of an error_handler.

Returns:

  • (Boolean) —

    true if the current batch job is a result of an error_handler



95
96
97
 
# File 'lib/eco/api/session/batch/job.rb', line 95

def error_handler?
  usecase? && usecase.is_a?(Eco::API::Error::Handler)
end

#errors? ⇒ Boolean

Returns true if there were Server errors, false otherwise.

Returns:

  • (Boolean) —

    true if there were Server errors, false otherwise

See Also:



166
167
168
 
# File 'lib/eco/api/session/batch/job.rb', line 166

def errors?
  status&.errors?
end

#launch(simulate: false) ⇒ Eco::API::Session::Batch::Status

Processes the queue and, unless simulate is true, launches against the server:

  1. pre_processes the queue obtaining the requests:
    • if the entries of queue got pending callbacks (delayed changes), it processes them
    • unless type == :create: if there's a defined api_excluded callback it calls it (see Config::People#api_excluded)
    • transforms the result to a Eco::API::Organization::People object
    • if there are api policies defined, it passes the entries through them in order (see Config#policies)
      • this step is skipped if the option -skip-api-policies was used in the command line
    • at this point all the transformations have taken place...
    • only include the entries that, after all above, still hold pending changes (!as_update.empty?) to be launched as update
  2. pre launch checks against the requests:
    • it generates stats (Eco::API::Session::Batch::Feedback::RequestStats) out of the requests
    • if there is a batch policy declared for the current job type, it checks compliance against stats (see Policies),
      • a non-compliant batch will stop the current session by raising an Exception
      • this setp is skipped if the option -skip-batch-policy was used in the command line
  3. if we are not in dry-run (or simulate), it:
    • backs up the raw queries (requests) launched to the Server, if we are not in dry-run (or simulate)
    • launches the batch request against the Server (see Eco::API::Session::Batch#launch)
    • links the resulting batch status to this Batch::Job (see Status)
    • prints any errors replied by the Server
  4. the post launch kicks in, and:
    • for success requests, it consolidates the associated entries (see Ecoportal::API::V1::Person#consolidate!)
    • launches specific error handlers, if there were errors from the Server as a result of the batch.launch, and there are Error::Handlers defined

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/eco/api/session/batch/job.rb', line 207

def launch(simulate: false) # rubocop:disable Metrics/AbcSize
  pqueue    = processed_queue
  @requests = as_update(pqueue)
  pre_checks(requests, simulate: simulate)

  if simulate
    if options.dig(:requests, :backup)
      req_backup = as_update(pqueue, add_feedback: false)
      backup_update(req_backup, simulate: simulate)
    end
  elsif !pqueue.empty?
    req_backup = as_update(pqueue, add_feedback: false)
    backup_update(req_backup)

    log(:debug) {
      "Job ('#{name}':#{type}): going to launch batch against #{pqueue.count} entries"
    }

    session.batch.launch(pqueue, method: type).tap do |job_status|
      @status     = job_status
      status.root = self
      status.errors.print
    end
  end

  unless requests.empty? || !simulate
    msg  = "--- simulate mode (dry-run) --  job '#{name}' "
    msg << "-- this would have launched #{type.to_s.upcase}"
    log(:info) { msg }
  end

  post_launch(queue: pqueue, simulate: simulate)
  @pending = false

  status
end

#options ⇒ Hash

Returns options the root usecase is run with.

Returns:

  • (Hash) —

    options the root usecase is run with



105
106
107
 
# File 'lib/eco/api/session/batch/job.rb', line 105

def options
  usecase?? usecase.options : {}
end

#pending? ⇒ Boolean

Returns has been this batch job launched?.

Returns:

  • (Boolean) —

    has been this batch job launched?



135
136
137
 
# File 'lib/eco/api/session/batch/job.rb', line 135

def pending?
  @pending
end

#people(input = @queue) ⇒ Eco::API::Organization::People

Note:

if input is not provided, it will use queue

Helper/shortcut to obtain a people object out of input

Returns:



173
174
175
 
# File 'lib/eco/api/session/batch/job.rb', line 173

def people(input = @queue)
  Eco::API::Organization::People.new(input)
end

#request_stats(requests = nil) ⇒ Object

See Also:

  • Feedback#request_stats


160
161
162
 
# File 'lib/eco/api/session/batch/job.rb', line 160

def request_stats(requests = nil)
  feedback.request_stats(requests || self.requests)
end

#requests ⇒ Enumbrable<Hash>

Note:

it requires launch to be firstly invoked

Returns the last requests that the queue will generate.

Returns:

  • (Enumbrable<Hash>) —

    the last requests that the queue will generate

Raises:

  • (Exception) —

    if 'launch' has not firstly invoked



152
153
154
155
156
157
 
# File 'lib/eco/api/session/batch/job.rb', line 152

def requests
  msg = "Method missuse. Firstly 'launch' should be invoked"
  raise msg unless instance_variable_defined?(:@requests)

  @requests
end

#reset ⇒ Object 



63
64
65
66
67
68
69
 
# File 'lib/eco/api/session/batch/job.rb', line 63

def reset
  @queue      = []
  @queue_hash = {}
  @callbacks  = {}
  @pending    = true
  @status     = nil
end

#subjobs ⇒ Eco::API::Session::Batch::Jobs

Returns group of subjobs of this Batch::Job.

Returns:



87
88
89
90
91
92
 
# File 'lib/eco/api/session/batch/job.rb', line 87

def subjobs
  @subjobs ||= Eco::API::Session::Batch::Jobs.new(
    enviro,
    name: "childs-of:#{name}"
  )
end

#summary ⇒ String

Note:

if launch was not invoked, it specifies so

Provides a text summary of the current status including:

  1. stats of the changes introduced by the job in the different parts of the person model
  2. if the job is compliant with the batch policy
  3. error messages in case they were errors from the server

Returns:

  • (String) —

    the summary



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/eco/api/session/batch/job.rb', line 250

def summary
  [].tap do |msg|
    msg << "PENDING Job -------->\n" if pending?
    ensure_requests!
    msg << feedback.generate(requests, only_stats: true)

    if batch_policy && !batch_policy.compliant?(request_stats)
      msg << 'Batch Policy Uncompliance:'
      msg << batch_policy.uncompliance(request_stats)
    end

    msg << status.errors.message if status
    msg << subjobs_summary
  end.join("\n")
end

#usecase? ⇒ Boolean

Returns was this batch job generated by a usecase? (Eco::API::UseCases::UseCase).

Returns:

  • (Boolean) —

    was this batch job generated by a usecase? (Eco::API::UseCases::UseCase)



100
101
102
 
# File 'lib/eco/api/session/batch/job.rb', line 100

def usecase?
  !!usecase
end