class Gapic::Operation

A class used to wrap Google::Longrunning::Operation objects. This class provides helper methods to check the status of an Operation

@example Checking Operation status

# this example assumes both api_client and operations_client
# already exist.
require "gapic/operation"

op = Gapic::Operation.new(
  api_client.method_that_returns_longrunning_operation(),
  operations_client,
  Google::Example::ResultType,
  Google::Example::MetadataType
)

op.done? # => false
op.reload! # => operation completed

if op.done?
  results = op.results
  handle_error(results) if op.error?
  # Handle results.
end

@example Working with callbacks

# this example assumes both api_client and operations_client
# already exist.
require "gapic/operation"

op = Gapic::Operation.new(
  api_client.method_that_returns_longrunning_operation(),
  operations_client,
  Google::Example::ResultType,
  Google::Example::MetadataType
)

# Register a callback to be run when an operation is done.
op.on_done do |operation|
  raise operation.results.message if operation.error?
  # process(operation.results)
  # process(operation.metadata)
end

# Reload the operation running callbacks if operation completed.
op.reload!

# Or block until the operation completes, passing a block to be called
# on completion.
op.wait_until_done! do |operation|
  raise operation.results.message if operation.error?
  # process(operation.results)
  # process(operation.rmetadata)
end

@attribute [r] grpc_op

@return [Google::Longrunning::Operation] The wrapped grpc
  operation object.

Attributes

grpc_op[R]

Public Class Methods

new(grpc_op, client, result_type: nil, metadata_type: nil, options: {}) click to toggle source

@param grpc_op [Google::Longrunning::Operation] The inital longrunning operation. @param client [Google::Longrunning::OperationsClient] The client that handles the grpc operations. @param result_type [Class] The class type to be unpacked from the result. If not provided the class type will be

looked up. Optional.

@param metadata_type [Class] The class type to be unpacked from the metadata. If not provided the class type

will be looked up. Optional.

@param options [Gapic::CallOptions] call options for this operation

# File lib/gapic/operation.rb, line 88
def initialize grpc_op, client, result_type: nil, metadata_type: nil, options: {}
  @grpc_op = grpc_op
  @client = client
  @result_type = result_type
  @metadata_type = metadata_type
  @on_done_callbacks = []
  @options = options
end

Public Instance Methods

cancel(options: nil) click to toggle source

Cancels the operation.

@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}.
# File lib/gapic/operation.rb, line 199
def cancel options: nil
  # Converts hash and nil to an options object
  options = Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h

  @client.cancel_operation({ name: @grpc_op.name }, options)
end
delete(options: nil) click to toggle source

Deletes the operation.

@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}.
# File lib/gapic/operation.rb, line 212
def delete options: nil
  # Converts hash and nil to an options object
  options = Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h

  @client.delete_operation({ name: @grpc_op.name }, options)
end
done?() click to toggle source

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/operation.rb, line 144
def done?
  @grpc_op.done
end
error() click to toggle source

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

@return [Google::Rpc::Status, nil] The error object.

# File lib/gapic/operation.rb, line 189
def error
  @grpc_op.error if error?
end
error?() click to toggle source

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/operation.rb, line 180
def error?
  done? ? @grpc_op.result == :error : false
end
metadata() click to toggle source

Returns the metadata of an operation. If a type is provided, the metadata will be unpacked using the type provided; returning nil if the metadata is not of the type provided. If the type is not of provided, the metadata will be unpacked using the metadata's type_url if the type_url is found in the {Google::Protobuf::DescriptorPool.generated_pool}. If the type cannot be found the raw metadata is retuned.

@return [Object, nil] The metadata of the operation. Can be nil.

# File lib/gapic/operation.rb, line 126
def metadata
  return if @grpc_op.metadata.nil?

  return @grpc_op.metadata.unpack @metadata_type if @metadata_type

  descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup @grpc_op.metadata.type_name

  return @grpc_op.metadata.unpack descriptor.msgclass if descriptor

  @grpc_op.metadata
end
name() click to toggle source

Returns the server-assigned name of the operation, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should have the format of operations/some/unique/name.

@return [String] The name of the operation.

# File lib/gapic/operation.rb, line 114
def name
  @grpc_op.name
end
on_done() { |self| ... } click to toggle source

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/operation.rb, line 275
def on_done &block
  if done?
    yield self
  else
    @on_done_callbacks.push block
  end
end
refresh!(options: nil)
Alias for: reload!
reload!(options: nil) click to toggle source

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::Operation] Since this method changes internal state, it returns itself.

# File lib/gapic/operation.rb, line 227
def reload! options: nil
  options = if options.respond_to? :to_h
              options.to_h.merge @options.to_h
            else
              @options.to_h
            end
  options = Gapic::CallOptions.new(**options)
  gax_op = @client.get_operation({ name: @grpc_op.name }, options)
  @grpc_op = gax_op.grpc_op

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

  self
end
Also aliased as: refresh!
response() click to toggle source

If the operation is done, returns the response, otherwise returns nil.

@return [Object, nil] The response of the operation.

# File lib/gapic/operation.rb, line 162
def response
  return unless response?

  return @grpc_op.response.unpack @result_type if @result_type

  descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup @grpc_op.response.type_name

  return @grpc_op.response.unpack descriptor.msgclass if descriptor

  @grpc_op.response
end
response?() click to toggle source

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

@return [Boolean] Whether a response has been returned.

# File lib/gapic/operation.rb, line 154
def response?
  done? ? @grpc_op.result == :response : false
end
results() click to toggle source

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, Google::Rpc::Status, nil] The result of the operation. If it is an error a

{Google::Rpc::Status} will be returned.
# File lib/gapic/operation.rb, line 103
def results
  return error if error?
  return response if response?
end
wait_until_done!(retry_policy: nil) { |self| ... } click to toggle source

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::Operation] Yields the finished Operation.

# File lib/gapic/operation.rb, line 255
def wait_until_done! retry_policy: nil
  retry_policy = RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
  retry_policy ||= RetryPolicy.new

  until done?
    reload!
    break unless retry_policy.call
  end

  yield self if block_given?

  self
end