Class: OracleBMC::Response

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/oraclebmc/response.rb,
lib/oraclebmc/waiter.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.



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

def initialize(status, headers, data)
  @status = status
  @headers = headers
  @data = data

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

Instance Attribute Details

#data ⇒ Object (readonly)

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



19
20
21
 
# File 'lib/oraclebmc/response.rb', line 19

def data
  @data
end

#headers ⇒ Hash (readonly)

A hash containing all response headers

Returns:

  • (Hash) 


15
16
17
 
# File 'lib/oraclebmc/response.rb', line 15

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) 


25
26
27
 
# File 'lib/oraclebmc/response.rb', line 25

def next_page
  @next_page
end

#request_id ⇒ String (readonly)

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

Returns:

  • (String) 


30
31
32
 
# File 'lib/oraclebmc/response.rb', line 30

def request_id
  @request_id
end

#status ⇒ Integer (readonly)

The HTTP status, such as 200, 401, etc

Returns:

  • (Integer) 


10
11
12
 
# File 'lib/oraclebmc/response.rb', line 10

def status
  @status
end

Instance Method Details

#api_call=(c) ⇒ Object 



81
82
83
 
# File 'lib/oraclebmc/response.rb', line 81

def api_call=(c)
  @api_call = c
end

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

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

OracleBMC::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’.



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

def each
  yield self
  page = @next_page

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

    if page == next_response.next_page
      fail "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) 


44
45
46
 
# File 'lib/oraclebmc/response.rb', line 44

def has_next_page?
  return !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, OracleBMC::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
100
101
102
103
104
105
106
107
108
 
# File 'lib/oraclebmc/waiter.rb', line 53

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

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

  response = self
  count = 0
  interval_seconds = 1
  start_time = Time.now

  while true
    if response.data.send(property) == state
       return response
    end

    elapsed_seconds = (Time.now - start_time).to_i

    if elapsed_seconds + interval_seconds > max_wait_seconds
      if max_wait_seconds > elapsed_seconds
        # Make one last request right at the maximum wait time.
        interval_seconds = max_wait_seconds - elapsed_seconds
      else
        raise Waiter::Errors::MaximumWaitTimeExceededError.new('Maximum wait time has been exceeded.')
      end
    end

    sleep(interval_seconds)

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

    response = @api_call.call(nil)

    if block_given?
      continue = false
      catch(:stop_fail) {
        catch(:stop_succeed) {
          yield response
          continue = true
        }

        if not continue
          return response
        end
      }

      if not continue
        raise Waiter::Errors::WaiterFailedError
      end
    end
  end

end