Class: Gapic::GenericLRO::Operation

Inherits:
BaseOperation show all
Defined in:
lib/gapic/generic_lro/operation.rb

Overview

A class used to wrap the longrunning operation objects, including the nonstandard ones (nonstandard meaning not conforming to the AIP-151). It provides helper methods to poll and check for status of these operations.

Defined Under Namespace

Classes: GenericError

Instance Attribute Summary

Attributes inherited from BaseOperation

#operation

Instance Method Summary collapse

Constructor Details

#initialize(operation, client:, polling_method_name:, operation_status_field:, request_values: {}, operation_name_field: nil, operation_err_field: nil, operation_err_code_field: nil, operation_err_msg_field: nil, operation_copy_fields: {}, options: {}) ⇒ Operation

Returns a new instance of Operation.

Parameters:

  • operation (Object) —

    The long-running operation object that is returned by the initial method call.

  • client (Object) —

    The client that handles the polling for the longrunning operation.

  • polling_method_name (String) —

    The name of the methods on the client that polls the longrunning operation.

  • operation_status_field (String) —

    The name of the status field in the underlying long-running operation object. The status field signals that the operation has finished. It should either contain symbols, and be set to :DONE when finished or contain a boolean and be set to true when finished.

  • request_values (Map<String, String>) (defaults to: {}) —

    The values that are to be copied from the request that triggered the longrunning operation, into the request that polls for the longrunning operation. The format is name of the request field -> value

  • operation_name_field (String, nil) (defaults to: nil) —

    The name of the name field in the underlying long-running operation object. Optional.

  • operation_err_field (String, nil) (defaults to: nil) —

    The name of the error field in the underlying long-running operation object. The error field should be a message-type, and have same semantics as google.rpc.Status, including an integer code subfield, that carries an error code. If the operation_err_field field is given, the operation_err_code_field and operation_err_msg_field parameters are ignored. Optional.

  • operation_err_code_field (String, nil) (defaults to: nil) —

    The name of the error_code field in the underlying long-running operation object. It is ignored if operation_err_field is given. Optional.

  • operation_err_msg_field (String, nil) (defaults to: nil) —

    The name of the error_message field in the underlying long-running operation object. It is ignored if operation_err_field is given. Optional.

  • operation_copy_fields (Map<String, String>) (defaults to: {}) —

    The map of the fields that need to be copied from the long-running operation object that the polling method returns to the polling request. The format is name of the operation object field -> name of the request field (from -> to)

  • options (Gapic::CallOptions) (defaults to: {}) —

    call options for this operation



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/gapic/generic_lro/operation.rb', line 61

def initialize operation, client:, polling_method_name:, operation_status_field:,
               request_values: {}, operation_name_field: nil, operation_err_field: nil,
               operation_err_code_field: nil, operation_err_msg_field: nil, operation_copy_fields: {},
               options: {}
  @client = client
  @polling_method_name = polling_method_name
  @operation_status_field = operation_status_field

  @request_values = request_values || {}

  @operation_name_field = operation_name_field
  @operation_err_field = operation_err_field
  @operation_err_code_field = operation_err_code_field
  @operation_err_msg_field = operation_err_msg_field

  @operation_copy_fields = operation_copy_fields || {}

  @on_done_callbacks = []
  @on_reload_callbacks = []
  @options = options || {}

  super operation
end

Instance Method Details

#done? ⇒ Boolean

Checks if the operation is done. This does not send a new api call, but checks the result of the previous api call to see if done.

Returns:

  • (Boolean) —

    Whether the operation is done.



112
113
114
115
116
 
# File 'lib/gapic/generic_lro/operation.rb', line 112

def done?
  return status if [true, false].include? status

  status == :DONE
end

#error ⇒ Object?

If the operation response is an error, the error will be returned, otherwise returns nil.

Returns:

  • (Object, nil) —

    The error object.



152
153
154
155
 
# File 'lib/gapic/generic_lro/operation.rb', line 152

def error
  return unless error?
  err || GenericError.new(error_code, error_msg)
end

#error? ⇒ Boolean

Checks if the operation is done and the result is an error. If the operation is not finished then this will return false.

Returns:

  • (Boolean) —

    Whether an error has been returned.



142
143
144
145
 
# File 'lib/gapic/generic_lro/operation.rb', line 142

def error?
  no_error_code = error_code.nil? || error_code.zero?
  done? && !(err.nil? && no_error_code)
end

#name ⇒ String?

Returns the name of the operation, if specified.

Returns:

  • (String, nil) —

    The name of the operation.



101
102
103
104
 
# File 'lib/gapic/generic_lro/operation.rb', line 101

def name
  return nil if @operation_name_field.nil?
  operation.send @operation_name_field if operation.respond_to? @operation_name_field
end

#on_done(&block) ⇒ Object

Registers a callback to be run when a refreshed operation is marked as done. If the operation has completed prior to a call to this function the callback will be called instead of registered.



232
233
234
235
236
237
238
 
# File 'lib/gapic/generic_lro/operation.rb', line 232

def on_done &block
  if done?
    yield self
  else
    @on_done_callbacks.push block
  end
end

#on_reload(&block) ⇒ Object

Registers a callback to be run when an operation is being reloaded. If the operation has completed prior to a call to this function the callback will NOT be called or registered.



221
222
223
224
 
# File 'lib/gapic/generic_lro/operation.rb', line 221

def on_reload &block
  return if done?
  @on_reload_callbacks.push block
end

#reload!(options: nil) ⇒ Gapic::GenericLRO::Operation Also known as: refresh!

Reloads the operation object.

to customize the options object, using keys that match the arguments for CallOptions.new.

Parameters:

  • options (Gapic::CallOptions, Hash) (defaults to: nil) —

    The options for making the RPC call. A Hash can be provided

Returns:



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/gapic/generic_lro/operation.rb', line 165

def reload! options: nil
  return self if done?

  @on_reload_callbacks.each { |proc| proc.call self }

  request_hash = @request_values.transform_keys(&:to_sym)
  @operation_copy_fields.each do |field_from, field_to|
    request_hash[field_to.to_sym] = operation.send field_from.to_s if operation.respond_to? field_from.to_s
  end

  options = merge_options options, @options

  ops = @client.send @polling_method_name, request_hash, options
  ops = ops.operation if ops.is_a? Gapic::GenericLRO::BaseOperation

  self.operation = ops

  if done?
    @on_reload_callbacks.clear
    @on_done_callbacks.each { |proc| proc.call self }
    @on_done_callbacks.clear
  end

  self
end

#response ⇒ Object?

If the operation is completed successfully, returns the underlying operation object, otherwise returns nil.

Returns:

  • (Object, nil) —

    The response of the operation.



132
133
134
 
# File 'lib/gapic/generic_lro/operation.rb', line 132

def response
  operation if response?
end

#response? ⇒ Boolean

Checks if the operation is done and the result is not an error. If the operation is not finished then this will return false.

Returns:

  • (Boolean) —

    Whether a response has been returned.



124
125
126
 
# File 'lib/gapic/generic_lro/operation.rb', line 124

def response?
  done? && !error?
end

#results ⇒ Object?

If the operation is done, returns the response. If the operation response is an error, the error will be returned. Otherwise returns nil.

Returns:

  • (Object, nil) —

    The result of the operation or an error.



91
92
93
94
 
# File 'lib/gapic/generic_lro/operation.rb', line 91

def results
  return error if error?
  return response if response?
end

#wait_until_done!(retry_policy: nil) {|_self| ... } ⇒ Object

Blocking method to wait until the operation has completed or the maximum timeout has been reached. Upon completion, registered callbacks will be called, then - if a block is given - the block will be called.

Parameters:

  • retry_policy (RetryPolicy, Hash, Proc) (defaults to: nil) —

    The policy for retry. A custom proc that takes the error as an argument and blocks can also be provided.

Yields:

  • (_self)

Yield Parameters:



201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/gapic/generic_lro/operation.rb', line 201

def wait_until_done! retry_policy: nil
  retry_policy = ::Gapic::Operation::RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
  retry_policy ||= ::Gapic::Operation::RetryPolicy.new

  until done?
    reload!
    break unless retry_policy.call
  end

  yield self if block_given?

  self
end