Class: OCI::Response

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/oci/waiter.rb,
lib/oci/response.rb

Overview

A response, which represents all successful API calls.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(status, headers, data) ⇒ Response

Returns a new instance of Response.



33
34
35
36
37
38
39
40
 
# File 'lib/oci/response.rb', line 33

def initialize(status, headers, data)
  @status = status
  @headers = OCI::ResponseHeaders.new(headers)
  @data = data

  @next_page = @headers['opc-next-page'] if headers
  @request_id = @headers['opc-request-id'] if headers
end

Instance Attribute Details

#api_call=(value) ⇒ Object (writeonly)

Sets the attribute api_call

Parameters:

  • value —

    the value to set the attribute api_call to.



31
32
33
 
# File 'lib/oci/response.rb', line 31

def api_call=(value)
  @api_call = value
end

#data ⇒ Object (readonly)

The body of the response. For example, this may contain a User object, or a list of Users.



18
19
20
 
# File 'lib/oci/response.rb', line 18

def data
  @data
end

#headers ⇒ ResponseHeaders (readonly)

A ResponseHeaders object containing all response headers

Returns:



14
15
16
 
# File 'lib/oci/response.rb', line 14

def headers
  @headers
end

#next_page ⇒ String (readonly)

The value of the next page token, if available, taken from the opc-next-page header.

Returns:

  • (String) 


24
25
26
 
# File 'lib/oci/response.rb', line 24

def next_page
  @next_page
end

#request_id ⇒ String (readonly)

The request ID, taken from the opc-request-id header.

Returns:

  • (String) 


29
30
31
 
# File 'lib/oci/response.rb', line 29

def request_id
  @request_id
end

#status ⇒ Integer (readonly)

The HTTP status, such as 200, 401, etc

Returns:

  • (Integer) 


9
10
11
 
# File 'lib/oci/response.rb', line 9

def status
  @status
end

Instance Method Details

#each {|response| ... } ⇒ Object

For paged responses, yields each page until the last page is reached. For example:

OCI::Identity::IdentityClient.new.list_users(compartment, limit:'3').each { |r| r.data.each { |user| puts user.name }}

The first response yielded is always the response that ‘each’ is being called on.

If any of the requests result in an error, that error will be thrown as normal, which will abort the enumeration.

While this can be called on non-paged responses, it will simply result in the response itself being yielded.

Yield Parameters:

  • response (Response) —

    A response object for each page, starting with the response used to call ‘each’.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/oci/response.rb', line 64

def each
  yield self
  page = @next_page

  while @api_call && page
    next_response = @api_call.call(page)

    if page == next_response.next_page
      raise 'Paging failure: Two consecutive responses had the same next page token.'
    end

    page = next_response.next_page
    yield next_response
  end
end

#has_next_page? ⇒ Boolean

Returns true if there is another page available.

Returns:

  • (Boolean) 


43
44
45
 
# File 'lib/oci/response.rb', line 43

def has_next_page?
  !next_page.nil?
end

#wait_until(property, state, max_interval_seconds: 30, max_wait_seconds: 1200) {|response| ... } ⇒ Response

Wait until the value of the given property in the response data has the given value. This will block the current thread until the the desired state is reached, the maximum wait time is reached, or the optional yield block throws :stop_succeed or :stop_fail. This is only supported for responses resulting from GET operations. A typical use case is to wait on an instance until it is in a running state:

compute_client.get_instance(@instance_id).wait_until(:lifecycle_state, OCI::Core::Models::Instance::LIFECYCLE_STATE_RUNNING)

Although this can be run on any property of the data resulting from any GET operation, the most common use case is to check state properties on operations that GET a single object.

The wait will poll at an increasing interval up to ‘max_interval_seconds’ for a maximum total time of ‘max_wait_seconds’. If the maximum time is exceeded, then it will raise a Waiter::Errors::MaximumWaitTimeExceededError.

On successful completion the final Response object will be returned. The original Response object will not be altered.

If any responses result in an error, then the error will be thrown as normal resulting in the wait being aborted.

Parameters:

  • property (Symbol) —

    The property of the response data to evaluate. For example, :lifecycle_state.

  • state —

    The value of the property that will indicate successful completion of the wait.

  • max_interval_seconds (Integer) (defaults to: 30) —

    The maximum interval between queries, in seconds.

  • max_wait_seconds (Integer) (defaults to: 1200) —

    The maximum time to wait, in seconds.

Yield Parameters:

  • response (Response) —

    A response object for every additional successful call to the get request. Throw :stop_succeed from the yield to stop the waiter and return the current response. Throw :stop_fail from the yield to stop the waiter and throw a WaiterFailedError.

Returns:

  • (Response) —

    The final response, which will contain the property in the specified state.

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/oci/waiter.rb', line 53

def wait_until(property, state, max_interval_seconds: 30, max_wait_seconds: 1200)
  raise 'Cannot wait on a response without data.' unless data
  raise 'Response data does not contain the given property.' unless data.methods.include? property

  raise Waiter::Errors::WaitUntilNotSupportedError, 'wait_until is not supported by this response.' unless @api_call

  response = self
  interval_seconds = 1
  start_time = Time.now

  loop do
    return response if response.data.send(property) == state

    elapsed_seconds = (Time.now - start_time).to_i

    if elapsed_seconds + interval_seconds > max_wait_seconds
      raise Waiter::Errors::MaximumWaitTimeExceededError, 'Maximum wait time has been exceeded.' \
        unless max_wait_seconds > elapsed_seconds

      # Make one last request right at the maximum wait time.
      interval_seconds = max_wait_seconds - elapsed_seconds
    end

    sleep(interval_seconds)

    interval_seconds *= 2
    if interval_seconds > max_interval_seconds
      interval_seconds = max_interval_seconds
    end

    response = @api_call.call(nil)

    next unless block_given?

    continue = false
    catch(:stop_fail) do
      catch(:stop_succeed) do
        yield response
        continue = true
      end

      return response unless continue
    end

    raise Waiter::Errors::WaiterFailedError unless continue
  end
end