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

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

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from Common::Session::BaseSession

#config, #environment, #session

Attributes included from Language::AuxiliarLogger

#logger

Class Method Summary collapse

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(e, name:, type:, sets:, usecase: nil, accept_update_with_no_id: false) ⇒ Job

Returns a new instance of Job.

Parameters:

  • e (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.



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/eco/api/session/batch/job.rb', line 42

def initialize(e, name:, type:, sets:, usecase: nil, accept_update_with_no_id: false)
  raise "A name is required to refer a job. Given: #{name}" if !name
  raise "Type should be one of #{self.class.types}. Given: #{type}"    unless self.class.valid_type?(type)
  raise "Sets should be some of #{self.class.sets}. Given: #{sets}"    unless self.class.valid_sets?(sets)
  raise "usecase must be a Eco::API::UseCases::UseCase object. Given: #{usecase.class}" if usecase && !usecase.is_a?(Eco::API::UseCases::UseCase)
  super(e)

  @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

Class Attribute Details

.sets ⇒ Object (readonly)

Returns the value of attribute sets.



18
19
20
 
# File 'lib/eco/api/session/batch/job.rb', line 18

def sets
  @sets
end

.types ⇒ Object (readonly)

Returns the value of attribute types.



18
19
20
 
# File 'lib/eco/api/session/batch/job.rb', line 18

def types
  @types
end

Instance Attribute Details

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

helper class for feedback and end-user decision making

Returns:



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

def feedback
  @feedback
end

#name ⇒ String (readonly)

the name of this batch job

Returns:

  • (String) —

    the current value of name



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

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



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

def sets
  @sets
end

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

if launched: the status of the batch

Returns:



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

def status
  @status
end

#type ⇒ Symbol (readonly)

a valid batch operation

Returns:

  • (Symbol) —

    the current value of type



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

def type
  @type
end

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

when provided: usecase that generated this batch job

Returns:



11
12
13
 
# File 'lib/eco/api/session/batch/job.rb', line 11

def usecase
  @usecase
end

Class Method Details

.valid_sets?(value) ⇒ Boolean

Returns:

  • (Boolean) 


24
25
26
27
 
# File 'lib/eco/api/session/batch/job.rb', line 24

def valid_sets?(value)
  sts = [value].flatten
  sts.all? { |s| sets.include?(s) }
end

.valid_type?(value) ⇒ Boolean

Returns:

  • (Boolean) 


20
21
22
 
# File 'lib/eco/api/session/batch/job.rb', line 20

def valid_type?(value)
  types.include?(value)
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:



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/eco/api/session/batch/job.rb', line 101

def add(entry, unique: true, &block)
  case entry
  when Enumerable
    entry.each {|e| add(e, unique: unique, &block)}
  else
    unless !entry
      unless unique && @queue_hash.key?(entry)
        @queue_hash[entry] = true
        @queue.push(entry)
        @callbacks[entry]  = block if block_given?
      end
    end
  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:



71
72
73
 
# File 'lib/eco/api/session/batch/job.rb', line 71

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

#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



81
82
83
 
# File 'lib/eco/api/session/batch/job.rb', line 81

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:



137
138
139
 
# File 'lib/eco/api/session/batch/job.rb', line 137

def errors?
  status && 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::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:



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/eco/api/session/batch/job.rb', line 171

def launch(simulate: false)
  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
  else
    if pqueue.length > 0
      req_backup = as_update(pqueue, add_feedback: false)
      backup_update(req_backup)
      logger.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
  end

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

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

#options ⇒ Hash

Returns options the root usecase is run with.

Returns:

  • (Hash) —

    options the root usecase is run with



91
92
93
 
# File 'lib/eco/api/session/batch/job.rb', line 91

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

#pending? ⇒ Boolean

Returns has been this batch job launched?.

Returns:

  • (Boolean) —

    has been this batch job launched?



118
119
120
 
# File 'lib/eco/api/session/batch/job.rb', line 118

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:



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

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

#request_stats(requests = nil) ⇒ Object

See Also:



131
132
133
 
# File 'lib/eco/api/session/batch/job.rb', line 131

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



125
126
127
128
 
# File 'lib/eco/api/session/batch/job.rb', line 125

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

#reset ⇒ Object 



58
59
60
61
62
63
64
 
# File 'lib/eco/api/session/batch/job.rb', line 58

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:



76
77
78
 
# File 'lib/eco/api/session/batch/job.rb', line 76

def subjobs
  @subjobs ||= Eco::API::Session::Batch::Jobs.new(enviro, name: "childs-of:#{self.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



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/eco/api/session/batch/job.rb', line 209

def summary
  [].tap do |msg|
    if pending?
      msg << "PENDING - Batch #{type.to_s.upcase} - job '#{name}' - length: #{@queue.length}"
    else
      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 unless !status
      msg << subjobs_summary
    end
  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)



86
87
88
 
# File 'lib/eco/api/session/batch/job.rb', line 86

def usecase?
  !!usecase
end