class Gapic::GenericLRO::Operation
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.
Attributes
@private @return [Object] The client that handles the polling for the longrunning operation.
Public Class Methods
@param operation [Object] The long-running operation object that is returned by the initial method call.
@param client [Object] The client that handles the polling for the longrunning operation.
@param polling_method_name [String] The name of the methods on the client that polls the longrunning operation.
@param 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.
@param request_values [Map<String, String>] 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`
@param operation_name_field [String, nil] The name of the `name` field in the underlying long-running operation
object. Optional.
@param operation_err_field [String, 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.
@param operation_err_code_field [String, 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.
@param operation_err_msg_field [String, 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.
@param operation_copy_fields [Map<String, String>] 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`)
@param options [Gapic::CallOptions] call options for this operation
Gapic::GenericLRO::BaseOperation::new
# 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
Public Instance Methods
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.
@return [Boolean] Whether the operation is done.
# File lib/gapic/generic_lro/operation.rb, line 112 def done? return status if [true, false].include? status status == :DONE end
If the operation response is an error, the error will be returned, otherwise returns nil.
@return [Object, nil] The error object.
# File lib/gapic/generic_lro/operation.rb, line 152 def error return unless error? err || GenericError.new(error_code, error_msg) end
Checks if the operation is done and the result is an error. If the operation is not finished then this will return false.
@return [Boolean] Whether an error has been returned.
# 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
Returns the name of the operation, if specified.
@return [String, nil] The name of the operation.
# 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
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.
@yield operation [Gapic::Operation] Yields the finished Operation
.
# 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
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.
@yield operation [Gapic::Operation] Yields the finished Operation
.
# File lib/gapic/generic_lro/operation.rb, line 221 def on_reload &block return if done? @on_reload_callbacks.push block end
Reloads the operation object.
@param options [Gapic::CallOptions, Hash] The options for making the RPC call. A Hash can be provided to customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}.
@return [Gapic::GenericLRO::Operation] Since this method changes internal state, it returns itself.
# 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
If the operation is completed successfully, returns the underlying operation object, otherwise returns nil.
@return [Object, nil] The response of the operation.
# File lib/gapic/generic_lro/operation.rb, line 132 def response operation if response? end
Checks if the operation is done and the result is not an error. If the operation is not finished then this will return false.
@return [Boolean] Whether a response has been returned.
# File lib/gapic/generic_lro/operation.rb, line 124 def response? done? && !error? end
If the operation is done, returns the response. If the operation response is an error, the error will be returned. Otherwise returns nil.
@return [Object, nil] The result of the operation or an error.
# File lib/gapic/generic_lro/operation.rb, line 91 def results return error if error? return response if response? end
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.
@param retry_policy [RetryPolicy, Hash, Proc] The policy for retry. A custom proc that takes the error as an
argument and blocks can also be provided.
@yield operation [Gapic::GenericLRO::Operation] Yields the finished Operation
.
# 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
Private Instance Methods
@return [String, nil] An error message if the error message field is specified
# File lib/gapic/generic_lro/operation.rb, line 254 def err return nil if @operation_err_field.nil? operation.send @operation_err_field if operation.respond_to? @operation_err_field end
@return [String, nil] An error code if the error code field is specified
# File lib/gapic/generic_lro/operation.rb, line 262 def error_code return nil if @operation_err_code_field.nil? operation.send @operation_err_code_field if operation.respond_to? @operation_err_code_field end
@return [String, nil] An error message if the error message field is specified
# File lib/gapic/generic_lro/operation.rb, line 270 def error_msg return nil if @operation_err_msg_field.nil? operation.send @operation_err_msg_field if operation.respond_to? @operation_err_msg_field end
Merges options given to the method with a baseline Gapic::Options object
@param method_opts [Gapic::CallOptions, Hash] The options for making the RPC call given to a method invocation.
A Hash can be provided to customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}.
@param baseline_opts [Gapic::CallOptions, Hash] The baseline options for making the RPC call.
A Hash can be provided to customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}.
# File lib/gapic/generic_lro/operation.rb, line 286 def merge_options method_opts, baseline_opts options = if method_opts.respond_to? :to_h method_opts.to_h.merge baseline_opts.to_h else baseline_opts.to_h end Gapic::CallOptions.new(**options) end
@return [String, Boolean, nil] A status, whether operation is Done,
as either a boolean (`true` === Done) or a symbol (`:DONE` === Done)
# File lib/gapic/generic_lro/operation.rb, line 246 def status return nil if @operation_status_field.nil? operation.send @operation_status_field end